lua: use uci_foreach_element_safe in uci_lua_foreach() - patch by jow
[project/uci.git] / uci.h
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 General Public License for more details.
13  */
14
15 #ifndef __LIBUCI_H
16 #define __LIBUCI_H
17
18 #include "uci_config.h"
19
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
29 #include <stdbool.h>
30 #include <setjmp.h>
31 #include <stdio.h>
32
33 #define UCI_CONFDIR "/etc/config"
34 #define UCI_SAVEDIR "/tmp/.uci"
35 #define UCI_DIRMODE 0700
36 #define UCI_FILEMODE 0600
37
38 enum
39 {
40         UCI_OK = 0,
41         UCI_ERR_MEM,
42         UCI_ERR_INVAL,
43         UCI_ERR_NOTFOUND,
44         UCI_ERR_IO,
45         UCI_ERR_PARSE,
46         UCI_ERR_DUPLICATE,
47         UCI_ERR_UNKNOWN,
48         UCI_ERR_LAST
49 };
50
51 struct uci_list;
52 struct uci_list
53 {
54         struct uci_list *next;
55         struct uci_list *prev;
56 };
57
58 struct uci_ptr;
59 struct uci_plugin;
60 struct uci_hook_ops;
61 struct uci_element;
62 struct uci_package;
63 struct uci_section;
64 struct uci_option;
65 struct uci_delta;
66 struct uci_context;
67 struct uci_backend;
68 struct uci_parse_context;
69
70
71 /**
72  * uci_alloc_context: Allocate a new uci context
73  */
74 extern struct uci_context *uci_alloc_context(void);
75
76 /**
77  * uci_free_context: Free the uci context including all of its data
78  */
79 extern void uci_free_context(struct uci_context *ctx);
80
81 /**
82  * uci_perror: Print the last uci error that occured
83  * @ctx: uci context
84  * @str: string to print before the error message
85  */
86 extern void uci_perror(struct uci_context *ctx, const char *str);
87
88 /**
89  * uci_geterror: Get an error string for the last uci error
90  * @ctx: uci context
91  * @dest: target pointer for the string
92  * @str: prefix for the error message
93  *
94  * Note: string must be freed by the caller
95  */
96 extern void uci_get_errorstr(struct uci_context *ctx, char **dest, const char *str);
97
98 /**
99  * uci_import: Import uci config data from a stream
100  * @ctx: uci context
101  * @stream: file stream to import from
102  * @name: (optional) assume the config has the given name
103  * @package: (optional) store the last parsed config package in this variable
104  * @single: ignore the 'package' keyword and parse everything into a single package
105  *
106  * the name parameter is for config files that don't explicitly use the 'package <...>' keyword
107  * if 'package' points to a non-null struct pointer, enable delta tracking and merge
108  */
109 extern int uci_import(struct uci_context *ctx, FILE *stream, const char *name, struct uci_package **package, bool single);
110
111 /**
112  * uci_export: Export one or all uci config packages
113  * @ctx: uci context
114  * @stream: output stream
115  * @package: (optional) uci config package to export
116  * @header: include the package header
117  */
118 extern int uci_export(struct uci_context *ctx, FILE *stream, struct uci_package *package, bool header);
119
120 /**
121  * uci_load: Parse an uci config file and store it in the uci context
122  *
123  * @ctx: uci context
124  * @name: name of the config file (relative to the config directory)
125  * @package: store the loaded config package in this variable
126  */
127 extern int uci_load(struct uci_context *ctx, const char *name, struct uci_package **package);
128
129 /**
130  * uci_unload: Unload a config file from the uci context
131  *
132  * @ctx: uci context
133  * @package: pointer to the uci_package struct
134  */
135 extern int uci_unload(struct uci_context *ctx, struct uci_package *p);
136
137 /**
138  * uci_lookup_ptr: Split an uci tuple string and look up an element tree
139  * @ctx: uci context
140  * @ptr: lookup result struct
141  * @str: uci tuple string to look up
142  * @extended: allow extended syntax lookup
143  *
144  * if extended is set to true, uci_lookup_ptr supports the following
145  * extended syntax:
146  *
147  * Examples:
148  *   network.@interface[0].ifname ('ifname' option of the first interface section)
149  *   network.@interface[-1]       (last interface section)
150  * Note: uci_lookup_ptr will automatically load a config package if necessary
151  * @str must not be constant, as it will be modified and used for the strings inside @ptr,
152  * thus it must also be available as long as @ptr is in use.
153  */
154 extern int uci_lookup_ptr(struct uci_context *ctx, struct uci_ptr *ptr, char *str, bool extended);
155
156 /**
157  * uci_add_section: Add an unnamed section
158  * @ctx: uci context
159  * @p: package to add the section to
160  * @type: section type
161  * @res: pointer to store a reference to the new section in
162  */
163 extern int uci_add_section(struct uci_context *ctx, struct uci_package *p, const char *type, struct uci_section **res);
164
165 /**
166  * uci_set: Set an element's value; create the element if necessary
167  * @ctx: uci context
168  * @ptr: uci pointer
169  *
170  * The updated/created element is stored in ptr->last
171  */
172 extern int uci_set(struct uci_context *ctx, struct uci_ptr *ptr);
173
174 /**
175  * uci_add_list: Append a string to an element list
176  * @ctx: uci context
177  * @ptr: uci pointer (with value)
178  *
179  * Note: if the given option already contains a string value,
180  * it will be converted to an 1-element-list before appending the next element
181  */
182 extern int uci_add_list(struct uci_context *ctx, struct uci_ptr *ptr);
183
184 /**
185  * uci_reorder: Reposition a section
186  * @ctx: uci context
187  * @s: uci section to reposition
188  * @pos: new position in the section list
189  */
190 extern int uci_reorder_section(struct uci_context *ctx, struct uci_section *s, int pos);
191
192 /**
193  * uci_rename: Rename an element
194  * @ctx: uci context
195  * @ptr: uci pointer (with value)
196  */
197 extern int uci_rename(struct uci_context *ctx, struct uci_ptr *ptr);
198
199 /**
200  * uci_delete: Delete a section or option
201  * @ctx: uci context
202  * @ptr: uci pointer
203  */
204 extern int uci_delete(struct uci_context *ctx, struct uci_ptr *ptr);
205
206 /**
207  * uci_save: save change delta for a package
208  * @ctx: uci context
209  * @p: uci_package struct
210  */
211 extern int uci_save(struct uci_context *ctx, struct uci_package *p);
212
213 /**
214  * uci_commit: commit changes to a package
215  * @ctx: uci context
216  * @p: uci_package struct pointer
217  * @overwrite: overwrite existing config data and flush delta
218  *
219  * committing may reload the whole uci_package data,
220  * the supplied pointer is updated accordingly
221  */
222 extern int uci_commit(struct uci_context *ctx, struct uci_package **p, bool overwrite);
223
224 /**
225  * uci_list_configs: List available uci config files
226  * @ctx: uci context
227  *
228  * caller is responsible for freeing the allocated memory behind list
229  */
230 extern int uci_list_configs(struct uci_context *ctx, char ***list);
231
232 /**
233  * uci_set_savedir: override the default delta save directory
234  * @ctx: uci context
235  * @dir: directory name
236  */
237 extern int uci_set_savedir(struct uci_context *ctx, const char *dir);
238
239 /**
240  * uci_set_savedir: override the default config storage directory
241  * @ctx: uci context
242  * @dir: directory name
243  */
244 extern int uci_set_confdir(struct uci_context *ctx, const char *dir);
245
246 /**
247  * uci_add_delta_path: add a directory to the search path for change delta files
248  * @ctx: uci context
249  * @dir: directory name
250  *
251  * This function allows you to add directories, which contain 'overlays'
252  * for the active config, that will never be committed.
253  */
254 extern int uci_add_delta_path(struct uci_context *ctx, const char *dir);
255
256 /**
257  * uci_revert: revert all changes to a config item
258  * @ctx: uci context
259  * @ptr: uci pointer
260  */
261 extern int uci_revert(struct uci_context *ctx, struct uci_ptr *ptr);
262
263 /**
264  * uci_parse_argument: parse a shell-style argument, with an arbitrary quoting style
265  * @ctx: uci context
266  * @stream: input stream
267  * @str: pointer to the current line (use NULL for parsing the next line)
268  * @result: pointer for the result
269  */
270 extern int uci_parse_argument(struct uci_context *ctx, FILE *stream, char **str, char **result);
271
272 /**
273  * uci_set_backend: change the default backend
274  * @ctx: uci context
275  * @name: name of the backend
276  *
277  * The default backend is "file", which uses /etc/config for config storage
278  */
279 extern int uci_set_backend(struct uci_context *ctx, const char *name);
280
281 /**
282  * uci_validate_text: validate a value string for uci options
283  * @str: value
284  *
285  * this function checks whether a given string is acceptable as value
286  * for uci options
287  */
288 extern bool uci_validate_text(const char *str);
289
290
291 /**
292  * uci_add_hook: add a uci hook
293  * @ctx: uci context
294  * @ops: uci hook ops
295  *
296  * NB: allocated and freed by the caller
297  */
298 extern int uci_add_hook(struct uci_context *ctx, const struct uci_hook_ops *ops);
299
300 /**
301  * uci_remove_hook: remove a uci hook
302  * @ctx: uci context
303  * @ops: uci hook ops
304  */
305 extern int uci_remove_hook(struct uci_context *ctx, const struct uci_hook_ops *ops);
306
307 /**
308  * uci_load_plugin: load an uci plugin
309  * @ctx: uci context
310  * @filename: path to the uci plugin
311  *
312  * NB: plugin will be unloaded automatically when the context is freed
313  */
314 int uci_load_plugin(struct uci_context *ctx, const char *filename);
315
316 /**
317  * uci_load_plugins: load all uci plugins from a directory
318  * @ctx: uci context
319  * @pattern: pattern of uci plugin files (optional)
320  *
321  * if pattern is NULL, then uci_load_plugins will call uci_load_plugin
322  * for uci_*.so in <prefix>/lib/
323  */
324 int uci_load_plugins(struct uci_context *ctx, const char *pattern);
325
326 /**
327  * uci_parse_ptr: parse a uci string into a uci_ptr
328  * @ctx: uci context
329  * @ptr: target data structure
330  * @str: string to parse
331  *
332  * str is modified by this function
333  */
334 int uci_parse_ptr(struct uci_context *ctx, struct uci_ptr *ptr, char *str);
335
336 /**
337  * uci_lookup_next: lookup a child element
338  * @ctx: uci context
339  * @e: target element pointer
340  * @list: list of elements
341  * @name: name of the child element
342  *
343  * if parent is NULL, the function looks up the package with the given name
344  */
345 int uci_lookup_next(struct uci_context *ctx, struct uci_element **e, struct uci_list *list, const char *name);
346
347
348 /* UCI data structures */
349 enum uci_type {
350         UCI_TYPE_UNSPEC = 0,
351         UCI_TYPE_DELTA = 1,
352         UCI_TYPE_PACKAGE = 2,
353         UCI_TYPE_SECTION = 3,
354         UCI_TYPE_OPTION = 4,
355         UCI_TYPE_PATH = 5,
356         UCI_TYPE_BACKEND = 6,
357         UCI_TYPE_ITEM = 7,
358         UCI_TYPE_HOOK = 8,
359         UCI_TYPE_PLUGIN = 9,
360 };
361
362 enum uci_option_type {
363         UCI_TYPE_STRING = 0,
364         UCI_TYPE_LIST = 1,
365 };
366
367 enum uci_flags {
368         UCI_FLAG_STRICT =        (1 << 0), /* strict mode for the parser */
369         UCI_FLAG_PERROR =        (1 << 1), /* print parser error messages */
370         UCI_FLAG_EXPORT_NAME =   (1 << 2), /* when exporting, name unnamed sections */
371         UCI_FLAG_SAVED_DELTA = (1 << 3), /* store the saved delta in memory as well */
372 };
373
374 struct uci_element
375 {
376         struct uci_list list;
377         enum uci_type type;
378         char *name;
379 };
380
381 struct uci_backend
382 {
383         struct uci_element e;
384         char **(*list_configs)(struct uci_context *ctx);
385         struct uci_package *(*load)(struct uci_context *ctx, const char *name);
386         void (*commit)(struct uci_context *ctx, struct uci_package **p, bool overwrite);
387
388         /* private: */
389         const void *ptr;
390         void *priv;
391 };
392
393 struct uci_context
394 {
395         /* list of config packages */
396         struct uci_list root;
397
398         /* parser context, use for error handling only */
399         struct uci_parse_context *pctx;
400
401         /* backend for import and export */
402         struct uci_backend *backend;
403         struct uci_list backends;
404
405         /* uci runtime flags */
406         enum uci_flags flags;
407
408         char *confdir;
409         char *savedir;
410
411         /* search path for delta files */
412         struct uci_list delta_path;
413
414         /* private: */
415         int err;
416         const char *func;
417         jmp_buf trap;
418         bool internal, nested;
419         char *buf;
420         int bufsz;
421
422         struct uci_list hooks;
423         struct uci_list plugins;
424 };
425
426 struct uci_package
427 {
428         struct uci_element e;
429         struct uci_list sections;
430         struct uci_context *ctx;
431         bool has_delta;
432         char *path;
433
434         /* private: */
435         struct uci_backend *backend;
436         void *priv;
437         int n_section;
438         struct uci_list delta;
439         struct uci_list saved_delta;
440 };
441
442 struct uci_section
443 {
444         struct uci_element e;
445         struct uci_list options;
446         struct uci_package *package;
447         bool anonymous;
448         char *type;
449 };
450
451 struct uci_option
452 {
453         struct uci_element e;
454         struct uci_section *section;
455         enum uci_option_type type;
456         union {
457                 struct uci_list list;
458                 char *string;
459         } v;
460 };
461
462 enum uci_command {
463         UCI_CMD_ADD,
464         UCI_CMD_REMOVE,
465         UCI_CMD_CHANGE,
466         UCI_CMD_RENAME,
467         UCI_CMD_REORDER,
468         UCI_CMD_LIST_ADD,
469 };
470
471 struct uci_delta
472 {
473         struct uci_element e;
474         enum uci_command cmd;
475         char *section;
476         char *value;
477 };
478
479 struct uci_ptr
480 {
481         enum uci_type target;
482         enum {
483                 UCI_LOOKUP_DONE =     (1 << 0),
484                 UCI_LOOKUP_COMPLETE = (1 << 1),
485                 UCI_LOOKUP_EXTENDED = (1 << 2),
486         } flags;
487
488         struct uci_package *p;
489         struct uci_section *s;
490         struct uci_option *o;
491         struct uci_element *last;
492
493         const char *package;
494         const char *section;
495         const char *option;
496         const char *value;
497 };
498
499 struct uci_hook_ops
500 {
501         void (*load)(const struct uci_hook_ops *ops, struct uci_package *p);
502         void (*set)(const struct uci_hook_ops *ops, struct uci_package *p, struct uci_delta *e);
503 };
504
505 struct uci_hook
506 {
507         struct uci_element e;
508         const struct uci_hook_ops *ops;
509 };
510
511 struct uci_plugin_ops
512 {
513         int (*attach)(struct uci_context *ctx);
514         void (*detach)(struct uci_context *ctx);
515 };
516
517 struct uci_plugin
518 {
519         struct uci_element e;
520         const struct uci_plugin_ops *ops;
521         void *dlh;
522 };
523
524
525 /* linked list handling */
526 #ifndef offsetof
527 #define offsetof(TYPE, MEMBER) ((size_t) &((TYPE *)0)->MEMBER)
528 #endif
529
530 /**
531  * container_of - cast a member of a structure out to the containing structure
532  * @ptr:    the pointer to the member.
533  * @type:   the type of the container struct this is embedded in.
534  * @member: the name of the member within the struct.
535  */
536 #ifndef container_of
537 #define container_of(ptr, type, member) \
538         ((type *) ((char *)ptr - offsetof(type,member)))
539 #endif
540
541
542 /**
543  * uci_list_entry: casts an uci_list pointer to the containing struct.
544  * @_type: config, section or option
545  * @_ptr: pointer to the uci_list struct
546  */
547 #define list_to_element(ptr) \
548         container_of(ptr, struct uci_element, list)
549
550 /**
551  * uci_foreach_entry: loop through a list of uci elements
552  * @_list: pointer to the uci_list struct
553  * @_ptr: iteration variable, struct uci_element
554  *
555  * use like a for loop, e.g:
556  *   uci_foreach(&list, p) {
557  *      ...
558  *   }
559  */
560 #define uci_foreach_element(_list, _ptr)                \
561         for(_ptr = list_to_element((_list)->next);      \
562                 &_ptr->list != (_list);                 \
563                 _ptr = list_to_element(_ptr->list.next))
564
565 /**
566  * uci_foreach_entry_safe: like uci_foreach_safe, but safe for deletion
567  * @_list: pointer to the uci_list struct
568  * @_tmp: temporary variable, struct uci_element *
569  * @_ptr: iteration variable, struct uci_element *
570  *
571  * use like a for loop, e.g:
572  *   uci_foreach(&list, p) {
573  *      ...
574  *   }
575  */
576 #define uci_foreach_element_safe(_list, _tmp, _ptr)             \
577         for(_ptr = list_to_element((_list)->next),              \
578                 _tmp = list_to_element(_ptr->list.next);        \
579                 &_ptr->list != (_list);                 \
580                 _ptr = _tmp, _tmp = list_to_element(_ptr->list.next))
581
582 /**
583  * uci_list_empty: returns true if a list is empty
584  * @list: list head
585  */
586 #define uci_list_empty(list) ((list)->next == (list))
587
588 /* wrappers for dynamic type handling */
589 #define uci_type_backend UCI_TYPE_BACKEND
590 #define uci_type_delta UCI_TYPE_DELTA
591 #define uci_type_package UCI_TYPE_PACKAGE
592 #define uci_type_section UCI_TYPE_SECTION
593 #define uci_type_option UCI_TYPE_OPTION
594 #define uci_type_hook UCI_TYPE_HOOK
595 #define uci_type_plugin UCI_TYPE_PLUGIN
596
597 /* element typecasting */
598 #ifdef UCI_DEBUG_TYPECAST
599 static const char *uci_typestr[] = {
600         [uci_type_backend] = "backend",
601         [uci_type_delta] = "delta",
602         [uci_type_package] = "package",
603         [uci_type_section] = "section",
604         [uci_type_option] = "option",
605         [uci_type_hook] = "hook",
606         [uci_type_plugin] = "plugin",
607 };
608
609 static void uci_typecast_error(int from, int to)
610 {
611         fprintf(stderr, "Invalid typecast from '%s' to '%s'\n", uci_typestr[from], uci_typestr[to]);
612 }
613
614 #define BUILD_CAST(_type) \
615         static inline struct uci_ ## _type *uci_to_ ## _type (struct uci_element *e) \
616         { \
617                 if (e->type != uci_type_ ## _type) { \
618                         uci_typecast_error(e->type, uci_type_ ## _type); \
619                 } \
620                 return (struct uci_ ## _type *) e; \
621         }
622
623 BUILD_CAST(backend)
624 BUILD_CAST(delta)
625 BUILD_CAST(package)
626 BUILD_CAST(section)
627 BUILD_CAST(option)
628 BUILD_CAST(hook)
629 BUILD_CAST(plugin)
630
631 #else
632 #define uci_to_backend(ptr) container_of(ptr, struct uci_backend, e)
633 #define uci_to_delta(ptr) container_of(ptr, struct uci_delta, e)
634 #define uci_to_package(ptr) container_of(ptr, struct uci_package, e)
635 #define uci_to_section(ptr) container_of(ptr, struct uci_section, e)
636 #define uci_to_option(ptr)  container_of(ptr, struct uci_option, e)
637 #define uci_to_hook(ptr)    container_of(ptr, struct uci_hook, e)
638 #define uci_to_plugin(ptr)  container_of(ptr, struct uci_plugin, e)
639 #endif
640
641 /**
642  * uci_alloc_element: allocate a generic uci_element, reserve a buffer and typecast
643  * @ctx: uci context
644  * @type: {package,section,option}
645  * @name: string containing the name of the element
646  * @datasize: additional buffer size to reserve at the end of the struct
647  */
648 #define uci_alloc_element(ctx, type, name, datasize) \
649         uci_to_ ## type (uci_alloc_generic(ctx, uci_type_ ## type, name, sizeof(struct uci_ ## type) + datasize))
650
651 #define uci_dataptr(ptr) \
652         (((char *) ptr) + sizeof(*ptr))
653
654 /**
655  * uci_lookup_package: look up a package
656  * @ctx: uci context
657  * @name: name of the package
658  */
659 static inline struct uci_package *
660 uci_lookup_package(struct uci_context *ctx, const char *name)
661 {
662         struct uci_element *e = NULL;
663         if (uci_lookup_next(ctx, &e, &ctx->root, name) == 0)
664                 return uci_to_package(e);
665         else
666                 return NULL;
667 }
668
669 /**
670  * uci_lookup_section: look up a section
671  * @ctx: uci context
672  * @p: package that the section belongs to
673  * @name: name of the section
674  */
675 static inline struct uci_section *
676 uci_lookup_section(struct uci_context *ctx, struct uci_package *p, const char *name)
677 {
678         struct uci_element *e = NULL;
679         if (uci_lookup_next(ctx, &e, &p->sections, name) == 0)
680                 return uci_to_section(e);
681         else
682                 return NULL;
683 }
684
685 /**
686  * uci_lookup_option: look up an option
687  * @ctx: uci context
688  * @section: section that the option belongs to
689  * @name: name of the option
690  */
691 static inline struct uci_option *
692 uci_lookup_option(struct uci_context *ctx, struct uci_section *s, const char *name)
693 {
694         struct uci_element *e = NULL;
695         if (uci_lookup_next(ctx, &e, &s->options, name) == 0)
696                 return uci_to_option(e);
697         else
698                 return NULL;
699 }
700
701 static inline const char *
702 uci_lookup_option_string(struct uci_context *ctx, struct uci_section *s, const char *name)
703 {
704         struct uci_option *o;
705
706         o = uci_lookup_option(ctx, s, name);
707         if (!o || o->type != UCI_TYPE_STRING)
708                 return NULL;
709
710         return o->v.string;
711 }
712
713 #endif