/* * Copyright (C) Internet Systems Consortium, Inc. ("ISC") * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, you can obtain one at https://mozilla.org/MPL/2.0/. * * See the COPYRIGHT file distributed with this work for additional * information regarding copyright ownership. */ #ifndef ISCCFG_CFG_H #define ISCCFG_CFG_H 1 /***** ***** Module Info *****/ /*! \file isccfg/cfg.h * \brief * This is the new, table-driven, YACC-free configuration file parser. */ /*** *** Imports ***/ #include <inttypes.h> #include <stdbool.h> #include <time.h> #include <isc/formatcheck.h> #include <isc/lang.h> #include <isc/list.h> #include <isc/refcount.h> #include <isc/types.h> /*** *** Types ***/ /*% * A configuration parser. */ typedef struct cfg_parser cfg_parser_t; /*% * A configuration type definition object. There is a single * static cfg_type_t object for each data type supported by * the configuration parser. */ typedef struct cfg_type cfg_type_t; /*% * A configuration object. This is the basic building block of the * configuration parse tree. It contains a value (which may be * of one of several types) and information identifying the file * and line number the value came from, for printing error * messages. */ typedef struct cfg_obj cfg_obj_t; /*% * A configuration object list element. */ typedef struct cfg_listelt cfg_listelt_t; /*% * A callback function to be called when parsing an option * that needs to be interpreted at parsing time, like * "directory". */ typedef isc_result_t (*cfg_parsecallback_t)(const char *clausename, const cfg_obj_t *obj, void *arg); /*** *** Functions ***/ ISC_LANG_BEGINDECLS void cfg_parser_attach(cfg_parser_t *src, cfg_parser_t **dest); /*%< * Reference a parser object. */ isc_result_t cfg_parser_create(isc_mem_t *mctx, isc_log_t *lctx, cfg_parser_t **ret); /*%< * Create a configuration file parser. Any warning and error * messages will be logged to 'lctx'. * * The parser object returned can be used for a single call * to cfg_parse_file() or cfg_parse_buffer(). It must not * be reused for parsing multiple files or buffers. */ void cfg_parser_setflags(cfg_parser_t *pctx, unsigned int flags, bool turn_on); /*%< * Set parser context flags. The flags are not checked for sensibility. * If 'turn_on' is 'true' the flags will be set, otherwise the flags will * be cleared. * * Requires: *\li "pctx" is not NULL. */ void cfg_parser_setcallback(cfg_parser_t *pctx, cfg_parsecallback_t callback, void *arg); /*%< * Make the parser call 'callback' whenever it encounters * a configuration clause with the callback attribute, * passing it the clause name, the clause value, * and 'arg' as arguments. * * To restore the default of not invoking callbacks, pass * callback==NULL and arg==NULL. */ isc_result_t cfg_parse_file(cfg_parser_t *pctx, const char *file, const cfg_type_t *type, cfg_obj_t **ret); isc_result_t cfg_parse_buffer(cfg_parser_t *pctx, isc_buffer_t *buffer, const char *file, unsigned int line, const cfg_type_t *type, unsigned int flags, cfg_obj_t **ret); /*%< * Read a configuration containing data of type 'type' * and make '*ret' point to its parse tree. * * The configuration is read from the file 'filename' * (isc_parse_file()) or the buffer 'buffer' * (isc_parse_buffer()). * * If 'file' is not NULL, it is the name of the file, or a name to use * for the buffer in place of the filename, when logging errors. * * If 'line' is not 0, then it is the beginning line number to report * when logging errors. This is useful when passing text that has been * read from the middle of a file. * * Returns an error if the file or buffer does not parse correctly. * * Requires: *\li "filename" is valid. *\li "mem" is valid. *\li "type" is valid. *\li "cfg" is non-NULL and "*cfg" is NULL. *\li "flags" be one or more of CFG_PCTX_NODEPRECATED or zero. * * Returns: * \li #ISC_R_SUCCESS - success *\li #ISC_R_NOMEMORY - no memory available *\li #ISC_R_INVALIDFILE - file doesn't exist or is unreadable *\li others - file contains errors */ isc_result_t cfg_parser_mapadd(cfg_parser_t *pctx, cfg_obj_t *mapobj, cfg_obj_t *obj, const char *clause); /*%< * Add the object 'obj' to the specified clause in mapbody 'mapobj'. * Used for adding new zones. * * Require: * \li 'obj' is a valid cfg_obj_t. * \li 'mapobj' is a valid cfg_obj_t of type map. * \li 'pctx' is a valid cfg_parser_t. */ void cfg_parser_reset(cfg_parser_t *pctx); /*%< * Reset an existing parser so it can be re-used for a new file or * buffer. */ void cfg_parser_destroy(cfg_parser_t **pctxp); /*%< * Remove a reference to a configuration parser; destroy it if there are no * more references. */ bool cfg_obj_isvoid(const cfg_obj_t *obj); /*%< * Return true iff 'obj' is of void type (e.g., an optional * value not specified). */ bool cfg_obj_ismap(const cfg_obj_t *obj); /*%< * Return true iff 'obj' is of a map type. */ bool cfg_obj_isfixedpoint(const cfg_obj_t *obj); /*%< * Return true iff 'obj' is of a fixedpoint type. */ bool cfg_obj_ispercentage(const cfg_obj_t *obj); /*%< * Return true iff 'obj' is of a percentage type. */ isc_result_t cfg_map_get(const cfg_obj_t *mapobj, const char *name, const cfg_obj_t **obj); /*%< * Extract an element from a configuration object, which * must be of a map type. * * Requires: * \li 'mapobj' points to a valid configuration object of a map type. * \li 'name' points to a null-terminated string. * \li 'obj' is non-NULL and '*obj' is NULL. * * Returns: * \li #ISC_R_SUCCESS - success * \li #ISC_R_NOTFOUND - name not found in map */ const cfg_obj_t * cfg_map_getname(const cfg_obj_t *mapobj); /*%< * Get the name of a named map object, like a server "key" clause. * * Requires: * \li 'mapobj' points to a valid configuration object of a map type. * * Returns: * \li A pointer to a configuration object naming the map object, * or NULL if the map object does not have a name. */ unsigned int cfg_map_count(const cfg_obj_t *mapobj); /*%< * Get the number of elements defined in the symbol table of a map object. * * Requires: * \li 'mapobj' points to a valid configuration object of a map type. * * Returns: * \li The number of elements in the map object. */ bool cfg_obj_istuple(const cfg_obj_t *obj); /*%< * Return true iff 'obj' is of a map type. */ const cfg_obj_t * cfg_tuple_get(const cfg_obj_t *tupleobj, const char *name); /*%< * Extract an element from a configuration object, which * must be of a tuple type. * * Requires: * \li 'tupleobj' points to a valid configuration object of a tuple type. * \li 'name' points to a null-terminated string naming one of the *\li fields of said tuple type. */ bool cfg_obj_isuint32(const cfg_obj_t *obj); /*%< * Return true iff 'obj' is of integer type. */ uint32_t cfg_obj_asuint32(const cfg_obj_t *obj); /*%< * Returns the value of a configuration object of 32-bit integer type. * * Requires: * \li 'obj' points to a valid configuration object of 32-bit integer type. * * Returns: * \li A 32-bit unsigned integer. */ bool cfg_obj_isuint64(const cfg_obj_t *obj); /*%< * Return true iff 'obj' is of integer type. */ uint64_t cfg_obj_asuint64(const cfg_obj_t *obj); /*%< * Returns the value of a configuration object of 64-bit integer type. * * Requires: * \li 'obj' points to a valid configuration object of 64-bit integer type. * * Returns: * \li A 64-bit unsigned integer. */ uint32_t cfg_obj_asfixedpoint(const cfg_obj_t *obj); /*%< * Returns the value of a configuration object of fixed point number. * * Requires: * \li 'obj' points to a valid configuration object of fixed point type. * * Returns: * \li A 32-bit unsigned integer. */ uint32_t cfg_obj_aspercentage(const cfg_obj_t *obj); /*%< * Returns the value of a configuration object of percentage * * Requires: * \li 'obj' points to a valid configuration object of percentage type. * * Returns: * \li A 32-bit unsigned integer. */ bool cfg_obj_isduration(const cfg_obj_t *obj); /*%< * Return true iff 'obj' is of duration type. */ uint32_t cfg_obj_asduration(const cfg_obj_t *obj); /*%< * Returns the value of a configuration object of duration * * Requires: * \li 'obj' points to a valid configuration object of duration type. * * Returns: * \li A duration in seconds. */ bool cfg_obj_isstring(const cfg_obj_t *obj); /*%< * Return true iff 'obj' is of string type. */ const char * cfg_obj_asstring(const cfg_obj_t *obj); /*%< * Returns the value of a configuration object of a string type * as a null-terminated string. * * Requires: * \li 'obj' points to a valid configuration object of a string type. * * Returns: * \li A pointer to a null terminated string. */ bool cfg_obj_isboolean(const cfg_obj_t *obj); /*%< * Return true iff 'obj' is of a boolean type. */ bool cfg_obj_asboolean(const cfg_obj_t *obj); /*%< * Returns the value of a configuration object of a boolean type. * * Requires: * \li 'obj' points to a valid configuration object of a boolean type. * * Returns: * \li A boolean value. */ bool cfg_obj_issockaddr(const cfg_obj_t *obj); /*%< * Return true iff 'obj' is a socket address. */ const isc_sockaddr_t * cfg_obj_assockaddr(const cfg_obj_t *obj); /*%< * Returns the value of a configuration object representing a socket address. * * Requires: * \li 'obj' points to a valid configuration object of a socket address * type. * * Returns: * \li A pointer to a sockaddr. The sockaddr must be copied by the caller * if necessary. */ isc_dscp_t cfg_obj_getdscp(const cfg_obj_t *obj); /*%< * Returns the DSCP value of a configuration object representing a * socket address. * * Requires: * \li 'obj' points to a valid configuration object of a * socket address type. * * Returns: * \li DSCP value associated with a sockaddr, or -1. */ bool cfg_obj_isnetprefix(const cfg_obj_t *obj); /*%< * Return true iff 'obj' is a network prefix. */ void cfg_obj_asnetprefix(const cfg_obj_t *obj, isc_netaddr_t *netaddr, unsigned int *prefixlen); /*%< * Gets the value of a configuration object representing a network * prefix. The network address is returned through 'netaddr' and the * prefix length in bits through 'prefixlen'. * * Requires: * \li 'obj' points to a valid configuration object of network prefix type. *\li 'netaddr' and 'prefixlen' are non-NULL. */ bool cfg_obj_islist(const cfg_obj_t *obj); /*%< * Return true iff 'obj' is of list type. */ const cfg_listelt_t * cfg_list_first(const cfg_obj_t *obj); /*%< * Returns the first list element in a configuration object of a list type. * * Requires: * \li 'obj' points to a valid configuration object of a list type or NULL. * * Returns: * \li A pointer to a cfg_listelt_t representing the first list element, * or NULL if the list is empty or nonexistent. */ const cfg_listelt_t * cfg_list_next(const cfg_listelt_t *elt); /*%< * Returns the next element of a list of configuration objects. * * Requires: * \li 'elt' points to cfg_listelt_t obtained from cfg_list_first() or * a previous call to cfg_list_next(). * * Returns: * \li A pointer to a cfg_listelt_t representing the next element, * or NULL if there are no more elements. */ unsigned int cfg_list_length(const cfg_obj_t *obj, bool recurse); /*%< * Returns the length of a list of configure objects. If obj is * not a list, returns 0. If recurse is true, add in the length of * all contained lists. */ cfg_obj_t * cfg_listelt_value(const cfg_listelt_t *elt); /*%< * Returns the configuration object associated with cfg_listelt_t. * * Requires: * \li 'elt' points to cfg_listelt_t obtained from cfg_list_first() or * cfg_list_next(). * * Returns: * \li A non-NULL pointer to a configuration object. */ void cfg_print(const cfg_obj_t *obj, void (*f)(void *closure, const char *text, int textlen), void *closure); void cfg_printx(const cfg_obj_t *obj, unsigned int flags, void (*f)(void *closure, const char *text, int textlen), void *closure); #define CFG_PRINTER_XKEY 0x1 /* '?' out shared keys. */ #define CFG_PRINTER_ONELINE 0x2 /* print config as a single line */ #define CFG_PRINTER_ACTIVEONLY \ 0x4 /* print only active configuration \ * options, omitting ancient, \ * obsolete, nonimplemented, \ * and test-only options. */ /*%< * Print the configuration object 'obj' by repeatedly calling the * function 'f', passing 'closure' and a region of text starting * at 'text' and comprising 'textlen' characters. * * If CFG_PRINTER_XKEY the contents of shared keys will be obscured * by replacing them with question marks ('?') */ void cfg_print_grammar(const cfg_type_t *type, unsigned int flags, void (*f)(void *closure, const char *text, int textlen), void *closure); /*%< * Print a summary of the grammar of the configuration type 'type'. */ bool cfg_obj_istype(const cfg_obj_t *obj, const cfg_type_t *type); /*%< * Return true iff 'obj' is of type 'type'. */ void cfg_obj_attach(cfg_obj_t *src, cfg_obj_t **dest); /*%< * Reference a configuration object. */ void cfg_obj_destroy(cfg_parser_t *pctx, cfg_obj_t **obj); /*%< * Delete a reference to a configuration object; destroy the object if * there are no more references. * * Require: * \li '*obj' is a valid cfg_obj_t. * \li 'pctx' is a valid cfg_parser_t. */ void cfg_obj_log(const cfg_obj_t *obj, isc_log_t *lctx, int level, const char *fmt, ...) ISC_FORMAT_PRINTF(4, 5); /*%< * Log a message concerning configuration object 'obj' to the logging * channel of 'pctx', at log level 'level'. The message will be prefixed * with the file name(s) and line number where 'obj' was defined. */ const char * cfg_obj_file(const cfg_obj_t *obj); /*%< * Return the file that defined this object. */ unsigned int cfg_obj_line(const cfg_obj_t *obj); /*%< * Return the line in file where this object was defined. */ const char * cfg_map_firstclause(const cfg_type_t *map, const void **clauses, unsigned int *idx); const char * cfg_map_nextclause(const cfg_type_t *map, const void **clauses, unsigned int *idx); typedef isc_result_t(pluginlist_cb_t)(const cfg_obj_t *config, const cfg_obj_t *obj, const char *plugin_path, const char *parameters, void *callback_data); /*%< * Function prototype for the callback used with cfg_pluginlist_foreach(). * Called once for each element of the list passed to cfg_pluginlist_foreach(). * If this callback returns anything else than #ISC_R_SUCCESS, no further list * elements will be processed. * * \li 'config' - the 'config' object passed to cfg_pluginlist_foreach() * \li 'obj' - object representing the specific "plugin" stanza to be processed * \li 'plugin_path' - path to the shared object with plugin code * \li 'parameters' - configuration text for the plugin * \li 'callback_data' - the pointer passed to cfg_pluginlist_foreach() */ isc_result_t cfg_pluginlist_foreach(const cfg_obj_t *config, const cfg_obj_t *list, isc_log_t *lctx, pluginlist_cb_t *callback, void *callback_data); /*%< * For every "plugin" stanza present in 'list' (which in turn is a part of * 'config'), invoke the given 'callback', passing 'callback_data' to it along * with a fixed set of arguments (see the definition of the #pluginlist_cb_t * type). Use logging context 'lctx' for logging error messages. Interrupt * processing if 'callback' returns something else than #ISC_R_SUCCESS for any * element of 'list'. * * Requires: * * \li 'config' is not NULL * \li 'callback' is not NULL * * Returns: * * \li #ISC_R_SUCCESS if 'callback' returned #ISC_R_SUCCESS for all elements of * 'list' * \li first 'callback' return value which was not #ISC_R_SUCCESS otherwise */ ISC_LANG_ENDDECLS #endif /* ISCCFG_CFG_H */