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/SilcConfigAPI
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.
29 * An Entity is composed by delimited area on a File object (it can take the
30 * 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.
35 * Now you can use the newly created Entity to register a group of expected
36 * known options and sub-blocks, and then you can call the main parsing loop
37 * with the silc_config_main() function.
38 * When silc_config_main() will return, if some error encoured the object file
39 * will point to the file that caused this error (this can be different from
40 * the originally opened file if it contained `Include' directives). If no
41 * errors encoured then the File objects will still point to the original
43 * While silc_config_main() will take care of destroying Entities before
44 * returning, you need to take care that the File object you created is freed
45 * with the silc_config_close() function.
47 * The SILC Config library won't take care about storing the values contained
48 * in the config file. You must take care about it with the callback
51 * The config file syntax is pretty straightforward. All lines starting
52 * with `#' will be skipped, while sub-blocks are delimited by braces (see
54 * Options with argument must have the `=' character between the option
55 * name and the value. Simple words and numbers does not require quoting.
56 * There is a special built-in directive "Include" which allows you to include
57 * another config file in the point the directive is. You can also Include
58 * inside a sub-block body, in this case when parsing the included config file
59 * it will be assumed that we are within this block, and the included file
60 * won't be allowed to close his root block.
66 * module = "aes.sim.so";
67 * key_length = 32; # usually the default is just fine
70 * Include "/etc/silc/hash_funcs.conf";
77 /****d* silcutil/SilcConfigAPI/errno
81 * enum { ... } - describe a SILC Config error
85 * The virtual integer `errno' is returned by the silc_config_main()
86 * function and indicates what went wrong.
87 * You can convert it to the corresponding error string with the function
88 * silc_config_strerror().
93 SILC_CONFIG_OK, /* OK */
94 SILC_CONFIG_ESILENT, /* Error defined by callback function */
95 SILC_CONFIG_EGENERIC, /* Invalid syntax */
96 SILC_CONFIG_EINTERNAL, /* Internal Error (caused by developer) */
97 SILC_CONFIG_ECANTOPEN, /* Can't open specified file */
98 SILC_CONFIG_EOPENBRACE, /* Expected open-brace '{' */
99 SILC_CONFIG_ECLOSEBRACE, /* Missing close-brace '}' */
100 SILC_CONFIG_ETYPE, /* Invalid data type */
101 SILC_CONFIG_EBADOPTION, /* Unknown option */
102 SILC_CONFIG_EINVALIDTEXT, /* Invalid text */
103 SILC_CONFIG_EDOUBLE, /* Double option specification */
104 SILC_CONFIG_EEXPECTED, /* Expected data but not found */
105 SILC_CONFIG_EEXPECTEDEQUAL, /* Expected '=' */
106 SILC_CONFIG_EUNEXPECTED, /* Unexpected data */
107 SILC_CONFIG_EMISSFIELDS, /* Missing mandatory fields */
108 SILC_CONFIG_EMISSCOLON, /* Missing ';' */
112 /****d* silcutil/SilcConfigAPI/SilcConfigType
116 * typedef enum { ... } SilcConfigType;
120 * This identifies the parameter type that an option has. This parameter
121 * is very important because the callback's *val pointer points to a
122 * memory location containing the previously specified data type.
123 * For example, if you specified an option with an integer parameter
124 * callback's *val will be a pointer to an integer.
129 SILC_CONFIG_ARG_TOGGLE, /* TOGGLE on,off; yes,no; true, false; */
130 SILC_CONFIG_ARG_INT, /* callback wants an integer */
131 SILC_CONFIG_ARG_STR, /* callback expects \0-terminated str */
132 SILC_CONFIG_ARG_STRE, /* same as above, but can also be empty */
133 SILC_CONFIG_ARG_BLOCK, /* this is a sub-block */
134 SILC_CONFIG_ARG_SIZE, /* like int, but accepts suffixes kMG */
135 SILC_CONFIG_ARG_NONE, /* does not expect any args */
139 /****f* silcutil/SilcConfigAPI/SilcConfigCallback
143 * typedef int (*SilcConfigCallback)(SilcConfigType type, const char *name,
144 * uint32 line, void *val, void *context);
147 * This is the callback prototype for the options handler. The pointer
148 * `val' points to a location of type described by `type'. `name' points
149 * to a null-terminated string with the name of the option which triggered
150 * this callback, that is stated at line `line'. `context' is the
151 * user-specified context provided when this option was registered.
154 typedef int (*SilcConfigCallback)(SilcConfigType type, const char *name,
155 uint32 line, void *val, void *context);
157 /****s* silcutil/SilcConfigAPI/SilcConfigTable
161 * typedef struct { ... } SilcConfigTable;
165 * SILC Config table defines an easy and quick way of registering options
166 * in an entity. The function silc_config_register_table() will take as
167 * argument a SilcConfigTable array terminated by a NULL struct, it is
168 * important thus, that the `name' field of the terminating struct is set
173 * The option name lowercase. The matching is always case-insensitive,
174 * but for convention the option specification must always be lowercase.
176 * SilcConfigType type
178 * This specifies what kind of parameter this option expects. The
179 * special cases SILC_CONFIG_ARG_BLOCK tells SILC Config that this is
180 * not a normal option but the name of a sub-block of the current
181 * block (there is no limit to the number of nested blocks allowed).
183 * SilcConfigCallback callback
185 * Normally this is the value handler of the current option. If this
186 * field is set to NULL then the value is silently discarded. Useful
187 * for example to support deprecated options.
189 * SilcConfigTable *subtable
191 * If the `type' field is set to SILC_CONFIG_ARG_BLOCK, then this field
192 * must point to a valid sub-table NULL-terminated array. If `type' is
193 * something else, this valued is unused.
196 typedef struct SilcConfigTableStruct {
199 SilcConfigCallback callback;
200 const struct SilcConfigTableStruct *subtable;
203 /****s* silcutil/SilcConfigAPI/SilcConfigFile
207 * typedef struct { ... } SilcConfigFile;
211 * A File object holds the data contained in a previously loaded file by
212 * the silc_config_open() function.
213 * This is an internally allocated struct and must be used only with the
217 typedef struct SilcConfigFileObject SilcConfigFile;
219 /****s* silcutil/SilcConfigAPI/SilcConfigEntity
223 * typedef struct { ... } SilcConfigEntity;
227 * The SILC Config is based on config entities. An entity contains the
228 * SilcConfigFile object we are parsing and the registered options.
231 typedef struct SilcConfigEntityObject *SilcConfigEntity;
235 /****d* silcutil/SilcConfigAPI/SILC_CONFIG_CALLBACK
239 * #define SILC_CONFIG_CALLBACK ...
243 * Generic macro to define SilcConfigCallback functions. This defines a
244 * static function with name `func' as a config callback function.
248 #define SILC_CONFIG_CALLBACK(func) \
249 static int func(SilcConfigType type, const char *name, \
250 uint32 line, void *val, void *context)
255 /****f* silcutil/SilcConfigAPI/silc_config_open
259 * SilcConfigFile *silc_config_open(char *configfile);
263 * Tries to open the config file `configfile' and returns a valid File
264 * object on success, or NULL on failure.
265 * An File object created this way must be destroyed with the function
266 * silc_config_close().
269 SilcConfigFile *silc_config_open(char *configfile);
271 /****f* silcutil/SilcConfigAPI/silc_config_close
275 * void silc_config_close(SilcConfigFile *file);
279 * Closes and frees the File object `file', which must have been returned
280 * by a previous call to silc_config_open(). Otherwise, or if
281 * this function has already been called before for the same File object,
282 * undefined behaviour occurs.
283 * If `file' is NULL, no operation is performed.
286 void silc_config_close(SilcConfigFile *file);
288 /****f* silcutil/SilcConfigAPI/silc_config_init
292 * SilcConfigEntity silc_config_init(SilcConfigFile *file);
296 * Creates an Entity pointing to the valid File object `file', which must
297 * be returned by a previous call to silc_config_open(), otherwise NULL
299 * Entities will be automatically destroyed after the call to the
300 * silc_config_main() function, because of this no uninit functions are
304 SilcConfigEntity silc_config_init(SilcConfigFile *file);
306 /****f* silcutil/SilcConfigAPI/silc_config_strerror
310 * char *silc_config_strerror(int errnum);
314 * The silc_config_strerror() function returns a string describing the
315 * error code passed in the argument `errnum'.
318 char *silc_config_strerror(int errnum);
320 /****f* silcutil/SilcConfigAPI/silc_config_get_filename
324 * char *silc_config_get_filename(SilcConfigFile *file);
328 * Returns the original filename of the object file.
329 * The returned pointer points to internally allocated storage and must
330 * not be freed, modified or stored.
333 char *silc_config_get_filename(SilcConfigFile *file);
335 /****f* silcutil/SilcConfigAPI/silc_config_get_line
339 * uint32 silc_config_get_line(SilcConfigFile *file);
343 * Returns the current line that file parsing arrived at.
346 uint32 silc_config_get_line(SilcConfigFile *file);
348 /****f* silcutil/SilcConfigAPI/silc_config_read_line
352 * char *silc_config_read_line(SilcConfigFile *file, uint32 line);
356 * Returns a dynamically allocated null-terminated buffer containing the
357 * line `line' of `file'.
358 * The returned pointer must be freed when it's not needed any longer.
361 * silc_config_read_current_line
364 char *silc_config_read_line(SilcConfigFile *file, uint32 line);
366 /****f* silcutil/SilcConfigAPI/silc_config_read_current_line
370 * char *silc_config_read_current_line(SilcConfigFile *file);
374 * Returns a dynamically allocated buffer containing the line that the
375 * parser stopped at. This is a convenience function for
376 * silc_config_read_line.
377 * The returned pointer must be freed when it's not needed any longer.
380 char *silc_config_read_current_line(SilcConfigFile *file);
382 /****f* silcutil/SilcConfigAPI/silc_config_register
386 * bool silc_config_register(SilcConfigEntity ent, const char *name,
387 * SilcConfigType type, SilcConfigCallback cb,
388 * const SilcConfigTable *subtable,
393 * Register option `name' in the entity `ent'. If `cb' is not NULL, it
394 * will be called with the *val pointer pointing to an internally
395 * allocated storage of type described by `type'.
396 * If `type' is SILC_CONFIG_ARG_BLOCK, then `subtable' must be a valid
397 * pointer to a SilcConfigTable array specifying the options in the
399 * If the option `name' was already registered in this sub-block or it
400 * matches the reserved word "Include", then this function returns FALSE,
401 * otherwise it returns TRUE.
404 * silc_config_register_table
407 bool silc_config_register(SilcConfigEntity ent, const char *name,
408 SilcConfigType type, SilcConfigCallback cb,
409 const SilcConfigTable *subtable, void *context);
411 /****f* silcutil/SilcConfigAPI/silc_config_register_table
415 * bool silc_config_register_table(SilcConfigEntity ent,
416 * const SilcConfigTable table[],
421 * Register the tableset of options `table' automatically in the entity
422 * `ent'. If defined in the table, the callback functions will be called
423 * all with the same context `context'.
424 * The `table' array must be terminated with an entry with the name field
426 * If the table contains invalid data this function returns FALSE, otherwise
427 * it returns TRUE. If a calling to this function failed, you must destroy
428 * and recreate the entity before retrying, as it's impossible to detect
429 * the point at the function stopped the registering process.
435 bool silc_config_register_table(SilcConfigEntity ent,
436 const SilcConfigTable table[], void *context);
438 /****f* silcutil/SilcConfigAPI/silc_config_main
442 * int silc_config_main(SilcConfigEntity ent);
446 * Enter the main parsing loop. When this function returns the parsing
447 * is finished in the current block (and sub-blocks).
448 * When this function exits, the entity is already destroyed, because
449 * of this you should set it to NULL right after the function call.
452 int silc_config_main(SilcConfigEntity ent);
454 #endif /* !SILCCONFIG_H */