Reference

Command Argument Processing

Types

typedef struct arguments *ARGUMENTS

An ARGUMENTS is a set of all options and parameter values captured from the command line.

typedef struct usage *USAGE

Defines a complete ‘usage’ for an application.

C API

void ca_add_flag(USAGE usage, char option, const char *name, const char *description, int override)

Add a flag option to the usage definition.

Parameters:

  • usage – The usage to add the option to.

  • option – The option character that is used to activate (EG -l, -H).

  • name – The option name, also used for long option version (EG —list, —host-name).

  • description – A short description of the option purpose.

  • override – If TRUE stops further argument processing if encountered during command line parse.

void ca_add_option(USAGE usage, char option, const char *name, const char *description, const char *default_value, int override)

Add an option to the usage definition.

Parameters:

  • usage – The usage to add the option to.

  • option – The option character that is used to activate (EG -l, -H).

  • name – The option name, also used for long option version (EG —list, —host-name).

  • description – A short description of the option purpose.

  • default_value – The default value for the option.

  • override – If TRUE stops further argument processing if encountered during command line parse.

void ca_add_parameter(USAGE usage, const char *name, const char *description)

Add a positional parameter to the usage definition.

Remark

The parameters will be documented by ca_print_usage() as being required in the order they are declared using this function call.

Parameters:

  • usage – The usage to add the parameter to.

  • name – An optional parameter name.

  • description – An optional short description of the parameter purpose.

void ca_add_arg_list(USAGE usage, const char *name, const char *description, int min, int max)

Allow ad hoc parameter values after all options and positional parameters. Often used for a file list.

Parameters:

  • usage – The usage to allow a list on.

  • name – An optional name for the list, used in usage messages.

  • description – An optional short description of the list, used in usage messages.

  • min – The minimum expected.

  • max – The maximum expected. Use zero for no maximum.

USAGE ca_create_usage(MEM_SCOPE mem, const char *title, const char *description, const char *remarks, const char *version, const char *copyright)

Create a usage definition to be used to parse command arguments.

Parameters:

  • mem – A memory scope to own the USAGE.

  • title – The application name or title.

  • description – A short description of the application purpose.

  • remarks – Important remarks about the application.

  • version – The application version.

  • copyright – The application copyright message.

Returns:

A USAGE.

int ca_get_flag(ARGUMENTS args, const char *name)

Get an argument flag value.

Parameters:

  • args – An ARGUMENTS returned from ca_parse().

  • name – The flag name.

Returns:

TRUE if the flag was detected, FALSE otherwise.

const char *ca_get_error(ARGUMENTS args)

Get the error message associated with the most recent parse.

Remark

Use ca_has_error() to test if there was an error. A NULL will be returned if there was no error.

See also

ca_has_error(), ca_print_error().

Parameters:

args – An ARGUMENTS returned from ca_parse().

Returns:

The error message.

const char *ca_get_option(ARGUMENTS args, const char *name)

Get an argument option value.

Parameters:

  • args – An ARGUMENTS returned from ca_parse().

  • name – The option name.

Returns:

The value of the option.

const char **ca_get_list(ARGUMENTS args)

Get the argument list values.

Parameters:

args – An ARGUMENTS returned from ca_parse().

Returns:

A NULL terminated array of list values.

const char *ca_get_parameter(ARGUMENTS args, const char *name)

Get an argument parameter value.

Parameters:

  • args – An ARGUMENTS returned from ca_parse().

  • name – The parameter name.

Returns:

The value of the parameter.

int ca_has_error(ARGUMENTS args)

Indicate if the argument parse had errors.

Parameters:

args – he arguments returned from ca_parse().

Returns:

TRUE if there were errors, FALSE otherwsie.

ARGUMENTS ca_parse(MEM_SCOPE mem, USAGE usage, int argc, char **argv)

Parse the application command arguments according to the USAGE_DEF description.

Parameters:

  • mem – A memory scope to own the returned ARGUMENTS.

  • usage – The usage data definition.

  • argc – The argc parameter as received in main().

  • argv – The argv parameter as received in main().

Returns:

An ARGUMENTS that can be used to retrieve argument data.

void ca_print_error(FILE *fp, ARGUMENTS args)

