The C API to the kunf library

This section is intended as a reference to C programmers who wish to make use of the kunf library. Shell programmers might want to have a look at the utilities which provide a similar service. Also refer to the examples for a more lively introduction to the kunf library.

Some functions return pointers to strings or structures. In no event should these strings or structures be modified or deallocated by the client code. The function kunfig_close() performs the deallocation for you.

Some functions return a pointer to a KITEM structure. Do not access the fields of that structure directly, otherwise your program is bound to break if the library changes. In other words, only check if pointer is zero - otherwise pass it to a kunf function which can use it.

Basic Functions

These functions are sufficient for typical uses. If you only require configuration information with known names, you should not need to use any other functions of this library.

int kunfig_open (char *fname, unsigned int flags);

Initializes the library. It has to be called before any call to any other kunf function is made. fname in almost all circumstances should be NULL (unless you need to specify the root configuration file, but that should not be required), while flags control some options of the system. These options can be bitwise ORed together.

KUNFIG_OPEN_STANDARD: The recommended value for flags. Is equivalent to KUNFIG_OPEN_NOENV|KUNFIG_OPEN_SIMPLEACCESS|KUNFIG_OPEN_PRINTERRORS|KUNFIG_OPEN_PRINTWARNINGS|KUNFIG_OPEN_EXITONERRORS. There should be little reason for you to use different flags unless you are writing a kunf browser or editor.
KUNFIG_OPEN_NOENV: Do not refer to the environment variable KUNFIG to find the root configuration file.
KUNFIG_OPEN_DEFAULTINGENV: Only consult the environment variable KUNFIG if the file in fname can not be opened.
KUNFIG_OPEN_OVERRIDINGENV: Consult the environment variable KUNFIG before trying to open fname.
KUNFIG_OPEN_SIMPLEACCESS: Do not make unprocessed entries available for viewing, disable writing of files and ignore comments.
KUNFIG_OPEN_COMPLEXACCESS: Store unprocessed entries as well as post-processed entries, comments and include directives.
KUNFIG_OPEN_PRINTERRORS: Print errors to stderr as they are encountered.
KUNFIG_OPEN_LOGERRORS: Log errors to syslog.
KUNFIG_OPEN_PRINTWARNINGS: Print warnings to stderr.
KUNFIG_OPEN_LOGWARNINGS: Log warnings to syslog.
KUNFIG_OPEN_EXITONERRORS: Exit with code 5 on encountering errors.
KUNFIG_OPEN_EXITONWARNINGS: Exit with code 5 on encountering warnings.

kunfig_open returns 0 if successful and nonzero otherwise (unless a KUNFIG_OPEN_EXITON... flags was specified in which case your program will have terminated if an error was encountered - this also applies to all other calls into the kunf library).

char *kunfig_findvalue (int number, char *first, ...);

Looks up the value of of an entry. number indicates the number of char * arguments passed to the function. number has to be larger than 0.

kunfig_findvalue(2,"foo","bar");

will retrieve baz for this entry:

[foo]
bar=baz

This function returns a pointer to a string if a match was encountered, otherwise NULL.

int kunfig_close ();

Shuts down the kunf library. It should always return 0. Once this function has been called, all strings and handles returned by the other functions will become invalid.

More Complex Functions

These functions are needed if you have to search for entries with unknown names. These functions are conceptually similar to directory navigation. Most of these functions operate on pointers to KITEM structures. Treat these as opaque handles (do not try and access their content directly, only check if they are non-null).

KITEM *kunfig_findentry (int number, char *first, ...);

Returns a handle to an entry or header. number indicates the number of char * arguments passed to the function. number has to be larger than 0.

kunfig_findvalue(3,"foo","bar","baz");

will retrieve a handle to:

[foo:bar] baz=xxyyzz

or:

[foo:bar:baz]

This function returns a pointer a KITEM structure if a match was encountered, otherwise NULL.

KITEM *kunfig_next (KITEM *prev);

This function returns a handle to the next item in a list if exits, otherwise it returns NULL. For sections

[a]
b=c
d=e
[f]

kunfig_next(prev) will return a handle to d=e if prev points to b=c and will return NULL if prev points to d=e. If prev points to [a] then kunfig_next(prev) will return a handle to [f].

kunfig_start(), kunfig_down() and kunfig_next() can be thought of as directory traversal routines.

KITEM *kunfig_down (KITEM *up);

This function returns a handle to the first entry in a section of up points to its header. If there are no entries for a header it returns NULL. For sections

[a]
b=c
d=e
[f]

kunfig_down(up) will return a handle to b=c if up points to [a] and will return NULL if up points to [f].

kunfig_start(), kunfig_down() and kunfig_next() can be thought of as directory traversal routines.

