conf.h File Reference

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

This graph shows which files directly or indirectly include this file:


Data Structures

struct  conf_t
 represents an element of a configuration description table. More...

Enumerations

enum  {
  CONF_TYPE_NO, CONF_TYPE_BOOL, CONF_TYPE_INT, CONF_TYPE_UINT,
  CONF_TYPE_REAL, CONF_TYPE_STR
}
 defines enum constants for types of values. More...
enum  {
  CONF_ERR_OK, CONF_ERR_FILE, CONF_ERR_IO, CONF_ERR_SPACE,
  CONF_ERR_CHAR, CONF_ERR_LINE, CONF_ERR_BSLASH, CONF_ERR_SEC,
  CONF_ERR_VAR, CONF_ERR_TYPE, CONF_ERR_MAX
}
 defines enum constants for error codes. More...
enum  { CONF_OPT_CASE = 0x01, CONF_OPT_ESC = CONF_OPT_CASE << 1 }
 defines masks for control options. More...

Functions

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

Detailed Description

Header for Configuration File Library (CEL).

Documentation for Configuration File Library (CEL).


Enumeration Type Documentation

anonymous enum

defines enum constants for types of values.

Enumerator:
CONF_TYPE_BOOL  has boolean (int) type
CONF_TYPE_INT  has integer (long) type
CONF_TYPE_UINT  has unsigned integer (unsigned long) type
CONF_TYPE_REAL  has floating-point (double) type
CONF_TYPE_STR  has string (char *) type

anonymous enum

defines enum constants for error codes.

Enumerator:
CONF_ERR_OK  everything is okay
CONF_ERR_FILE  file not found
CONF_ERR_IO  I/O error occurred
CONF_ERR_SPACE  space in section/variable name
CONF_ERR_CHAR  invalid character encountered
CONF_ERR_LINE  invalid line encountered
CONF_ERR_BSLASH  no following line for slicing
CONF_ERR_SEC  section not found
CONF_ERR_VAR  variable not found
CONF_ERR_TYPE  data type mismatch

anonymous enum

defines masks for control options.

Enumerator:
CONF_OPT_CASE  case-sensitive variable/section name
CONF_OPT_ESC  supports escape sequence in quoted value


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:13 2011 for The Configuration File Library by  doxygen 1.5.8