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/SILC Config Interface
  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/SilcConfigErrno
  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_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 ';' */
 112 };
 113 /***/
 114
 115 /****d* silcutil/SilcConfigAPI/SilcConfigType
 116  *
 117  * NAME
 118  *
 119  *    typedef enum { ... } SilcConfigType;
 120  *
 121  * DESCRIPTION
 122  *
 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.
 128  *
 129  * SOURCE
 130  */
 131 typedef enum {
 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 */
 139 } SilcConfigType;
 140 /***/
 141
 142 /****f* silcutil/SilcConfigAPI/SilcConfigCallback
 143  *
 144  * SYNOPSIS
 145  *
 146  *    typedef int (*SilcConfigCallback)(SilcConfigType type, const char *name,
 147  *                                      SilcUInt32 line, void *val, void *context);
 148  * DESCRIPTION
 149  *
 150  *    This is the callback prototype for the options handler.  The pointer
 151  *    `val' points to a location of type described by `type'.  `name' points
 152  *    to a null-terminated string with the name of the option which triggered
 153  *    this callback, that is stated at line `line'.  `context' is the
 154  *    user-specified context provided when this option was registered.
 155  *
 156  ***/
 157 typedef int (*SilcConfigCallback)(SilcConfigType type, const char *name,
 158                                   SilcUInt32 line, void *val, void *context);
 159
 160 /****s* silcutil/SilcConfigAPI/SilcConfigTable
 161  *
 162  * SYNOPSIS
 163  *
 164  *    typedef struct { ... } SilcConfigTable;
 165  *
 166  * DESCRIPTION
 167  *
 168  *    SILC Config table defines an easy and quick way of registering options
 169  *    in an entity. The function silc_config_register_table() will take as
 170  *    argument a SilcConfigTable array terminated by a NULL struct, it is
 171  *    important thus, that the `name' field of the terminating struct is set
 172  *    to NULL.
 173  *
 174  *    char *name
 175  *
 176  *       The option name lowercase. The matching is always case-insensitive,
 177  *       but for convention the option specification must always be lowercase.
 178  *
 179  *    SilcConfigType type
 180  *
 181  *       This specifies what kind of parameter this option expects.  The
 182  *       special cases SILC_CONFIG_ARG_BLOCK tells SILC Config that this is
 183  *       not a normal option but the name of a sub-block of the current
 184  *       block (there is no limit to the number of nested blocks allowed).
 185  *
 186  *    SilcConfigCallback callback
 187  *
 188  *       Normally this is the value handler of the current option. If this
 189  *       field is set to NULL then the value is silently discarded. Useful
 190  *       for example to support deprecated options.
 191  *
 192  *    SilcConfigTable *subtable
 193  *
 194  *       If the `type' field is set to SILC_CONFIG_ARG_BLOCK, then this field
 195  *       must point to a valid sub-table NULL-terminated array. If `type' is
 196  *       something else, this valued is unused.
 197  *
 198  ***/
 199 typedef struct SilcConfigTableStruct {
 200   char *name;
 201   SilcConfigType type;
 202   SilcConfigCallback callback;
 203   const struct SilcConfigTableStruct *subtable;
 204 } SilcConfigTable;
 205
 206 /****s* silcutil/SilcConfigAPI/SilcConfigFile
 207  *
 208  * SYNOPSIS
 209  *
 210  *    typedef struct { ... } SilcConfigFile;
 211  *
 212  * DESCRIPTION
 213  *
 214  *    A File object holds the data contained in a previously loaded file by
 215  *    the silc_config_open() function.
 216  *    This is an internally allocated struct and must be used only with the
 217  *    helper functions.
 218  *
 219  ***/
 220 typedef struct SilcConfigFileObject SilcConfigFile;
 221
 222 /****s* silcutil/SilcConfigAPI/SilcConfigEntity
 223  *
 224  * SYNOPSIS
 225  *
 226  *    typedef struct { ... } SilcConfigEntity;
 227  *
 228  * DESCRIPTION
 229  *
 230  *    The SILC Config is based on config entities.  An entity contains the
 231  *    SilcConfigFile object we are parsing and the registered options.
 232  *
 233  ***/
 234 typedef struct SilcConfigEntityObject *SilcConfigEntity;
 235
 236 /* Macros */
 237
 238 /****d* silcutil/SilcConfigAPI/SILC_CONFIG_CALLBACK
 239  *
 240  * NAME
 241  *
 242  *    #define SILC_CONFIG_CALLBACK ...
 243  *
 244  * DESCRIPTION
 245  *
 246  *    Generic macro to define SilcConfigCallback functions. This defines a
 247  *    static function with name `func' as a config callback function.
 248  *
 249  * SOURCE
 250  */
 251 #define SILC_CONFIG_CALLBACK(func)                              \
 252 static int func(SilcConfigType type, const char *name,          \
 253                 SilcUInt32 line, void *val, void *context)
 254 /***/
 255
 256 /* Prototypes */
 257
 258 /****f* silcutil/SilcConfigAPI/silc_config_open
 259  *
 260  * SYNOPSIS
 261  *
 262  *    SilcConfigFile *silc_config_open(char *configfile);
 263  *
 264  * DESCRIPTION
 265  *
 266  *    Tries to open the config file `configfile' and returns a valid File
 267  *    object on success, or NULL on failure.
 268  *    An File object created this way must be destroyed with the function
 269  *    silc_config_close().
 270  *
 271  ***/
 272 SilcConfigFile *silc_config_open(const char *configfile);
 273
 274 /****f* silcutil/SilcConfigAPI/silc_config_close
 275  *
 276  * SYNOPSIS
 277  *
 278  *    void silc_config_close(SilcConfigFile *file);
 279  *
 280  * DESCRIPTION
 281  *
 282  *    Closes and frees the File object `file', which must have been returned
 283  *    by a previous call to silc_config_open().  Otherwise, or if
 284  *    this function has already been called before for the same File object,
 285  *    undefined behaviour occurs.
 286  *    If `file' is NULL, no operation is performed.
 287  *
 288  ***/
 289 void silc_config_close(SilcConfigFile *file);
 290
 291 /****f* silcutil/SilcConfigAPI/silc_config_init
 292  *
 293  * SYNOPSIS
 294  *
 295  *    SilcConfigEntity silc_config_init(SilcConfigFile *file);
 296  *
 297  * DESCRIPTION
 298  *
 299  *    Creates an Entity pointing to the valid File object `file', which must
 300  *    be returned by a previous call to silc_config_open(), otherwise NULL
 301  *    is returned.
 302  *    Entities will be automatically destroyed after the call to the
 303  *    silc_config_main() function, because of this no uninit functions are
 304  *    provided.
 305  *
 306  ***/
 307 SilcConfigEntity silc_config_init(SilcConfigFile *file);
 308
 309 /****f* silcutil/SilcConfigAPI/silc_config_strerror
 310  *
 311  * SYNOPSIS
 312  *
 313  *    char *silc_config_strerror(int errnum);
 314  *
 315  * DESCRIPTION
 316  *
 317  *    The silc_config_strerror() function returns a string describing the
 318  *    error code passed in the argument `errnum'.
 319  *
 320  ***/
 321 char *silc_config_strerror(int errnum);
 322
 323 /****f* silcutil/SilcConfigAPI/silc_config_get_filename
 324  *
 325  * SYNOPSIS
 326  *
 327  *    char *silc_config_get_filename(SilcConfigFile *file);
 328  *
 329  * DESCRIPTION
 330  *
 331  *    Returns the original filename of the object file.
 332  *    The returned pointer points to internally allocated storage and must
 333  *    not be freed, modified or stored.
 334  *
 335  ***/
 336 char *silc_config_get_filename(SilcConfigFile *file);
 337
 338 /****f* silcutil/SilcConfigAPI/silc_config_get_line
 339  *
 340  * SYNOPSIS
 341  *
 342  *    SilcUInt32 silc_config_get_line(SilcConfigFile *file);
 343  *
 344  * DESCRIPTION
 345  *
 346  *    Returns the current line that file parsing arrived at.
 347  *
 348  ***/
 349 SilcUInt32 silc_config_get_line(SilcConfigFile *file);
 350
 351 /****f* silcutil/SilcConfigAPI/silc_config_read_line
 352  *
 353  * SYNOPSIS
 354  *
 355  *    char *silc_config_read_line(SilcConfigFile *file, SilcUInt32 line);
 356  *
 357  * DESCRIPTION
 358  *
 359  *    Returns a dynamically allocated null-terminated buffer containing the
 360  *    line `line' of `file'.
 361  *    The returned pointer must be freed when it's not needed any longer.
 362  *
 363  * SEE ALSO
 364  *    silc_config_read_current_line
 365  *
 366  ***/
 367 char *silc_config_read_line(SilcConfigFile *file, SilcUInt32 line);
 368
 369 /****f* silcutil/SilcConfigAPI/silc_config_read_current_line
 370  *
 371  * SYNOPSIS
 372  *
 373  *    char *silc_config_read_current_line(SilcConfigFile *file);
 374  *
 375  * DESCRIPTION
 376  *
 377  *    Returns a dynamically allocated buffer containing the line that the
 378  *    parser stopped at.  This is a convenience function for
 379  *    silc_config_read_line.
 380  *    The returned pointer must be freed when it's not needed any longer.
 381  *
 382  ***/
 383 char *silc_config_read_current_line(SilcConfigFile *file);
 384
 385 /****f* silcutil/SilcConfigAPI/silc_config_register
 386  *
 387  * SYNOPSIS
 388  *
 389  *    bool silc_config_register(SilcConfigEntity ent, const char *name,
 390  *                              SilcConfigType type, SilcConfigCallback cb,
 391  *                              const SilcConfigTable *subtable,
 392  *                              void *context);
 393  *
 394  * DESCRIPTION
 395  *
 396  *    Register option `name' in the entity `ent'. If `cb' is not NULL, it
 397  *    will be called with the *val pointer pointing to an internally
 398  *    allocated storage of type described by `type'.
 399  *    If `type' is SILC_CONFIG_ARG_BLOCK, then `subtable' must be a valid
 400  *    pointer to a SilcConfigTable array specifying the options in the
 401  *    sub-block.
 402  *    If the option `name' was already registered in this sub-block or it
 403  *    matches the reserved word "Include", then this function returns FALSE,
 404  *    otherwise it returns TRUE.
 405  *
 406  * SEE ALSO
 407  *    silc_config_register_table
 408  *
 409  ***/
 410 bool silc_config_register(SilcConfigEntity ent, const char *name,
 411                           SilcConfigType type, SilcConfigCallback cb,
 412                           const SilcConfigTable *subtable, void *context);
 413
 414 /****f* silcutil/SilcConfigAPI/silc_config_register_table
 415  *
 416  * SYNOPSIS
 417  *
 418  *    bool silc_config_register_table(SilcConfigEntity ent,
 419  *                                    const SilcConfigTable table[],
 420  *                                    void *context);
 421  *
 422  * DESCRIPTION
 423  *
 424  *    Register the tableset of options `table' automatically in the entity
 425  *    `ent'.  If defined in the table, the callback functions will be called
 426  *    all with the same context `context'.
 427  *    The `table' array must be terminated with an entry with the name field
 428  *    set to NULL.
 429  *    If the table contains invalid data this function returns FALSE, otherwise
 430  *    it returns TRUE.  If a calling to this function failed, you must destroy
 431  *    and recreate the entity before retrying, as it's impossible to detect
 432  *    the point at the function stopped the registering process.
 433  *
 434  * SEE ALSO
 435  *    SilcConfigTable
 436  *
 437  ***/
 438 bool silc_config_register_table(SilcConfigEntity ent,
 439                                 const SilcConfigTable table[], void *context);
 440
 441 /****f* silcutil/SilcConfigAPI/silc_config_main
 442  *
 443  * SYNOPSIS
 444  *
 445  *    int silc_config_main(SilcConfigEntity ent);
 446  *
 447  * DESCRIPTION
 448  *
 449  *    Enter the main parsing loop. When this function returns the parsing
 450  *    is finished in the current block (and sub-blocks).
 451  *    When this function exits, the entity is already destroyed, because
 452  *    of this you should set it to NULL right after the function call.
 453  *
 454  ***/
 455 int silc_config_main(SilcConfigEntity ent);
 456
 457 #endif  /* !SILCCONFIG_H */