<H2>NAME</H2>
lc_register_callback - Register a function for callback in config processing.
<P>
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>
<B>#include &lt;<A HREF="artifact/7c61a9805e664fde7943807af8d5e164e7cebdb6">libconfig.h</A>&gt;</B>
<P>
<B>int lc_register_callback(const char *</B><I>var</I><B>, char </B><I>opt</I><B>, lc_var_type_t </B><I>type</I><B>, int (*</B><I>callback</I><B>)(const char *, const char *, const char *, const char *, lc_flags_t, void *), void *</B><I>extra</I><B>);</B>
<P>
<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>
The
<B><A HREF="wiki/Manual for lc_register_callback">lc_register_callback</A></B>(3)
function registers a function to be called when
<I>var</I>
is encounted in a configuration file, command line, or environment variable.
The parameters are as follows:
<DL COMPACT>
<DT><I>const char *var</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>var</I>
parameter indicates the name of the variable to register for a callback when encountered in a configuration file, the environment, or as a long option.  The
<I>var</I>
may be prefixed with &quot;*.&quot; to indicate that the object can occur in any section or subsection.
</DL>
<P>
<DT><I>const char opt</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>opt</I>
parameter indicates the single charectar short option to use from the command line to invoke the register callback.  A value of 0 indicates that no short option is acceptable.
</DL>
<P>
<DT><I>lc_var_type_t type</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>type</I>
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 currently ignored.
</DL>
<P>
<DT><I>int (*callback)(...)</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>callback</I>
parameter indicates the name of the function to invoke when the above parameters are met.  The specified function should take 6 parameters, see below for more information.  This value may not be NULL.
</DL>
<P>
<DT><I>void *extra</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>extra</I>
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.
</DL>
<P>
The arguments to the function specified as
<I>callback</I>
are as follows:
<DT><I>const char *shortvar</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>shortvar</I>
parameter is the local variable name, provided as a convience.  It is the portion of the variable name after the first &quot;dot&quot; (.) in the fully qualified variable name.  The &quot;dot&quot; (.) value in the fully qualified variable name indicates a section or subsection that the variable belongs to.
This may be
<B>NULL</B>
if the
<I>var</I>
parameter to
<B><A HREF="wiki/Manual for lc_register_callback">lc_register_callback</A></B>(3)
was
<B>NULL</B>
too.
</DL>
<DT><I>const char *var</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>var</I>
parameter is the fully qualified variable name.  It includes in the prefix any sections and subsections that contain this variable.
This may be
<B>NULL</B>
if the
<I>var</I>
parameter to
<B><A HREF="wiki/Manual for lc_register_callback">lc_register_callback</A></B>(3)
was
<B>NULL</B>
too.
</DL>
<DT><I>const char *arguments</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>arguments</I>
parameter provides the arguments passed to the variable, currently only sections may have arguments.
This may be
<B>NULL</B>
if there were no arguments specified, or if arguments were not applicable.
</DL>
<DT><I>const char *value</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>value</I>
parameter provides the value of the variable specified.
This may be
<B>NULL</B>
if no value was specified.  Values are required if the
<I>type</I>
parameter to
<B><A HREF="wiki/Manual for lc_register_callback">lc_register_callback</A></B>(3)
was not specified as one of LC_VAR_NONE, LC_VAR_SECTION, LC_VAR_SECTIONSTART, or LC_VAR_SECTIONEND.
</DL>
<DT><I>lc_flags_t flags</I>
<DD>
<DL COMPACT><DT><DD>
The flags parameter provides information about the type of command being called.  The valid values are:
<DL COMPACT>
<DT>LC_FLAGS_VAR<DD>
To indicate a regular variable in a configuration file.
<DT>LC_FLAGS_CMDLINE<DD>
To indicate a command line option has been used to invoke this option.
<DT>LC_FLAGS_SECTIONSTART<DD>
To indicate that this command represents the beginning of a section.
<DT>LC_FLAGS_SECTIONEND<DD>
To indicate that this command represents the end of a section.
</DL>
</DL>
<DT><I>void *extra</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>extra</I>
parameter is just a copy of the
<I>extra</I>
parameter passed to
<B><A HREF="wiki/Manual for lc_register_callback">lc_register_callback</A></B>(3)
when the callback was registered.
</DL>
<P>
The
<I>callback</I>
function should return one of three values:
<DT>LC_CBRET_IGNORESECTION<DD>
Returning LC_CBRET_IGNORESECTION from a callback that begins a section causes the entire section to be ignored without generating an error.
<DT>LC_CBRET_OKAY<DD>
Returning LC_CBRET_OKAY from a callback indicates that all went well and further processing may continue.
<DT>LC_CBRET_ERROR<DD>
Returnning LC_CBRET_ERROR from a callback indicates that the command failed for some reason, the error will be passed back down the chain back to the
<B><A HREF="wiki/Manual for lc_process">lc_process</A></B>(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.  If LC_CBRET_ERROR is returned from a callback that ends a section, the error is ignored.
<P>
<P>
</DL>
<A NAME="lbAE">&nbsp;</A>
<H2>RETURN VALUE</H2>
On success 0 is returned, otherwise -1 is returned.
<P>
<A NAME="lbAF">&nbsp;</A>
<H2>EXAMPLE</H2>
<PRE>
#include &lt;<A HREF="artifact/7c61a9805e664fde7943807af8d5e164e7cebdb6">libconfig.h</A>&gt;
#include &lt;<A HREF="file:/usr/include/strings.h">strings.h</A>&gt;
#include &lt;<A HREF="file:/usr/include/stdlib.h">stdlib.h</A>&gt;
#include &lt;<A HREF="file:/usr/include/stdio.h">stdio.h</A>&gt;
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 (arguments == NULL) {
                lc_seterrstr(&quot;You must specify an argument to \
                              IfModule.&quot;);
                return(LC_CBRET_ERROR);
        }
        printf(&quot;IfModule %s\n&quot;, arguments);
        if (strcasecmp(arguments, &quot;MyModule&quot;) == 0) {
                return(LC_CBRET_IGNORESECTION);
        }
        return(LC_CBRET_OKAY);
}
int main(int argc, char **argv) {
        int lc_rc_ret, lc_p_ret;
        lc_rc_ret = lc_register_callback(&quot;*.IfModule&quot;, 0, LC_VAR_SECTION,
                                         callback_ifmodule, NULL);
        if (lc_rc_ret != 0) {
                fprintf(stderr, &quot;Error registering callback.\n&quot;);
                return(EXIT_FAILURE);
        }
        lc_p_ret = lc_process(argc, argv, &quot;example&quot;, LC_CONF_APACHE,
                              NULL);
        lc_cleanup();
        if (lc_p_ret != 0) {
                fprintf(stderr, &quot;Error processing configuration: \
                        %s\n&quot;, lc_geterrstr());
                return(EXIT_FAILURE);
        }
        return(EXIT_SUCCESS);
}
</PRE>
<P>
<A NAME="lbAG">&nbsp;</A>
<H2>ERRORS</H2>
<DL COMPACT>
<DT><B>ENOMEM</B>
<DD>
Memory could not be allocated to create the needed internal structures.
<P>
</DL>
<A NAME="lbAH">&nbsp;</A>
<H2>SEE ALSO</H2>
<B><A HREF="wiki/Manual">libconfig</A></B>(3),
<B><A HREF="wiki/Manual for lc_register_var">lc_register_var</A></B>(3),
<B><A HREF="wiki/Manual for lc_geterrno">lc_geterrno</A></B>(3),
<B><A HREF="wiki/Manual for lc_geterrstr">lc_geterrstr</A></B>(3),
<B><A HREF="wiki/Manual for lc_seterrstr">lc_seterrstr</A></B>(3),
<B><A HREF="wiki/Manual for lc_handle_type">lc_handle_type</A></B>(3),
<B><A HREF="wiki/Manual for lc_process">lc_process</A></B>(3),
<B><A HREF="wiki/Manual for lc_process_file">lc_process_file</A></B>(3),
<B><A HREF="wiki/Manual for lc_cleanup">lc_cleanup</A></B>(3)
<P>