.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "CFG_CONTEXT" "3" "17 February 2004" "libcfg+ 0.6.2" "libcfg+ 0.6.2"
.SH NAME
cfg_context, cfg_get_context, cfg_get_cmdline_context, cfg_get_cfgfile_context, cfg_set_cmdline_context, cfg_set_cfgfile_context, cfg_reset_context, cfg_free_context \- libcfg+ context manipulation
.SH "SYNOPSIS | CREATING CONTEXT"
.PP
The parsing capabilities of libcfg+ are accessed through a
\fIcontext\fR, 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.  
.PP
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.
.sp
\fB#include <cfg+.h>
.sp
CFG_CONTEXT cfg_get_context (struct cfg_option \fI*options\fB);
.sp
CFG_CONTEXT cfg_get_cmdline_context (long \fIbegin_pos\fB, long \fIsize\fB, char \fI**argv\fB, struct cfg_option \fIoptions\fB);
.sp
CFG_CONTEXT cfg_get_cfgfile_context (long \fIbegin_pos\fB, long \fIsize\fB, char \fI*filename\fB, struct cfg_option \fIoptions\fB);
.sp
void cfg_set_cmdline_context (CFG_CONTEXT \fIcon\fB, long \fIbegin_pos\fB, long \fIsize\fB, char \fI**argv\fB);
.sp
void cfg_set_cfgfile_context (CFG_CONTEXT \fIcon\fB, long \fIbegin_pos\fB, long \fIsize\fB, char \fI*filename\fB);
\fR
.SH "DESCRIPTION"
.PP
The function \fBcfg_get_context()\fR initializes a context but
does not associate it with either the command line or a file. It takes a
pointer to the option set \fI*options\fR and returns a new
context. The association with the command line or a file can be done with
\fBcfg_set_cmdline_context()\fR and
\fBcfg_set_cfgline_context()\fR respectively. 
.PP
The function \fBcfg_get_cmdline_context()\fR is used for full
context initialization, which includes the initialization itself and assigning
the newly created context to the command line. The
\fIbegin_pos\fR parameter stores the starting parsing
position in the array of command line arguments. The
\fIsize\fR parameter defines the number of arguments (array
elements) to parse. If a negative value is passed, the parsing will stop only
when an NULL is encountered. The
\fIargv\fR parameter is a pointer to a
NULL terminated array of strings (options\~+\~arguments) to
be parsed. As most of you probably know, \fIargv\fR is the
second parameter passed to the \fBmain()\fR function.
.PP
The function \fBcfg_get_cfgfile_function()\fR initializes a new
context and associates it with a configuration file. The parameter
\fIbegin_pos\fR determines the file offset at which the
parsing will start. Whether the offset 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), \fIbegin_pos\fR
should be interpreted as a byte offset. If the flag is set,
\fIbegin_pos\fR is a line offset. See the Context flags section for
more information about this. Whatever the case, the offset is zero based.  The
\fIsize\fR 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 \fIfilename\fR.
.PP
\fBcfg_set_cmdline_context()\fR and
\fBcfg_set_cfgfile_context()\fR 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
\fBcfg_get_cfgfile_function()\fR and
\fBcfg_get_cmdline_context()\fR.  Note that the two sets of
functions differ in their return values. The context setting functions return
void while the context creating functions 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.
.PP
Note, that while \fIbegin_pos\fR of the file context defines
the starting parsing offset in a file, the same parameter for the command line
context specifies the offset in the \fIargv\fR array.  Note
also that all offsets are zero-based. For example, the third line of a file is
at\~offset\~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.
.PP
Starting from version 0.5.2, the
\fBcfg_get_cmdline_context_argc()\fR and
\fBcfg_set_cmdline_context_argc()\fR functions became
available.  It creates a new context by passing the
\fIargc\fR and \fIargv\fR parameters
directly from \fBmain()\fR function. Its parameters are similar
to those of \fBcfg_get_cmdline_context()\fR, but instead of
\fIbegin_pos\fR and \fIsize\fR, only
\fIargc\fR 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.
.PP
There are also two groups of macros for managing contexts. The first group
includes \fBcfg_get_cmdline_context_pos()\fR and
\fBcfg_get_cfgfile_context_pos()\fR and is used for creating a
new context of the needed type. You can use the second group, which consist of
\fBcfg_set_cmdline_context_pos()\fR and
\fBcfg_set_cfgfile_context_pos()\fR, for manipulating an
existing context. The difference between these four macros and their function
counterparts is in the \fIsize\fR parameter, which is
replaced by \fIend_pos\fR 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
\fIargv\fR array.
.SH "SYNOPSIS | FREEING CONTEXT"
.PP
The following functions are used for reseting and freeing a context.
.sp
\fB#include <cfg+.h>
.sp
void cfg_reset_context (CFG_CONTEXT \fIcon\fB);
.sp
void cfg_free_context (CFG_CONTEXT \fIcon\fB);
\fR
.SH "DESCRIPTION"
.PP
You may come across situations when a context reset is necessary. You can use
\fBcfg_reset_context()\fR to perform this task. When this
function is called on a command line context, the offset in the
\fIargv\fR is set to the value of
\fIbegin_pos\fR. For a file context, the offset is reset to
the value of \fIbegin_pos\fR. Context flags and context
properties remain unchanged after a call to
\fBcfg_reset_context()\fR. 
.PP
After you are done with a context, you should use
\fBcfg_free_context()\fR to free the resources associated with
it. The function takes a context in its only parameter
\fIcon\fR. 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.
.\" This is common footer for libcfg+ manpages. 
.\" Written by Ondrej Jombik in 14th September 2002
.SH "SEE ALSO"
You can get library overview, table of contents and such additional information
info from main \fBlibcfg+\fR(3) manpage by typing "man libcfg+" on UNIX-based
systems. Also use this command to get information about authors, homepage and
license conditions.