conf.c File Reference

Source for Configuration File Library (CEL). More...

#include <stddef.h>
#include <stdio.h>
#include <ctype.h>
#include <string.h>
#include <stdlib.h>
#include <errno.h>
#include "cbl/assert.h"
#include "cbl/memory.h"
#include "cdsl/hash.h"
#include "cdsl/table.h"
#include "conf.h"

Include dependency graph for conf.c:


Data Structures

struct  valnode_t

Defines

#define BUFLEN   80
#define VALID_CHR(c)   (isalpha(c) || isdigit(c) || (c) == '_')

Functions

int() conf_preset (const conf_t *tab, int ctrl)
 constructs a default set for configuration variables.
size_t() conf_init (FILE *fp, int ctrl)
 reads a configuration file and constructs the configuration data.
const void * conf_conv (const char *val, int type)
 converts a string based on a type.
const void *() conf_get (const char *var)
 retrieves a value with a section/variable name.
int() conf_getbool (const char *var, int errval)
 retrieves a boolean value with a section/variable name.
long() conf_getint (const char *var, long errval)
 retrieves an integral value with a section/variable name.
unsigned long() conf_getuint (const char *var, unsigned long errval)
 retrieves an unsigned integral value with a section/variable name.
double() conf_getreal (const char *var, double errval)
 retrieves a real value with a section/variable name.
const char *() conf_getstr (const char *var)
 retrieves a string with a section/variable name.
int() conf_set (const char *secvar, const char *value)
 inserts or replaces a value associated with a variable.
int() conf_section (const char *sec)
 sets the current section.
void() conf_free (void)
 deallocates the stroage for the configuration data.
void() conf_hashreset (void)
 resets the hash table using hash_reset().
int() conf_errcode (void)
 returns an error code.
const char *() conf_errstr (int code)
 returns an error message.

Detailed Description

Source for Configuration File Library (CEL).


Function Documentation

const void* conf_conv ( const char *  val,
int  type 
)

converts a string based on a type.

conf_conv() converts a string to an integer or floating-point number as requested. type should be CONF_TYPE_BOOL (which recognizes some forms of boolean values), CONF_TYPE_INT (which indicates conversion to signed long int), CONT_TYPE_UINT (conversion to unsigned long int), CONF_TYPE_REAL (conversion to double) or CONF_TYPE_STR (no conversion necessary). The expected forms for CONF_TYPE_INT, CONF_TYPE_UINT and CONF_TYPE_REAL are respectively those for strtol(), strtoul() and strtod(). CONF_TYPE_BOOL gives 1 for a string starting with 't', 'T', 'y', 'Y', '1' and 0 for others. conf_conv() returns a pointer to the storage that contains the converted value (an integer, floating-point number or string) and its caller (user code) has to convert the pointer properly (to const int *, const long *, const unsigned long *, const double * and const char *) before use. If the conversion fails, conf_conv() returns a null pointer and sets CONF_ERR_TYPE as an error code.

Warning:
A subsequent call to conf_getbool(), conf_getint(), conf_getuint() and conf_getreal() may overwrite the contents of the buffer pointed by the resulting pointer. Similarly, a subsequent call to conf_conv() and conf_get() may overwrite the contents of the buffer pointed by the resulting pointer unless the type is CONF_TYPE_STR.
Parameters:
[in] val string to convert
[in] type type based on which conversion performed
Returns:
pointer to storage that contains result or null pointer
Return values:
non-null pointer to conversion result
NULL conversion failure

Here is the caller graph for this function:

int() conf_errcode ( void   ) 

returns an error code.

Every function in this library sets the internal error variable as it performs its operation. Unlike errno provided by <errno.h>, the error variable of this library is set to CONF_ERR_OK before starting an operation, thus a user code need not to clear it before calling a conf_ function.

When using a function returning an error code (of the int type), the returned value is the same as what conf_errcode() will return if there is no intervening call to a conf_ function between them. When using a function returning a pointer, the only way to get what the error has been occurred is to use conf_errcode().

The following code fragment shows an example for how to use conf_errcode() and conf_errstr():

      fp = fopen(conf, "r");
      if (!fp)
          fprintf(stderr, "%s:%s: %s\n", prg, conf, conf_errstr(CONF_ERR_FILE));
      line = conf_init(fp, CONF_OPT_CASE | CONF_OPT_ESC);
      if (line != 0)
          fprintf(stderr, "%s:%s:%lu: %s\n", prg, conf, line, conf_errstr(conf_errcode()));

Possible exceptions: none

Unchecked errors: none

Returns:
current error code

const char*() conf_errstr ( int  code  ) 

returns an error message.

conf_errstr() returns an error message for a given error code.

Possible exceptions: assert_exceptfail

Unchecked errors: none

Parameters:
[in] code error code for which error message returned
Returns:
error message

void() conf_free ( void   ) 

deallocates the stroage for the configuration data.

conf_free() deallocates storages for the configuration data. After conf_free() invoked, other conf_ functions should not be called without an intervening call to conf_preset() or conf_init().

