libcfg+/man/cfg_context.3.html

CFG_CONTEXT(3)                                   libcfg+ 0.6.2                                  CFG_CONTEXT(3)

NAME
       cfg_context,  cfg_get_context,  cfg_get_cmdline_context,  cfg_get_cfgfile_context, cfg_set_cmdline_con‐
       text, 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 associate it with either the command
       line or a file. It takes a pointer to the option set *options and returns a new context.  The  associa‐
       tion  with  the  command  line  or  a  file can be done with cfg_set_cmdline_context() and cfg_set_cfg‐
       line_context() respectively.

       The function cfg_get_cmdline_context() is used for full context initialization, which includes the ini‐
       tialization 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 arguments. The size 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 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  configura‐
       tion  file. The parameter begin_pos 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), 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  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.

       Note,  that while begin_pos 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 argv array.  Note also that all off‐
       sets  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.

       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_cmdline_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_cmd‐
       line_context_pos()  and  cfg_get_cfgfile_context_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_context_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 spec‐
       ifies  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.  Con‐
       text 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 informa‐
       tion about authors, homepage and license conditions.

libcfg+ 0.6.2                                  17 February 2004                                 CFG_CONTEXT(3)