Print an error.

Parameters:

  • fp – The FILE stream to write to.

  • args – The arguments returned from ca_parse().

void ca_print_usage(FILE *fp, USAGE usage)

Print a usage message to the given FILE stream.

Parameters:

  • fp – An open, writeable file stream.

  • usage – The usage data definition.

void ca_print_version(FILE *fp, USAGE usage)

Print a version and copyright message to the given FILE stream.

Parameters:

  • fp – An open, writeable file stream.

  • usage – The usage data definition.

INI File Processing

Types

typedef struct app_config *APP_CONFIG

Application configuration.

C API

const char *cfg_get_item(APP_CONFIG cfg, const char *section, const char *item)

Get an application configuration item.

Parameters:

  • cfg – Application configuration.

  • section – The section name.

  • item – The item key.

Returns:

The configuration item value, or NULL if the value does not exist.

const char **cfg_get_section(APP_CONFIG cfg, const char *section)

Get a set of application configuration item for an entire section.

Remark

If the section is not found at all a NULL is returned.

Parameters:

  • cfg – Application configuration.

  • section – The section name.

Returns:

A NULL terminated list of item strings ‘as is’ not separated by the ‘=’ character.

APP_CONFIG cfg_load(MEM_SCOPE mem, const char *name, const char **paths)

Load application configuration.

Remark

If the file name contains one or more ‘/’ characters it is assumed to be a full pathname and no path search will take place, regardless of the value of the paths argument.

If the search path argument is NULL or the file is not found in any path, then the current directory will searched, followed by the paths listed in the environment variable INI_PATH.

INI_PATH paths should be separated by the ‘:’ character.

Parameters:

  • mem – A memory scope to own the memory.

  • name – The INI file name.

  • paths – A NULL terminated set of search paths.

Returns:

Application configuration, or NULL if there was an error reading the configuration.

const char *cfg_pathname(APP_CONFIG cfg)

Return the INI file pathname used to compile configuration.

Parameters:

cfg – The application configuration.

Returns:

The pathname of the first found INI file.

Environment Utilities

const char *get_host_name()

Get the computer system host name.

Returns:

The host name.

const char *get_program_name()

Get the program name by reading /proc/self/status.

Returns:

The program name.

char *shell(MEM_SCOPE mem, const char *command)

Run a shell command and capture the output.

Remark

Because the command is run in a shell redirects are possible, so stderr may also be captured by using a shell redirect in the command.

Parameters:

  • mem – A memory scope to own the memory.

  • command – The shell command to run.

Returns:

The stdout output from the command.

Variables

C API

char *var_environment(MEM_SCOPE mem, const char *key)

Get the value of an environment variable. The key may include the specification of a default value that will be returned if the environment variable does not exist or is empty.

Remark

A default value is specified by adding it to the key separating with the ‘:’ colon character. EG: MY_VAR:my value, will return ‘my value’ if MY_VAR does not exist or is empty.

Parameters:

  • mem – A memory scope to hold the returned value.

  • key – The environment variable name.

Returns:

The environment value, or default value if not found.

char *var_to_key(MEM_SCOPE mem, const char *var)

Get the key name for a given transform variable.

Remark

For example, the value ‘@MY_KEY@’ returns ‘MY_KEY’.

Parameters:

  • mem – A memory scope to hold the returned value.

  • var – The variable to get the key for.

Returns:

The key value.

char *var_from_key(MEM_SCOPE mem, const char *key)

Get the variable name for a given transform key.

Remark

For example, the value ‘MY_KEY’ returns ‘@MY_KEY@’.

Parameters:

  • mem – A memory scope to hold the returned value.

  • key – The key to get the variable for.

Returns:

The full variable name.

char *var_transform(MEM_SCOPE mem, APP_CONFIG cfg, const char *template, const char *sections[], int no_exec)

Transform the contents of a template string using the properties found in an APP_CONFIG map.

Remark

