1 /* 2 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 * 4 * Permission to use, copy, modify, and/or distribute this software for any 5 * purpose with or without fee is hereby granted, provided that the above 6 * copyright notice and this permission notice appear in all copies. 7 * 8 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 9 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 10 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 11 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 12 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 13 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 14 * PERFORMANCE OF THIS SOFTWARE. 15 */ 16 17 /* $Id: cfg.h,v 1.6 2020/09/14 08:40:44 florian Exp $ */ 18 19 #ifndef ISCCFG_CFG_H 20 #define ISCCFG_CFG_H 1 21 22 /***** 23 ***** Module Info 24 *****/ 25 26 /*! \file isccfg/cfg.h 27 * \brief 28 * This is the new, table-driven, YACC-free configuration file parser. 29 */ 30 31 /*** 32 *** Imports 33 ***/ 34 35 #include <isc/refcount.h> 36 #include <isc/types.h> 37 #include <isc/list.h> 38 39 /*** 40 *** Types 41 ***/ 42 43 /*% 44 * A configuration parser. 45 */ 46 typedef struct cfg_parser cfg_parser_t; 47 48 /*% 49 * A configuration type definition object. There is a single 50 * static cfg_type_t object for each data type supported by 51 * the configuration parser. 52 */ 53 typedef struct cfg_type cfg_type_t; 54 55 /*% 56 * A configuration object. This is the basic building block of the 57 * configuration parse tree. It contains a value (which may be 58 * of one of several types) and information identifying the file 59 * and line number the value came from, for printing error 60 * messages. 61 */ 62 typedef struct cfg_obj cfg_obj_t; 63 64 /*% 65 * A configuration object list element. 66 */ 67 typedef struct cfg_listelt cfg_listelt_t; 68 69 /*** 70 *** Functions 71 ***/ 72 73 isc_result_t 74 cfg_parser_create(isc_log_t *lctx, cfg_parser_t **ret); 75 /*%< 76 * Create a configuration file parser. Any warning and error 77 * messages will be logged to 'lctx'. 78 * 79 * The parser object returned can be used for a single call 80 * to cfg_parse_file() or cfg_parse_buffer(). It must not 81 * be reused for parsing multiple files or buffers. 82 */ 83 84 isc_result_t 85 cfg_parse_file(cfg_parser_t *pctx, const char *filename, 86 const cfg_type_t *type, cfg_obj_t **ret); 87 /*%< 88 * Read a configuration containing data of type 'type' 89 * and make '*ret' point to its parse tree. 90 * 91 * The configuration is read from the file 'filename' 92 * (isc_parse_file()) or the buffer 'buffer' 93 * (isc_parse_buffer()). 94 * 95 * Returns an error if the file does not parse correctly. 96 * 97 * Requires: 98 *\li "filename" is valid. 99 *\li "mem" is valid. 100 *\li "type" is valid. 101 *\li "cfg" is non-NULL and "*cfg" is NULL. 102 *\li "flags" be one or more of CFG_PCTX_NODEPRECATED or zero. 103 * 104 * Returns: 105 * \li #ISC_R_SUCCESS - success 106 *\li #ISC_R_NOMEMORY - no memory available 107 *\li #ISC_R_INVALIDFILE - file doesn't exist or is unreadable 108 *\li others - file contains errors 109 */ 110 111 void 112 cfg_parser_destroy(cfg_parser_t **pctxp); 113 /*%< 114 * Remove a reference to a configuration parser; destroy it if there are no 115 * more references. 116 */ 117 118 isc_result_t 119 cfg_map_get(const cfg_obj_t *mapobj, const char* name, const cfg_obj_t **obj); 120 /*%< 121 * Extract an element from a configuration object, which 122 * must be of a map type. 123 * 124 * Requires: 125 * \li 'mapobj' points to a valid configuration object of a map type. 126 * \li 'name' points to a null-terminated string. 127 * \li 'obj' is non-NULL and '*obj' is NULL. 128 * 129 * Returns: 130 * \li #ISC_R_SUCCESS - success 131 * \li #ISC_R_NOTFOUND - name not found in map 132 */ 133 134 const cfg_obj_t * 135 cfg_map_getname(const cfg_obj_t *mapobj); 136 /*%< 137 * Get the name of a named map object, like a server "key" clause. 138 * 139 * Requires: 140 * \li 'mapobj' points to a valid configuration object of a map type. 141 * 142 * Returns: 143 * \li A pointer to a configuration object naming the map object, 144 * or NULL if the map object does not have a name. 145 */ 146 147 const char * 148 cfg_obj_asstring(const cfg_obj_t *obj); 149 /*%< 150 * Returns the value of a configuration object of a string type 151 * as a null-terminated string. 152 * 153 * Requires: 154 * \li 'obj' points to a valid configuration object of a string type. 155 * 156 * Returns: 157 * \li A pointer to a null terminated string. 158 */ 159 160 int 161 cfg_obj_islist(const cfg_obj_t *obj); 162 /*%< 163 * Return true iff 'obj' is of list type. 164 */ 165 166 const cfg_listelt_t * 167 cfg_list_first(const cfg_obj_t *obj); 168 /*%< 169 * Returns the first list element in a configuration object of a list type. 170 * 171 * Requires: 172 * \li 'obj' points to a valid configuration object of a list type or NULL. 173 * 174 * Returns: 175 * \li A pointer to a cfg_listelt_t representing the first list element, 176 * or NULL if the list is empty or nonexistent. 177 */ 178 179 const cfg_listelt_t * 180 cfg_list_next(const cfg_listelt_t *elt); 181 /*%< 182 * Returns the next element of a list of configuration objects. 183 * 184 * Requires: 185 * \li 'elt' points to cfg_listelt_t obtained from cfg_list_first() or 186 * a previous call to cfg_list_next(). 187 * 188 * Returns: 189 * \li A pointer to a cfg_listelt_t representing the next element, 190 * or NULL if there are no more elements. 191 */ 192 193 unsigned int 194 cfg_list_length(const cfg_obj_t *obj, int recurse); 195 /*%< 196 * Returns the length of a list of configure objects. If obj is 197 * not a list, returns 0. If recurse is true, add in the length of 198 * all contained lists. 199 */ 200 201 void 202 cfg_print(const cfg_obj_t *obj, 203 void (*f)(void *closure, const char *text, int textlen), 204 void *closure); 205 void 206 cfg_printx(const cfg_obj_t *obj, unsigned int flags, 207 void (*f)(void *closure, const char *text, int textlen), 208 void *closure); 209 210 #define CFG_PRINTER_XKEY 0x1 /* '?' out shared keys. */ 211 212 /*%< 213 * Print the configuration object 'obj' by repeatedly calling the 214 * function 'f', passing 'closure' and a region of text starting 215 * at 'text' and comprising 'textlen' characters. 216 * 217 * If CFG_PRINTER_XKEY the contents of shared keys will be obscured 218 * by replacing them with question marks ('?') 219 */ 220 221 void 222 cfg_print_grammar(const cfg_type_t *type, 223 void (*f)(void *closure, const char *text, int textlen), 224 void *closure); 225 /*%< 226 * Print a summary of the grammar of the configuration type 'type'. 227 */ 228 229 void 230 cfg_obj_destroy(cfg_parser_t *pctx, cfg_obj_t **obj); 231 /*%< 232 * Delete a reference to a configuration object; destroy the object if 233 * there are no more references. 234 * 235 * Require: 236 * \li '*obj' is a valid cfg_obj_t. 237 * \li 'pctx' is a valid cfg_parser_t. 238 */ 239 240 #endif /* ISCCFG_CFG_H */ 241