Configuration files are used by all netraf programs (netrafd, netrafg and netrafl) to read or write every configurable aspects of them. Their syntax is clear and human readable, so the user can easily change settings to meet his demands. Operations on configuration files are divided on two levels:

• low level - allows simple operations like inserting text or reading single line
• high level - looks after correct syntax, proper positioning of inserting text, etc.

This division makes eventual changes much more easier to develop.

Configuration interface

    It is a collection of functions allowing low-level operations on specified file. First of all it must be opened. All necessary structures will be initialized and ready to work. We do this by calling iconf_open() function. It will return pointer to iconf_t structure, and will be used in every operation until it is closed. After then, we can read the file line by line using iconf_getline function, insert any text at given position, clean area in the file appointed by start position and end position, finally override selected line. When we finished working with file, it should be closed by iconf_close() function.

Configuration file syntax

    Basically, all configuration files consist of sections. Each section begins with name, which must be enclosed with a pair of '[[' and ']]' strings. Moreover every section must end with '[[]]' string. Section can have any number of entries. Entry is simply a line containing entry name, equation mark, quoted value, and semicolon as terminator. We can also insert comments into the file. It must begin with '#' character and all data after it will be ignored until end of line. Let's look at the configuration file example:

    Now, knowing how configuration file should look like, let's explain how to control it. At the beginning it must be opened (as we did with configuration interface) by conf_open() function. Pointer to conf_t structure will be returned. How to read it? There are two ways. First one is sequential. We call get_first_section() function to move to the first section. It'll return it's name or NULL if there is no section in the file. Then, using next_section() we get other sections, until NULL is returned. Second way is to call goto_section() function. But we must know exact name of section we want to go. There is also an option to get name of current section, by calling current_section(). Retrieving entry values from current section is similar operation. get_first_entry() and next_entry() are used to review following entries giving their names. Finally, to get entry value current_entry() function is used. There is also a shortcut. We can use get_value() with entry name as one of the arguments, to search whole section for it. We will get value, or NULL if there was no such entry.
    Inserting new sections or entries into the configuration file is even more easy than reading it. We use new_section() to add new section, new_pair() to add new entry in the current section and delete_section() to delete one. An example showing the usage of all, mentioned functions is available in code chunks.

T.J.