5 Author: Johnny Mnemonic <johnny@themnemonic.org>
7 Copyright (C) 1997 - 2002 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; either version 2 of the License, or
12 (at your option) any later version.
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License for more details.
21 /****h* silcutil/SILC Config Interface
25 * The SILC Config util library is based on two main objects, SilcConfigFile
26 * (or File object) and SilcConfigEntity (or Entity). The File objects are
27 * structs directly corresponding to the real files in the filesystem, while
28 * Entities are a little more abstract.
30 * An Entity is composed by delimited area on a File object (it can take the
31 * whole File object or just part of it), plus a group of known options.
32 * In order to parse this file, first you need to create a File object with
33 * the silc_config_open() function, and then you need to create the Entity
34 * with the silc_config_init() function.
36 * Now you can use the newly created Entity to register a group of expected
37 * known options and sub-blocks, and then you can call the main parsing loop
38 * with the silc_config_main() function. When silc_config_main() will
39 * return, if some error encoured the object file will point to the file
40 * that caused this error (this can be different from the originally
41 * opened file if it contained `Include' directives). If no errors
42 * encoured then the File objects will still point to the original file.
44 * While silc_config_main() will take care of destroying Entities before
45 * returning, you need to take care that the File object you created is freed
46 * with the silc_config_close() function.
48 * The SILC Config library won't take care about storing the values contained
49 * in the config file. You must take care about it with the callback
52 * The config file syntax is pretty straightforward. All lines starting
53 * with `#' will be skipped, while sub-blocks are delimited by braces (see
56 * Options with argument must have the `=' character between the option
57 * name and the value. Simple words and numbers does not require quoting.
58 * There is a special built-in directive "Include" which allows you to include
59 * another config file in the point the directive is. You can also Include
60 * inside a sub-block body, in this case when parsing the included config file
61 * it will be assumed that we are within this block, and the included file
62 * won't be allowed to close his root block.
68 * module = "aes.sim.so";
69 * key_length = 32; # usually the default is just fine
72 * Include "/etc/silc/hash_funcs.conf";
79 /****d* silcutil/SilcConfigAPI/SilcConfigErrno
83 * enum { ... } - describe a SILC Config error
87 * The virtual integer `errno' is returned by the silc_config_main()
88 * function and indicates what went wrong.
89 * You can convert it to the corresponding error string with the function
90 * silc_config_strerror().
95 SILC_CONFIG_OK, /* OK */
96 SILC_CONFIG_ESILENT, /* Error defined by callback function */
97 SILC_CONFIG_EPRINTLINE, /* Error defined by callback function */
98 SILC_CONFIG_EGENERIC, /* Invalid syntax */
99 SILC_CONFIG_EINTERNAL, /* Internal Error (caused by developer) */
100 SILC_CONFIG_ECANTOPEN, /* Can't open specified file */
101 SILC_CONFIG_EOPENBRACE, /* Expected open-brace '{' */
102 SILC_CONFIG_ECLOSEBRACE, /* Missing close-brace '}' */
103 SILC_CONFIG_ETYPE, /* Invalid data type */
104 SILC_CONFIG_EBADOPTION, /* Unknown option */
105 SILC_CONFIG_EINVALIDTEXT, /* Invalid text */
106 SILC_CONFIG_EDOUBLE, /* Double option specification */
107 SILC_CONFIG_EEXPECTED, /* Expected data but not found */
108 SILC_CONFIG_EEXPECTEDEQUAL, /* Expected '=' */
109 SILC_CONFIG_EUNEXPECTED, /* Unexpected data */
110 SILC_CONFIG_EMISSFIELDS, /* Missing mandatory fields */
111 SILC_CONFIG_EMISSCOLON, /* Missing ';' */
115 /****d* silcutil/SilcConfigAPI/SilcConfigType
119 * typedef enum { ... } SilcConfigType;
123 * This identifies the parameter type that an option has. This parameter
124 * is very important because the callback's *val pointer points to a
125 * memory location containing the previously specified data type.
126 * For example, if you specified an option with an integer parameter
127 * callback's *val will be a pointer to an integer.
132 SILC_CONFIG_ARG_TOGGLE, /* TOGGLE on,off; yes,no; true, false; */
133 SILC_CONFIG_ARG_INT, /* callback wants an integer */
134 SILC_CONFIG_ARG_STR, /* callback expects \0-terminated str */
135 SILC_CONFIG_ARG_STRE, /* same as above, but can also be empty */
136 SILC_CONFIG_ARG_BLOCK, /* this is a sub-block */
137 SILC_CONFIG_ARG_SIZE, /* like int, but accepts suffixes kMG */
138 SILC_CONFIG_ARG_NONE, /* does not expect any args */
142 /****f* silcutil/SilcConfigAPI/SilcConfigCallback
146 * typedef int (*SilcConfigCallback)(SilcConfigType type, const char *name,
147 * SilcUInt32 line, void *val,
151 * This is the callback prototype for the options handler. The pointer
152 * `val' points to a location of type described by `type'. `name' points
153 * to a null-terminated string with the name of the option which triggered
154 * this callback, that is stated at line `line'. `context' is the
155 * user-specified context provided when this option was registered.
158 typedef int (*SilcConfigCallback)(SilcConfigType type, const char *name,
159 SilcUInt32 line, void *val, void *context);
161 /****s* silcutil/SilcConfigAPI/SilcConfigTable
165 * typedef struct { ... } SilcConfigTable;
169 * SILC Config table defines an easy and quick way of registering options
170 * in an entity. The function silc_config_register_table() will take as
171 * argument a SilcConfigTable array terminated by a NULL struct, it is
172 * important thus, that the `name' field of the terminating struct is set
177 * The option name lowercase. The matching is always case-insensitive,
178 * but for convention the option specification must always be lowercase.
180 * SilcConfigType type
182 * This specifies what kind of parameter this option expects. The
183 * special cases SILC_CONFIG_ARG_BLOCK tells SILC Config that this is
184 * not a normal option but the name of a sub-block of the current
185 * block (there is no limit to the number of nested blocks allowed).
187 * SilcConfigCallback callback
189 * Normally this is the value handler of the current option. If this
190 * field is set to NULL then the value is silently discarded. Useful
191 * for example to support deprecated options.
193 * SilcConfigTable *subtable
195 * If the `type' field is set to SILC_CONFIG_ARG_BLOCK, then this field
196 * must point to a valid sub-table NULL-terminated array. If `type' is
197 * something else, this valued is unused.
200 typedef struct SilcConfigTableStruct {
203 SilcConfigCallback callback;
204 const struct SilcConfigTableStruct *subtable;
207 /****s* silcutil/SilcConfigAPI/SilcConfigFile
211 * typedef struct SilcConfigFileObject SilcConfigFile;
215 * A File object holds the data contained in a previously loaded file by
216 * the silc_config_open() function.
217 * This is an internally allocated struct and must be used only with the
221 typedef struct SilcConfigFileObject SilcConfigFile;
223 /****s* silcutil/SilcConfigAPI/SilcConfigEntity
227 * typedef struct SilcConfigEntityObject *SilcConfigEntity;
231 * The SILC Config is based on config entities. An entity contains the
232 * SilcConfigFile object we are parsing and the registered options.
235 typedef struct SilcConfigEntityObject *SilcConfigEntity;
239 /****d* silcutil/SilcConfigAPI/SILC_CONFIG_CALLBACK
243 * #define SILC_CONFIG_CALLBACK ...
247 * Generic macro to define SilcConfigCallback functions. This defines a
248 * static function with name `func' as a config callback function.
252 #define SILC_CONFIG_CALLBACK(func) \
253 static int func(SilcConfigType type, const char *name, \
254 SilcUInt32 line, void *val, void *context)
259 /****f* silcutil/SilcConfigAPI/silc_config_open
263 * SilcConfigFile *silc_config_open(char *configfile);
267 * Tries to open the config file `configfile' and returns a valid File
268 * object on success, or NULL on failure.
269 * An File object created this way must be destroyed with the function
270 * silc_config_close().
273 SilcConfigFile *silc_config_open(const char *configfile);
275 /****f* silcutil/SilcConfigAPI/silc_config_close
279 * void silc_config_close(SilcConfigFile *file);
283 * Closes and frees the File object `file', which must have been returned
284 * by a previous call to silc_config_open(). Otherwise, or if
285 * this function has already been called before for the same File object,
286 * undefined behaviour occurs.
287 * If `file' is NULL, no operation is performed.
290 void silc_config_close(SilcConfigFile *file);
292 /****f* silcutil/SilcConfigAPI/silc_config_init
296 * SilcConfigEntity silc_config_init(SilcConfigFile *file);
300 * Creates an Entity pointing to the valid File object `file', which must
301 * be returned by a previous call to silc_config_open(), otherwise NULL
303 * Entities will be automatically destroyed after the call to the
304 * silc_config_main() function, because of this no uninit functions are
308 SilcConfigEntity silc_config_init(SilcConfigFile *file);
310 /****f* silcutil/SilcConfigAPI/silc_config_strerror
314 * char *silc_config_strerror(int errnum);
318 * The silc_config_strerror() function returns a string describing the
319 * error code passed in the argument `errnum'.
322 char *silc_config_strerror(int errnum);
324 /****f* silcutil/SilcConfigAPI/silc_config_get_filename
328 * char *silc_config_get_filename(SilcConfigFile *file);
332 * Returns the original filename of the object file.
333 * The returned pointer points to internally allocated storage and must
334 * not be freed, modified or stored.
337 char *silc_config_get_filename(SilcConfigFile *file);
339 /****f* silcutil/SilcConfigAPI/silc_config_get_line
343 * SilcUInt32 silc_config_get_line(SilcConfigFile *file);
347 * Returns the current line that file parsing arrived at.
350 SilcUInt32 silc_config_get_line(SilcConfigFile *file);
352 /****f* silcutil/SilcConfigAPI/silc_config_read_line
356 * char *silc_config_read_line(SilcConfigFile *file, SilcUInt32 line);
360 * Returns a dynamically allocated null-terminated buffer containing the
361 * line `line' of `file'.
362 * The returned pointer must be freed when it's not needed any longer.
365 * silc_config_read_current_line
368 char *silc_config_read_line(SilcConfigFile *file, SilcUInt32 line);
370 /****f* silcutil/SilcConfigAPI/silc_config_read_current_line
374 * char *silc_config_read_current_line(SilcConfigFile *file);
378 * Returns a dynamically allocated buffer containing the line that the
379 * parser stopped at. This is a convenience function for
380 * silc_config_read_line.
381 * The returned pointer must be freed when it's not needed any longer.
384 char *silc_config_read_current_line(SilcConfigFile *file);
386 /****f* silcutil/SilcConfigAPI/silc_config_register
390 * bool silc_config_register(SilcConfigEntity ent, const char *name,
391 * SilcConfigType type, SilcConfigCallback cb,
392 * const SilcConfigTable *subtable,
397 * Register option `name' in the entity `ent'. If `cb' is not NULL, it
398 * will be called with the *val pointer pointing to an internally
399 * allocated storage of type described by `type'.
400 * If `type' is SILC_CONFIG_ARG_BLOCK, then `subtable' must be a valid
401 * pointer to a SilcConfigTable array specifying the options in the
403 * If the option `name' was already registered in this sub-block or it
404 * matches the reserved word "Include", then this function returns FALSE,
405 * otherwise it returns TRUE.
408 * silc_config_register_table
411 bool silc_config_register(SilcConfigEntity ent, const char *name,
412 SilcConfigType type, SilcConfigCallback cb,
413 const SilcConfigTable *subtable, void *context);
415 /****f* silcutil/SilcConfigAPI/silc_config_register_table
419 * bool silc_config_register_table(SilcConfigEntity ent,
420 * const SilcConfigTable table[],
425 * Register the tableset of options `table' automatically in the entity
426 * `ent'. If defined in the table, the callback functions will be called
427 * all with the same context `context'.
428 * The `table' array must be terminated with an entry with the name field
430 * If the table contains invalid data this function returns FALSE, otherwise
431 * it returns TRUE. If a calling to this function failed, you must destroy
432 * and recreate the entity before retrying, as it's impossible to detect
433 * the point at the function stopped the registering process.
439 bool silc_config_register_table(SilcConfigEntity ent,
440 const SilcConfigTable table[], void *context);
442 /****f* silcutil/SilcConfigAPI/silc_config_main
446 * int silc_config_main(SilcConfigEntity ent);
450 * Enter the main parsing loop. When this function returns the parsing
451 * is finished in the current block (and sub-blocks).
452 * When this function exits, the entity is already destroyed, because
453 * of this you should set it to NULL right after the function call.
456 int silc_config_main(SilcConfigEntity ent);
458 #endif /* !SILCCONFIG_H */