Possible exceptions: assert_exceptfail

Unchecked errors: none

Warning:
conf_free() does not reset the hash table used internally since it may be used by other parts of the program. Invoking hash_reset() through conf_hashreset() before program termination cleans up storages occupied by the table.
Returns:
nothing

const void*() conf_get ( const char *  var  ) 

retrieves a value with a section/variable name.

conf_get() retrieves a value with a section/variable name.

In a program (e.g., when using conf_get()), variables can be referred to using one of the following forms:

      variable
      . variable
      section . variable

where whitespaces are optional before and after section and variable names. The first form refers to a variable belonging to the "current" section; the current section can be set by invoking conf_section(). The second form refers to a variable belonging to the global section. The last form refers to a variable belonging to a specific section.

Warning:
A subsequent call to conf_conv() and conf_get() may overwrite the contents of the buffer pointed by the resulting pointer unless the type is CONF_TYPE_STR. Similarly, a subsequent call to conf_getbool(), conf_getint(), conf_getuint() and conf_getreal() may overwrite the contents of the buffer pointed by the resulting pointer.
Possible exceptions: assert_exceptfail, mem_exceptfail

Unchecked errors: none

Parameters:
[in] var section/variable name
Returns:
pointer to storage that contains value or null pointer
Return values:
non-null value retrieved
NULL failure

Here is the call graph for this function:

int() conf_getbool ( const char *  var,
int  errval 
)

retrieves a boolean value with a section/variable name.

conf_getbool() retrieves a boolean value with a section/variable name. Every value for a variable is stored in a string form, and conf_getbool() converts it to a boolean value; the result is 1 (indicating true) if the string starts with 't', 'T', 'y', 'Y' or '1' ignoring any leading spaces and 0 (indicating false) otherwise. If there is no variable with the given name or the preset type of the variable is not CONF_TYPE_BOOL, the value of errval is returned.

For how to refer to variables in a program, see conf_get().

Possible exceptions: assert_exceptfail, mem_exceptfail

Unchecked errors: none

Parameters:
[in] var section/variable name
[in] errval value returned as error
Returns:
converted result or errval

Here is the call graph for this function:

long() conf_getint ( const char *  var,
long  errval 
)

retrieves an integral value with a section/variable name.

conf_getint() retrieves an integral value with a section/variable name. Every value for a variable is stored in a string form, and conf_getint() converts it to an integer using strtol() declared in <stdlib.h>. If there is no variable with the given name or the preset type of the variable is not CONF_TYPE_INT, the value of errval is returned.

For how to refer to variables in a program, see conf_get().

Possible exceptions: assert_exceptfail, mem_exceptfail

Unchecked errors: none

Parameters:
[in] var section/variable name
[in] errval value returned as error
Returns:
converted result or errval

Here is the call graph for this function:

double() conf_getreal ( const char *  var,
double  errval 
)

retrieves a real value with a section/variable name.

conf_getreal() retrieves a real value with a section/variable name. Every value for a variable is stored in a string form, and conf_getreal() converts it to a floating-point number using strtod() declared in <stdlib.h>. If there is no variable with the given name or the preset type of the variable is not CONF_TYPE_REAL, the value of errval is returned; HUGE_VAL defined <math.h> would be a nice choice for errval.

For how to refer to variables in a program, see conf_get().

Possible exceptions: assert_exceptfail, mem_exceptfail

Unchecked errors: none

Parameters:
[in] var section/variable name
[in] errval value returned as error
Returns:
converted result or errval

Here is the call graph for this function:

const char*() conf_getstr ( const char *  var  ) 

retrieves a string with a section/variable name.

conf_getstr() retrieves a string with a section/variable name. Every value for a variable is stored in a string form, thus conf_getstr() performs no conversion. If there is no variable with the given name or the preset type of the variable is not CONF_TYPE_STR, a null pointer is returned.

For how to refer to variables in a program, see conf_get().

Possible exceptions: assert_exceptfail, mem_exceptfail

Unchecked errors: none

Parameters:
[in] var section/variable name
Returns:
string or null pointer
Return values:
non-null string retrieved
NULL failure

Here is the call graph for this function:

unsigned long() conf_getuint ( const char *  var,
unsigned long  errval 
)

retrieves an unsigned integral value with a section/variable name.

conf_getuint() retrieves an unsigned integral value with a section/variable name. Every value for a variable is stored in a string form, and conf_getuint() converts it to an unsigned integer using strtoul() declared in <stdlib.h>. If there is no variable with the given name or the preset type of the variable is not CONF_TYPE_UINT, the value of errval is returned.

For how to refer to variables in a program, see conf_get().

Possible exceptions: assert_exceptfail, mem_exceptfail

Unchecked errors: none

Parameters:
[in] var section/variable name
[in] errval value returned as error
Returns:
converted result or errval

Here is the call graph for this function:

void() conf_hashreset ( void   ) 

resets the hash table using hash_reset().

