econf_readFile - parse a configuration file

NAME SYNOPSIS DESCRIPTION RETURN VALUE ERRORS EXAMPLE APPLICATION USAGE SEE ALSO

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);

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.