ini.h File Reference

A configuration file (INI) reader. More...

Go to the source code of this file.

Classes
struct	ini_tuple
	holds key/value pair data More...
struct	ini_section
	container to hold data for a section More...
struct	ini
	container to hold sections More...

Enumerations
enum	ini_options { INI_OPTION_NONE = (0<<1) }
	place holder for future parsing options More...

Functions
int	ini_assign (struct ini *const o_ini)
	initialize ini object More...
void	ini_discharge (struct ini *const io_ini)
	release resources held by the object More...
char const *	ini_lookup (int *const o_found, struct ini *const i_ini, char const *i_section, char const *i_key)
	lookup a value More...
int	ini_parse (struct ini *const io_ini, char const *i_path, enum ini_options const i_options)
	read an INI file More...

Detailed Description

A configuration file (INI) reader.

Keys not contained in a section are placed in a section named 'defaults.'

Comment lines start with a semi-colon (;) or hash ('#') symbol. These lines are ignored.

Sections and keys are converted to lower case.

Duplicate sections are combined into one.

Duplicate keys will have their value replaced.

Example:

; no section defined, the key will go into implicit [defaults] section
name=value

[defaults]
foo=value

[other]
foo=value

The 'defaults' section will contain two keys: (1) name and (2) foo.

The 'other' section will contain one key: (1) foo.

Following is an example on how to read key/value pairs from an INI file.

#include "ini.h"
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <errno.h>

int
main()
{
    int exit; /* application exit code */
    struct ini ini; /* ini object */
    int rc; /* return code*/
    char const *value; /* pointer to hold value */
    int found; /* indicator if key was found */

    exit = 0;

    do {
        /* initialize ini object */
        rc = ini_assign(&ini);

        if (rc) {
            /* error */
            exit = rc;
            break;
        }

        /* load the configuration file */
        rc = ini_parse(&ini, "book.ini", INI_OPTION_NONE);

        /* check for error */
        if (rc) {
            /* error */
            exit = rc;
            break;
        }

        value = ini_lookup(&found, &ini, "book", "chapter1");

        if (0 == found) {
            fprintf(
                stderr,
                "Unable to find key\n");
            exit = ENOENT;
            break;
        }

        /* output the value */
        fprintf(
            stdout,
            "Book -> Chapter1: %s\n",
            value);

    } while (0);

    ini_discharge(&ini);

    return exit;
}

Enumeration Type Documentation

ini_options

enum ini_options

place holder for future parsing options

Enumerator
INI_OPTION_NONE	absence of options

Function Documentation

ini_assign()

int ini_assign

(

struct ini *const

o_ini

)

initialize ini object

Parameters

[out]

o_ini

object to initialize

Returns

0 success

ENOMEM memory allocation failed

Upon failure, it is not advisable to use other routines.

ini_discharge()

void ini_discharge

(

struct ini *const

io_ini

)

release resources held by the object

Parameters

[in,out]

io_ini

object to release

Returns

none

ini_lookup()

char const * ini_lookup	(	int *const	o_found,
		struct ini *const	i_ini,
		char const *	i_section,
		char const *	i_key
	)

lookup a value

Parameters

[out]	o_found	indicator if key exists
[in]	i_ini	valid ini object
[in]	i_section	name of section
[in]	i_key	name of key

Returns

value of key

Zero is a valid return value. Check o_found to see if the key exists.

ini_parse()

int ini_parse	(	struct ini *const	io_ini,
		char const *	i_path,
		enum ini_options const	i_options
	)

read an INI file

Parameters

[in,out]	io_ini	valid ini object
[in]	i_path	file to load
[in]	i_options	(place holder for future options)

Returns

0 success

ENOMEM memory allocation failed

E2BIG capacity of a line exceeded

!0 see errno (read file error)

When an error is encountered, this routine will print a diagnostic message to stderr.