libcfg+/man/cfg_option.3.html
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 definiâ
tion 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 whiteâ
space character, any non-zero number of whitespace characters will be matched during parsing. For examâ
ple, 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 porâ
tion 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 informaâ
tion about authors, homepage and license conditions.
libcfg+ 0.6.2 17 February 2004 CFG_OPTION(3)
|
Login
Registration
Slovak
