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