KITEM *kunfig_start ();

Returns a handle to the top entry in the kunf database, if exists. kunfig_start(), kunfig_down() and kunfig_next() can be thought of as directory traversal routines, where kunfig_start() is analogous to cd /.

int kunfig_isentry (KITEM *ptr);

Returns nonzero if the handle ptr points to a proper entry as opposed to a section header. Otherwise it returns zero. Can be thought of as a test for a regular file (if we use the directory analogy).

int kunfig_isheader (KITEM *ptr);

Returns nonzero if the handle ptr points to a header as opposed to an entry. Otherwise it returns zero. Can be though of as a test for a directory (if we use the directory analogy).

char *kunfig_getname (KITEM *ptr);

Returns the name of the entry which is pointed to by ptr. For ptr pointing to

foo=bar

kunfig_getname() will return foo. This function is similar to a fstat() function if we use the directory analogy.

char *kunfig_getvalue (KITEM *ptr);

Returns the value of the entry which is pointed to by ptr. For ptr pointing to

foo=bar

kunfig_getvalue() will return bar. This function should only be used on proper entries (which can be checked with the function kunfig_isentry()). This function is similar to a fstat() function if we use the directory analogy.

Browser Functions

These functions can be used to acquire more detailed information about the internal structure of the database. Thus these functions should not be used by plain client applications - it is suggested that only browsers, syntax checkers, editors and other utilities associated with the database maintenance make use of these functions.

char *kunfig_getrawname (KITEM *ptr);: Returns the raw name (no % escapes interpreted) of the entry which is pointed to by ptr. This is only available if kunfig_open was called with the KUNFIG_OPEN_COMPLEXACCESS flag.
char *kunfig_getrawvalue (KITEM *ptr);: Returns the raw value (no % escapes interpreted) of the entry which is pointed to by ptr. This is only available if kunfig_open was called with the KUNFIG_OPEN_COMPLEXACCESS flag.
char *kunfig_getdescription (KITEM *ptr);: Returns the associated comment of the entry which is pointed to by ptr. This function is only available if kunfig_open was called with the KUNFIG_OPEN_COMPLEXACCESS flag.
char *kunfig_isredirected (KITEM *ptr);: Returns true (1) if ptr points to a redirected header (a header of the form [x:y=file] as opposed to a plain header of the form [x:y]). Otherwise this function returns false (0).
char *kunfig_isincludestart (KITEM *ptr);: Returns true (1) if ptr points to an include directive. Subsequent calls to kunfig_next will retrieve the entries in the include directive until a special end of include marker is encountered (can be found with kunfig_isincludeend). Thereafter the content of the previous file will be returned. Start and end of include file markers are only present if kunfig_open was called with the KUNFIG_OPEN_COMPLEXACCESS flag.
char *kunfig_isincludeend (KITEM *ptr);: Returns true (1) if ptr points to an end of include file marker (like the start of include file marker, these entries always return NULL for a kunfig_getname() call). Start and end of include file markers are only present if kunfig_open was called with the KUNFIG_OPEN_COMPLEXACCESS flag.
char *kunfig_getfilename (KITEM *ptr);: Returns the name of the file which ptr points to (if ptr is an include or redirection directive. Otherwise it returns NULL. This function is only available if kunfig_open was called with the KUNFIG_OPEN_COMPLEXACCESS flag.

Editing Functions

These functions modify the content of the kunf database. You will have to use the KUNFIG_OPEN_COMPLEXACCESS flag to make use of these functions. Please note that these functions have not been tested particularly well and that further functions will probably have to be added to this section.

int kunfig_setrawvalue (KITEM *ptr, char *rawvalue);: Sets the value of an (already existant) entry. Only plain entries can be modified. This function does not write changes to file (use kunfig_writeback to write changes). kunfig_setrawvalue returns zero if successful and nonzero otherwise.
int kunfig_writeback ();: Writes (flushes) changes to file. At this stage no locking is implemented. The function returns zero if successful and nonzero otherwise.

Error Functions

These functions can be used to check if errors have occured while the configuration information was acquired.

int kunfig_printerror (FILE *stream);

Prints a message describing the errors encountered by previous kunf functions to stream stream.

Returns zero. Using this function only makes sense if you have called kunfig_open() without an KUNFIG_OPEN_EXIT... flag. Otherwise the program will have aborted with code 5 before there was a chance to call this function.

int kunfig_waserror ();

Returns nonzero if an error has occurred and zero if everything seems ok. Using this function only makes sense if you have called kunfig_open() without an KUNFIG_OPEN_EXIT... flag. Otherwise the program will have aborted with code 5 before there was a chance to call this function.

Next: Utilities