iniparser 3.1
Functions
iniparser.h File Reference

Parser for ini files. More...

Functions

int iniparser_getnsec (dictionary *d)
 Get number of sections in a dictionary.
char * iniparser_getsecname (dictionary *d, int n)
 Get name for section n in a dictionary.
void iniparser_dump_ini (dictionary *d, FILE *f)
 Save a dictionary to a loadable ini file.
void iniparser_dumpsection_ini (dictionary *d, char *s, FILE *f)
 Save a dictionary section to a loadable ini file.
void iniparser_dump (dictionary *d, FILE *f)
 Dump a dictionary to an opened file pointer.
int iniparser_getsecnkeys (dictionary *d, char *s)
 Get the number of keys in a section of a dictionary.
char ** iniparser_getseckeys (dictionary *d, char *s)
 Get the number of keys in a section of a dictionary.
char * iniparser_getstring (dictionary *d, const char *key, char *def)
 Get the string associated to a key.
int iniparser_getint (dictionary *d, const char *key, int notfound)
 Get the string associated to a key, convert to an int.
double iniparser_getdouble (dictionary *d, const char *key, double notfound)
 Get the string associated to a key, convert to a double.
int iniparser_getboolean (dictionary *d, const char *key, int notfound)
 Get the string associated to a key, convert to a boolean.
int iniparser_set (dictionary *ini, const char *entry, const char *val)
 Set an entry in a dictionary.
void iniparser_unset (dictionary *ini, const char *entry)
 Delete an entry in a dictionary.
int iniparser_find_entry (dictionary *ini, const char *entry)
 Finds out if a given entry exists in a dictionary.
dictionary * iniparser_load (const char *ininame)
 Parse an ini file and return an allocated dictionary object.
void iniparser_freedict (dictionary *d)
 Free all memory associated to an ini dictionary.

Detailed Description

Parser for ini files.

Author:
N. Devillard

Function Documentation

void iniparser_dump ( dictionary *  d,
FILE *  f 
)

Dump a dictionary to an opened file pointer.

Parameters:
dDictionary to dump.
fOpened file pointer to dump to.
Returns:
void

This function prints out the contents of a dictionary, one element by line, onto the provided file pointer. It is OK to specify stderr or stdout as output files. This function is meant for debugging purposes mostly.

void iniparser_dump_ini ( dictionary *  d,
FILE *  f 
)

Save a dictionary to a loadable ini file.

Parameters:
dDictionary to dump
fOpened file pointer to dump to
Returns:
void

This function dumps a given dictionary into a loadable ini file. It is Ok to specify stderr or stdout as output files.

void iniparser_dumpsection_ini ( dictionary *  d,
char *  s,
FILE *  f 
)

Save a dictionary section to a loadable ini file.

Parameters:
dDictionary to dump
sSection name of dictionary to dump
fOpened file pointer to dump to
Returns:
void

This function dumps a given section of a given dictionary into a loadable ini file. It is Ok to specify stderr or stdout as output files.

int iniparser_find_entry ( dictionary *  ini,
const char *  entry 
)

Finds out if a given entry exists in a dictionary.

Parameters:
iniDictionary to search
entryName of the entry to look for
Returns:
integer 1 if entry exists, 0 otherwise

Finds out if a given entry exists in the dictionary. Since sections are stored as keys with NULL associated values, this is the only way of querying for the presence of sections in a dictionary.

void iniparser_freedict ( dictionary *  d)

Free all memory associated to an ini dictionary.

Parameters:
dDictionary to free
Returns:
void

Free all memory associated to an ini dictionary. It is mandatory to call this function before the dictionary object gets out of the current context.

int iniparser_getboolean ( dictionary *  d,
const char *  key,
int  notfound 
)

Get the string associated to a key, convert to a boolean.

Parameters:
dDictionary to search
keyKey string to look for
notfoundValue to return in case of error
Returns:
integer

This function queries a dictionary for a key. A key as read from an ini file is given as "section:key". If the key cannot be found, the notfound value is returned.

A true boolean is found if one of the following is matched:

  • A string starting with 'y'
  • A string starting with 'Y'
  • A string starting with 't'
  • A string starting with 'T'
  • A string starting with '1'

A false boolean is found if one of the following is matched:

  • A string starting with 'n'
  • A string starting with 'N'
  • A string starting with 'f'
  • A string starting with 'F'
  • A string starting with '0'

