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.7 2022/06/25 12:14:18 jsg 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 #define CFG_PRINTER_XKEY 0x1 /* '?' out shared keys. */ 161 162 void 163 cfg_obj_destroy(cfg_parser_t *pctx, cfg_obj_t **obj); 164 /*%< 165 * Delete a reference to a configuration object; destroy the object if 166 * there are no more references. 167 * 168 * Require: 169 * \li '*obj' is a valid cfg_obj_t. 170 * \li 'pctx' is a valid cfg_parser_t. 171 */ 172 173 #endif /* ISCCFG_CFG_H */ 174