ECONF_READFILE(3)

NAME
econf_readFile - parse a configuration file

SYNOPSIS

#include <libeconf.h>

econf_err econf_readFile(econf_file **result, const char *file_name, const char *delim, const char *comment);

DESCRIPTION

econf_readFile reads and parses the configuration file specified by file_name. The function allocates a new econf_file object, populates it with the parsed data, and stores a pointer to it in result.

The delim argument specifies the character (or characters) used to separate keys from values (e.g., "=" or ":"). The comment argument specifies the character that introduces a comment (e.g., "#" or ";"). Lines starting with this character are ignored during parsing.

The caller is responsible for freeing the allocated memory by calling econf_free on result when it is no longer needed.

RETURN VALUE

On success, econf_readFile returns ECONF_SUCCESS.

On failure, a non-zero error code of type econf_err is returned.

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_ARGUMENT_IS_NULL_VALUE
              One of the required arguments (such as result or file_name) is NULL.

EXAMPLE

The following example demonstrates how to read a simple configuration file:

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

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

              /* Read file with "=" as delimiter and "#" as comment */
              err = econf_readFile(&conf, "/etc/example.conf", "=", "#");

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

              /* ... Process configuration ... */

              econf_free(conf);
              return 0;
          }

APPLICATION USAGE

Default behaviour if entries have the same name in one file: The first hit will be returned. Further entries will be ignored. This can be changed by setting the environment variable JOIN_SAME_ENTRIES (see econf_set_opt). In that case entries with the same name will be joined to one single entry. Keys have to be unique per section. Otherwise the behaviour is undefined.

SEE ALSO

libeconf(3), econf_free(3), econf_writeFile(3), econf_errString(3) econf_set_opt(3).