CFG_CONTEXT(3) libcfg+ 0.6.2 CFG_CONTEXT(3)NAME
cfg_context, cfg_get_context, cfg_get_cmdline_context, cfg_get_cfg‐
file_context, cfg_set_cmdline_context, cfg_set_cfgfile_context,
cfg_reset_context, cfg_free_context - libcfg+ context manipulation
SYNOPSIS | CREATING CONTEXT
The parsing capabilities of libcfg+ are accessed through a context,
which is defined by the CFG_CONTEXT structure. By using contexts, one
can parse several configuration files and the command line at the same
time.
The functions used for creating a new context are described below.
Those used for freeing (destroying) a context are described at the end
of this manpage.
#include <cfg+.h>
CFG_CONTEXT cfg_get_context (struct cfg_option *options);
CFG_CONTEXT cfg_get_cmdline_context (long begin_pos, long size, char
**argv, struct cfg_option options);
CFG_CONTEXT cfg_get_cfgfile_context (long begin_pos, long size, char
*filename, struct cfg_option options);
void cfg_set_cmdline_context (CFG_CONTEXT con, long begin_pos, long
size, char **argv);
void cfg_set_cfgfile_context (CFG_CONTEXT con, long begin_pos, long
size, char *filename);
DESCRIPTION
The function cfg_get_context() initializes a context but does not asso‐
ciate it with either the command line or a file. It takes a pointer to
the option set *options and returns a new context. The association with
the command line or a file can be done with cfg_set_cmdline_context()
and cfg_set_cfgline_context() respectively.
The function cfg_get_cmdline_context() is used for full context ini‐
tialization, which includes the initialization itself and assigning the
newly created context to the command line. The begin_pos parameter
stores the starting parsing position in the array of command line argu‐
ments. The size parameter defines the number of arguments (array ele‐
ments) to parse. If a negative value is passed, the parsing will stop
only when an NULL is encountered. The argv parameter is a pointer to a
NULL terminated array of strings (options + arguments) to be parsed. As
most of you probably know, argv is the second parameter passed to the
main() function.
The function cfg_get_cfgfile_function() initializes a new context and
associates it with a configuration file. The parameter begin_pos deter‐
mines the file offset at which the parsing will start. Whether the off‐
set is expressed in bytes or lines depends on the value of the context
flag CFG_FILE_LINE_POS_USAGE. If the flag is unset (the default
value), begin_pos should be interpreted as a byte offset. If the flag
is set, begin_pos is a line offset. See the Context flags section for
more information about this. Whatever the case, the offset is zero
based. The size parameter defines the number of bytes or lines to
parse. If the value is negative, the file will be parsed in its
entirety. The name of the file to parse is passed in filename.
cfg_set_cmdline_context() and cfg_set_cfgfile_context() work on an
already existing context. These functions accept the existing context
in their first parameter. The rest of their arguments are the same as
those of cfg_get_cfgfile_function() and cfg_get_cmdline_context().
Note that the two sets of functions differ in their return values. The
context setting functions return void while the context creating func‐
tions return a new context. Working with existing contexts may be more
convenient than creating new contexts from scratch, especially when
there is a need to switch from parsing a file to parsing the command
line and vice versa.
Note, that while begin_pos of the file context defines the starting
parsing offset in a file, the same parameter for the command line con‐
text specifies the offset in the argv array. Note also that all off‐
sets are zero-based. For example, the third line of a file is at off‐
set 2. However, the error handling routines of libcfg+ increment all
offsets by one when reporting an error, thus human readable messages
are returned. So for the first position on command line it will print
something like on position 1, for second line in configuration file it
will print on line 2 and so on.
Starting from version 0.5.2, the cfg_get_cmdline_context_argc() and
cfg_set_cmdline_context_argc() functions became available. It creates
a new context by passing the argc and argv parameters directly from
main() function. Its parameters are similar to those of cfg_get_cmd‐
line_context(), but instead of begin_pos and size, only argc is
present. Whether one is more convenient than the other depends on the
circumstances and it is for you to decide which one suits you best.
There are also two groups of macros for managing contexts. The first
group includes cfg_get_cmdline_context_pos() and cfg_get_cfgfile_con‐
text_pos() and is used for creating a new context of the needed type.
You can use the second group, which consist of cfg_set_cmdline_con‐
text_pos() and cfg_set_cfgfile_context_pos(), for manipulating an
existing context. The difference between these four macros and their
function counterparts is in the size parameter, which is replaced by
end_pos and specifies the offset of the last element to be parsed. For
a file context the value is the byte offset (or line number) while for
a command line context it is the offset in the argv array.
SYNOPSIS | FREEING CONTEXT
The following functions are used for reseting and freeing a context.
#include <cfg+.h>
void cfg_reset_context (CFG_CONTEXT con);
void cfg_free_context (CFG_CONTEXT con);
DESCRIPTION
You may come across situations when a context reset is necessary. You
can use cfg_reset_context() to perform this task. When this function is
called on a command line context, the offset in the argv is set to the
value of begin_pos. For a file context, the offset is reset to the
value of begin_pos. Context flags and context properties remain
unchanged after a call to cfg_reset_context().
After you are done with a context, you should use cfg_free_context() to
free the resources associated with it. The function takes a context in
its only parameter con. The function does not deallocate the memory for
any arguments or argument arrays you might have allocated in your
option set. You need to free that memory manually. However, it will
free all internal context structures, which includes the context flags,
context properties, and the context itself.
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_CONTEXT(3)
