ECONF_READCONFIGWITHCALLBACK(3)

NAME
econf_readConfigWithCallback - evaluate configuration files for a specific project

SYNOPSIS

#include <libeconf.h>

econf_err econf_readConfigWithCallback(econf_file **key_file, const char *project, const char *usr_subdir, const char *config_name, const char *config_suffix, const char *delim, const char *comment, bool (*callback)(const char *filename, const void *data), const void *callback_data);

DESCRIPTION

econf_readConfigWithCallback evaluats key/values of a given configuration by reading and merging all needed/available files from different directories. Order is:

   /etc/project/config_name.config_suffix does exist:

     * /etc/project/config_name.config_suffix
     * usr_subdir/project/config_name.config_suffix.d/*.config_suffix
     * /run/project/config_name.config_suffix.d/*.config_suffix
     * /etc/project/config_name.config_suffix.d/*.config_suffix

   /etc/project/config_name.config_suffix does NOT exist:

     /run/project/config_name.config_suffix does exist:

       * /run/project/config_name.config_suffix
       * usr_subdir/project/config_name.config_suffix.d/*.config_suffix
       * /run/project/config_name.config_suffix.d/*.config_suffix
       * /etc/project/config_name.config_suffix.d/*.config_suffix

     /run/project/config_name.config_suffix does NOT exist:

       * usr_subdir/project/config_name.config_suffix
       * usr_subdir/project/config_name.config_suffix.d/*.config_suffix
       * /run/project/config_name.config_suffix.d/*.config_suffix
       * /etc/project/config_name.config_suffix.d/*.config_suffix

   No main config_name.config_suffix file is defined or must not be parsed:

     * usr_subdir/project.d/*.config_suffix
     * /run/project.d/*.config_suffix
     * /etc/project.d/*.config_suffix

For each parsed file the user defined function callback will be called in order e.g. to check the correct file permissions. This user defined function has the pathname as parameter and returns true if this file can be parsed. If not, the parsing of all files will be aborted and ECONF_PARSING_CALLBACK_FAILED will be returned.

callback_data is a pointer which will be given to the callback function.

project name of the project used as subdirectory, can be NULL.

If config_name is NULL, drop-ins without a main configuration file will be parsed only.

config_suffix can also be NULL.

The delim parameter specifies the character used to separate keys from values (e.g., "="). If delim contains space characters AND none space characters, multiline values are not parseable. The comment parameter specifies an array of characters which define the start of a comment (e.g., "#").

The parsed and merged configuration is stored in a newly allocated econf_file structure, which is returned via the key_file pointer.

RETURN VALUE

On success, econf_readConfigWithCallback returns ECONF_SUCCESS.

On failure, a specific error code is returned as defined in econf_err.

ERRORS

ECONF_NOFILE
              The specified file_name does not exist.

ECONF_NOMEM
              Insufficient memory to allocate the result structure.

ECONF_MISSING_BRACKET
ECONF_TEXT_AFTER_SECTION
ECONF_EMPTY_SECTION_NAME
ECONF_MISSING_DELIMITER
              The file contains syntax errors and could not be parsed successfully.

ECONF_PARSING_CALLBACK_FAILED
              The user-provided callback returned false, aborting the operation.

ECONF_ARGUMENT_IS_NULL_VALUE
              One of the required arguments (such as result or file_name) is NULL.

EXAMPLE

Reading content in different cases in following order:

   /etc/foo/example.conf does exist:

     * /etc/foo/example.conf
     * /usr/lib/foo/example.conf.d/ *.conf
     * /run/foo/example.conf.d/ *.conf
     * /etc/foo/example.conf.d/ *.conf

   /etc/foo/example.conf does NOT exist:

     /run/foo/example.conf does exist:

       */run/foo/example.conf
       * /usr/lib/foo/example.conf.d/ *.conf
       * /run/foo/example.conf.d/ *.conf
       * /etc/foo/example.conf.d/ *.conf

     /run/foo/example.conf does NOT exist:

       * /usr/lib/foo/example.conf
       * /usr/lib/foo/example.conf.d/ *.conf
       * /run/foo/example.conf.d/ *.conf
       * /etc/foo/example.conf.d/ *.conf

    #include <libeconf.h>
    #include <stdio.h>

    bool checkFile(const char *filename, const void *data) {
      /* checking code which returns true or false */
      return true;
    }

    int main(void) {
         econf_file *conf = NULL;
         econf_err err;

         /*
          * Reading
          */
         err = econf_readConfigWithCallback(&conf,
                                "foo",                 /* project name */
                                "/usr/lib",            /* vendor directory */
                                "example",             /* config name */
                                "conf",                /* suffix */
                                "=",                   /* delimiter */
                                "#",                   /* comment */
                                checkFile,             /* callback */
                                NULL);                 /* no data for callback */

         if (err != ECONF_SUCCESS) {
             fprintf(stderr, "Failed to read config: %d\n", err);
             return 1;
         }

         /* Use econf_get... functions here to access values */

         econf_free(conf);
         return 0;
    }

SEE ALSO

libeconf(3), econf_readConfig(3), econf_free(3), econf_errString(3).