The notfound value returned if no boolean is identified, does not necessarily have to be 0 or 1.

double iniparser_getdouble ( dictionary *  d,
const char *  key,
double  notfound 
)

Get the string associated to a key, convert to a double.

Parameters:
dDictionary to search
keyKey string to look for
notfoundValue to return in case of error
Returns:
double

This function queries a dictionary for a key. A key as read from an ini file is given as "section:key". If the key cannot be found, the notfound value is returned.

int iniparser_getint ( dictionary *  d,
const char *  key,
int  notfound 
)

Get the string associated to a key, convert to an int.

Parameters:
dDictionary to search
keyKey string to look for
notfoundValue to return in case of error
Returns:
integer

This function queries a dictionary for a key. A key as read from an ini file is given as "section:key". If the key cannot be found, the notfound value is returned.

Supported values for integers include the usual C notation so decimal, octal (starting with 0) and hexadecimal (starting with 0x) are supported. Examples:

  • "42" -> 42
  • "042" -> 34 (octal -> decimal)
  • "0x42" -> 66 (hexa -> decimal)

Warning: the conversion may overflow in various ways. Conversion is totally outsourced to strtol(), see the associated man page for overflow handling.

Credits: Thanks to A. Becker for suggesting strtol()

int iniparser_getnsec ( dictionary *  d)

Get number of sections in a dictionary.

Parameters:
dDictionary to examine
Returns:
int Number of sections found in dictionary

This function returns the number of sections found in a dictionary. The test to recognize sections is done on the string stored in the dictionary: a section name is given as "section" whereas a key is stored as "section:key", thus the test looks for entries that do not contain a colon.

This clearly fails in the case a section name contains a colon, but this should simply be avoided.

This function returns -1 in case of error.

char** iniparser_getseckeys ( dictionary *  d,
char *  s 
)

Get the number of keys in a section of a dictionary.

Parameters:
dDictionary to examine
sSection name of dictionary to examine
Returns:
pointer to statically allocated character strings

This function queries a dictionary and finds all keys in a given section. Each pointer in the returned char pointer-to-pointer is pointing to a string allocated in the dictionary; do not free or modify them.

This function returns NULL in case of error.

char* iniparser_getsecname ( dictionary *  d,
int  n 
)

Get name for section n in a dictionary.

Parameters:
dDictionary to examine
nSection number (from 0 to nsec-1).
Returns:
Pointer to char string

This function locates the n-th section in a dictionary and returns its name as a pointer to a string statically allocated inside the dictionary. Do not free or modify the returned string!

This function returns NULL in case of error.

int iniparser_getsecnkeys ( dictionary *  d,
char *  s 
)

Get the number of keys in a section of a dictionary.

Parameters:
dDictionary to examine
sSection name of dictionary to examine
Returns:
Number of keys in section
char* iniparser_getstring ( dictionary *  d,
const char *  key,
char *  def 
)

Get the string associated to a key.

Parameters:
dDictionary to search
keyKey string to look for
defDefault value to return if key not found.
Returns:
pointer to statically allocated character string

This function queries a dictionary for a key. A key as read from an ini file is given as "section:key". If the key cannot be found, the pointer passed as 'def' is returned. The returned char pointer is pointing to a string allocated in the dictionary, do not free or modify it.

dictionary* iniparser_load ( const char *  ininame)

Parse an ini file and return an allocated dictionary object.

Parameters:
ininameName of the ini file to read.
Returns:
Pointer to newly allocated dictionary

This is the parser for ini files. This function is called, providing the name of the file to be read. It returns a dictionary object that should not be accessed directly, but through accessor functions instead.

The returned dictionary must be freed using iniparser_freedict().

int iniparser_set ( dictionary *  ini,
const char *  entry,
const char *  val 
)

Set an entry in a dictionary.

Parameters:
iniDictionary to modify.
entryEntry to modify (entry name)
valNew value to associate to the entry.
Returns:
int 0 if Ok, -1 otherwise.

If the given entry can be found in the dictionary, it is modified to contain the provided value. If it cannot be found, -1 is returned. It is Ok to set val to NULL.

void iniparser_unset ( dictionary *  ini,
const char *  entry 
)

Delete an entry in a dictionary.

Parameters:
iniDictionary to modify
entryEntry to delete (entry name)
Returns:
void

If the given entry can be found, it is deleted from the dictionary.