libeconf(3)

1libeconf(3)                        libeconf                        libeconf(3)
2
3
4

NAME

6       include/libeconf.h - Public API for the econf library.
7       include/libeconf_ext.h - Public extended API for the econf library.
8
9

DESCRIPTION

11       libeconf is a highly flexible and configurable library to parse and
12       manage key=value configuration files.
13       It reads configuration file snippets from different directories and
14       builds the final configuration file for the application from it.
15
16       The first file is the vendor provided configuration file.
17
18       There are two methods of overriding this vendor settings: Copy the file
19       from /usr/_vendordir_ to /etc and modify the settings (see xample 1).
20
21       Alternatively, a directory named _file_._suffix_.d/ within /etc can be
22       created, with drop-in files in the form _name_._suffix_ (see Example
23       2).
24
25       These files contain only the changes of the specific settings the user
26       is interested in.
27       There can be several such drop-in files, they are processed in
28       lexicographic order of their filename.
29
30       The first method is useful to override the complete configuration file
31       with an own one, the vendor supplied configuration is ignored.
32
33       So, if /etc/_example_._suffix_ exists, /usr/_vendor_/_example_._suffix_
34       will not be read.
35       The disadvantage is, that changes of the vendor configuration file, due
36       e.g.  an package update, are ignored and the user has to manually merge
37       them.
38
39       The other method will continue to use /usr/_vendor_/_example_._suffix_
40       as base configuration file and merge all changes from
41       /etc/_example_._suffix_.d/*._suffix_.
42       So the user will automatically get improvements of the vendor, with the
43       drawback, that they could be incompatible with the user made changes.
44       If there is a file with the same name in
45       /usr/_vendor_/_example_._suffix_.d/ and in
46       /etc/_example_._suffix_.d/*._suffix_., the file in
47       /usr/_vendor_/_example_._suffix_.d/ will completely ignored.
48       To disable a configuration file supplied by the vendor, the recommended
49       way is to place a symlink to /dev/null in the configuration directory
50       in /etc/, with the same filename as the vendor configuration file.
51
52
53
54   Example 1
55       If a /etc/_example_._suffix_ files exists:
56
57       * /etc/_example_._suffix_
58
59       * /usr/_vendor_/_example_._suffix_.d/*._suffix_
60
61       * /etc/_example_._suffix_.d/*._suffix_
62
63
64   Example 2
65       The list of files and directories read if **no**
66       /etc/_example_._suffix_ file exists:
67
68       * /usr/_vendor_/_example_._suffix_
69
70       * /usr/_vendor_/_example_._suffix_.d/*._suffix_
71
72       * /etc/_example_._suffix_.d/*._suffix_
73
74

SYNOPSIS

76       #include <stdbool.h>
77       #include <stdint.h>
78       #include <stdlib.h>
79       #include 'libeconf.h'
80       #include 'libeconf_ext.h'
81
82
83   Typedefs
84       typedef enum econf_err econf_err
85       typedef struct econf_file econf_file
86       typedef struct econf_ext_value econf_ext_value
87
88   Enumerations
89       enum econf_err { ECONF_SUCCESS = 0, ECONF_ERROR = 1, ECONF_NOMEM = 2,
90           ECONF_NOFILE = 3, ECONF_NOGROUP = 4, ECONF_NOKEY = 5,
91           ECONF_EMPTYKEY = 6, ECONF_WRITEERROR = 7, ECONF_PARSE_ERROR = 8,
92           ECONF_MISSING_BRACKET = 9, ECONF_MISSING_DELIMITER = 10,
93           ECONF_EMPTY_SECTION_NAME = 11, ECONF_TEXT_AFTER_SECTION = 12,
94           ECONF_FILE_LIST_IS_NULL = 13, ECONF_WRONG_BOOLEAN_VALUE = 14,
95           ECONF_KEY_HAS_NULL_VALUE = 15, ECONF_WRONG_OWNER = 16,
96           ECONF_WRONG_GROUP = 17, ECONF_WRONG_FILE_PERMISSION = 18,
97           ECONF_WRONG_DIR_PERMISSION = 19, ECONF_ERROR_FILE_IS_SYM_LINK = 20,
98           ECONF_PARSING_CALLBACK_FAILED = 21 }
99           libeconf error codes
100
101   Functions
102       econf_err econf_readFile (econf_file **result, const char *file_name,
103           const char *delim, const char *comment)
104           Process the file of the given file_name and save its contents into
105           key_file object.
106       econf_err econf_readFileWithCallback (econf_file **result, const char
107           *file_name, const char *delim, const char *comment, bool
108           (*callback)(const char *filename, const void *data), const void
109           *callback_data)
110           Has the same functionality like econf_readFile. The user can
111           additionally define a callback in order to check the parsed file.
112       econf_err econf_mergeFiles (econf_file **merged_file, econf_file
113           *usr_file, econf_file *etc_file)
114           Merge the contents of two key_files objects.
115       econf_err econf_readDirs (econf_file **key_file, const char
116           *usr_conf_dir, const char *etc_conf_dir, const char *project_name,
117           const char *config_suffix, const char *delim, const char *comment)
118           Evaluating key/values of a given configuration by reading and
119           merging all needed/available files in two different directories
120           (normally in /usr/etc and /etc).
121       econf_err econf_readDirsWithCallback (econf_file **key_file, const char
122           *usr_conf_dir, const char *etc_conf_dir, const char *project_name,
123           const char *config_suffix, const char *delim, const char *comment,
124           bool (*callback)(const char *filename, const void *data), const
125           void *callback_data)
126           Has the same functionality like econf_readDirs. The user can
127           additionally define a callback in order e.g. to check all parsed
128           file.
129       econf_err econf_readDirsHistory (econf_file ***key_files, size_t *size,
130           const char *usr_conf_dir, const char *etc_conf_dir, const char
131           *project_name, const char *config_suffix, const char *delim, const
132           char *comment)
133           Evaluating key/values for every given configuration files in two
134           different directories (normally in /usr/etc and /etc).
135       econf_err econf_readDirsHistoryWithCallback (econf_file ***key_files,
136           size_t *size, const char *usr_conf_dir, const char *etc_conf_dir,
137           const char *project_name, const char *config_suffix, const char
138           *delim, const char *comment, bool (*callback)(const char *filename,
139           const void *data), const void *callback_data)
140           Has the same functionality like econf_readDirsHistory. The user can
141           additionally define a callback in order e.g. to check all parsed
142           file.
143       econf_err econf_newKeyFile (econf_file **result, char delimiter, char
144           comment)
145           Create a new econf_file object.
146       econf_err econf_newIniFile (econf_file **result)
147           Create a new econf_file object in IniFile format.
148       econf_err econf_writeFile (econf_file *key_file, const char
149           *save_to_dir, const char *file_name)
150           Write content of a econf_file struct to specified location.
151       char * econf_getPath (econf_file *kf)
152           Evaluating path name of the regarding configuration file.
153       econf_err econf_getGroups (econf_file *kf, size_t *length, char
154           ***groups)
155           Evaluating all group entries.
156       econf_err econf_getKeys (econf_file *kf, const char *group, size_t
157           *length, char ***keys)
158           Evaluating all keys.
159       econf_err econf_getIntValue (econf_file *kf, const char *group, const
160           char *key, int32_t *result)
161           Evaluating int32 value for given group/key.
162       econf_err econf_getInt64Value (econf_file *kf, const char *group, const
163           char *key, int64_t *result)
164           Evaluating int64 value for given group/key.
165       econf_err econf_getUIntValue (econf_file *kf, const char *group, const
166           char *key, uint32_t *result)
167           Evaluating uint32 value for given group/key.
168       econf_err econf_getUInt64Value (econf_file *kf, const char *group,
169           const char *key, uint64_t *result)
170           Evaluating uint64 value for given group/key.
171       econf_err econf_getFloatValue (econf_file *kf, const char *group, const
172           char *key, float *result)
173           Evaluating float value for given group/key.
174       econf_err econf_getDoubleValue (econf_file *kf, const char *group,
175           const char *key, double *result)
176           Evaluating double value for given group/key.
177       econf_err econf_getStringValue (econf_file *kf, const char *group,
178           const char *key, char **result)
179           Evaluating string value for given group/key.
180       econf_err econf_getBoolValue (econf_file *kf, const char *group, const
181           char *key, bool *result)
182           Evaluating bool value for given group/key.
183       econf_err econf_getIntValueDef (econf_file *kf, const char *group,
184           const char *key, int32_t *result, int32_t def)
185           Evaluating int32 value for given group/key.
186       econf_err econf_getInt64ValueDef (econf_file *kf, const char *group,
187           const char *key, int64_t *result, int64_t def)
188           Evaluating int64 value for given group/key.
189       econf_err econf_getUIntValueDef (econf_file *kf, const char *group,
190           const char *key, uint32_t *result, uint32_t def)
191           Evaluating uint32 value for given group/key.
192       econf_err econf_getUInt64ValueDef (econf_file *kf, const char *group,
193           const char *key, uint64_t *result, uint64_t def)
194           Evaluating uint64 value for given group/key.
195       econf_err econf_getFloatValueDef (econf_file *kf, const char *group,
196           const char *key, float *result, float def)
197           Evaluating float value for given group/key.
198       econf_err econf_getDoubleValueDef (econf_file *kf, const char *group,
199           const char *key, double *result, double def)
200           Evaluating double value for given group/key.
201       econf_err econf_getStringValueDef (econf_file *kf, const char *group,
202           const char *key, char **result, char *def)
203           Evaluating string value for given group/key.
204       econf_err econf_getBoolValueDef (econf_file *kf, const char *group,
205           const char *key, bool *result, bool def)
206           Evaluating bool value for given group/key.
207       econf_err econf_setIntValue (econf_file *kf, const char *group, const
208           char *key, int32_t value)
209           Set int32 value for given group/key.
210       econf_err econf_setInt64Value (econf_file *kf, const char *group, const
211           char *key, int64_t value)
212           Set int64 value for given group/key.
213       econf_err econf_setUIntValue (econf_file *kf, const char *group, const
214           char *key, uint32_t value)
215           Set uint32 value for given group/key.
216       econf_err econf_setUInt64Value (econf_file *kf, const char *group,
217           const char *key, uint64_t value)
218           Set uint64 value for given group/key.
219       econf_err econf_setFloatValue (econf_file *kf, const char *group, const
220           char *key, float value)
221           Set float value for given group/key.
222       econf_err econf_setDoubleValue (econf_file *kf, const char *group,
223           const char *key, double value)
224           Set double value for given group/key.
225       econf_err econf_setStringValue (econf_file *kf, const char *group,
226           const char *key, const char *value)
227           Set string value for given group/key.
228       econf_err econf_setBoolValue (econf_file *kf, const char *group, const
229           char *key, const char *value)
230           Set bool value for given group/key.
231       const char * econf_errString (const econf_err error)
232           Convert an econf_err type to a string.
233       void econf_errLocation (char **filename, uint64_t *line_nr)
234           Info about where the error has happened.
235       void econf_freeArray (char **array)
236           Free an array of type char** created by econf_getGroups() or
237           econf_getKeys().
238       void econf_freeFile (econf_file *key_file)
239           Free memory allocated by e.g.
240       char econf_comment_tag (econf_file *key_file)
241           Returns the comment character tag of the given econf_file object.
242       char econf_delimiter_tag (econf_file *key_file)
243           Returns the delimiter character of the given econf_file object.
244       void econf_set_comment_tag (econf_file *key_file, const char comment)
245           Set the comment character tag of the given econf_file object.
246       void econf_set_delimiter_tag (econf_file *key_file, const char
247           delimiter)
248           Set the delimiter character of the given econf_file object.
249       econf_err econf_getExtValue (econf_file *kf, const char *group, const
250       char *key, econf_ext_value **result)
251           Evaluating more information for given group/key.
252       void econf_freeExtValue (econf_ext_value *to_free)
253           Free an complete econf_ext_value struct.
254       econf_err econf_set_conf_dirs (const char **dir_postfix_list)
255           Sets a list of directory structures (with order) which describes
256           the directories in which the files have to be parsed.
257

Detailed Description

259       Public API for the econf library.
260
261
262
263       Definition in file libeconf.h and libeconf_ext.h.
264
265

Typedef Documentation

267   typedef struct econf_file econf_file
268       Container which includes all information about the configuration
269       file(s).
270
271   typedef struct econf_ext_value econf_ext_value
272       char ** values
273           Values of a given key in form of an string array.
274       char * file
275           Path of the configuration file where this value has been read.
276       uint64_t line_number
277           Line number of the configuration key/value.
278       char * comment_before_key
279           Comment before the key/value entry.
280       char * comment_after_value
281           Comment after the value entry.
282
283
284

Enumeration Type Documentation

286   enum econf_err
287       libeconf error codes
288
289       Enumerator
290
291       ECONF_SUCCESS
292              General purpose success code.
293
294       ECONF_ERROR
295              Generic Error.
296
297       ECONF_NOMEM
298              Out of memory.
299
300       ECONF_NOFILE
301              Config file not found.
302
303       ECONF_NOGROUP
304              Group not found.
305
306       ECONF_NOKEY
307              Key not found.
308
309       ECONF_EMPTYKEY
310              Key has empty value.
311
312       ECONF_WRITEERROR
313              Error creating or writing to a file.
314
315       ECONF_PARSE_ERROR
316              General syntax error in input file.
317
318       ECONF_MISSING_BRACKET
319              Missing closing section bracket.
320
321       ECONF_MISSING_DELIMITER
322              Missing delimiter.
323
324       ECONF_EMPTY_SECTION_NAME
325              Empty section name.
326
327       ECONF_TEXT_AFTER_SECTION
328              Text after section.
329
330       ECONF_FILE_LIST_IS_NULL
331              Parsed file list is NULL.
332
333       ECONF_WRONG_BOOLEAN_VALUE
334              Wrong boolean value (1/0 true/false yes/no)
335
336       ECONF_KEY_HAS_NULL_VALUE
337              Given key has NULL value.
338
339       ECONF_WRONG_OWNER
340              File has wrong owner.
341
342       ECONF_WRONG_GROUP
343              File has wrong group.
344
345       ECONF_WRONG_FILE_PERMISSION
346              File has wrong file permissions.
347
348       ECONF_WRONG_DIR_PERMISSION
349              File has wrong dir permissions.
350
351       ECONF_ERROR_FILE_IS_SYM_LINK
352              File is a sym link which is not permitted.
353
354       ECONF_PARSING_CALLBACK_FAILED
355              User defined parsing callback has failed.
356

Function Documentation

358   econf_err econf_readFile (econf_file ** result, const char * file_name,
359       const char * delim, const char * comment)
360       Process the file of the given file_name and save its contents into
361       key_file object.
362
363       Parameters:
364           result content of parsed file
365           file_name absolute path of parsed file
366           delim delimiters of key/value e.g. '\t ='
367           comment array of characters which define the start of a comment
368
369       Returns:
370           econf_err ECONF_SUCCESS or error code
371
372       Usage:
373
374       #include "libeconf.h"
375
376       econf_file *key_file = NULL;
377       econf_err error;
378
379       error = econf_readFile (&key_file, "/etc/test.conf", "=", "#");
380
381       econf_free (key_file);
382
383
384       Default behaviour if entries have the same name in one file: The first
385       hit will be returned. Further entries will be ignored. This can be
386       changed by setting the environment variable ECONF_JOIN_SAME_ENTRIES. In
387       that case entries with the same name will be joined to one single
388       entry.
389
390
391   econf_err econf_readFileWithCallback (econf_file ** result, const char *
392       file_name, const char * delim, const char * comment, bool
393       (*callback)(const char *filename, const void *data), const void
394       *callback_data)
395       Process the file of the given file_name and save its contents into
396       key_file object. The user defined function will be called in order e.g.
397       to check the correct file permissions.
398
399       Parameters:
400           result content of parsed file
401           file_name absolute path of parsed file
402           delim delimiters of key/value e.g. '\t ='
403           comment array of characters which define the start of a comment
404           callback function which will be called for the given filename. This
405           user defined function has the pathname as paramter and returns true
406           if this file can be parsed. If not, the parsing will be aborted and
407           ECONF_PARSING_CALLBACK_FAILED will be returned.
408           callback_data pointer which will be given to the callback function.
409
410       Returns:
411           econf_err ECONF_SUCCESS or error code
412
413       Usage:
414
415       #include "libeconf.h"
416       bool checkFile(const char *filename, const void *data) {
417         /* checking code which returns true or false */
418         return true;
419       }
420
421       econf_file *key_file = NULL;
422       econf_err error;
423
424       error = econf_readFileWithCallback (&key_file, "/etc/test.conf", "=", "#", checkFile, NULL);
425       econf_free (key_file);
426
427       Default behaviour if entries have the same name in one file: The first
428       hit will be returned. Further entries will be ignored. This can be
429       changed by setting the environment variable ECONF_JOIN_SAME_ENTRIES. In
430       that case entries with the same name will be joined to one single
431       entry.
432
433
434   econf_err econf_mergeFiles (econf_file ** merged_file, econf_file *
435       usr_file, econf_file * etc_file)
436       Merge the contents of two key_files objects. Entries in etc_file will
437       be prefered. Comment and delimiter tag will be taken from usr_file.
438       This can be changed by calling the functions econf_set_comment_tag and
439       econf_set_delimiter_tag.
440
441       Parameters:
442           merged_file merged data
443           usr_file First data block which has to be merged.
444           etc_file Second data block which has to be merged.
445
446       Returns:
447           econf_err ECONF_SUCCESS or error code
448
449       Usage:
450
451       #include "libeconf.h"
452
453       econf_file *key_file_1 = NULL, *key_file_2 = NULL, *key_file_ret = NULL
454       econf_err error;
455
456       error = econf_readFile (&key_file1, "/usr/etc/test.conf", "=", "#");
457       error = econf_readFile (&key_file2, /etc/test.conf", "=", "#");
458       error = econf_mergeFiles (&key_file_ret, key_file_1, key_file_2);
459
460       econf_free (key_file_ret);
461       econf_free (key_file_1);
462       econf_free (key_file_2);
463
464
465   econf_err econf_readDirs (econf_file ** key_file, const char *
466       usr_conf_dir, const char * etc_conf_dir, const char * project_name,
467       const char * config_suffix, const char * delim, const char * comment)
468       Evaluating the content of a given configuration file by reading all
469       needed/available files in two different directories (normally in
470       /usr/etc and /etc).
471
472       Parameters:
473           key_file content of parsed file(s)
474           usr_conf_dir absolute path of the first directory (normally
475           '/usr/etc')
476           etc_conf_dir absolute path of the second directory (normally
477           '/etc')
478           project_name basename of the configuration file
479           config_suffix suffix of the configuration file. Can also be NULL.
480           delim delimiters of key/value e.g. '\t ='
481           comment array of characters which define the start of a comment
482
483       Returns:
484           econf_err ECONF_SUCCESS or error code
485
486       Example: Reading content of example.conf in /usr/etc and /etc
487       directory.
488
489       #include "libeconf.h"
490
491       econf_file *key_file = NULL;
492       econf_err error;
493
494       error = econf_readDirs (&key_file,
495                               "/usr/etc",
496                               "/etc",
497                               "example",
498                               "conf",
499                               "=", "#");
500
501       econf_free (key_file);
502
503
504   econf_err econf_readDirsWithCallback (econf_file ** key_file, const char *
505       usr_conf_dir, const char * etc_conf_dir, const char * project_name,
506       const char * config_suffix, const char * delim, const char * comment,
507       bool (*callback)(const char *filename, const void *data), const void
508       *callback_data)
509       Evaluating the content of a given configuration file by reading all
510       needed/available files in two different directories (normally in
511       /usr/etc and /etc). For each parsed file the user defined function will
512       be called in order e.g. to check the correct file permissions.
513
514       Parameters:
515           key_file content of parsed file(s)
516           usr_conf_dir absolute path of the first directory (normally
517           '/usr/etc')
518           etc_conf_dir absolute path of the second directory (normally
519           '/etc')
520           project_name basename of the configuration file
521           config_suffix suffix of the configuration file. Can also be NULL.
522           delim delimiters of key/value e.g. '\t ='
523           comment array of characters which define the start of a comment
524           callback function which will be called for each file. This user
525           defined function has the pathname as paramter and returns true if
526           this file can be parsed. If not, the parsing of all files will be
527           aborted and ECONF_PARSING_CALLBACK_FAILED will be returned.
528           callback_data pointer which will be given to the callback function.
529
530       Returns:
531           econf_err ECONF_SUCCESS or error code
532
533       Example: Reading content of example.conf in /usr/etc and /etc
534       directory.
535
536       #include "libeconf.h"
537
538       bool checkFile(const char *filename, const void *data) {
539         /* checking code which returns true or false */
540         return true;
541       }
542
543       econf_file *key_file = NULL;
544       econf_err error;
545
546       error = econf_readDirsWithCallback (&key_file,
547                                         "/usr/etc",
548                                         "/etc",
549                                         "example",
550                                         "conf",
551                                         "=", "#",
552                                         checkFile,
553                                         NULL);
554
555       econf_free (key_file);
556
557   econf_err econf_readDirsHistory (econf_file *** key_files, size_t * size,
558       const char * usr_conf_dir, const char * etc_conf_dir, const char *
559       project_name, const char * config_suffix, const char * delim, const
560       char * comment)
561       Evaluating key/values for every given configuration files in two
562       different directories (normally in /usr/etc and /etc). Returns a list
563       of read configuration files and their values.
564
565       Parameters:
566           key_files list of parsed file(s). Each entry includes all
567           key/value, path, comments,... information of the regarding file.
568           size Size of the evaluated key_files list.
569           usr_conf_dir absolute path of the first directory (normally
570           '/usr/etc')
571           etc_conf_dir absolute path of the second directory (normally
572           '/etc')
573           project_name basename of the configuration file
574           config_suffix suffix of the configuration file. Can also be NULL.
575           delim delimiters of key/value e.g. '\t ='
576           comment array of characters which define the start of a comment
577
578       Returns:
579           econf_err ECONF_SUCCESS or error code
580
581   econf_err econf_readDirsHistoryWithCallback (econf_file *** key_files,
582       size_t * size, const char * usr_conf_dir, const char * etc_conf_dir,
583       const char * project_name, const char * config_suffix, const char *
584       delim, const char * comment, bool (*callback)(const char *filename,
585       const void *data), const void *callback_data)
586       Evaluating key/values for every given configuration files in two
587       different directories (normally in /usr/etc and /etc). For each parsed
588       file the user defined function will be called in order e.g. to check
589       the correct file permissions. Returns a list of read configuration
590       files and their values.
591
592       Parameters:
593           key_files list of parsed file(s). Each entry includes all
594           key/value, path, comments,... information of the regarding file.
595           size Size of the evaluated key_files list.
596           usr_conf_dir absolute path of the first directory (normally
597           '/usr/etc')
598           etc_conf_dir absolute path of the second directory (normally
599           '/etc')
600           project_name basename of the configuration file
601           config_suffix suffix of the configuration file. Can also be NULL.
602           delim delimiters of key/value e.g. '\t ='
603           comment array of characters which define the start of a comment
604           callback function which will be called for each file. This user
605           defined function has the pathname as paramter and returns true if
606           this file can be parsed. If not, the parsing of all files will be
607           aborted and ECONF_PARSING_CALLBACK_FAILED will be returned.
608           callback_data pointer which will be given to the callback function.
609
610       Returns:
611           econf_err ECONF_SUCCESS or error code
612
613   econf_err econf_newKeyFile (econf_file ** result, char delimiter, char
614       comment)
615       Create a new econf_file object.
616
617       Parameters:
618           result Pointer to the allocated econf_file object.
619           delimiter delimiter of key/value e.g. '='
620           comment Character which defines the start of a comment.
621
622       Returns:
623           econf_err ECONF_SUCCESS or error code
624
625   econf_err econf_newIniFile (econf_file ** result)
626       Create a new econf_file object in IniFile format. So the delimiter will
627       be '=' and comments are beginning with '#'.
628
629       Parameters:
630           result Pointer to the allocated econf_file object.
631
632       Returns:
633           econf_err ECONF_SUCCESS or error code
634
635   econf_err econf_writeFile (econf_file * key_file, const char * save_to_dir,
636       const char * file_name)
637       Write content of a econf_file struct to specified location.
638
639       Parameters:
640           key_file Data which has to be written.
641           save_to_dir Directory into which the file has to be written.
642           file_name filename (with suffix)
643
644       Returns:
645           econf_err ECONF_SUCCESS or error code
646
647   char* econf_getPath (econf_file * kf)
648       Evaluating path name.
649
650       Parameters:
651           kf given/parsed data
652
653       Returns:
654           Absolute path name or an empty string if kf is a result of already
655           merged data (e.G. returned by econf_readDirs).
656
657   econf_err econf_getGroups (econf_file * kf, size_t * length, char ***
658       groups)
659       Evaluating all group entries.
660
661       Parameters:
662           kf given/parsed data
663           length Length of the returned group array.
664           groups String array of evaluated groups.
665
666       Returns:
667           econf_err ECONF_SUCCESS or error code
668
669   econf_err econf_getKeys (econf_file * kf, const char * group, size_t *
670       length, char *** keys)
671       Evaluating all keys.
672
673       Parameters:
674           kf given/parsed data
675           group Group name for which the keys have to be evaluated or NULL
676           for all keys.
677           length Length of the returned key array.
678           keys String array of evaluated keys.
679
680       Returns:
681           econf_err ECONF_SUCCESS or error code
682
683   econf_err econf_getIntValue (econf_file * kf, const char * group, const
684       char * key, int32_t * result)
685       Evaluating int32 value for given group/key.
686
687       Parameters:
688           kf given/parsed data
689           group Desired group or NULL if there is no group defined.
690           key Key for which the value is requested.
691           result determined value
692
693       Returns:
694           econf_err ECONF_SUCCESS or error code
695
696   econf_err econf_getInt64Value (econf_file * kf, const char * group, const
697       char * key, int64_t * result)
698       Evaluating int64 value for given group/key.
699
700       Parameters:
701           kf given/parsed data
702           group Desired group or NULL if there is no group defined.
703           key Key for which the value is requested.
704           result determined value
705
706       Returns:
707           econf_err ECONF_SUCCESS or error code
708
709   econf_err econf_getUIntValue (econf_file * kf, const char * group, const
710       char * key, uint32_t * result)
711       Evaluating uint32 value for given group/key.
712
713       Parameters:
714           kf given/parsed data
715           group Desired group or NULL if there is no group defined.
716           key Key for which the value is requested.
717           result determined value
718
719       Returns:
720           econf_err ECONF_SUCCESS or error code
721
722   econf_err econf_getUInt64Value (econf_file * kf, const char * group, const
723       char * key, uint64_t * result)
724       Evaluating uint64 value for given group/key.
725
726       Parameters:
727           kf given/parsed data
728           group Desired group or NULL if there is no group defined.
729           key Key for which the value is requested.
730           result determined value
731
732       Returns:
733           econf_err ECONF_SUCCESS or error code
734
735   econf_err econf_getFloatValue (econf_file * kf, const char * group, const
736       char * key, float * result)
737       Evaluating float value for given group/key.
738
739       Parameters:
740           kf given/parsed data
741           group Desired group or NULL if there is no group defined.
742           key Key for which the value is requested.
743           result determined value
744
745       Returns:
746           econf_err ECONF_SUCCESS or error code
747
748   econf_err econf_getDoubleValue (econf_file * kf, const char * group, const
749       char * key, double * result)
750       Evaluating double value for given group/key.
751
752       Parameters:
753           kf given/parsed data
754           group Desired group or NULL if there is no group defined.
755           key Key for which the value is requested.
756           result determined value
757
758       Returns:
759           econf_err ECONF_SUCCESS or error code
760
761   econf_err econf_getStringValue (econf_file * kf, const char * group, const
762       char * key, char ** result)
763       Evaluating string value for given group/key.
764
765       Parameters:
766           kf given/parsed data
767           group Desired group or NULL if there is no group defined.
768           key Key for which the value is requested.
769           result A newly allocated string or NULL in error case.
770
771       Returns:
772           econf_err ECONF_SUCCESS or error code
773
774   econf_err econf_getBoolValue (econf_file * kf, const char * group, const
775       char * key, bool * result)
776       Evaluating bool value for given group/key.
777
778       Parameters:
779           kf given/parsed data
780           group Desired group or NULL if there is no group defined.
781           key Key for which the value is requested.
782           result determined value
783
784       Returns:
785           econf_err ECONF_SUCCESS or error code
786
787   econf_err econf_getIntValueDef (econf_file * kf, const char * group, const
788       char * key, int32_t * result, int32_t def)
789       Evaluating int32 value for given group/key. If key is not found, the
790       default value is returned and error is ECONF_NOKEY.
791
792       Parameters:
793           kf given/parsed data
794           group Desired group or NULL if there is no group defined.
795           key Key for which the value is requested.
796           result determined value
797           def Default value if the value has not been found.
798
799       Returns:
800           econf_err ECONF_SUCCESS or error code
801
802   econf_err econf_getInt64ValueDef (econf_file * kf, const char * group,
803       const char * key, int64_t * result, int64_t def)
804       Evaluating int64 value for given group/key. If key is not found, the
805       default value is returned and error is ECONF_NOKEY.
806
807       Parameters:
808           kf given/parsed data
809           group Desired group or NULL if there is no group defined.
810           key Key for which the value is requested.
811           result determined value
812           def Default value if the value has not been found.
813
814       Returns:
815           econf_err ECONF_SUCCESS or error code
816
817   econf_err econf_getUIntValueDef (econf_file * kf, const char * group, const
818       char * key, uint32_t * result, uint32_t def)
819       Evaluating uint32 value for given group/key. If key is not found, the
820       default value is returned and error is ECONF_NOKEY.
821
822       Parameters:
823           kf given/parsed data
824           group Desired group or NULL if there is no group defined.
825           key Key for which the value is requested.
826           result determined value
827           def Default value if the value has not been found.
828
829       Returns:
830           econf_err ECONF_SUCCESS or error code
831
832   econf_err econf_getUInt64ValueDef (econf_file * kf, const char * group,
833       const char * key, uint64_t * result, uint64_t def)
834       Evaluating uint64 value for given group/key. If key is not found, the
835       default value is returned and error is ECONF_NOKEY.
836
837       Parameters:
838           kf given/parsed data
839           group Desired group or NULL if there is no group defined.
840           key Key for which the value is requested.
841           result determined value
842           def Default value if the value has not been found.
843
844       Returns:
845           econf_err ECONF_SUCCESS or error code
846
847   econf_err econf_getFloatValueDef (econf_file * kf, const char * group,
848       const char * key, float * result, float def)
849       Evaluating float value for given group/key. If key is not found, the
850       default value is returned and error is ECONF_NOKEY.
851
852       Parameters:
853           kf given/parsed data
854           group Desired group or NULL if there is no group defined.
855           key Key for which the value is requested.
856           result determined value
857           def Default value if the value has not been found.
858
859       Returns:
860           econf_err ECONF_SUCCESS or error code
861
862   econf_err econf_getDoubleValueDef (econf_file * kf, const char * group,
863       const char * key, double * result, double def)
864       Evaluating double value for given group/key. If key is not found, the
865       default value is returned and error is ECONF_NOKEY.
866
867       Parameters:
868           kf given/parsed data
869           group Desired group or NULL if there is no group defined.
870           key Key for which the value is requested.
871           result determined value
872           def Default value if the value has not been found.
873
874       Returns:
875           econf_err ECONF_SUCCESS or error code
876
877   econf_err econf_getStringValueDef (econf_file * kf, const char * group,
878       const char * key, char ** result, char * def)
879       Evaluating string value for given group/key. If key is not found, the
880       default value is returned and error is ECONF_NOKEY.
881
882       Parameters:
883           kf given/parsed data
884           group Desired group or NULL if there is no group defined.
885           key Key for which the value is requested.
886           result Returns a newly allocated string, even if 'default' is
887           returned.
888           def Default value if the value has not been found.
889
890       Returns:
891           econf_err ECONF_SUCCESS or error code
892
893   econf_err econf_getBoolValueDef (econf_file * kf, const char * group, const
894       char * key, bool * result, bool def)
895       Evaluating bool value for given group/key. If key is not found, the
896       default value is returned and error is ECONF_NOKEY.
897
898       Parameters:
899           kf given/parsed data
900           group Desired group or NULL if there is no group defined.
901           key Key for which the value is requested.
902           result determined value
903           def Default value if the value has not been found.
904
905       Returns:
906           econf_err ECONF_SUCCESS or error code
907
908   econf_err econf_setIntValue (econf_file * kf, const char * group, const
909       char * key, int32_t value)
910       Set int32 value for given group/key.
911
912       Parameters:
913           kf given/parsed data
914           group Desired group or NULL if there is no group defined.
915           key Key for which the value has to be set.
916           value Value which has to be set.
917
918       Returns:
919           econf_err ECONF_SUCCESS or error code
920
921   econf_err econf_setInt64Value (econf_file * kf, const char * group, const
922       char * key, int64_t value)
923       Set int64 value for given group/key.
924
925       Parameters:
926           kf given/parsed data
927           group Desired group or NULL if there is no group defined.
928           key Key for which the value has to be set.
929           value Value which has to be set.
930
931       Returns:
932           econf_err ECONF_SUCCESS or error code
933
934   econf_err econf_setUIntValue (econf_file * kf, const char * group, const
935       char * key, uint32_t value)
936       Set uint32 value for given group/key.
937
938       Parameters:
939           kf given/parsed data
940           group Desired group or NULL if there is no group defined.
941           key Key for which the value has to be set.
942           value Value which has to be set.
943
944       Returns:
945           econf_err ECONF_SUCCESS or error code
946
947   econf_err econf_setUInt64Value (econf_file * kf, const char * group, const
948       char * key, uint64_t value)
949       Set uint64 value for given group/key.
950
951       Parameters:
952           kf given/parsed data
953           group Desired group or NULL if there is no group defined.
954           key Key for which the value has to be set.
955           value Value which has to be set.
956
957       Returns:
958           econf_err ECONF_SUCCESS or error code
959
960   econf_err econf_setFloatValue (econf_file * kf, const char * group, const
961       char * key, float value)
962       Set float value for given group/key.
963
964       Parameters:
965           kf given/parsed data
966           group Desired group or NULL if there is no group defined.
967           key Key for which the value has to be set.
968           value Value which has to be set.
969
970       Returns:
971           econf_err ECONF_SUCCESS or error code
972
973   econf_err econf_setDoubleValue (econf_file * kf, const char * group, const
974       char * key, double value)
975       Set double value for given group/key.
976
977       Parameters:
978           kf given/parsed data
979           group Desired group or NULL if there is no group defined.
980           key Key for which the value has to be set.
981           value Value which has to be set.
982
983       Returns:
984           econf_err ECONF_SUCCESS or error code
985
986   econf_err econf_setStringValue (econf_file * kf, const char * group, const
987       char * key, const char * value)
988       Set string value for given group/key.
989
990       Parameters:
991           kf given/parsed data
992           group Desired group or NULL if there is no group defined.
993           key Key for which the value has to be set.
994           value Value which has to be set.
995
996       Returns:
997           econf_err ECONF_SUCCESS or error code
998
999   econf_err econf_setBoolValue (econf_file * kf, const char * group, const
1000       char * key, const char * value)
1001       Set bool value for given group/key.
1002
1003       Parameters:
1004           kf given/parsed data
1005           group Desired group or NULL if there is no group defined.
1006           key Key for which the value has to be set.
1007           value Value which has to be set.
1008
1009       Returns:
1010           econf_err ECONF_SUCCESS or error code
1011
1012   const char* econf_errString (const econf_err error)
1013       Convert an econf_err type to a string.
1014
1015       Parameters:
1016           error error enum
1017
1018       Returns:
1019           human readable string
1020
1021   void econf_errLocation (char ** filename, uint64_t * line_nr)
1022       Info about where the error has happened.
1023
1024       Parameters:
1025           filename Path of the last scanned file.
1026           line_nr Number of the last handled line.
1027
1028   void econf_freeArray (char ** array)
1029       Free an array of type char** created by econf_getGroups() or
1030       econf_getKeys().
1031
1032       Parameters:
1033           array array of strings
1034
1035       Returns:
1036           void
1037
1038   void econf_freeFile (econf_file * key_file)
1039       Free memory allocated by e.g. econf_readFile(), econf_readDirs(),...
1040
1041       Parameters:
1042           key_file allocated data
1043
1044       Returns:
1045           void
1046
1047   char econf_comment_tag (econf_file * key_file)
1048       Returns the comment character tag of the given econf_file object. This
1049       tag will be taken while writing comments to file.
1050
1051       Parameters:
1052           key_file econf_file object.
1053
1054       Returns:
1055           char comment character tag
1056
1057   char econf_delimiter_tag (econf_file * key_file)
1058       Returns the delimiter character of the given econf_file object. This
1059       delimiter will be taken while writing the data to file.
1060
1061       Parameters:
1062           key_file econf_file object.
1063
1064       Returns:
1065           char delimiter of key/value
1066
1067   void econf_set_comment_tag (econf_file * key_file, const char comment)
1068       Set the comment character tag of the given econf_file object. This tag
1069       will be taken while writing comments to file.
1070
1071       Parameters:
1072           key_file econf_file object.
1073           comment comment tag
1074
1075   void econf_set_delimiter_tag (econf_file * key_file, const char delimiter)
1076       Set the delimiter character of the given econf_file object. This
1077       delimiter will be taken while writing the data to file.
1078
1079       Parameters:
1080           key_file econf_file object.
1081           delimiter delimiter of key/value
1082
1083   econf_err econf_getExtValue (econf_file * kf, const char * group, const
1084       char * key, econf_ext_value ** result)
1085       Evaluating more information for given group/key.
1086
1087       Parameters:
1088           kf given/parsed data
1089           group Desired group or NULL if there is no group defined.
1090           key Key for which the value is requested.
1091           result A newly allocated struct or NULL in error case.
1092
1093       Returns:
1094           econf_err ECONF_SUCCESS or error code
1095
1096   void econf_freeExtValue (econf_ext_value * to_free)
1097       Free an complete econf_ext_value struct.
1098
1099       Parameters:
1100           to_free struct which has to be freed
1101
1102       Returns:
1103           void
1104
1105   econf_err econf_set_conf_dirs (const char **dir_postfix_list)
1106       Sets a list of directory structures (with order) which describes the
1107       directories in which the files have to be parsed.
1108
1109       Parameters:
1110           dir_postfix_list list of directory structures.  E.G. with the given
1111           list: {"/conf.d/", ".d/", "/", NULL} files in following directories
1112           will be parsed: <default_dirs>/<project_name>.<suffix>.d/
1113           <default_dirs>/<project_name>/conf.d/,
1114           <default_dirs>/<project_name>.d/, <default_dirs>/<project_name>/.
1115           The entry <default_dirs>/<project_name>.<suffix>.d/ will be added
1116           automatically.
1117
1118       Returns:
1119           econf_err ECONF_SUCCESS or error code
1120