The Configuration File Library  0.2.0
Data Structures | Enumerations
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_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
}
 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]valstring to convert
[in]typetype based on which conversion performed
Returns:
pointer to storage that contains result or null pointer
Return values:
non-nullpointer to conversion result
NULLconversion 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]codeerror 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]varsection/variable name
Returns:
pointer to storage that contains value or null pointer
Return values:
non-nullvalue retrieved
NULLfailure

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]varsection/variable name
[in]errvalvalue 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]varsection/variable name
[in]errvalvalue 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]varsection/variable name
[in]errvalvalue 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]varsection/variable name
Returns:
string or null pointer
Return values:
non-nullstring retrieved
NULLfailure

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]varsection/variable name
[in]errvalvalue 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]fpfile pointer from which configuration data read
[in]ctrlcontrol code
Returns:
success/failure indicator
Return values:
0success
positiveline 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]tabconfiguration description table
[in]ctrlcontrol code
Returns:
success/failure indicator
Return values:
CONF_ERR_OKsuccess
othersfailure
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]secsection name to set as current section
Returns:
success/failure indicator
Return values:
CONF_ERR_OKsuccess
othersfailure
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]secvarsection/variable name
[in]valuevalue to store
Returns:
success/failure indicator
Return values:
CONF_ERR_OKsuccess
othersfailure
Todo:
Improvements are possible and planned:
  • some adjustment on arguments to table_new() is necessary.
 All Data Structures Files Functions Variables Enumerator