iniparser 2.x

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


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_dump (dictionary d, FILE f)
	Dump a dictionary to an opened file pointer.
char *	iniparser_getstr (dictionary d, const char key)
	Get the string associated to a key, return NULL if not found.
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, 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_setstr (dictionary ini, char entry, char *val)
	Set an entry in a dictionary.
void	iniparser_unset (dictionary ini, char entry)
	Delete an entry in a dictionary.
int	iniparser_find_entry (dictionary ini, 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

Function Documentation

- - - - - - - - - - - - - - - - - - -

void iniparser_dump	(	dictionary *	d,
		FILE *	f
	)

- -

-Dump a dictionary to an opened file pointer. -

Parameters:

- - - -

	d	Dictionary to dump.
	f	Opened 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:

- - - -

	d	Dictionary to dump
	f	Opened 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. -

- - - - - - - - - - - - - - - - - - -

int iniparser_find_entry	(	dictionary *	ini,
		char *	entry
	)

- -

-Finds out if a given entry exists in a dictionary. -

Parameters:

- - - -

	ini	Dictionary to search
	entry	Name 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:

- - -

Dictionary 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:

- - - - -

	d	Dictionary to search
	key	Key string to look for
	notfound	Value 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,
		char *	key,
		double	notfound
	)

- -

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

Parameters:

- - - - -

	d	Dictionary to search
	key	Key string to look for
	notfound	Value 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:

- - - - -

	d	Dictionary to search
	key	Key string to look for
	notfound	Value 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:

- - -

Dictionary 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_getsecname	(	dictionary *	d,
		int	n
	)

- -

-Get name for section n in a dictionary. -

Parameters:

- - - -

	d	Dictionary to examine
	n	Section 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. -

- - - - - - - - - - - - - - - - - - -

char* iniparser_getstr	(	dictionary *	d,
		const char *	key
	)

- -

-Get the string associated to a key, return NULL if not found. -

Parameters:

- - - -

	d	Dictionary to search
	key	Key string to look for

Returns:: pointer to statically allocated character string, or NULL.

-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, NULL is returned. The returned char pointer is pointing to a string allocated in the dictionary, do not free or modify it.

-This function is only provided for backwards compatibility with previous versions of iniparser. It is recommended to use iniparser_getstring() instead. -

- - - - - - - - - - - - - - - - - - - - - - - - -

char* iniparser_getstring	(	dictionary *	d,
		const char *	key,
		char *	def
	)

- -

-Get the string associated to a key. -

Parameters:

- - - - -

	d	Dictionary to search
	key	Key string to look for
	def	Default 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:

- - -

ininame

Name 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_setstr	(	dictionary *	ini,
		char *	entry,
		char *	val
	)

- -

-Set an entry in a dictionary. -

Parameters:

- - - - -

	ini	Dictionary to modify.
	entry	Entry to modify (entry name)
	val	New 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,
		char *	entry
	)

- -

-Delete an entry in a dictionary. -

Parameters:

- - - -

	ini	Dictionary to modify
	entry	Entry to delete (entry name)

Returns:: void

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

iniparser.h File Reference

Functions

Detailed Description

Function Documentation