@@ -0,0 +1,229 @@ +.TH LC_REGISTER_CALLBACK 3 "25 Oct 04" "@PACKAGE_STRING@" +.SH NAME +lc_register_callback \- Register a function for callback in config processing. + +.SH SYNOPSIS +.B #include +.sp +.BI "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); + +.SH DESCRIPTION +The +.B lc_register_callback +function registers a function to be called when +.IR var +is encounted in a configuration file, command line, or environment variable. +The parameters are as follows: +.TP +.IR "const char *var" +.RS +The +.IR var +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 +.IR var +may be prefixed with "*." to indicate that the object can occur in any section or subsection. +.RE + +.TP +.IR "const char opt" +.RS +The +.IR opt +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. +.RE + +.TP +.IR "lc_var_type_t type" +.RS +The +.IR type +parameter indicates the type of values that are acceptable for this callback. Currently only LC_VAR_NONE is acceptable, since callbacks may not have values (though they may have arguments). +.RE + +.TP +.IR "int (*callback)(...)" +.RS +The +.IR callback +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. +.RE + +.TP +.IR "void *extra" +.RS +The +.IR 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. +.RE + +The arguments to the function specified as +.IR callback +are as follows: +.TP +.I "const char *shortvar" +.RS +The +.I 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 indicates a section or subsection that the variable belongs to. +This may be +.B NULL +if the +.IR var +parameter to +.BI lc_register_callback (3) +was +.B NULL +too. +.RE +.TP +.I "const char *var" +.RS +The +.I var +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 +if the +.IR var +parameter to +.BI lc_register_callback (3) +was +.B NULL +too. +.RE +.TP +.I "const char *arguments" +.RS +The +.I arguments +parameter provides the arguments passed to the variable, currently only sections may have arguments. +This may be +.B NULL +if there were no arguments specified, or if arguments were not applicable. +.RE +.TP +.I "const char *value" +.RS +The +.I value +parameter provides the value of the variable specified. +This may be +.B NULL +if no value was specified. Values are required if the +.IR type +parameter to +.BI lc_register_callback (3) +was not specified as one of LC_VAR_NONE, LC_VAR_SECTION, LC_VAR_SECTIONSTART, or LC_VAR_SECTIONEND. +.RE +.TP +.I "lc_flags_t flags" +.RS +The flags parameter provides information about the type of command being called. The valid values are: +.IP LC_FLAGS_VAR +To indicate a regular variable in a configuration file. +.IP LC_FLAGS_CMDLINE +To indicate a command line option has been used to invoke this option. +.IP LC_FLAGS_SECTIONSTART +To indicate that this command represents the beginning of a section. +.IP LC_FLAGS_SECTIONEND +To indicate that this command represents the end of a section. +.RE +.TP +.I "void *extra" +.RS +The +.I extra +parameter is just a copy of the +.IR extra +parameter passed to +.BI lc_register_callback (3) +when the callback was registered. +.RE + +The +.IR callback +function should return one of three values: +.TP +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. +.TP +LC_CBRET_OKAY +Returning LC_CBRET_OKAY from a callback indicates that all went well and further processing may continue. +.TP +LC_CBRET_ERROR +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 +.BI 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. + +.SH EXAMPLE +.nf +#include +#include +#include +#include + +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); + if (lc_p_ret != 0) { + fprintf(stderr, "Error processing configuration: \\ + %s\\n", lc_geterrstr()); + return(EXIT_FAILURE); + } + + return(EXIT_SUCCESS); +} +.fi + +.SH ERRORS +.TP +.B ENOMEM +Memory could not be allocated to create the needed internal structures. + +.SH "SEE ALSO" +.BR lc_register_var (3), +.BR lc_geterrno (3), +.BR lc_geterrstr (3), +.BR lc_process (3), +.BR lc_register_var (3)