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.

Return

A USAGE.

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.

int ca_get_flag(ARGUMENTS args, const char *name)¶

Get an argument flag value.

Return

TRUE if the flag was detected, FALSE otherwise.

Parameters

args: An ARGUMENTS returned from ca_parse().
name: The flag name.

const char *ca_get_error(ARGUMENTS args)¶

Get the error message associated with the most recent parse.

Return

The error message.

Remark

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

See

ca_has_error(), ca_print_error().

Parameters

args: An ARGUMENTS returned from ca_parse().

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

Get an argument option value.

Return

The value of the option.

Parameters

args: An ARGUMENTS returned from ca_parse().
name: The option name.

const char **ca_get_list(ARGUMENTS args)¶

Get the argument list values.

Return

A NULL terminated array of list values.

Parameters

args: An ARGUMENTS returned from ca_parse().

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

Get an argument parameter value.

Return

The value of the parameter.

Parameters

args: An ARGUMENTS returned from ca_parse().
name: The parameter name.

int ca_has_error(ARGUMENTS args)¶

Indicate if the argument parse had errors.

Return

TRUE if there were errors, FALSE otherwsie.

Parameters

args: he arguments returned from ca_parse().

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

Parse the application command arguments according to the USAGE_DEF description.

Return

An ARGUMENTS that can be used to retrieve argument data.

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().

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.

Return

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

Parameters

cfg: Application configuration.
section: The section name.
item: The item key.

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

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

Return

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

Remark

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

Parameters

cfg: Application configuration.
section: The section name.

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

Load application configuration.

Return

Application configuration, or NULL if there was an error reading the 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.

const char *cfg_pathname(APP_CONFIG cfg)¶

Return the INI file pathname used to compile configuration.

Return

The pathname of the first found INI file.

Parameters

cfg: The application configuration.

Environment Utilities¶

const char *get_host_name()¶

Get the computer system host name.

Return: The host name.

const char *get_program_name()¶

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

Return: The program name.

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

Run a shell command and capture the output.

Return

The stdout output from the command.

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.

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.

Return

The environment value, or default value if not found.

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.

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

Get the key name for a given transform variable.

Return

The key value.

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.

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

Get the variable name for a given transform key.

Return

The full variable name.

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.

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.

Return

The transformed string.

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

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.

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:

L_FATAL¶: Severe enough that the process must end immediately.

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

L_WARN¶: A general error that will be ignored.

L_INFO¶: A progress statement for information only.

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.

Return

A LOG to use for logging.

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.

LOG log_std_create(const MEM_SCOPE mem)¶

Create a log that writes appropriately to stdout and stderr.

Return

A LOG to use for logging.

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.

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

Create a log that writes to a named file.

Return

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

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.

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

Crate a log that write to the system syslog.

Return

A LOG to use for logging.

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).

Reference¶

Command Argument Processing¶

Types¶

C API¶

INI File Processing¶

Types¶

C API¶

Environment Utilities¶

Variables¶

C API¶

Logging¶

Defines¶

Types¶

C API¶

C Craft

Navigation

Related Topics