conf_hashreset() simply calls hash_reset() to reset the hash table. As explained in conf_free(), conf_free() does not invoke hash_reset() because the single hash table may be used by other parts of a user program. Since requiring a reference to hash_reset() when using the Configuration File Library is inconsistent and inconvenient (e.g., a user code is obliged to include "hash.h"), conf_hashreset() is provided as a wrapper for hash_reset().

Warning:
Do not forget that the effect on the hash table caused by conf_hashreset() is not limited to eliminating only what conf_ functions adds to the table; it completely cleans up the entire hash table.
Possible exceptions: none

Unchecked errors: none

Returns:
nothing

size_t() conf_init ( FILE *  fp,
int  ctrl 
)

reads a configuration file and constructs the configuration data.

conf_init() reads a configuration file and constructs the configuration data by analyzing the file. For how conf_init() interacts with conf_preset(), see conf_preset().

The default behavior of the library is that names are not case-insensitive and that escape sequences are not recognized. This behavior can be changed by setting the CONF_OPT_CASE and CONF_OPT_ESC bits in ctrl, respectively; see also conf_preset().

If the control mode that can be set through ctrl has been already set by conf_preset(), conf_init() ignores ctrl.

Possible exceptions: assert_exceptfail, mem_exceptfail

Unchecked errors: invalid file pointer given for fp

Parameters:
[in] fp file pointer from which configuration data read
[in] ctrl control code
Returns:
success/failure indicator
Return values:
0 success
positive line number on which error occurred
Todo:
Improvements are possible and planned:
  • some adjustment on arguments to table_new() is necessary.

int() conf_preset ( const conf_t tab,
int  ctrl 
)

constructs a default set for configuration variables.

A user program can specify the default set of configuration variables (including sections to which they belong and their types) with conf_preset(). The table (an array, in fact) containing necessary information have the conf_t type and called a "configuration description table." For a detailed explanation and examples, see conf_t. conf_preset(), if invoked, has to be called before conf_init(). conf_init() is not necessarily invoked if conf_preset() is used.

If invoked, conf_preset() remembers names that need to be recognized as sections and variables, types of variables, and their default values. When conf_init() processes a configuration file, a sections or variable that is not given via conf_preset() is considered an error. Using conf_preset() and a configuration description table is the only way to let variables have other types than CONF_TYPE_STR (string type).

If not invoked, conf_init() accepts any section and variable name (if they have a valid form) and all of variables are assumed to be of CONF_TYPE_STR type.

conf_preset() also takes ctrl for controling some behaviors of the library, especially handling section/variable names and values. If the CONF_OPT_CASE bit is set in ctrl (that is, CONF_OPT_CASE & ctrl is not 0), section and variable names are case-sensitive. If the CONF_OPT_ESC bit is set in ctrl, some forms of escape sequences are supported in a quoted value. The default behavior is that section and variable names are case-insensitive and no escape sequences are supported.

Warning:
conf_preset() does not warn that a default value for a variable does not have an expected form for the variable's type. It is to be treated as an error when retrieving the value by conf_get() or similar functions.
Possible exceptions: assert_exceptfail, mem_exceptfail

Unchecked errors: none

Parameters:
[in] tab configuration description table
[in] ctrl control code
Returns:
success/failure indicator
Return values:
CONF_ERR_OK success
others failure
Todo:
Improvements are possible and planned:
  • some adjustment on arguments to table_new() is necessary;
  • considering changes to the format of a configuration file as a program to accept it is upgraded, making it a recoverable error to encounter a non-preset section or variable name would be useful; this enables an old version of the program to accept a new configuration file with diagnostics.

int() conf_section ( const char *  sec  ) 

sets the current section.

conf_section() sets the current section to a given section. The global section can be set as the current section by giving an empty string "" to conf_section(). conf_section() affects how conf_get(), conf_getbool(), conf_getint(), confgetuint(), confgetreal(), confgetstr() and conf_set() work.

Parameters:
[in] sec section name to set as current section
Returns:
success/failure indicator
Return values:
CONF_ERR_OK success
others failure

int() conf_set ( const char *  secvar,
const char *  value 
)

inserts or replaces a value associated with a variable.

conf_set() inserts or replaces a value associated with a variable. If conf_preset() has been invoked, conf_set() is able to only replace a value associated with an existing variable, which means an error code is returned when a user tries to insert a new variable and its value (possibly with a new section). conf_set() is allowed to insert a new variable-value pair otherwise.

For how to refer to variables in a program, see conf_get().

Warning:
When conf_preset() invoked, conf_set() does not check if a given value is appropriate to the preset type of a variable. That mismatch is to be detected when conf_get() or similar functions called later for the variable.
Possible exceptions: assert_exceptfail, mem_exceptfail

Unchecked errors: none

Parameters:
[in] secvar section/variable name
[in] value value to store
Returns:
success/failure indicator
Return values:
CONF_ERR_OK success
others failure
Todo:
Improvements are possible and planned:
  • some adjustment on arguments to table_new() is necessary.


Generated on Mon Jan 24 01:13:11 2011 for The Configuration File Library by  doxygen 1.5.8