lib/silcutil/silcconfig.h

   1 /*
   2
   3   silcconfig.h
   4
   5   Author: Johnny Mnemonic <johnny@themnemonic.org>
   6
   7   Copyright (C) 1997 - 2002 Pekka Riikonen
   8
   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.
  13
  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.
  18
  19 */
  20
  21 /****h* silcutil/SilcConfigAPI
  22  *
  23  * DESCRIPTION
  24  *
  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.
  31  *
  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
  42  * file.
  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.
  46  *
  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
  49  * functions.
  50  *
  51  * The config file syntax is pretty straightforward.  All lines starting
  52  * with `#' will be skipped, while sub-blocks are delimited by braces (see
  53  * the example below).
  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.
  61  *
  62  * Example:
  63  *
  64  *    cipher {
  65  *       name = aes-256-cbc;
  66  *       module = "aes.sim.so";
  67  *       key_length = 32;       # usually the default is just fine
  68  *       block_length = 16;
  69  *    };
  70  *    Include "/etc/silc/hash_funcs.conf";
  71  *
  72  ***/
  73
  74 #ifndef SILCCONFIG_H
  75 #define SILCCONFIG_H
  76
  77 /****d* silcutil/SilcConfigAPI/errno
  78  *
  79  * NAME
  80  *
  81  *    enum { ... } - describe a SILC Config error
  82  *
  83  * DESCRIPTION
  84  *
  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().
  89  *
  90  * SOURCE
  91  */
  92 enum {
  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 needed fields */
 108   SILC_CONFIG_EMISSCOLON,       /* Missing ';' */
 109 };
 110 /***/
 111
 112 /****d* silcutil/SilcConfigAPI/SilcConfigType
 113  *
 114  * NAME
 115  *
 116  *    typedef enum { ... } SilcConfigType;
 117  *
 118  * DESCRIPTION
 119  *
 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.
 125  *
 126  * SOURCE
 127  */
 128 typedef enum {
 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 */
 136 } SilcConfigType;
 137 /***/
 138
 139 /****f* silcutil/SilcConfigAPI/SilcConfigCallback
 140  *
 141  * SYNOPSIS
 142  *
 143  *    typedef int (*SilcConfigCallback)(SilcConfigType type, const char *name,
 144  *                                      uint32 line, void *val, void *context);
 145  * DESCRIPTION
 146  *
 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.
 152  *
 153  ***/
 154 typedef int (*SilcConfigCallback)(SilcConfigType type, const char *name,
 155                                   uint32 line, void *val, void *context);
 156
 157 /****s* silcutil/SilcConfigAPI/SilcConfigTable
 158  *
 159  * SYNOPSIS
 160  *
 161  *    typedef struct { ... } SilcConfigTable;
 162  *
 163  * DESCRIPTION
 164  *
 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
 169  *    to NULL.
 170  *
 171  *    char *name
 172  *
 173  *       The option name lowercase. The matching is always case-insensitive,
 174  *       but for convention the option specification must always be lowercase.
 175  *
 176  *    SilcConfigType type
 177  *
 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).
 182  *
 183  *    SilcConfigCallback callback
 184  *
 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.
 188  *
 189  *    SilcConfigTable *subtable
 190  *
 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.
 194  *
 195  ***/
 196 typedef struct SilcConfigTableStruct {
 197   char *name;
 198   SilcConfigType type;
 199   SilcConfigCallback callback;
 200   const struct SilcConfigTableStruct *subtable;
 201 } SilcConfigTable;
 202
 203 /****s* silcutil/SilcConfigAPI/SilcConfigFile
 204  *
 205  * SYNOPSIS
 206  *
 207  *    typedef struct { ... } SilcConfigFile;
 208  *
 209  * DESCRIPTION
 210  *
 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
 214  *    helper functions.
 215  *
 216  ***/
 217 typedef struct SilcConfigFileObject SilcConfigFile;
 218
 219 /****s* silcutil/SilcConfigAPI/SilcConfigEntity
 220  *
 221  * SYNOPSIS
 222  *
 223  *    typedef struct { ... } SilcConfigEntity;
 224  *
 225  * DESCRIPTION
 226  *
 227  *    The SILC Config is based on config entities.  An entity contains the
 228  *    SilcConfigFile object we are parsing and the registered options.
 229  *
 230  ***/
 231 typedef struct SilcConfigEntityObject *SilcConfigEntity;
 232
 233 /* Macros */
 234
 235 /****d* silcutil/SilcConfigAPI/SILC_CONFIG_CALLBACK
 236  *
 237  * NAME
 238  *
 239  *    #define SILC_CONFIG_CALLBACK ...
 240  *
 241  * DESCRIPTION
 242  *
 243  *    Generic macro to define SilcConfigCallback functions. This defines a
 244  *    static function with name `func' as a config callback function.
 245  *
 246  * SOURCE
 247  */
 248 #define SILC_CONFIG_CALLBACK(func)                              \
 249 static int func(SilcConfigType type, const char *name,          \
 250                 uint32 line, void *val, void *context)
 251 /***/
 252
 253 /* Prototypes */
 254
 255 /****f* silcutil/SilcConfigAPI/silc_config_open
 256  *
 257  * SYNOPSIS
 258  *
 259  *    SilcConfigFile *silc_config_open(char *configfile);
 260  *
 261  * DESCRIPTION
 262  *
 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().
 267  *
 268  ***/
 269 SilcConfigFile *silc_config_open(char *configfile);
 270
 271 /****f* silcutil/SilcConfigAPI/silc_config_close
 272  *
 273  * SYNOPSIS
 274  *
 275  *    void silc_config_close(SilcConfigFile *file);
 276  *
 277  * DESCRIPTION
 278  *
 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.
 284  *
 285  ***/
 286 void silc_config_close(SilcConfigFile *file);
 287
 288 /****f* silcutil/SilcConfigAPI/silc_config_init
 289  *
 290  * SYNOPSIS
 291  *
 292  *    SilcConfigEntity silc_config_init(SilcConfigFile *file);
 293  *
 294  * DESCRIPTION
 295  *
 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
 298  *    is returned.
 299  *    Entities will be automatically destroyed after the call to the
 300  *    silc_config_main() function, because of this no uninit functions are
 301  *    provided.
 302  *
 303  ***/
 304 SilcConfigEntity silc_config_init(SilcConfigFile *file);
 305
 306 /****f* silcutil/SilcConfigAPI/silc_config_strerror
 307  *
 308  * SYNOPSIS
 309  *
 310  *    char *silc_config_strerror(int errnum);
 311  *
 312  * DESCRIPTION
 313  *
 314  *    The silc_config_strerror() function returns a string describing the
 315  *    error code passed in the argument `errnum'.
 316  *
 317  ***/
 318 char *silc_config_strerror(int errnum);
 319
 320 /****f* silcutil/SilcConfigAPI/silc_config_get_filename
 321  *
 322  * SYNOPSIS
 323  *
 324  *    char *silc_config_get_filename(SilcConfigFile *file);
 325  *
 326  * DESCRIPTION
 327  *
 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.
 331  *
 332  ***/
 333 char *silc_config_get_filename(SilcConfigFile *file);
 334
 335 /****f* silcutil/SilcConfigAPI/silc_config_get_line
 336  *
 337  * SYNOPSIS
 338  *
 339  *    uint32 silc_config_get_line(SilcConfigFile *file);
 340  *
 341  * DESCRIPTION
 342  *
 343  *    Returns the current line that file parsing arrived at.
 344  *
 345  ***/
 346 uint32 silc_config_get_line(SilcConfigFile *file);
 347
 348 /****f* silcutil/SilcConfigAPI/silc_config_read_line
 349  *
 350  * SYNOPSIS
 351  *
 352  *    char *silc_config_read_line(SilcConfigFile *file, uint32 line);
 353  *
 354  * DESCRIPTION
 355  *
 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.
 359  *
 360  * SEE ALSO
 361  *    silc_config_read_current_line
 362  *
 363  ***/
 364 char *silc_config_read_line(SilcConfigFile *file, uint32 line);
 365
 366 /****f* silcutil/SilcConfigAPI/silc_config_read_current_line
 367  *
 368  * SYNOPSIS
 369  *
 370  *    char *silc_config_read_current_line(SilcConfigFile *file);
 371  *
 372  * DESCRIPTION
 373  *
 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.
 378  *
 379  ***/
 380 char *silc_config_read_current_line(SilcConfigFile *file);
 381
 382 /****f* silcutil/SilcConfigAPI/silc_config_register
 383  *
 384  * SYNOPSIS
 385  *
 386  *    void silc_config_register(SilcConfigEntity ent, const char *name,
 387  *                              SilcConfigType type, SilcConfigCallback cb,
 388  *                              const SilcConfigTable *subtable,
 389  *                              void *context);
 390  *
 391  * DESCRIPTION
 392  *
 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 specified the options in the
 398  *    sub-block.
 399  *
 400  * SEE ALSO
 401  *    silc_config_register_table
 402  *
 403  ***/
 404 void silc_config_register(SilcConfigEntity ent, const char *name,
 405                           SilcConfigType type, SilcConfigCallback cb,
 406                           const SilcConfigTable *subtable, void *context);
 407
 408 /****f* silcutil/SilcConfigAPI/silc_config_register_table
 409  *
 410  * SYNOPSIS
 411  *
 412  *    void silc_config_register_table(SilcConfigEntity ent,
 413  *                                    const SilcConfigTable table[],
 414  *                                    void *context);
 415  *
 416  * DESCRIPTION
 417  *
 418  *    Register the tableset of options `table' automatically in the entity
 419  *    `ent'.  If defined in the table, the callback functions will be called
 420  *    all with the same context `context'.
 421  *    The `table' array must be terminated with an entry with the name field
 422  *    set to NULL.
 423  *
 424  * SEE ALSO
 425  *    SilcConfigTable
 426  *
 427  ***/
 428 void silc_config_register_table(SilcConfigEntity ent,
 429                                 const SilcConfigTable table[], void *context);
 430
 431 /****f* silcutil/SilcConfigAPI/silc_config_main
 432  *
 433  * SYNOPSIS
 434  *
 435  *    int silc_config_main(SilcConfigEntity ent);
 436  *
 437  * DESCRIPTION
 438  *
 439  *    Enter the main parsing loop. When this function returns the parsing
 440  *    is finished in the current block (and sub-blocks).
 441  *    When this function exits, the entity is already destroyed, because
 442  *    of this you should set it to NULL right after the function call.
 443  *
 444  ***/
 445 int silc_config_main(SilcConfigEntity ent);
 446
 447 #endif  /* !SILCCONFIG_H */