"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.11.23/lib/isccfg/include/isccfg/cfg.h" (7 Sep 2020, 14226 Bytes) of package /linux/misc/dns/bind9/9.11.23/bind-9.11.23.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "cfg.h" see the Fossies "Dox" file reference documentation.

    1 /*
    2  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
    3  *
    4  * This Source Code Form is subject to the terms of the Mozilla Public
    5  * License, v. 2.0. If a copy of the MPL was not distributed with this
    6  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
    7  *
    8  * See the COPYRIGHT file distributed with this work for additional
    9  * information regarding copyright ownership.
   10  */
   11 
   12 #ifndef ISCCFG_CFG_H
   13 #define ISCCFG_CFG_H 1
   14 
   15 /*****
   16  ***** Module Info
   17  *****/
   18 
   19 /*! \file isccfg/cfg.h
   20  * \brief
   21  * This is the new, table-driven, YACC-free configuration file parser.
   22  */
   23 
   24 /***
   25  *** Imports
   26  ***/
   27 
   28 #include <inttypes.h>
   29 #include <stdbool.h>
   30 
   31 #include <isc/formatcheck.h>
   32 #include <isc/lang.h>
   33 #include <isc/types.h>
   34 #include <isc/list.h>
   35 
   36 /***
   37  *** Types
   38  ***/
   39 
   40 /*%
   41  * A configuration parser.
   42  */
   43 typedef struct cfg_parser cfg_parser_t;
   44 
   45 /*%
   46  * A configuration type definition object.  There is a single
   47  * static cfg_type_t object for each data type supported by
   48  * the configuration parser.
   49  */
   50 typedef struct cfg_type cfg_type_t;
   51 
   52 /*%
   53  * A configuration object.  This is the basic building block of the
   54  * configuration parse tree.  It contains a value (which may be
   55  * of one of several types) and information identifying the file
   56  * and line number the value came from, for printing error
   57  * messages.
   58  */
   59 typedef struct cfg_obj cfg_obj_t;
   60 
   61 /*%
   62  * A configuration object list element.
   63  */
   64 typedef struct cfg_listelt cfg_listelt_t;
   65 
   66 /*%
   67  * A callback function to be called when parsing an option
   68  * that needs to be interpreted at parsing time, like
   69  * "directory".
   70  */
   71 typedef isc_result_t
   72 (*cfg_parsecallback_t)(const char *clausename, const cfg_obj_t *obj, void *arg);
   73 
   74 /***
   75  *** Functions
   76  ***/
   77 
   78 ISC_LANG_BEGINDECLS
   79 
   80 void
   81 cfg_parser_attach(cfg_parser_t *src, cfg_parser_t **dest);
   82 /*%<
   83  * Reference a parser object.
   84  */
   85 
   86 isc_result_t
   87 cfg_parser_create(isc_mem_t *mctx, isc_log_t *lctx, cfg_parser_t **ret);
   88 /*%<
   89  * Create a configuration file parser.  Any warning and error
   90  * messages will be logged to 'lctx'.
   91  *
   92  * The parser object returned can be used for a single call
   93  * to cfg_parse_file() or cfg_parse_buffer().  It must not
   94  * be reused for parsing multiple files or buffers.
   95  */
   96 
   97 void
   98 cfg_parser_setcallback(cfg_parser_t *pctx,
   99                cfg_parsecallback_t callback,
  100                void *arg);
  101 /*%<
  102  * Make the parser call 'callback' whenever it encounters
  103  * a configuration clause with the callback attribute,
  104  * passing it the clause name, the clause value,
  105  * and 'arg' as arguments.
  106  *
  107  * To restore the default of not invoking callbacks, pass
  108  * callback==NULL and arg==NULL.
  109  */
  110 
  111 isc_result_t
  112 cfg_parse_file(cfg_parser_t *pctx, const char *file,
  113            const cfg_type_t *type, cfg_obj_t **ret);
  114 
  115 isc_result_t
  116 cfg_parse_buffer(cfg_parser_t *pctx, isc_buffer_t *buffer,
  117          const cfg_type_t *type, cfg_obj_t **ret);
  118 isc_result_t
  119 cfg_parse_buffer2(cfg_parser_t *pctx, isc_buffer_t *buffer,
  120           const char *file, const cfg_type_t *type,
  121           cfg_obj_t **ret);
  122 isc_result_t
  123 cfg_parse_buffer3(cfg_parser_t *pctx, isc_buffer_t *buffer,
  124           const char *file, unsigned int line,
  125           const cfg_type_t *type, cfg_obj_t **ret);
  126 isc_result_t
  127 cfg_parse_buffer4(cfg_parser_t *pctx, isc_buffer_t *buffer,
  128           const char *file, unsigned int line,
  129           const cfg_type_t *type, unsigned int flags,
  130           cfg_obj_t **ret);
  131 /*%<
  132  * Read a configuration containing data of type 'type'
  133  * and make '*ret' point to its parse tree.
  134  *
  135  * The configuration is read from the file 'filename'
  136  * (isc_parse_file()) or the buffer 'buffer'
  137  * (isc_parse_buffer()).
  138  *
  139  * If 'file' is not NULL, it is the name of the file, or a name to use
  140  * for the buffer in place of the filename, when logging errors.
  141  *
  142  * If 'line' is not 0, then it is the beginning line number to report
  143  * when logging errors. This is useful when passing text that has been
  144  * read from the middle of a file.
  145  *
  146  * Returns an error if the file or buffer does not parse correctly.
  147  *
  148  * Requires:
  149  *\li   "filename" is valid.
  150  *\li   "mem" is valid.
  151  *\li   "type" is valid.
  152  *\li   "cfg" is non-NULL and "*cfg" is NULL.
  153  *\li   "flags" be one or more of CFG_PCTX_NODEPRECATED or zero.
  154  *
  155  * Returns:
  156  *     \li #ISC_R_SUCCESS                 - success
  157  *\li      #ISC_R_NOMEMORY                - no memory available
  158  *\li      #ISC_R_INVALIDFILE             - file doesn't exist or is unreadable
  159  *\li      others                         - file contains errors
  160  */
  161 
  162 isc_result_t
  163 cfg_parser_mapadd(cfg_parser_t *pctx, cfg_obj_t *mapobj,
  164           cfg_obj_t *obj, const char *clause);
  165 /*%<
  166  * Add the object 'obj' to the specified clause in mapbody 'mapobj'.
  167  * Used for adding new zones.
  168  *
  169  * Require:
  170  * \li     'obj' is a valid cfg_obj_t.
  171  * \li     'mapobj' is a valid cfg_obj_t of type map.
  172  * \li     'pctx' is a valid cfg_parser_t.
  173  */
  174 
  175 void
  176 cfg_parser_reset(cfg_parser_t *pctx);
  177 /*%<
  178  * Reset an existing parser so it can be re-used for a new file or
  179  * buffer.
  180  */
  181 
  182 void
  183 cfg_parser_destroy(cfg_parser_t **pctxp);
  184 /*%<
  185  * Remove a reference to a configuration parser; destroy it if there are no
  186  * more references.
  187  */
  188 
  189 bool
  190 cfg_obj_isvoid(const cfg_obj_t *obj);
  191 /*%<
  192  * Return true iff 'obj' is of void type (e.g., an optional
  193  * value not specified).
  194  */
  195 
  196 bool
  197 cfg_obj_ismap(const cfg_obj_t *obj);
  198 /*%<
  199  * Return true iff 'obj' is of a map type.
  200  */
  201 
  202 bool
  203 cfg_obj_isfixedpoint(const cfg_obj_t *obj);
  204 /*%<
  205  * Return true iff 'obj' is of a fixedpoint type.
  206  */
  207 
  208 bool
  209 cfg_obj_ispercentage(const cfg_obj_t *obj);
  210 /*%<
  211  * Return true iff 'obj' is of a percentage type.
  212  */
  213 
  214 isc_result_t
  215 cfg_map_get(const cfg_obj_t *mapobj, const char* name, const cfg_obj_t **obj);
  216 /*%<
  217  * Extract an element from a configuration object, which
  218  * must be of a map type.
  219  *
  220  * Requires:
  221  * \li     'mapobj' points to a valid configuration object of a map type.
  222  * \li     'name' points to a null-terminated string.
  223  * \li  'obj' is non-NULL and '*obj' is NULL.
  224  *
  225  * Returns:
  226  * \li     #ISC_R_SUCCESS                  - success
  227  * \li     #ISC_R_NOTFOUND                 - name not found in map
  228  */
  229 
  230 const cfg_obj_t *
  231 cfg_map_getname(const cfg_obj_t *mapobj);
  232 /*%<
  233  * Get the name of a named map object, like a server "key" clause.
  234  *
  235  * Requires:
  236  *    \li  'mapobj' points to a valid configuration object of a map type.
  237  *
  238  * Returns:
  239  * \li     A pointer to a configuration object naming the map object,
  240  *  or NULL if the map object does not have a name.
  241  */
  242 
  243 unsigned int
  244 cfg_map_count(const cfg_obj_t *mapobj);
  245 /*%<
  246  * Get the number of elements defined in the symbol table of a map object.
  247  *
  248  * Requires:
  249  *    \li  'mapobj' points to a valid configuration object of a map type.
  250  *
  251  * Returns:
  252  * \li     The number of elements in the map object.
  253  */
  254 
  255 bool
  256 cfg_obj_istuple(const cfg_obj_t *obj);
  257 /*%<
  258  * Return true iff 'obj' is of a map type.
  259  */
  260 
  261 const cfg_obj_t *
  262 cfg_tuple_get(const cfg_obj_t *tupleobj, const char *name);
  263 /*%<
  264  * Extract an element from a configuration object, which
  265  * must be of a tuple type.
  266  *
  267  * Requires:
  268  * \li     'tupleobj' points to a valid configuration object of a tuple type.
  269  * \li     'name' points to a null-terminated string naming one of the
  270  *\li   fields of said tuple type.
  271  */
  272 
  273 bool
  274 cfg_obj_isuint32(const cfg_obj_t *obj);
  275 /*%<
  276  * Return true iff 'obj' is of integer type.
  277  */
  278 
  279 uint32_t
  280 cfg_obj_asuint32(const cfg_obj_t *obj);
  281 /*%<
  282  * Returns the value of a configuration object of 32-bit integer type.
  283  *
  284  * Requires:
  285  * \li     'obj' points to a valid configuration object of 32-bit integer type.
  286  *
  287  * Returns:
  288  * \li     A 32-bit unsigned integer.
  289  */
  290 
  291 bool
  292 cfg_obj_isuint64(const cfg_obj_t *obj);
  293 /*%<
  294  * Return true iff 'obj' is of integer type.
  295  */
  296 
  297 uint64_t
  298 cfg_obj_asuint64(const cfg_obj_t *obj);
  299 /*%<
  300  * Returns the value of a configuration object of 64-bit integer type.
  301  *
  302  * Requires:
  303  * \li     'obj' points to a valid configuration object of 64-bit integer type.
  304  *
  305  * Returns:
  306  * \li     A 64-bit unsigned integer.
  307  */
  308 
  309 uint32_t
  310 cfg_obj_asfixedpoint(const cfg_obj_t *obj);
  311 /*%<
  312  * Returns the value of a configuration object of fixed point number.
  313  *
  314  * Requires:
  315  * \li     'obj' points to a valid configuration object of fixed point type.
  316  *
  317  * Returns:
  318  * \li     A 32-bit unsigned integer.
  319  */
  320 
  321 uint32_t
  322 cfg_obj_aspercentage(const cfg_obj_t *obj);
  323 /*%<
  324  * Returns the value of a configuration object of percentage
  325  *
  326  * Requires:
  327  * \li     'obj' points to a valid configuration object of percentage type.
  328  *
  329  * Returns:
  330  * \li     A 32-bit unsigned integer.
  331  */
  332 
  333 bool
  334 cfg_obj_isstring(const cfg_obj_t *obj);
  335 /*%<
  336  * Return true iff 'obj' is of string type.
  337  */
  338 
  339 const char *
  340 cfg_obj_asstring(const cfg_obj_t *obj);
  341 /*%<
  342  * Returns the value of a configuration object of a string type
  343  * as a null-terminated string.
  344  *
  345  * Requires:
  346  * \li     'obj' points to a valid configuration object of a string type.
  347  *
  348  * Returns:
  349  * \li     A pointer to a null terminated string.
  350  */
  351 
  352 bool
  353 cfg_obj_isboolean(const cfg_obj_t *obj);
  354 /*%<
  355  * Return true iff 'obj' is of a boolean type.
  356  */
  357 
  358 bool
  359 cfg_obj_asboolean(const cfg_obj_t *obj);
  360 /*%<
  361  * Returns the value of a configuration object of a boolean type.
  362  *
  363  * Requires:
  364  * \li     'obj' points to a valid configuration object of a boolean type.
  365  *
  366  * Returns:
  367  * \li     A boolean value.
  368  */
  369 
  370 bool
  371 cfg_obj_issockaddr(const cfg_obj_t *obj);
  372 /*%<
  373  * Return true iff 'obj' is a socket address.
  374  */
  375 
  376 const isc_sockaddr_t *
  377 cfg_obj_assockaddr(const cfg_obj_t *obj);
  378 /*%<
  379  * Returns the value of a configuration object representing a socket address.
  380  *
  381  * Requires:
  382  * \li     'obj' points to a valid configuration object of a socket address type.
  383  *
  384  * Returns:
  385  * \li     A pointer to a sockaddr.  The sockaddr must be copied by the caller
  386  *      if necessary.
  387  */
  388 
  389 isc_dscp_t
  390 cfg_obj_getdscp(const cfg_obj_t *obj);
  391 /*%<
  392  * Returns the DSCP value of a configuration object representing a
  393  * socket address.
  394  *
  395  * Requires:
  396  * \li     'obj' points to a valid configuration object of a
  397  *         socket address type.
  398  *
  399  * Returns:
  400  * \li     DSCP value associated with a sockaddr, or -1.
  401  */
  402 
  403 bool
  404 cfg_obj_isnetprefix(const cfg_obj_t *obj);
  405 /*%<
  406  * Return true iff 'obj' is a network prefix.
  407  */
  408 
  409 void
  410 cfg_obj_asnetprefix(const cfg_obj_t *obj, isc_netaddr_t *netaddr,
  411             unsigned int *prefixlen);
  412 /*%<
  413  * Gets the value of a configuration object representing a network
  414  * prefix.  The network address is returned through 'netaddr' and the
  415  * prefix length in bits through 'prefixlen'.
  416  *
  417  * Requires:
  418  * \li     'obj' points to a valid configuration object of network prefix type.
  419  *\li   'netaddr' and 'prefixlen' are non-NULL.
  420  */
  421 
  422 bool
  423 cfg_obj_islist(const cfg_obj_t *obj);
  424 /*%<
  425  * Return true iff 'obj' is of list type.
  426  */
  427 
  428 const cfg_listelt_t *
  429 cfg_list_first(const cfg_obj_t *obj);
  430 /*%<
  431  * Returns the first list element in a configuration object of a list type.
  432  *
  433  * Requires:
  434  * \li     'obj' points to a valid configuration object of a list type or NULL.
  435  *
  436  * Returns:
  437  *   \li   A pointer to a cfg_listelt_t representing the first list element,
  438  *  or NULL if the list is empty or nonexistent.
  439  */
  440 
  441 const cfg_listelt_t *
  442 cfg_list_next(const cfg_listelt_t *elt);
  443 /*%<
  444  * Returns the next element of a list of configuration objects.
  445  *
  446  * Requires:
  447  * \li     'elt' points to cfg_listelt_t obtained from cfg_list_first() or
  448  *  a previous call to cfg_list_next().
  449  *
  450  * Returns:
  451  * \li     A pointer to a cfg_listelt_t representing the next element,
  452  *  or NULL if there are no more elements.
  453  */
  454 
  455 unsigned int
  456 cfg_list_length(const cfg_obj_t *obj, bool recurse);
  457 /*%<
  458  * Returns the length of a list of configure objects.  If obj is
  459  * not a list, returns 0.  If recurse is true, add in the length of
  460  * all contained lists.
  461  */
  462 
  463 cfg_obj_t *
  464 cfg_listelt_value(const cfg_listelt_t *elt);
  465 /*%<
  466  * Returns the configuration object associated with cfg_listelt_t.
  467  *
  468  * Requires:
  469  * \li     'elt' points to cfg_listelt_t obtained from cfg_list_first() or
  470  *  cfg_list_next().
  471  *
  472  * Returns:
  473  * \li     A non-NULL pointer to a configuration object.
  474  */
  475 
  476 void
  477 cfg_print(const cfg_obj_t *obj,
  478       void (*f)(void *closure, const char *text, int textlen),
  479       void *closure);
  480 void
  481 cfg_printx(const cfg_obj_t *obj, unsigned int flags,
  482        void (*f)(void *closure, const char *text, int textlen),
  483        void *closure);
  484 
  485 #define CFG_PRINTER_XKEY        0x1     /* '?' out shared keys. */
  486 #define CFG_PRINTER_ONELINE     0x2     /* print config as a single line */
  487 
  488 /*%<
  489  * Print the configuration object 'obj' by repeatedly calling the
  490  * function 'f', passing 'closure' and a region of text starting
  491  * at 'text' and comprising 'textlen' characters.
  492  *
  493  * If CFG_PRINTER_XKEY the contents of shared keys will be obscured
  494  * by replacing them with question marks ('?')
  495  */
  496 
  497 void
  498 cfg_print_grammar(const cfg_type_t *type,
  499       void (*f)(void *closure, const char *text, int textlen),
  500       void *closure);
  501 /*%<
  502  * Print a summary of the grammar of the configuration type 'type'.
  503  */
  504 
  505 bool
  506 cfg_obj_istype(const cfg_obj_t *obj, const cfg_type_t *type);
  507 /*%<
  508  * Return true iff 'obj' is of type 'type'.
  509  */
  510 
  511 void
  512 cfg_obj_attach(cfg_obj_t *src, cfg_obj_t **dest);
  513 /*%<
  514  * Reference a configuration object.
  515  */
  516 
  517 void
  518 cfg_obj_destroy(cfg_parser_t *pctx, cfg_obj_t **obj);
  519 /*%<
  520  * Delete a reference to a configuration object; destroy the object if
  521  * there are no more references.
  522  *
  523  * Require:
  524  * \li     '*obj' is a valid cfg_obj_t.
  525  * \li     'pctx' is a valid cfg_parser_t.
  526  */
  527 
  528 void
  529 cfg_obj_log(const cfg_obj_t *obj, isc_log_t *lctx, int level,
  530         const char *fmt, ...)
  531     ISC_FORMAT_PRINTF(4, 5);
  532 /*%<
  533  * Log a message concerning configuration object 'obj' to the logging
  534  * channel of 'pctx', at log level 'level'.  The message will be prefixed
  535  * with the file name(s) and line number where 'obj' was defined.
  536  */
  537 
  538 const char *
  539 cfg_obj_file(const cfg_obj_t *obj);
  540 /*%<
  541  * Return the file that defined this object.
  542  */
  543 
  544 unsigned int
  545 cfg_obj_line(const cfg_obj_t *obj);
  546 /*%<
  547  * Return the line in file where this object was defined.
  548  */
  549 
  550 const char *
  551 cfg_map_firstclause(const cfg_type_t *map, const void **clauses,
  552             unsigned int *idx);
  553 const char *
  554 cfg_map_nextclause(const cfg_type_t *map, const void **clauses,
  555            unsigned int *idx);
  556 
  557 ISC_LANG_ENDDECLS
  558 
  559 #endif /* ISCCFG_CFG_H */