/contrib/bind9/lib/isccfg/include/isccfg/cfg.h

https://bitbucket.org/freebsd/freebsd-head/ · C Header · 441 lines · 101 code · 54 blank · 286 comment · 0 complexity · f3fde430a2d24610e476574716841c51 MD5 · raw file

  1. /*
  2. * Copyright (C) 2004-2007, 2010 Internet Systems Consortium, Inc. ("ISC")
  3. * Copyright (C) 2000-2002 Internet Software Consortium.
  4. *
  5. * Permission to use, copy, modify, and/or distribute this software for any
  6. * purpose with or without fee is hereby granted, provided that the above
  7. * copyright notice and this permission notice appear in all copies.
  8. *
  9. * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10. * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11. * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12. * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13. * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14. * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15. * PERFORMANCE OF THIS SOFTWARE.
  16. */
  17. /* $Id: cfg.h,v 1.46 2010/08/13 23:47:04 tbox Exp $ */
  18. #ifndef ISCCFG_CFG_H
  19. #define ISCCFG_CFG_H 1
  20. /*****
  21. ***** Module Info
  22. *****/
  23. /*! \file isccfg/cfg.h
  24. * \brief
  25. * This is the new, table-driven, YACC-free configuration file parser.
  26. */
  27. /***
  28. *** Imports
  29. ***/
  30. #include <isc/formatcheck.h>
  31. #include <isc/lang.h>
  32. #include <isc/refcount.h>
  33. #include <isc/types.h>
  34. #include <isc/list.h>
  35. /***
  36. *** Types
  37. ***/
  38. /*%
  39. * A configuration parser.
  40. */
  41. typedef struct cfg_parser cfg_parser_t;
  42. /*%
  43. * A configuration type definition object. There is a single
  44. * static cfg_type_t object for each data type supported by
  45. * the configuration parser.
  46. */
  47. typedef struct cfg_type cfg_type_t;
  48. /*%
  49. * A configuration object. This is the basic building block of the
  50. * configuration parse tree. It contains a value (which may be
  51. * of one of several types) and information identifying the file
  52. * and line number the value came from, for printing error
  53. * messages.
  54. */
  55. typedef struct cfg_obj cfg_obj_t;
  56. /*%
  57. * A configuration object list element.
  58. */
  59. typedef struct cfg_listelt cfg_listelt_t;
  60. /*%
  61. * A callback function to be called when parsing an option
  62. * that needs to be interpreted at parsing time, like
  63. * "directory".
  64. */
  65. typedef isc_result_t
  66. (*cfg_parsecallback_t)(const char *clausename, const cfg_obj_t *obj, void *arg);
  67. /***
  68. *** Functions
  69. ***/
  70. ISC_LANG_BEGINDECLS
  71. void
  72. cfg_parser_attach(cfg_parser_t *src, cfg_parser_t **dest);
  73. /*%<
  74. * Reference a parser object.
  75. */
  76. isc_result_t
  77. cfg_parser_create(isc_mem_t *mctx, isc_log_t *lctx, cfg_parser_t **ret);
  78. /*%<
  79. * Create a configuration file parser. Any warning and error
  80. * messages will be logged to 'lctx'.
  81. *
  82. * The parser object returned can be used for a single call
  83. * to cfg_parse_file() or cfg_parse_buffer(). It must not
  84. * be reused for parsing multiple files or buffers.
  85. */
  86. void
  87. cfg_parser_setcallback(cfg_parser_t *pctx,
  88. cfg_parsecallback_t callback,
  89. void *arg);
  90. /*%<
  91. * Make the parser call 'callback' whenever it encounters
  92. * a configuration clause with the callback attribute,
  93. * passing it the clause name, the clause value,
  94. * and 'arg' as arguments.
  95. *
  96. * To restore the default of not invoking callbacks, pass
  97. * callback==NULL and arg==NULL.
  98. */
  99. isc_result_t
  100. cfg_parse_file(cfg_parser_t *pctx, const char *filename,
  101. const cfg_type_t *type, cfg_obj_t **ret);
  102. isc_result_t
  103. cfg_parse_buffer(cfg_parser_t *pctx, isc_buffer_t *buffer,
  104. const cfg_type_t *type, cfg_obj_t **ret);
  105. /*%<
  106. * Read a configuration containing data of type 'type'
  107. * and make '*ret' point to its parse tree.
  108. *
  109. * The configuration is read from the file 'filename'
  110. * (isc_parse_file()) or the buffer 'buffer'
  111. * (isc_parse_buffer()).
  112. *
  113. * Returns an error if the file does not parse correctly.
  114. *
  115. * Requires:
  116. *\li "filename" is valid.
  117. *\li "mem" is valid.
  118. *\li "type" is valid.
  119. *\li "cfg" is non-NULL and "*cfg" is NULL.
  120. *
  121. * Returns:
  122. * \li #ISC_R_SUCCESS - success
  123. *\li #ISC_R_NOMEMORY - no memory available
  124. *\li #ISC_R_INVALIDFILE - file doesn't exist or is unreadable
  125. *\li others - file contains errors
  126. */
  127. void
  128. cfg_parser_destroy(cfg_parser_t **pctxp);
  129. /*%<
  130. * Remove a reference to a configuration parser; destroy it if there are no
  131. * more references.
  132. */
  133. isc_boolean_t
  134. cfg_obj_isvoid(const cfg_obj_t *obj);
  135. /*%<
  136. * Return true iff 'obj' is of void type (e.g., an optional
  137. * value not specified).
  138. */
  139. isc_boolean_t
  140. cfg_obj_ismap(const cfg_obj_t *obj);
  141. /*%<
  142. * Return true iff 'obj' is of a map type.
  143. */
  144. isc_result_t
  145. cfg_map_get(const cfg_obj_t *mapobj, const char* name, const cfg_obj_t **obj);
  146. /*%<
  147. * Extract an element from a configuration object, which
  148. * must be of a map type.
  149. *
  150. * Requires:
  151. * \li 'mapobj' points to a valid configuration object of a map type.
  152. * \li 'name' points to a null-terminated string.
  153. * \li 'obj' is non-NULL and '*obj' is NULL.
  154. *
  155. * Returns:
  156. * \li #ISC_R_SUCCESS - success
  157. * \li #ISC_R_NOTFOUND - name not found in map
  158. */
  159. const cfg_obj_t *
  160. cfg_map_getname(const cfg_obj_t *mapobj);
  161. /*%<
  162. * Get the name of a named map object, like a server "key" clause.
  163. *
  164. * Requires:
  165. * \li 'mapobj' points to a valid configuration object of a map type.
  166. *
  167. * Returns:
  168. * \li A pointer to a configuration object naming the map object,
  169. * or NULL if the map object does not have a name.
  170. */
  171. isc_boolean_t
  172. cfg_obj_istuple(const cfg_obj_t *obj);
  173. /*%<
  174. * Return true iff 'obj' is of a map type.
  175. */
  176. const cfg_obj_t *
  177. cfg_tuple_get(const cfg_obj_t *tupleobj, const char *name);
  178. /*%<
  179. * Extract an element from a configuration object, which
  180. * must be of a tuple type.
  181. *
  182. * Requires:
  183. * \li 'tupleobj' points to a valid configuration object of a tuple type.
  184. * \li 'name' points to a null-terminated string naming one of the
  185. *\li fields of said tuple type.
  186. */
  187. isc_boolean_t
  188. cfg_obj_isuint32(const cfg_obj_t *obj);
  189. /*%<
  190. * Return true iff 'obj' is of integer type.
  191. */
  192. isc_uint32_t
  193. cfg_obj_asuint32(const cfg_obj_t *obj);
  194. /*%<
  195. * Returns the value of a configuration object of 32-bit integer type.
  196. *
  197. * Requires:
  198. * \li 'obj' points to a valid configuration object of 32-bit integer type.
  199. *
  200. * Returns:
  201. * \li A 32-bit unsigned integer.
  202. */
  203. isc_boolean_t
  204. cfg_obj_isuint64(const cfg_obj_t *obj);
  205. /*%<
  206. * Return true iff 'obj' is of integer type.
  207. */
  208. isc_uint64_t
  209. cfg_obj_asuint64(const cfg_obj_t *obj);
  210. /*%<
  211. * Returns the value of a configuration object of 64-bit integer type.
  212. *
  213. * Requires:
  214. * \li 'obj' points to a valid configuration object of 64-bit integer type.
  215. *
  216. * Returns:
  217. * \li A 64-bit unsigned integer.
  218. */
  219. isc_boolean_t
  220. cfg_obj_isstring(const cfg_obj_t *obj);
  221. /*%<
  222. * Return true iff 'obj' is of string type.
  223. */
  224. const char *
  225. cfg_obj_asstring(const cfg_obj_t *obj);
  226. /*%<
  227. * Returns the value of a configuration object of a string type
  228. * as a null-terminated string.
  229. *
  230. * Requires:
  231. * \li 'obj' points to a valid configuration object of a string type.
  232. *
  233. * Returns:
  234. * \li A pointer to a null terminated string.
  235. */
  236. isc_boolean_t
  237. cfg_obj_isboolean(const cfg_obj_t *obj);
  238. /*%<
  239. * Return true iff 'obj' is of a boolean type.
  240. */
  241. isc_boolean_t
  242. cfg_obj_asboolean(const cfg_obj_t *obj);
  243. /*%<
  244. * Returns the value of a configuration object of a boolean type.
  245. *
  246. * Requires:
  247. * \li 'obj' points to a valid configuration object of a boolean type.
  248. *
  249. * Returns:
  250. * \li A boolean value.
  251. */
  252. isc_boolean_t
  253. cfg_obj_issockaddr(const cfg_obj_t *obj);
  254. /*%<
  255. * Return true iff 'obj' is a socket address.
  256. */
  257. const isc_sockaddr_t *
  258. cfg_obj_assockaddr(const cfg_obj_t *obj);
  259. /*%<
  260. * Returns the value of a configuration object representing a socket address.
  261. *
  262. * Requires:
  263. * \li 'obj' points to a valid configuration object of a socket address type.
  264. *
  265. * Returns:
  266. * \li A pointer to a sockaddr. The sockaddr must be copied by the caller
  267. * if necessary.
  268. */
  269. isc_boolean_t
  270. cfg_obj_isnetprefix(const cfg_obj_t *obj);
  271. /*%<
  272. * Return true iff 'obj' is a network prefix.
  273. */
  274. void
  275. cfg_obj_asnetprefix(const cfg_obj_t *obj, isc_netaddr_t *netaddr,
  276. unsigned int *prefixlen);
  277. /*%<
  278. * Gets the value of a configuration object representing a network
  279. * prefix. The network address is returned through 'netaddr' and the
  280. * prefix length in bits through 'prefixlen'.
  281. *
  282. * Requires:
  283. * \li 'obj' points to a valid configuration object of network prefix type.
  284. *\li 'netaddr' and 'prefixlen' are non-NULL.
  285. */
  286. isc_boolean_t
  287. cfg_obj_islist(const cfg_obj_t *obj);
  288. /*%<
  289. * Return true iff 'obj' is of list type.
  290. */
  291. const cfg_listelt_t *
  292. cfg_list_first(const cfg_obj_t *obj);
  293. /*%<
  294. * Returns the first list element in a configuration object of a list type.
  295. *
  296. * Requires:
  297. * \li 'obj' points to a valid configuration object of a list type or NULL.
  298. *
  299. * Returns:
  300. * \li A pointer to a cfg_listelt_t representing the first list element,
  301. * or NULL if the list is empty or nonexistent.
  302. */
  303. const cfg_listelt_t *
  304. cfg_list_next(const cfg_listelt_t *elt);
  305. /*%<
  306. * Returns the next element of a list of configuration objects.
  307. *
  308. * Requires:
  309. * \li 'elt' points to cfg_listelt_t obtained from cfg_list_first() or
  310. * a previous call to cfg_list_next().
  311. *
  312. * Returns:
  313. * \li A pointer to a cfg_listelt_t representing the next element,
  314. * or NULL if there are no more elements.
  315. */
  316. unsigned int
  317. cfg_list_length(const cfg_obj_t *obj, isc_boolean_t recurse);
  318. /*%<
  319. * Returns the length of a list of configure objects. If obj is
  320. * not a list, returns 0. If recurse is true, add in the length of
  321. * all contained lists.
  322. */
  323. cfg_obj_t *
  324. cfg_listelt_value(const cfg_listelt_t *elt);
  325. /*%<
  326. * Returns the configuration object associated with cfg_listelt_t.
  327. *
  328. * Requires:
  329. * \li 'elt' points to cfg_listelt_t obtained from cfg_list_first() or
  330. * cfg_list_next().
  331. *
  332. * Returns:
  333. * \li A non-NULL pointer to a configuration object.
  334. */
  335. void
  336. cfg_print(const cfg_obj_t *obj,
  337. void (*f)(void *closure, const char *text, int textlen),
  338. void *closure);
  339. /*%<
  340. * Print the configuration object 'obj' by repeatedly calling the
  341. * function 'f', passing 'closure' and a region of text starting
  342. * at 'text' and comprising 'textlen' characters.
  343. */
  344. void
  345. cfg_print_grammar(const cfg_type_t *type,
  346. void (*f)(void *closure, const char *text, int textlen),
  347. void *closure);
  348. /*%<
  349. * Print a summary of the grammar of the configuration type 'type'.
  350. */
  351. isc_boolean_t
  352. cfg_obj_istype(const cfg_obj_t *obj, const cfg_type_t *type);
  353. /*%<
  354. * Return true iff 'obj' is of type 'type'.
  355. */
  356. void
  357. cfg_obj_attach(cfg_obj_t *src, cfg_obj_t **dest);
  358. /*%<
  359. * Reference a configuration object.
  360. */
  361. void
  362. cfg_obj_destroy(cfg_parser_t *pctx, cfg_obj_t **obj);
  363. /*%<
  364. * Delete a reference to a configuration object; destroy the object if
  365. * there are no more references.
  366. */
  367. void
  368. cfg_obj_log(const cfg_obj_t *obj, isc_log_t *lctx, int level,
  369. const char *fmt, ...)
  370. ISC_FORMAT_PRINTF(4, 5);
  371. /*%<
  372. * Log a message concerning configuration object 'obj' to the logging
  373. * channel of 'pctx', at log level 'level'. The message will be prefixed
  374. * with the file name(s) and line number where 'obj' was defined.
  375. */
  376. const char *
  377. cfg_obj_file(const cfg_obj_t *obj);
  378. /*%<
  379. * Return the file that defined this object.
  380. */
  381. unsigned int
  382. cfg_obj_line(const cfg_obj_t *obj);
  383. /*%<
  384. * Return the line in file where this object was defined.
  385. */
  386. ISC_LANG_ENDDECLS
  387. #endif /* ISCCFG_CFG_H */