View of /netsukuku/src/conf.h

    1 /* This file is part of Netsukuku
    2  * (c) Copyright 2005 Andrea Lo Pumo aka AlpT <alpt@freaknet.org>
    3  *
    4  * This source code is free software; you can redistribute it and/or
    5  * modify it under the terms of the GNU General Public License as published
    6  * by the Free Software Foundation; either version 2 of the License,
    7  * or (at your option) any later version.
    8  *
    9  * This source code is distributed in the hope that it will be useful,
   10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
   11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   12  * Please refer to the GNU Public License for more details.
   13  *
   14  * You should have received a copy of the GNU Public License along with
   15  * this source code; if not, write to:
   16  * Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
   17  *
   18  * --
   19  * conf.c
   20  *
   21  * General configuration file loader and parser.
   22  */
   23 
   24 #ifndef CONF_H
   25 #define CONF_H
   26 
   27 /*\
   28  *              |{conf-usage}|
   29  *                  Conf.c usage
   30  *                ================
   31  *
   32  *
   33  * First of all, it is necessary to register all the valid options with
   34  * add_option(), f.e.:
   35  *
   36  *  ntkopt *myoptions=0;
   37  *
   38  *  int main()
   39  *  {
   40  *    add_option("map_file",  &myoptions);
   41  *    add_option("speed", &myoptions);
   42  *    add_option("load_module",  &myoptions);
   43  *
   44  *    ...
   45  *  }
   46  *
   47  * You can then load the options from the configuration file:
   48  *
   49  *  load_config_file("/etc/my.conf", myoptions);
   50  *
   51  * In the configuration file the options must be written in this format:
   52  *
   53  *  opt_name [[=] value]
   54  *
   55  * For example:
   56  *
   57  *  speed   = 140 Km/h
   58  *  load_module andna arg1=foo, arg2=bar
   59  *  load_module Viphilama    es=netsukuku.org
   60  *
   61  * All the parsed values are stored in the `myoptions' linked list.
   62  * If load_config_file() encounters a syntax error, it calls immediately
   63  * fatal().
   64  *
   65  * To retrieve the value of a specific option use opt_get_value():
   66  *
   67  *  filename=opt_get_value("map_file", myoptions);
   68  *
   69  * Alternatively you can use the OPT_GET_INT_VALUE(),
   70  * OPT_GET_STRN_VALUE() and OPT_GET_ARGZ_VALUE() macros. Their description is
   71  * in opt.h.
   72  *
   73  * Do not free the strings containing the retrieved value, because they are
   74  * stored in the `myoptions' llist and they will be freed when
   75  * close_conf() will be called.
   76  *
   77  *
   78  * The values of an option, which has been specified multiple times in the same
   79  * configuration file, are stored in a unique string and they are separated by
   80  * the '\0' character. In other words, they are unified in a argz vector.
   81  * In the example above, "load_module" has been specified two times, therefore
   82  * the string returned by
   83  *
   84  *  opt_get_value("load_module", myoptions);
   85  *
   86  * will be:
   87  *
   88  *  "andna  arg1=foo, arg2=bar\0Viphilama es=netsukuku.org"
   89  *
   90  * The argz functions (man args_add(3)) are a nice way to handle this type of
   91  * strings. You should use the local xargz.h functions, f.e.:
   92  *
   93  *  char *argz=0, *entry=0;
   94  *  size_t argz_sz=0;
   95  *
   96  *  OPT_GET_ARGZ_VALUE("load_module", myoptions, argz, argz_sz);
   97  *
   98  *  while ((entry = xargz_next (argz, argz_sz, entry))) {
   99  *
  100  *    ... code here ...
  101  *
  102  *  }
  103  *
  104  *  xfree(argz);
  105  *
  106  *
  107  * Finally, at the end of your program you can free all the allocated space:
  108  *
  109  *   opt_close(&myoptions);
  110 \*/
  111 
  112 #include "opt.h"
  113 
  114 /*\
  115  *  * * *  Functions' declaration  * * *
  116 \*/
  117 
  118 int load_config_file(char *file, ntkopt *opt_head);
  119 
  120 #endif /*CONF_H*/