Name

Synopsis

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

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.

Return Value

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

Table of Contents

• Name
• Synopsis
• Description
• Return Value
• Example
• Errors
• See Also