Any variables found in the template string are resolved by looking up values in the APP_CONFIG key/value map. Resolution is cumulative, so values in the map may be further resolved where variables are found within. A variable is indicated by a preceding and trailing ‘@’ character, EG @MY_VAR@. Variable values in the APP_CONFIG map may themselves contain variables. Environment variables may also be used. These are indicated with a preceding ‘$’ character and trailing whitespace. Additionally, a subshell may be used to return a value. This is indicated by a preceding and trailing ‘ backtick character. The content is taken as a shell command and run. The standard output is returned as the value, with any trailing newline removed. For more information see ‘tgen’.

See also

The ‘tgen’ application.

Parameters:

  • mem – A memory scope to hold the returned value.

  • cfg – An APP_CONFIG map, such as data loaded from the properties section of an ini file.

  • template – The template string to transform.

  • sections – A NULL terminated list of sections to search for variables without a section. Variables may be specified with a section, EG ‘General/Name’, or just the variable name. Those without a section will be searched for in these sections in the order they appear. The list can be empty or NULL. A NULL list is provided for backward compatibility and will result in a search of the ‘Properties’ section. An empty list, IE a single NULL entry, will result in no search at all, relying on global scope and section qualified variables only.

  • no_exec – If TRUE, inhibits using shell commands to resolve a variable. This is useful if security is a concern.

Returns:

The transformed string.

Logging

Defines

ASSERT(expr, msg, ...)

Assert with a useful message. In DEBUG builds ASSERT delegates to system standard assert(). In RELEASE builds ASSERT prints the provided message to stderr and then aborts().

Types

typedef enum log_level LOG_LEVEL
enum log_level

An enumeration to indicate the severity of a log message.

Values:

enumerator L_FATAL

Severe enough that the process must end immediately.

enumerator L_ERROR

A general error that will cause an error code branch to be executed.

enumerator L_WARN

A general error that will be ignored.

enumerator L_INFO

A progress statement for information only.

enumerator L_TRACE

A trace statement, usually reserved for diagnostics.

typedef struct log *LOG

Defines a log destination.

C API

void set_log_level(LOG log, LOG_LEVEL level)

Sets the logging level for the specified log instance.

Parameters:

  • log – The log instance for which the level will be set.

  • level – The new logging level to be assigned to the log instance.

void log_printf(LOG log, LOG_LEVEL level, const char *format, ...)

Write a log message.

Remark

Messages with a level greater than that set by set_log_level() are ignored and not sent to the log.

Parameters:

  • log – The log instance to send the log message to.

  • level – The log level to write at.

  • format – A printf style format string.

  • ... – Printf style arguments.

void log_close(LOG log)

Close a log.

Remark

Not all log types require closing. It is good practice to always close a log regardless.

Parameters:

log – The log to close

LOG log_fp_create(const MEM_SCOPE mem, FILE *fp)

Create a log that writes to a FILE.

Remark

The FILE must be open for writing. Calling log_close() for this type log does not close the file.

Parameters:

  • mem – A memory scope to own the memory.

  • fp – The FILE to write messages to.

Returns:

A LOG to use for logging.

LOG log_std_create(const MEM_SCOPE mem)

Create a log that writes appropriately to stdout and stderr.

Remark

L_INFO and L_TRACE write to stdout, L_WARN, L_ERROR and L_FATAL write to stderr.

Parameters:

mem – A memory scope to own the memory.

Returns:

A LOG to use for logging.

LOG log_file_create(const MEM_SCOPE mem, const char *filename)

Create a log that writes to a named file.

Remark

The file will be opened for appending.

Parameters:

  • mem – A memory scope to own the memory.

  • filename – The name of a file to open for sending log messages to.

Returns:

A LOG to use for logging, or NULL if there was an error.

LOG log_sys_create(const MEM_SCOPE mem, const int option, const int facility)

Crate a log that write to the system syslog.

Remark

The standard system log levels include LOG_EMERG, LOG_ALERT and LOG_DEBUG not supported by c-craft logging and will never be generated in syslog. Others map like so: LOG_FATAL -> LOG_CRIT LOG_ERROR -> LOG_ERR LOG_WARN -> LOG_WARNING LOG_INFO -> LOG_NOTICE LOG_TRACE -> LOG_INFO

Parameters:

  • mem – A memory scope to own the memory.

  • option – The syslog option. See syslog (3).

  • facility – The syslog facility. See syslog (3).

Returns:

A LOG to use for logging.