Confloader Documentation

Confloader: a simple configuration file loader and parser.

Version:

Version 0.1 is described here

Author:

Nicolas Bernard <http://www.lafraze.net/nbernard/>

Download

Have a look at <http://www.lafraze.net/nbernard/projects/confloader/download/>

What is it?

Often, a program must load some parameters from a configuration file.

In some languages (Perl, etc), it is very easy to parse a configuration file. C is not one of them. Even if anyone can do a configuration file loader for his application, it remains boring. Worse, there is nothing new in doing such a thing as a lot of pieces of software uses a similar system...

The goal of confloader is to provide such a parser which can be adapted with as few efforts as possible, so developers of software applications can concentrate on tasks which interest them.

Types of data allowed in a configuration file

• boolean (type YESNO)
• integer (type INTOPT)
• floating point number (type FLOATOPT)
• string (type STRINGOPT)
• filename (type FILEOPT)
• logging method (type LOGOPT): currently possible values are "none", "syslog" or a log file. For more details, see the "Using the 'LOGOPT' type" subsection below.

Using Confloader

The easiest way to use confloader is probably to make a "confloader" subdirectory in your project source directory and to copy confloader's source files (confloader.c, confloader.h, Makefile) in it.

In the source file in which you need to load the configuration file, add the confloader.h header and create a global "conf" array according to the options you want to allow in a configuration file, and ending with a {NULL}, for example:

#include "confloader.h"

option conf[] = {{"Name", STRINGOPT, 1, {0}},
                 {"Port", INTOPT, 1, {0}},
                 {"UID", INTOPT, 1, {0}},
                 {"Hostlist", STRINGOPT, 1, {0}},
                 {"Root", YESNO, 1, {0}},
                 {"NBHostPerRequest", INTOPT, 1, {0}},
                 {"LocalClients" , YESNO, 1, {0}},
                 {"RemotePort", STRINGOPT, 1, {0}},
                 {"captain", FLOATOPT, 1, {0}},
                 {"LocalPort", STRINGOPT, 1, {0}},
                 {"pidfile", FILEOPT, 1, {0}},
                 {"log", LOGOPT, 1, {0}},
                 {NULL}};

As you can see, this is an array of "option". An option is a structure.

• The first value is the string which will be used in the configuration file.
• The second one indicates the type of the option.
• The third one should be put to one if the option is mandatory in the configuration file, to 0 otherwise
• The last one is the initialization of the option. If the value is not mandatory and not set in the configuration file, this value will be used.

Using the "LOGOPT" type

There is currently five types of log options: none, logfile, syslog and the standart and error output, so with the '{"log", LOGOPT, 1, {0}},' in the conf array, the five lines below in the configuration file are correct (but not in the same time, of course!):

log = syslog
log = file "/var/log/test"
log = none  
log = stdout
log = stderr

You can use a log function based on the following framework:

void logger(option log, char* logline)
{
        static FILE* logfiledesc = NULL;
        if (log.type != LOGOPT)
                exit(1);

        switch(log.value.log.logtype) {
        case LOG__NOTDEF: /* use stderr if not log facility defined */
        case LOG__STDERR:
                fprintf(stderr, logline);
                break;
        case LOG__STDOUT:
                fprintf(stdout, logline);
                break;
        case LOG__FILE:
                if (logfiledesc == NULL)
                        logfiledesc = fopen(log.value.log.filename, "a");
                fprintf(logfiledesc, logline);
                break;
        case LOG__SYSLOG:
                syslog(priority, logline);
                break;
        case LOG__NONE:
                break;
        }
}

Example

Have a look at the test program (test.c) and it's associated files (test.conf) which are in the tarball.

Frequently Asked Questions

• Why is confloader distributed as source files to include in a piece of software and not as a library ?

The main reason is that confloader is pretty minimalistic and made to be modified and extended by it's users according to their needs.

Another reason is that confloader's API is not freezed yet.

• Is confloader thread-safe ?

Yes and no ;-) The only problem could be write-access to the conf array, but there shouldn't be any such access to this array after the loading of the configuration file... If you load the configuration file before creating threads there should be no problem.

• Is there similar projects ?

libConfuse <http://www.nongnu.org/confuse/> is designed to parse more complex configuration files. Released under LGPL.

History

Confloader was originaly developed for the True Nyms project.

• 2004-09: version 0.1

License

Confloader is distributed under the following BSD-inspired licence. It is not a very known licence, but it is recommended by the OpenBSD project.

Copyright (c) 2004 Nicolas Bernard <http://www.lafraze/net/nbernard/>

Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

---