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  *
  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.
  35  *
  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.
  43  *
  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.
  47  *
  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
  50  * functions.
  51  *
  52  * The config file syntax is pretty straightforward.  All lines starting
  53  * with `#' will be skipped, while sub-blocks are delimited by braces (see
  54  * the example below).
  55  *
  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.
  63  *
  64  * Example:
  65  *
  66  *    cipher {
  67  *       name = aes-256-cbc;
  68  *       module = "aes.sim.so";
  69  *       key_length = 32;       # usually the default is just fine
  70  *       block_length = 16;
  71  *    };
  72  *    Include "/etc/silc/hash_funcs.conf";
  73  *
  74  ***/
  75
  76 #ifndef SILCCONFIG_H
  77 #define SILCCONFIG_H
  78
  79 /****d* silcutil/SilcConfigAPI/errno
  80  *
  81  * NAME
  82  *
  83  *    enum { ... } - describe a SILC Config error
  84  *
  85  * DESCRIPTION
  86  *
  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().
  91  *
  92  * SOURCE
  93  */
  94 enum {
  95   SILC_CONFIG_OK,               /* OK */
  96   SILC_CONFIG_ESILENT,          /* Error defined by callback function */
  97   SILC_CONFIG_EGENERIC,         /* Invalid syntax */
  98   SILC_CONFIG_EINTERNAL,        /* Internal Error (caused by developer) */
  99   SILC_CONFIG_ECANTOPEN,        /* Can't open specified file */
 100   SILC_CONFIG_EOPENBRACE,       /* Expected open-brace '{' */
 101   SILC_CONFIG_ECLOSEBRACE,      /* Missing close-brace '}' */
 102   SILC_CONFIG_ETYPE,            /* Invalid data type */
 103   SILC_CONFIG_EBADOPTION,       /* Unknown option */
 104   SILC_CONFIG_EINVALIDTEXT,     /* Invalid text */
 105   SILC_CONFIG_EDOUBLE,          /* Double option specification */
 106   SILC_CONFIG_EEXPECTED,        /* Expected data but not found */
 107   SILC_CONFIG_EEXPECTEDEQUAL,   /* Expected '=' */
 108   SILC_CONFIG_EUNEXPECTED,      /* Unexpected data */
 109   SILC_CONFIG_EMISSFIELDS,      /* Missing mandatory fields */
 110   SILC_CONFIG_EMISSCOLON,       /* Missing ';' */
 111 };
 112 /***/
 113
 114 /****d* silcutil/SilcConfigAPI/SilcConfigType
 115  *
 116  * NAME
 117  *
 118  *    typedef enum { ... } SilcConfigType;
 119  *
 120  * DESCRIPTION
 121  *
 122  *    This identifies the parameter type that an option has. This parameter
 123  *    is very important because the callback's *val pointer points to a
 124  *    memory location containing the previously specified data type.
 125  *    For example, if you specified an option with an integer parameter
 126  *    callback's *val will be a pointer to an integer.
 127  *
 128  * SOURCE
 129  */
 130 typedef enum {
 131   SILC_CONFIG_ARG_TOGGLE,       /* TOGGLE on,off; yes,no; true, false; */
 132   SILC_CONFIG_ARG_INT,          /* callback wants an integer */
 133   SILC_CONFIG_ARG_STR,          /* callback expects \0-terminated str */
 134   SILC_CONFIG_ARG_STRE,         /* same as above, but can also be empty */
 135   SILC_CONFIG_ARG_BLOCK,        /* this is a sub-block */
 136   SILC_CONFIG_ARG_SIZE,         /* like int, but accepts suffixes kMG */
 137   SILC_CONFIG_ARG_NONE,         /* does not expect any args */
 138 } SilcConfigType;
 139 /***/
 140
 141 /****f* silcutil/SilcConfigAPI/SilcConfigCallback
 142  *
 143  * SYNOPSIS
 144  *
 145  *    typedef int (*SilcConfigCallback)(SilcConfigType type, const char *name,
 146  *                                      SilcUInt32 line, void *val, void *context);
 147  * DESCRIPTION
 148  *
 149  *    This is the callback prototype for the options handler.  The pointer
 150  *    `val' points to a location of type described by `type'.  `name' points
 151  *    to a null-terminated string with the name of the option which triggered
 152  *    this callback, that is stated at line `line'.  `context' is the
 153  *    user-specified context provided when this option was registered.
 154  *
 155  ***/
 156 typedef int (*SilcConfigCallback)(SilcConfigType type, const char *name,
 157                                   SilcUInt32 line, void *val, void *context);
 158
 159 /****s* silcutil/SilcConfigAPI/SilcConfigTable
 160  *
 161  * SYNOPSIS
 162  *
 163  *    typedef struct { ... } SilcConfigTable;
 164  *
 165  * DESCRIPTION
 166  *
 167  *    SILC Config table defines an easy and quick way of registering options
 168  *    in an entity. The function silc_config_register_table() will take as
 169  *    argument a SilcConfigTable array terminated by a NULL struct, it is
 170  *    important thus, that the `name' field of the terminating struct is set
 171  *    to NULL.
 172  *
 173  *    char *name
 174  *
 175  *       The option name lowercase. The matching is always case-insensitive,
 176  *       but for convention the option specification must always be lowercase.
 177  *
 178  *    SilcConfigType type
 179  *
 180  *       This specifies what kind of parameter this option expects.  The
 181  *       special cases SILC_CONFIG_ARG_BLOCK tells SILC Config that this is
 182  *       not a normal option but the name of a sub-block of the current
 183  *       block (there is no limit to the number of nested blocks allowed).
 184  *
 185  *    SilcConfigCallback callback
 186  *
 187  *       Normally this is the value handler of the current option. If this
 188  *       field is set to NULL then the value is silently discarded. Useful
 189  *       for example to support deprecated options.
 190  *
 191  *    SilcConfigTable *subtable
 192  *
 193  *       If the `type' field is set to SILC_CONFIG_ARG_BLOCK, then this field
 194  *       must point to a valid sub-table NULL-terminated array. If `type' is
 195  *       something else, this valued is unused.
 196  *
 197  ***/
 198 typedef struct SilcConfigTableStruct {
 199   char *name;
 200   SilcConfigType type;
 201   SilcConfigCallback callback;
 202   const struct SilcConfigTableStruct *subtable;
 203 } SilcConfigTable;
 204
 205 /****s* silcutil/SilcConfigAPI/SilcConfigFile
 206  *
 207  * SYNOPSIS
 208  *
 209  *    typedef struct { ... } SilcConfigFile;
 210  *
 211  * DESCRIPTION
 212  *
 213  *    A File object holds the data contained in a previously loaded file by
 214  *    the silc_config_open() function.
 215  *    This is an internally allocated struct and must be used only with the
 216  *    helper functions.
 217  *
 218  ***/
 219 typedef struct SilcConfigFileObject SilcConfigFile;
 220
 221 /****s* silcutil/SilcConfigAPI/SilcConfigEntity
 222  *
 223  * SYNOPSIS
 224  *
 225  *    typedef struct { ... } SilcConfigEntity;
 226  *
 227  * DESCRIPTION
 228  *
 229  *    The SILC Config is based on config entities.  An entity contains the
 230  *    SilcConfigFile object we are parsing and the registered options.
 231  *
 232  ***/
 233 typedef struct SilcConfigEntityObject *SilcConfigEntity;
 234
 235 /* Macros */
 236
 237 /****d* silcutil/SilcConfigAPI/SILC_CONFIG_CALLBACK
 238  *
 239  * NAME
 240  *
 241  *    #define SILC_CONFIG_CALLBACK ...
 242  *
 243  * DESCRIPTION
 244  *
 245  *    Generic macro to define SilcConfigCallback functions. This defines a
 246  *    static function with name `func' as a config callback function.
 247  *
 248  * SOURCE
 249  */
 250 #define SILC_CONFIG_CALLBACK(func)                              \
 251 static int func(SilcConfigType type, const char *name,          \
 252                 SilcUInt32 line, void *val, void *context)
 253 /***/
 254
 255 /* Prototypes */
 256
 257 /****f* silcutil/SilcConfigAPI/silc_config_open
 258  *
 259  * SYNOPSIS
 260  *
 261  *    SilcConfigFile *silc_config_open(char *configfile);
 262  *
 263  * DESCRIPTION
 264  *
 265  *    Tries to open the config file `configfile' and returns a valid File
 266  *    object on success, or NULL on failure.
 267  *    An File object created this way must be destroyed with the function
 268  *    silc_config_close().
 269  *
 270  ***/
 271 SilcConfigFile *silc_config_open(char *configfile);
 272
 273 /****f* silcutil/SilcConfigAPI/silc_config_close
 274  *
 275  * SYNOPSIS
 276  *
 277  *    void silc_config_close(SilcConfigFile *file);
 278  *
 279  * DESCRIPTION
 280  *
 281  *    Closes and frees the File object `file', which must have been returned
 282  *    by a previous call to silc_config_open().  Otherwise, or if
 283  *    this function has already been called before for the same File object,
 284  *    undefined behaviour occurs.
 285  *    If `file' is NULL, no operation is performed.
 286  *
 287  ***/
 288 void silc_config_close(SilcConfigFile *file);
 289
 290 /****f* silcutil/SilcConfigAPI/silc_config_init
 291  *
 292  * SYNOPSIS
 293  *
 294  *    SilcConfigEntity silc_config_init(SilcConfigFile *file);
 295  *
 296  * DESCRIPTION
 297  *
 298  *    Creates an Entity pointing to the valid File object `file', which must
 299  *    be returned by a previous call to silc_config_open(), otherwise NULL
 300  *    is returned.
 301  *    Entities will be automatically destroyed after the call to the
 302  *    silc_config_main() function, because of this no uninit functions are
 303  *    provided.
 304  *
 305  ***/
 306 SilcConfigEntity silc_config_init(SilcConfigFile *file);
 307
 308 /****f* silcutil/SilcConfigAPI/silc_config_strerror
 309  *
 310  * SYNOPSIS
 311  *
 312  *    char *silc_config_strerror(int errnum);
 313  *
 314  * DESCRIPTION
 315  *
 316  *    The silc_config_strerror() function returns a string describing the
 317  *    error code passed in the argument `errnum'.
 318  *
 319  ***/
 320 char *silc_config_strerror(int errnum);
 321
 322 /****f* silcutil/SilcConfigAPI/silc_config_get_filename
 323  *
 324  * SYNOPSIS
 325  *
 326  *    char *silc_config_get_filename(SilcConfigFile *file);
 327  *
 328  * DESCRIPTION
 329  *
 330  *    Returns the original filename of the object file.
 331  *    The returned pointer points to internally allocated storage and must
 332  *    not be freed, modified or stored.
 333  *
 334  ***/
 335 char *silc_config_get_filename(SilcConfigFile *file);
 336
 337 /****f* silcutil/SilcConfigAPI/silc_config_get_line
 338  *
 339  * SYNOPSIS
 340  *
 341  *    SilcUInt32 silc_config_get_line(SilcConfigFile *file);
 342  *
 343  * DESCRIPTION
 344  *
 345  *    Returns the current line that file parsing arrived at.
 346  *
 347  ***/
 348 SilcUInt32 silc_config_get_line(SilcConfigFile *file);
 349
 350 /****f* silcutil/SilcConfigAPI/silc_config_read_line
 351  *
 352  * SYNOPSIS
 353  *
 354  *    char *silc_config_read_line(SilcConfigFile *file, SilcUInt32 line);
 355  *
 356  * DESCRIPTION
 357  *
 358  *    Returns a dynamically allocated null-terminated buffer containing the
 359  *    line `line' of `file'.
 360  *    The returned pointer must be freed when it's not needed any longer.
 361  *
 362  * SEE ALSO
 363  *    silc_config_read_current_line
 364  *
 365  ***/
 366 char *silc_config_read_line(SilcConfigFile *file, SilcUInt32 line);
 367
 368 /****f* silcutil/SilcConfigAPI/silc_config_read_current_line
 369  *
 370  * SYNOPSIS
 371  *
 372  *    char *silc_config_read_current_line(SilcConfigFile *file);
 373  *
 374  * DESCRIPTION
 375  *
 376  *    Returns a dynamically allocated buffer containing the line that the
 377  *    parser stopped at.  This is a convenience function for
 378  *    silc_config_read_line.
 379  *    The returned pointer must be freed when it's not needed any longer.
 380  *
 381  ***/
 382 char *silc_config_read_current_line(SilcConfigFile *file);
 383
 384 /****f* silcutil/SilcConfigAPI/silc_config_register
 385  *
 386  * SYNOPSIS
 387  *
 388  *    bool silc_config_register(SilcConfigEntity ent, const char *name,
 389  *                              SilcConfigType type, SilcConfigCallback cb,
 390  *                              const SilcConfigTable *subtable,
 391  *                              void *context);
 392  *
 393  * DESCRIPTION
 394  *
 395  *    Register option `name' in the entity `ent'. If `cb' is not NULL, it
 396  *    will be called with the *val pointer pointing to an internally
 397  *    allocated storage of type described by `type'.
 398  *    If `type' is SILC_CONFIG_ARG_BLOCK, then `subtable' must be a valid
 399  *    pointer to a SilcConfigTable array specifying the options in the
 400  *    sub-block.
 401  *    If the option `name' was already registered in this sub-block or it
 402  *    matches the reserved word "Include", then this function returns FALSE,
 403  *    otherwise it returns TRUE.
 404  *
 405  * SEE ALSO
 406  *    silc_config_register_table
 407  *
 408  ***/
 409 bool silc_config_register(SilcConfigEntity ent, const char *name,
 410                           SilcConfigType type, SilcConfigCallback cb,
 411                           const SilcConfigTable *subtable, void *context);
 412
 413 /****f* silcutil/SilcConfigAPI/silc_config_register_table
 414  *
 415  * SYNOPSIS
 416  *
 417  *    bool silc_config_register_table(SilcConfigEntity ent,
 418  *                                    const SilcConfigTable table[],
 419  *                                    void *context);
 420  *
 421  * DESCRIPTION
 422  *
 423  *    Register the tableset of options `table' automatically in the entity
 424  *    `ent'.  If defined in the table, the callback functions will be called
 425  *    all with the same context `context'.
 426  *    The `table' array must be terminated with an entry with the name field
 427  *    set to NULL.
 428  *    If the table contains invalid data this function returns FALSE, otherwise
 429  *    it returns TRUE.  If a calling to this function failed, you must destroy
 430  *    and recreate the entity before retrying, as it's impossible to detect
 431  *    the point at the function stopped the registering process.
 432  *
 433  * SEE ALSO
 434  *    SilcConfigTable
 435  *
 436  ***/
 437 bool silc_config_register_table(SilcConfigEntity ent,
 438                                 const SilcConfigTable table[], void *context);
 439
 440 /****f* silcutil/SilcConfigAPI/silc_config_main
 441  *
 442  * SYNOPSIS
 443  *
 444  *    int silc_config_main(SilcConfigEntity ent);
 445  *
 446  * DESCRIPTION
 447  *
 448  *    Enter the main parsing loop. When this function returns the parsing
 449  *    is finished in the current block (and sub-blocks).
 450  *    When this function exits, the entity is already destroyed, because
 451  *    of this you should set it to NULL right after the function call.
 452  *
 453  ***/
 454 int silc_config_main(SilcConfigEntity ent);
 455
 456 #endif  /* !SILCCONFIG_H */