libconfig: Manual for lc_register

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 function to be called when var is encounted in a configuration file, command line, or environment variable. The parameters are as follows:

const char *var

: The 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 var may be prefixed with "*." to indicate that the object can occur in any section 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 indicates 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 currently 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 parameters, 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 indicates a section or subsection that the variable belongs to. This may be NULL if the var parameter 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_callback(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 values are:

LC_FLAGS_VAR: To indicate a regular variable in a configuration 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 indicates 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. If LC_CBRET_ERROR is returned from a callback that ends a section, the error 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 (arguments == NULL) {
                lc_seterrstr("You must specify an argument to \
                              IfModule.");
                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, lc_p_ret;
        lc_rc_ret = lc_register_callback("*.IfModule", 0, LC_VAR_SECTION,
                                         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