Changes To Manual for lc_register_callback
            1  +<H2>NAME</H2>
            2  +lc_register_callback - Register a function for callback in config processing.
            3  +<P>
            4  +<A NAME="lbAC">&nbsp;</A>
            5  +<H2>SYNOPSIS</H2>
            6  +<B>#include &lt;<A HREF="artifact/7c61a9805e664fde7943807af8d5e164e7cebdb6">libconfig.h</A>&gt;</B>
            7  +<P>
            8  +<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>
            9  +<P>
           10  +<A NAME="lbAD">&nbsp;</A>
           11  +<H2>DESCRIPTION</H2>
           12  +The
           13  +<B><A HREF="wiki/Manual for lc_register_callback">lc_register_callback</A></B>(3)
           14  +function registers a function to be called when
           15  +<I>var</I>
           16  +is encounted in a configuration file, command line, or environment variable.
           17  +The parameters are as follows:
           18  +<DL COMPACT>
           19  +<DT><I>const char *var</I>
           20  +<DD>
           21  +<DL COMPACT><DT><DD>
           22  +The
           23  +<I>var</I>
           24  +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
           25  +<I>var</I>
           26  +may be prefixed with &quot;*.&quot; to indicate that the object can occur in any section or subsection.
           27  +</DL>
           28  +<P>
           29  +<DT><I>const char opt</I>
           30  +<DD>
           31  +<DL COMPACT><DT><DD>
           32  +The
           33  +<I>opt</I>
           34  +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.
           35  +</DL>
           36  +<P>
           37  +<DT><I>lc_var_type_t type</I>
           38  +<DD>
           39  +<DL COMPACT><DT><DD>
           40  +The
           41  +<I>type</I>
           42  +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.
           43  +</DL>
           44  +<P>
           45  +<DT><I>int (*callback)(...)</I>
           46  +<DD>
           47  +<DL COMPACT><DT><DD>
           48  +The
           49  +<I>callback</I>
           50  +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.
           51  +</DL>
           52  +<P>
           53  +<DT><I>void *extra</I>
           54  +<DD>
           55  +<DL COMPACT><DT><DD>
           56  +The
           57  +<I>extra</I>
           58  +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.
           59  +</DL>
           60  +<P>
           61  +The arguments to the function specified as
           62  +<I>callback</I>
           63  +are as follows:
           64  +<DT><I>const char *shortvar</I>
           65  +<DD>
           66  +<DL COMPACT><DT><DD>
           67  +The
           68  +<I>shortvar</I>
           69  +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.
           70  +This may be
           71  +<B>NULL</B>
           72  +if the
           73  +<I>var</I>
           74  +parameter to
           75  +<B><A HREF="wiki/Manual for lc_register_callback">lc_register_callback</A></B>(3)
           76  +was
           77  +<B>NULL</B>
           78  +too.
           79  +</DL>
           80  +<DT><I>const char *var</I>
           81  +<DD>
           82  +<DL COMPACT><DT><DD>
           83  +The
           84  +<I>var</I>
           85  +parameter is the fully qualified variable name.  It includes in the prefix any sections and subsections that contain this variable.
           86  +This may be
           87  +<B>NULL</B>
           88  +if the
           89  +<I>var</I>
           90  +parameter to
           91  +<B><A HREF="wiki/Manual for lc_register_callback">lc_register_callback</A></B>(3)
           92  +was
           93  +<B>NULL</B>
           94  +too.
           95  +</DL>
           96  +<DT><I>const char *arguments</I>
           97  +<DD>
           98  +<DL COMPACT><DT><DD>
           99  +The
          100  +<I>arguments</I>
          101  +parameter provides the arguments passed to the variable, currently only sections may have arguments.
          102  +This may be
          103  +<B>NULL</B>
          104  +if there were no arguments specified, or if arguments were not applicable.
          105  +</DL>
          106  +<DT><I>const char *value</I>
          107  +<DD>
          108  +<DL COMPACT><DT><DD>
          109  +The
          110  +<I>value</I>
          111  +parameter provides the value of the variable specified.
          112  +This may be
          113  +<B>NULL</B>
          114  +if no value was specified.  Values are required if the
          115  +<I>type</I>
          116  +parameter to
          117  +<B><A HREF="wiki/Manual for lc_register_callback">lc_register_callback</A></B>(3)
          118  +was not specified as one of LC_VAR_NONE, LC_VAR_SECTION, LC_VAR_SECTIONSTART, or LC_VAR_SECTIONEND.
          119  +</DL>
          120  +<DT><I>lc_flags_t flags</I>
          121  +<DD>
          122  +<DL COMPACT><DT><DD>
          123  +The flags parameter provides information about the type of command being called.  The valid values are:
          124  +<DL COMPACT>
          125  +<DT>LC_FLAGS_VAR<DD>
          126  +To indicate a regular variable in a configuration file.
          127  +<DT>LC_FLAGS_CMDLINE<DD>
          128  +To indicate a command line option has been used to invoke this option.
          129  +<DT>LC_FLAGS_SECTIONSTART<DD>
          130  +To indicate that this command represents the beginning of a section.
          131  +<DT>LC_FLAGS_SECTIONEND<DD>
          132  +To indicate that this command represents the end of a section.
          133  +</DL>
          134  +</DL>
          135  +<DT><I>void *extra</I>
          136  +<DD>
          137  +<DL COMPACT><DT><DD>
          138  +The
          139  +<I>extra</I>
          140  +parameter is just a copy of the
          141  +<I>extra</I>
          142  +parameter passed to
          143  +<B><A HREF="wiki/Manual for lc_register_callback">lc_register_callback</A></B>(3)
          144  +when the callback was registered.
          145  +</DL>
          146  +<P>
          147  +The
          148  +<I>callback</I>
          149  +function should return one of three values:
          150  +<DT>LC_CBRET_IGNORESECTION<DD>
          151  +Returning LC_CBRET_IGNORESECTION from a callback that begins a section causes the entire section to be ignored without generating an error.
          152  +<DT>LC_CBRET_OKAY<DD>
          153  +Returning LC_CBRET_OKAY from a callback indicates that all went well and further processing may continue.
          154  +<DT>LC_CBRET_ERROR<DD>
          155  +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
          156  +<B><A HREF="wiki/Manual for lc_process">lc_process</A></B>(3)
          157  +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.
          158  +<P>
          159  +<P>
          160  +</DL>
          161  +<A NAME="lbAE">&nbsp;</A>
          162  +<H2>RETURN VALUE</H2>
          163  +On success 0 is returned, otherwise -1 is returned.
          164  +<P>
          165  +<A NAME="lbAF">&nbsp;</A>
          166  +<H2>EXAMPLE</H2>
          167  +<PRE>
          168  +#include &lt;<A HREF="artifact/7c61a9805e664fde7943807af8d5e164e7cebdb6">libconfig.h</A>&gt;
          169  +#include &lt;<A HREF="file:/usr/include/strings.h">strings.h</A>&gt;
          170  +#include &lt;<A HREF="file:/usr/include/stdlib.h">stdlib.h</A>&gt;
          171  +#include &lt;<A HREF="file:/usr/include/stdio.h">stdio.h</A>&gt;
          172  +int callback_ifmodule(const char *shortvar, const char *var,
          173  +                      const char *arguments, const char *value,
          174  +                      lc_flags_t flags, void *extra) {
          175  +        if (flags == LC_FLAGS_SECTIONEND) {
          176  +                return(LC_CBRET_OKAY);
          177  +        }
          178  +        if (arguments == NULL) {
          179  +                lc_seterrstr(&quot;You must specify an argument to \
          180  +                              IfModule.&quot;);
          181  +                return(LC_CBRET_ERROR);
          182  +        }
          183  +        printf(&quot;IfModule %s\n&quot;, arguments);
          184  +        if (strcasecmp(arguments, &quot;MyModule&quot;) == 0) {
          185  +                return(LC_CBRET_IGNORESECTION);
          186  +        }
          187  +        return(LC_CBRET_OKAY);
          188  +}
          189  +int main(int argc, char **argv) {
          190  +        int lc_rc_ret, lc_p_ret;
          191  +        lc_rc_ret = lc_register_callback(&quot;*.IfModule&quot;, 0, LC_VAR_SECTION,
          192  +                                         callback_ifmodule, NULL);
          193  +        if (lc_rc_ret != 0) {
          194  +                fprintf(stderr, &quot;Error registering callback.\n&quot;);
          195  +                return(EXIT_FAILURE);
          196  +        }
          197  +        lc_p_ret = lc_process(argc, argv, &quot;example&quot;, LC_CONF_APACHE,
          198  +                              NULL);
          199  +        lc_cleanup();
          200  +        if (lc_p_ret != 0) {
          201  +                fprintf(stderr, &quot;Error processing configuration: \
          202  +                        %s\n&quot;, lc_geterrstr());
          203  +                return(EXIT_FAILURE);
          204  +        }
          205  +        return(EXIT_SUCCESS);
          206  +}
          207  +</PRE>
          208  +<P>
          209  +<A NAME="lbAG">&nbsp;</A>
          210  +<H2>ERRORS</H2>
          211  +<DL COMPACT>
          212  +<DT><B>ENOMEM</B>
          213  +<DD>
          214  +Memory could not be allocated to create the needed internal structures.
          215  +<P>
          216  +</DL>
          217  +<A NAME="lbAH">&nbsp;</A>
          218  +<H2>SEE ALSO</H2>
          219  +<B><A HREF="wiki/Manual">libconfig</A></B>(3),
          220  +<B><A HREF="wiki/Manual for lc_register_var">lc_register_var</A></B>(3),
          221  +<B><A HREF="wiki/Manual for lc_geterrno">lc_geterrno</A></B>(3),
          222  +<B><A HREF="wiki/Manual for lc_geterrstr">lc_geterrstr</A></B>(3),
          223  +<B><A HREF="wiki/Manual for lc_seterrstr">lc_seterrstr</A></B>(3),
          224  +<B><A HREF="wiki/Manual for lc_handle_type">lc_handle_type</A></B>(3),
          225  +<B><A HREF="wiki/Manual for lc_process">lc_process</A></B>(3),
          226  +<B><A HREF="wiki/Manual for lc_process_file">lc_process_file</A></B>(3),
          227  +<B><A HREF="wiki/Manual for lc_cleanup">lc_cleanup</A></B>(3)
          228  +<P>