DragonFly On-Line Manual Pages
CFG_OPTION(3) libcfg+ 0.6.2 CFG_OPTION(3)
NAME
cfg_option - libcfg+ options set
SYNOPSIS
The basic unit of libcfg+ is an option. An option is defined by the
cfg_option structure, whose definition is presented below:
struct cfg_option {
const char *cmdline_long_name;
const char cmdline_short_name;
const char *cfgfile_name;
const enum cfg_option_type type;
void *value;
int val;
};
DESCRIPTION
The first two members of the cfg_option structure, cmdline_long_name
and cmdline_short_name, specify the long and short name of the option
when parsing the command line. The third member, cfgfile_name,
specifies the name of the option in a configuration file. Setting the
first two fields to NULL and '\0' respectively will effectively
eliminate the option from taking part in command line parsing. Setting
cfgfile_name to NULL will eliminate this option from taking part in
configuration file parsing.
Note also that if cmdline_long_name or cfgfile_name point to a string
containing at least one whitespace character, any non-zero number of
whitespace characters will be matched during parsing. For example, if
the separator is a space, a tab character will also match, as will two
spaces and a tab, two tabs and a space, and so on. This simplifies the
configuration for the user because one does not have to pay attention
to the number of spaces used in a configuration option. For example,
debug level, debug\tlevel and debug \tlevel will match the same option.
The variable type is an enumeration defining the type of an option with
each member of the enumeration being either a type or a flag. The
possible values of type are summarized in tables Option type flags and
Option type flags
The variable value is a pointer to the argument(s) of an option. The
argument(s) must be of the type stored in the type member of the
cfg_option structure. Note that value could also contain a NULL value,
which would suggest that the option arguments will not be stored.
The last field of the structure is val. It defines the exit code of
parsing function when this option is found in the token stream. Setting
this field to 0 will cause cfg_get_next_opt() to proceed to the next
option instead of returning. Also, since cfg_get_next_opt() also
returns negative integers to signal an error, it is a good idea to keep
the value of this field in the positive range. You can read more about
this in the Parsing section.
"OPTION TYPES"
CFG_BOOL, CFG_BOOLEAN
value type: int
No argument for an option is expected. Boolean datatype with two
states.
CFG_INT, CFG_INTEGER
value type: int
Integer argument
CFG_UINT, CFG_UNSIGNED, CFG_UNSIGNED_INT
value type: unsigned int
Unsigned integer argument
CFG_LONG
value type: long int
Long integer argument
CFG_ULONG, CFG_UNSIGNED_LONG
value type: unsigned long int
Unsigned long integer argument
CFG_FLOAT
value type: float
Float argument
CFG_DOUBLE
value type: double
Double argument
CFG_STR, CFG_STRING
value type: char *
String argument
The next table describes the possible "type flags" of an option. The
purpose of the flags is to add more variety and thus flexibility to the
basic data types presented in the previous table. By combining one of
the flags with one of the basic types, a completely new data type can
be produced. For example, to define an array of strings, one would use
the CFG_MULTI flag in addition to the CFG_STRING data type. One of the
obvious rules of this data type combining is that the flags must always
be used in conjunction with the basic types since a flag is only a data
type modifier and not a self-contained data type.
"OPTION TYPE FLAGS"
CFG_MULTI, CFG_MULTI_ARRAY
<type> **
The Option can be specified more than once and the result is a
dynamic array of the defined type.
CFG_MULTI_SEPARATED
<type> **
Same as CFG_MULTI_ARRAY, but a dynamic array is also created by
splitting the option value according to the defined separators.
See the Properties section for more information about the
separators that can be used and ways to change them.
CFG_LAST_ARGS, CFG_LAST_ARGUMENTS, CFG_LEFTOVER_ARGS,
CFG_LEFTOVER_ARGUMENTS
<type> **
Leftover arguments are stored here.
Of the basic data types, only strings are dynamically allocated and in
that case value points to a portion of memory allocated with malloc()
function. Do not forget to free that memory when you do not need it
anymore using the free() function. If the CFG_MULTI_ARRAY or the
CFG_MULTI_SEPARATED flag was used, value will point to a NULL
terminated array of a basic type. It can be freed using
cfg_strdyn_free().
The constants CFG_END_OPTION and CFG_END_OF_LIST are used to mark the
end of an option set. They set all pointer values to NULL and all
numeric values to 0.
EXAMPLE OF OPTIONS SET DEFINITION
#include <cfg+.h>
/* Option variables */
int help, verbose, nice;
char *cfg_file;
char **command;
/* Option set */
struct cfg_option options[] = {
{"help", 'h', NULL, CFG_BOOL, (void *) &help, 0},
{"nice", 'n', "nice", CFG_INT, (void *) &nice, 0},
{"verbose", 'v', "verbose", CFG_BOOL+CFG_MULTI,(void *) &verbose, 0},
{NULL, 'f', NULL, CFG_STR, (void *) &cfg_file, 0},
{NULL, '\0', "command", CFG_STR+CFG_MULTI_SEPARATED+CFG_LEFTOVER_ARGS,
(void *) &command, 0},
CFG_END_OF_LIST
};
SEE ALSO
You can get library overview, table of contents and such additional
information info from main libcfg+(3) manpage by typing "man libcfg+"
on UNIX-based systems. Also use this command to get information about
authors, homepage and license conditions.
libcfg+ 0.6.2 17 February 2004 CFG_OPTION(3)