uci.h 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691
  1. /*
  2. * libuci - Library for the Unified Configuration Interface
  3. * Copyright (C) 2008 Felix Fietkau <nbd@openwrt.org>
  4. *
  5. * This program is free software; you can redistribute it and/or modify
  6. * it under the terms of the GNU Lesser General Public License version 2.1
  7. * as published by the Free Software Foundation
  8. *
  9. * This program is distributed in the hope that it will be useful,
  10. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  12. * GNU Lesser General Public License for more details.
  13. */
  14. #ifndef __LIBUCI_H
  15. #define __LIBUCI_H
  16. #ifdef __cplusplus
  17. extern "C" {
  18. #endif
  19. #include "uci_config.h"
  20. /*
  21. * you can use these defines to enable debugging behavior for
  22. * apps compiled against libuci:
  23. *
  24. * #define UCI_DEBUG_TYPECAST:
  25. * enable uci_element typecast checking at run time
  26. *
  27. */
  28. #include <stdbool.h>
  29. #include <setjmp.h>
  30. #include <stdio.h>
  31. #include <stdint.h>
  32. #include <stddef.h>
  33. #define UCI_CONFDIR "/etc/config"
  34. #define UCI_SAVEDIR "/tmp/.uci"
  35. #define UCI_DIRMODE 0700
  36. #define UCI_FILEMODE 0600
  37. enum
  38. {
  39. UCI_OK = 0,
  40. UCI_ERR_MEM,
  41. UCI_ERR_INVAL,
  42. UCI_ERR_NOTFOUND,
  43. UCI_ERR_IO,
  44. UCI_ERR_PARSE,
  45. UCI_ERR_DUPLICATE,
  46. UCI_ERR_UNKNOWN,
  47. UCI_ERR_LAST
  48. };
  49. struct uci_list;
  50. struct uci_list
  51. {
  52. struct uci_list *next;
  53. struct uci_list *prev;
  54. };
  55. struct uci_ptr;
  56. struct uci_element;
  57. struct uci_package;
  58. struct uci_section;
  59. struct uci_option;
  60. struct uci_delta;
  61. struct uci_context;
  62. struct uci_backend;
  63. struct uci_parse_option;
  64. struct uci_parse_context;
  65. /**
  66. * uci_alloc_context: Allocate a new uci context
  67. */
  68. extern struct uci_context *uci_alloc_context(void);
  69. /**
  70. * uci_free_context: Free the uci context including all of its data
  71. */
  72. extern void uci_free_context(struct uci_context *ctx);
  73. /**
  74. * uci_perror: Print the last uci error that occured
  75. * @ctx: uci context
  76. * @str: string to print before the error message
  77. */
  78. extern void uci_perror(struct uci_context *ctx, const char *str);
  79. /**
  80. * uci_geterror: Get an error string for the last uci error
  81. * @ctx: uci context
  82. * @dest: target pointer for the string
  83. * @str: prefix for the error message
  84. *
  85. * Note: string must be freed by the caller
  86. */
  87. extern void uci_get_errorstr(struct uci_context *ctx, char **dest, const char *str);
  88. /**
  89. * uci_import: Import uci config data from a stream
  90. * @ctx: uci context
  91. * @stream: file stream to import from
  92. * @name: (optional) assume the config has the given name
  93. * @package: (optional) store the last parsed config package in this variable
  94. * @single: ignore the 'package' keyword and parse everything into a single package
  95. *
  96. * the name parameter is for config files that don't explicitly use the 'package <...>' keyword
  97. * if 'package' points to a non-null struct pointer, enable delta tracking and merge
  98. */
  99. extern int uci_import(struct uci_context *ctx, FILE *stream, const char *name, struct uci_package **package, bool single);
  100. /**
  101. * uci_export: Export one or all uci config packages
  102. * @ctx: uci context
  103. * @stream: output stream
  104. * @package: (optional) uci config package to export
  105. * @header: include the package header
  106. */
  107. extern int uci_export(struct uci_context *ctx, FILE *stream, struct uci_package *package, bool header);
  108. /**
  109. * uci_load: Parse an uci config file and store it in the uci context
  110. *
  111. * @ctx: uci context
  112. * @name: name of the config file (relative to the config directory)
  113. * @package: store the loaded config package in this variable
  114. */
  115. extern int uci_load(struct uci_context *ctx, const char *name, struct uci_package **package);
  116. /**
  117. * uci_unload: Unload a config file from the uci context
  118. *
  119. * @ctx: uci context
  120. * @package: pointer to the uci_package struct
  121. */
  122. extern int uci_unload(struct uci_context *ctx, struct uci_package *p);
  123. /**
  124. * uci_lookup_ptr: Split an uci tuple string and look up an element tree
  125. * @ctx: uci context
  126. * @ptr: lookup result struct
  127. * @str: uci tuple string to look up
  128. * @extended: allow extended syntax lookup
  129. *
  130. * if extended is set to true, uci_lookup_ptr supports the following
  131. * extended syntax:
  132. *
  133. * Examples:
  134. * network.@interface[0].ifname ('ifname' option of the first interface section)
  135. * network.@interface[-1] (last interface section)
  136. * Note: uci_lookup_ptr will automatically load a config package if necessary
  137. * @str must not be constant, as it will be modified and used for the strings inside @ptr,
  138. * thus it must also be available as long as @ptr is in use.
  139. *
  140. * This function returns UCI_ERR_NOTFOUND if the package specified in the tuple
  141. * string cannot be found. Otherwise it will return UCI_OK.
  142. *
  143. * Note that failures in looking up other parts, if they are also specfied,
  144. * including section and option, will also have a return value UCI_OK but with
  145. * ptr->flags * UCI_LOOKUP_COMPLETE not set.
  146. */
  147. extern int uci_lookup_ptr(struct uci_context *ctx, struct uci_ptr *ptr, char *str, bool extended);
  148. /**
  149. * uci_add_section: Add an unnamed section
  150. * @ctx: uci context
  151. * @p: package to add the section to
  152. * @type: section type
  153. * @res: pointer to store a reference to the new section in
  154. */
  155. extern int uci_add_section(struct uci_context *ctx, struct uci_package *p, const char *type, struct uci_section **res);
  156. /**
  157. * uci_set: Set an element's value; create the element if necessary
  158. * @ctx: uci context
  159. * @ptr: uci pointer
  160. *
  161. * The updated/created element is stored in ptr->last
  162. */
  163. extern int uci_set(struct uci_context *ctx, struct uci_ptr *ptr);
  164. /**
  165. * uci_add_list: Append a string to an element list
  166. * @ctx: uci context
  167. * @ptr: uci pointer (with value)
  168. *
  169. * Note: if the given option already contains a string value,
  170. * it will be converted to an 1-element-list before appending the next element
  171. */
  172. extern int uci_add_list(struct uci_context *ctx, struct uci_ptr *ptr);
  173. /**
  174. * uci_del_list: Remove a string from an element list
  175. * @ctx: uci context
  176. * @ptr: uci pointer (with value)
  177. *
  178. */
  179. extern int uci_del_list(struct uci_context *ctx, struct uci_ptr *ptr);
  180. /**
  181. * uci_reorder: Reposition a section
  182. * @ctx: uci context
  183. * @s: uci section to reposition
  184. * @pos: new position in the section list
  185. */
  186. extern int uci_reorder_section(struct uci_context *ctx, struct uci_section *s, int pos);
  187. /**
  188. * uci_rename: Rename an element
  189. * @ctx: uci context
  190. * @ptr: uci pointer (with value)
  191. */
  192. extern int uci_rename(struct uci_context *ctx, struct uci_ptr *ptr);
  193. /**
  194. * uci_delete: Delete a section or option
  195. * @ctx: uci context
  196. * @ptr: uci pointer
  197. */
  198. extern int uci_delete(struct uci_context *ctx, struct uci_ptr *ptr);
  199. /**
  200. * uci_save: save change delta for a package
  201. * @ctx: uci context
  202. * @p: uci_package struct
  203. */
  204. extern int uci_save(struct uci_context *ctx, struct uci_package *p);
  205. /**
  206. * uci_commit: commit changes to a package
  207. * @ctx: uci context
  208. * @p: uci_package struct pointer
  209. * @overwrite: overwrite existing config data and flush delta
  210. *
  211. * committing may reload the whole uci_package data,
  212. * the supplied pointer is updated accordingly
  213. */
  214. extern int uci_commit(struct uci_context *ctx, struct uci_package **p, bool overwrite);
  215. /**
  216. * uci_list_configs: List available uci config files
  217. * @ctx: uci context
  218. *
  219. * caller is responsible for freeing the allocated memory behind list
  220. */
  221. extern int uci_list_configs(struct uci_context *ctx, char ***list);
  222. /**
  223. * uci_set_savedir: override the default delta save directory
  224. * @ctx: uci context
  225. * @dir: directory name
  226. *
  227. * This will also try adding the specified dir to the end of delta pathes.
  228. */
  229. extern int uci_set_savedir(struct uci_context *ctx, const char *dir);
  230. /**
  231. * uci_set_savedir: override the default config storage directory
  232. * @ctx: uci context
  233. * @dir: directory name
  234. */
  235. extern int uci_set_confdir(struct uci_context *ctx, const char *dir);
  236. /**
  237. * uci_add_delta_path: add a directory to the search path for change delta files
  238. * @ctx: uci context
  239. * @dir: directory name
  240. *
  241. * This function allows you to add directories, which contain 'overlays'
  242. * for the active config, that will never be committed.
  243. *
  244. * Adding a duplicate directory will cause UCI_ERR_DUPLICATE be returned.
  245. */
  246. extern int uci_add_delta_path(struct uci_context *ctx, const char *dir);
  247. /**
  248. * uci_revert: revert all changes to a config item
  249. * @ctx: uci context
  250. * @ptr: uci pointer
  251. */
  252. extern int uci_revert(struct uci_context *ctx, struct uci_ptr *ptr);
  253. /**
  254. * uci_parse_argument: parse a shell-style argument, with an arbitrary quoting style
  255. * @ctx: uci context
  256. * @stream: input stream
  257. * @str: pointer to the current line (use NULL for parsing the next line)
  258. * @result: pointer for the result
  259. */
  260. extern int uci_parse_argument(struct uci_context *ctx, FILE *stream, char **str, char **result);
  261. /**
  262. * uci_set_backend: change the default backend
  263. * @ctx: uci context
  264. * @name: name of the backend
  265. *
  266. * The default backend is "file", which uses /etc/config for config storage
  267. */
  268. extern int uci_set_backend(struct uci_context *ctx, const char *name);
  269. /**
  270. * uci_validate_text: validate a value string for uci options
  271. * @str: value
  272. *
  273. * this function checks whether a given string is acceptable as value
  274. * for uci options
  275. */
  276. extern bool uci_validate_text(const char *str);
  277. /**
  278. * uci_parse_ptr: parse a uci string into a uci_ptr
  279. * @ctx: uci context
  280. * @ptr: target data structure
  281. * @str: string to parse
  282. *
  283. * str is modified by this function
  284. */
  285. int uci_parse_ptr(struct uci_context *ctx, struct uci_ptr *ptr, char *str);
  286. /**
  287. * uci_lookup_next: lookup a child element
  288. * @ctx: uci context
  289. * @e: target element pointer
  290. * @list: list of elements
  291. * @name: name of the child element
  292. *
  293. * if parent is NULL, the function looks up the package with the given name
  294. */
  295. int uci_lookup_next(struct uci_context *ctx, struct uci_element **e, struct uci_list *list, const char *name);
  296. /**
  297. * uci_parse_section: look up a set of options
  298. * @s: uci section
  299. * @opts: list of options to look up
  300. * @n_opts: number of options to look up
  301. * @tb: array of pointers to found options
  302. */
  303. void uci_parse_section(struct uci_section *s, const struct uci_parse_option *opts,
  304. int n_opts, struct uci_option **tb);
  305. /**
  306. * uci_hash_options: build a hash over a list of options
  307. * @tb: list of option pointers
  308. * @n_opts: number of options
  309. */
  310. uint32_t uci_hash_options(struct uci_option **tb, int n_opts);
  311. /* UCI data structures */
  312. enum uci_type {
  313. UCI_TYPE_UNSPEC = 0,
  314. UCI_TYPE_DELTA = 1,
  315. UCI_TYPE_PACKAGE = 2,
  316. UCI_TYPE_SECTION = 3,
  317. UCI_TYPE_OPTION = 4,
  318. UCI_TYPE_PATH = 5,
  319. UCI_TYPE_BACKEND = 6,
  320. UCI_TYPE_ITEM = 7,
  321. UCI_TYPE_HOOK = 8,
  322. };
  323. enum uci_option_type {
  324. UCI_TYPE_STRING = 0,
  325. UCI_TYPE_LIST = 1,
  326. };
  327. enum uci_flags {
  328. UCI_FLAG_STRICT = (1 << 0), /* strict mode for the parser */
  329. UCI_FLAG_PERROR = (1 << 1), /* print parser error messages */
  330. UCI_FLAG_EXPORT_NAME = (1 << 2), /* when exporting, name unnamed sections */
  331. UCI_FLAG_SAVED_DELTA = (1 << 3), /* store the saved delta in memory as well */
  332. };
  333. struct uci_element
  334. {
  335. struct uci_list list;
  336. enum uci_type type;
  337. char *name;
  338. };
  339. struct uci_backend
  340. {
  341. struct uci_element e;
  342. char **(*list_configs)(struct uci_context *ctx);
  343. struct uci_package *(*load)(struct uci_context *ctx, const char *name);
  344. void (*commit)(struct uci_context *ctx, struct uci_package **p, bool overwrite);
  345. /* private: */
  346. const void *ptr;
  347. void *priv;
  348. };
  349. struct uci_context
  350. {
  351. /* list of config packages */
  352. struct uci_list root;
  353. /* parser context, use for error handling only */
  354. struct uci_parse_context *pctx;
  355. /* backend for import and export */
  356. struct uci_backend *backend;
  357. struct uci_list backends;
  358. /* uci runtime flags */
  359. enum uci_flags flags;
  360. char *confdir;
  361. char *savedir;
  362. /* search path for delta files */
  363. struct uci_list delta_path;
  364. /* private: */
  365. int err;
  366. const char *func;
  367. jmp_buf trap;
  368. bool internal, nested;
  369. char *buf;
  370. int bufsz;
  371. };
  372. struct uci_package
  373. {
  374. struct uci_element e;
  375. struct uci_list sections;
  376. struct uci_context *ctx;
  377. bool has_delta;
  378. char *path;
  379. /* private: */
  380. struct uci_backend *backend;
  381. void *priv;
  382. int n_section;
  383. struct uci_list delta;
  384. struct uci_list saved_delta;
  385. };
  386. struct uci_section
  387. {
  388. struct uci_element e;
  389. struct uci_list options;
  390. struct uci_package *package;
  391. bool anonymous;
  392. char *type;
  393. };
  394. struct uci_option
  395. {
  396. struct uci_element e;
  397. struct uci_section *section;
  398. enum uci_option_type type;
  399. union {
  400. struct uci_list list;
  401. char *string;
  402. } v;
  403. };
  404. /*
  405. * UCI_CMD_ADD is used for anonymous sections or list values
  406. */
  407. enum uci_command {
  408. UCI_CMD_ADD,
  409. UCI_CMD_REMOVE,
  410. UCI_CMD_CHANGE,
  411. UCI_CMD_RENAME,
  412. UCI_CMD_REORDER,
  413. UCI_CMD_LIST_ADD,
  414. UCI_CMD_LIST_DEL,
  415. __UCI_CMD_MAX,
  416. __UCI_CMD_LAST = __UCI_CMD_MAX - 1
  417. };
  418. extern char const uci_command_char[];
  419. struct uci_delta
  420. {
  421. struct uci_element e;
  422. enum uci_command cmd;
  423. char *section;
  424. char *value;
  425. };
  426. struct uci_ptr
  427. {
  428. enum uci_type target;
  429. enum {
  430. UCI_LOOKUP_DONE = (1 << 0),
  431. UCI_LOOKUP_COMPLETE = (1 << 1),
  432. UCI_LOOKUP_EXTENDED = (1 << 2),
  433. } flags;
  434. struct uci_package *p;
  435. struct uci_section *s;
  436. struct uci_option *o;
  437. struct uci_element *last;
  438. const char *package;
  439. const char *section;
  440. const char *option;
  441. const char *value;
  442. };
  443. struct uci_parse_option {
  444. const char *name;
  445. enum uci_option_type type;
  446. };
  447. /**
  448. * container_of - cast a member of a structure out to the containing structure
  449. * @ptr: the pointer to the member.
  450. * @type: the type of the container struct this is embedded in.
  451. * @member: the name of the member within the struct.
  452. */
  453. #ifndef container_of
  454. #define container_of(ptr, type, member) \
  455. ((type *) ((char *)ptr - offsetof(type,member)))
  456. #endif
  457. /**
  458. * uci_list_entry: casts an uci_list pointer to the containing struct.
  459. * @_type: config, section or option
  460. * @_ptr: pointer to the uci_list struct
  461. */
  462. #define list_to_element(ptr) \
  463. container_of(ptr, struct uci_element, list)
  464. /**
  465. * uci_foreach_entry: loop through a list of uci elements
  466. * @_list: pointer to the uci_list struct
  467. * @_ptr: iteration variable, struct uci_element
  468. *
  469. * use like a for loop, e.g:
  470. * uci_foreach(&list, p) {
  471. * ...
  472. * }
  473. */
  474. #define uci_foreach_element(_list, _ptr) \
  475. for(_ptr = list_to_element((_list)->next); \
  476. &_ptr->list != (_list); \
  477. _ptr = list_to_element(_ptr->list.next))
  478. /**
  479. * uci_foreach_entry_safe: like uci_foreach_safe, but safe for deletion
  480. * @_list: pointer to the uci_list struct
  481. * @_tmp: temporary variable, struct uci_element *
  482. * @_ptr: iteration variable, struct uci_element *
  483. *
  484. * use like a for loop, e.g:
  485. * uci_foreach(&list, p) {
  486. * ...
  487. * }
  488. */
  489. #define uci_foreach_element_safe(_list, _tmp, _ptr) \
  490. for(_ptr = list_to_element((_list)->next), \
  491. _tmp = list_to_element(_ptr->list.next); \
  492. &_ptr->list != (_list); \
  493. _ptr = _tmp, _tmp = list_to_element(_ptr->list.next))
  494. /**
  495. * uci_list_empty: returns true if a list is empty
  496. * @list: list head
  497. */
  498. #define uci_list_empty(list) ((list)->next == (list))
  499. /* wrappers for dynamic type handling */
  500. #define uci_type_backend UCI_TYPE_BACKEND
  501. #define uci_type_delta UCI_TYPE_DELTA
  502. #define uci_type_package UCI_TYPE_PACKAGE
  503. #define uci_type_section UCI_TYPE_SECTION
  504. #define uci_type_option UCI_TYPE_OPTION
  505. /* element typecasting */
  506. #ifdef UCI_DEBUG_TYPECAST
  507. static const char *uci_typestr[] = {
  508. [uci_type_backend] = "backend",
  509. [uci_type_delta] = "delta",
  510. [uci_type_package] = "package",
  511. [uci_type_section] = "section",
  512. [uci_type_option] = "option",
  513. };
  514. static void uci_typecast_error(int from, int to)
  515. {
  516. fprintf(stderr, "Invalid typecast from '%s' to '%s'\n", uci_typestr[from], uci_typestr[to]);
  517. }
  518. #define BUILD_CAST(_type) \
  519. static inline struct uci_ ## _type *uci_to_ ## _type (struct uci_element *e) \
  520. { \
  521. if (e->type != uci_type_ ## _type) { \
  522. uci_typecast_error(e->type, uci_type_ ## _type); \
  523. } \
  524. return (struct uci_ ## _type *) e; \
  525. }
  526. BUILD_CAST(backend)
  527. BUILD_CAST(delta)
  528. BUILD_CAST(package)
  529. BUILD_CAST(section)
  530. BUILD_CAST(option)
  531. #else
  532. #define uci_to_backend(ptr) container_of(ptr, struct uci_backend, e)
  533. #define uci_to_delta(ptr) container_of(ptr, struct uci_delta, e)
  534. #define uci_to_package(ptr) container_of(ptr, struct uci_package, e)
  535. #define uci_to_section(ptr) container_of(ptr, struct uci_section, e)
  536. #define uci_to_option(ptr) container_of(ptr, struct uci_option, e)
  537. #endif
  538. #define uci_dataptr(ptr) \
  539. (((char *) ptr) + sizeof(*ptr))
  540. /**
  541. * uci_lookup_package: look up a package
  542. * @ctx: uci context
  543. * @name: name of the package
  544. */
  545. static inline struct uci_package *
  546. uci_lookup_package(struct uci_context *ctx, const char *name)
  547. {
  548. struct uci_element *e = NULL;
  549. if (uci_lookup_next(ctx, &e, &ctx->root, name) == 0)
  550. return uci_to_package(e);
  551. else
  552. return NULL;
  553. }
  554. /**
  555. * uci_lookup_section: look up a section
  556. * @ctx: uci context
  557. * @p: package that the section belongs to
  558. * @name: name of the section
  559. */
  560. static inline struct uci_section *
  561. uci_lookup_section(struct uci_context *ctx, struct uci_package *p, const char *name)
  562. {
  563. struct uci_element *e = NULL;
  564. if (uci_lookup_next(ctx, &e, &p->sections, name) == 0)
  565. return uci_to_section(e);
  566. else
  567. return NULL;
  568. }
  569. /**
  570. * uci_lookup_option: look up an option
  571. * @ctx: uci context
  572. * @section: section that the option belongs to
  573. * @name: name of the option
  574. */
  575. static inline struct uci_option *
  576. uci_lookup_option(struct uci_context *ctx, struct uci_section *s, const char *name)
  577. {
  578. struct uci_element *e = NULL;
  579. if (uci_lookup_next(ctx, &e, &s->options, name) == 0)
  580. return uci_to_option(e);
  581. else
  582. return NULL;
  583. }
  584. static inline const char *
  585. uci_lookup_option_string(struct uci_context *ctx, struct uci_section *s, const char *name)
  586. {
  587. struct uci_option *o;
  588. o = uci_lookup_option(ctx, s, name);
  589. if (!o || o->type != UCI_TYPE_STRING)
  590. return NULL;
  591. return o->v.string;
  592. }
  593. #ifndef BITS_PER_LONG
  594. #define BITS_PER_LONG (8 * sizeof(unsigned long))
  595. #endif
  596. static inline void uci_bitfield_set(unsigned long *bits, int bit)
  597. {
  598. bits[bit / BITS_PER_LONG] |= (1UL << (bit % BITS_PER_LONG));
  599. }
  600. #ifdef __cplusplus
  601. }
  602. #endif
  603. #endif