LC_REGISTER_CALLBACK(3)                 LC_REGISTER_CALLBACK(3)





NAME
       lc_register_callback  - Register a function for callback
       in config processing.


SYNOPSIS
       #include <libconfig.h>

       int  lc_register_callback(const  char  *var,  char  opt,
       lc_var_type_t  type, int (*callback)(const char *, const
       char *, const char *, const char *, lc_flags_t, void *),
       void *extra);


DESCRIPTION
       The  lc_register_callback(3)  function registers a func-
       tion to be called when var is encounted in a  configura-
       tion  file,  command line, or environment variable.  The
       parameters are as follows:

       const char *var
              The var parameter indicates the name of the vari-
              able  to register for a callback when encountered
              in a configuration file, the environment, or as a
              long  option.   The var may be prefixed with "*."
              to indicate that the object can occur in any sec-
              tion or subsection.


       const char opt
              The  opt parameter indicates the single charectar
              short option to use  from  the  command  line  to
              invoke the register callback.  A value of 0 indi-
              cates that no short option is acceptable.


       lc_var_type_t type
              The type parameter indicates the type  of  values
              that  are  acceptable for this callback.  A value
              of LC_VAR_NONE means that the command will accept
              no  arguments,  while  a  value of LC_VAR_UNKNOWN
              indicates that it's not known whether or  not  an
              argument  is  applicable,  this will also disable
              command line processing.  Any other value is cur-
              rently ignored.


       int (*callback)(...)
              The  callback parameter indicates the name of the
              function to invoke when the above parameters  are
              met.  The specified function should take 6 param-
              eters, see  below  for  more  information.   This
              value may not be NULL.


       void *extra
              The extra parameter is a pointer that can be used
              to pass data to the callback upon invocation,  it
              will  not be mangled or examined by any function.

       The arguments to the function specified as callback  are
       as follows:

       const char *shortvar
              The  shortvar  parameter  is  the  local variable
              name, provided as a convience.  It is the portion
              of the variable name after the first "dot" (.) in
              the fully qualified variable name.  The "dot" (.)
              value  in the fully qualified variable name indi-
              cates a section or subsection that  the  variable
              belongs  to.  This may be NULL if the var parame-
              ter to lc_register_callback(3) was NULL too.

       const char *var
              The var parameter is the fully qualified variable
              name.  It includes in the prefix any sections and
              subsections that contain this variable.  This may
              be NULL if the var parameter to lc_register_call-
              back(3) was NULL too.

       const char *arguments
              The arguments parameter  provides  the  arguments
              passed  to  the variable, currently only sections
              may have arguments.  This may be  NULL  if  there
              were no arguments specified, or if arguments were
              not applicable.

       const char *value
              The value parameter provides  the  value  of  the
              variable specified.  This may be NULL if no value
              was specified.  Values are required if  the  type
              parameter   to  lc_register_callback(3)  was  not
              specified as one of LC_VAR_NONE,  LC_VAR_SECTION,
              LC_VAR_SECTIONSTART, or LC_VAR_SECTIONEND.

       lc_flags_t flags
              The  flags  parameter  provides information about
              the type of command being called.  The valid val-
              ues are:

              LC_FLAGS_VAR
                     To  indicate  a regular variable in a con-
                     figuration file.

              LC_FLAGS_CMDLINE
                     To indicate a command line option has been
                     used to invoke this option.

              LC_FLAGS_SECTIONSTART
                     To  indicate  that this command represents
                     the beginning of a section.

              LC_FLAGS_SECTIONEND
                     To indicate that this  command  represents
                     the end of a section.

       void *extra
              The  extra  parameter is just a copy of the extra
              parameter passed to lc_register_callback(3)  when
              the callback was registered.

       The callback function should return one of three values:

       LC_CBRET_IGNORESECTION
              Returning LC_CBRET_IGNORESECTION from a  callback
              that  begins  a section causes the entire section
              to be ignored without generating an error.

       LC_CBRET_OKAY
              Returning LC_CBRET_OKAY from a callback indicates
              that  all  went  well  and further processing may
              continue.

       LC_CBRET_ERROR
              Returnning LC_CBRET_ERROR from a  callback  indi-
              cates  that  the  command failed for some reason,
              the error will be passed back down the chain back
              to  the  lc_process(3) call that began processing
              the configuration  data.   If  LC_CBRET_ERROR  is
              returned  from  a callback that begins a section,
              the entire section is ignored.



RETURN VALUE
       On success 0 is returned, otherwise -1 is returned.


EXAMPLE
       #include <libconfig.h>
       #include <strings.h>
       #include <stdlib.h>
       #include <stdio.h>

       int callback_ifmodule(const char *shortvar, const char *var,
                             const char *arguments, const char *value,
                             lc_flags_t flags, void *extra) {
            if (flags == LC_FLAGS_SECTIONEND) {
                 return(LC_CBRET_OKAY);
            }

            if (flags != LC_FLAGS_SECTIONSTART) {
                 fprintf(stderr, "IfModule can only be used as a \
                         section.\n");
                 return(LC_CBRET_ERROR);
            }
            if (arguments == NULL) {
                 fprintf(stderr, "You must specify an argument to \
                         IfModule.\n");
                 return(LC_CBRET_ERROR);
            }

            printf("IfModule %s\n", arguments);

            if (strcasecmp(arguments, "MyModule") == 0) {
                 return(LC_CBRET_IGNORESECTION);
            }

            return(LC_CBRET_OKAY);
       }

       int main(int argc, char **argv) {
            int lc_rc_ret = 0, lc_p_ret;

            lc_rc_ret = lc_register_callback("*.IfModule", 0, LC_VAR_NONE,
                                             callback_ifmodule, NULL);

            if (lc_rc_ret != 0) {
                 fprintf(stderr, "Error registering callback.\n");
                 return(EXIT_FAILURE);
            }

            lc_p_ret = lc_process(argc, argv, "example", LC_CONF_APACHE,
                                  NULL);

            lc_cleanup();

            if (lc_p_ret != 0) {
                 fprintf(stderr, "Error processing configuration: \
                         %s\n", lc_geterrstr());
                 return(EXIT_FAILURE);
            }

            return(EXIT_SUCCESS);
       }


ERRORS
       ENOMEM Memory could  not  be  allocated  to  create  the
              needed internal structures.


SEE ALSO
       lc_register_var(3),   lc_geterrno(3),   lc_geterrstr(3),
       lc_cleanup(3), lc_process_file(3), lc_process(3)



libconfig 0.1.16           25 Oct 04    LC_REGISTER_CALLBACK(3)
