X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;f=ucw%2Fconf.h;h=11026b7a6fdf7d0bffde4468412e485ee11a12a8;hb=a7992185caf3d46b152653937063fe72582214df;hp=fc0f95591ef5730b4ad0fec36cd2095767b1fe50;hpb=508bb06ba7a9d9737bb4174594e79a51205087c4;p=libucw.git diff --git a/ucw/conf.h b/ucw/conf.h index fc0f9559..11026b7a 100644 --- a/ucw/conf.h +++ b/ucw/conf.h @@ -2,7 +2,7 @@ * UCW Library -- Configuration files * * (c) 2001--2006 Robert Spalek - * (c) 2003--2006 Martin Mares + * (c) 2003--2014 Martin Mares * * This software may be freely distributed and used according to the terms * of the GNU Lesser General Public License. @@ -11,6 +11,133 @@ #ifndef _UCW_CONF_H #define _UCW_CONF_H +#include +#include + +#ifdef CONFIG_UCW_CLEAN_ABI +#define cf_close_group ucw_cf_close_group +#define cf_declare_rel_section ucw_cf_declare_rel_section +#define cf_declare_section ucw_cf_declare_section +#define cf_delete_context ucw_cf_delete_context +#define cf_dump_sections ucw_cf_dump_sections +#define cf_find_item ucw_cf_find_item +#define cf_get_pool ucw_cf_get_pool +#define cf_init_section ucw_cf_init_section +#define cf_journal_block ucw_cf_journal_block +#define cf_journal_commit_transaction ucw_cf_journal_commit_transaction +#define cf_journal_new_transaction ucw_cf_journal_new_transaction +#define cf_journal_rollback_transaction ucw_cf_journal_rollback_transaction +#define cf_load ucw_cf_load +#define cf_malloc ucw_cf_malloc +#define cf_malloc_zero ucw_cf_malloc_zero +#define cf_modify_item ucw_cf_modify_item +#define cf_new_context ucw_cf_new_context +#define cf_open_group ucw_cf_open_group +#define cf_parse_double ucw_cf_parse_double +#define cf_parse_int ucw_cf_parse_int +#define cf_parse_ip ucw_cf_parse_ip +#define cf_parse_u64 ucw_cf_parse_u64 +#define cf_printf ucw_cf_printf +#define cf_reload ucw_cf_reload +#define cf_revert ucw_cf_revert +#define cf_set ucw_cf_set +#define cf_set_journalling ucw_cf_set_journalling +#define cf_strdup ucw_cf_strdup +#define cf_switch_context ucw_cf_switch_context +#endif + +struct mempool; + +/*** + * [[conf_ctxt]] + * Configuration contexts + * ~~~~~~~~~~~~~~~~~~~~~~ + * + * The state of the configuration parser is stored within a configuration context. + * One such context is automatically created during initialization of the library + * and you need not care about more, as long as you use a single configuration file. + * + * In full generality, you can define as many contexts as you wish and switch + * between them. Each thread has its own pointer to the current context, which + * must not be shared with other threads. + ***/ + +/** Create a new configuration context. **/ +struct cf_context *cf_new_context(void); + +/** + * Free a configuration context. The context must not be set as current + * for any thread, nor can it be the default context. + * + * All configuration settings made within the context are rolled back + * (except when journalling is turned off). All memory allocated on behalf + * of the context is freed, which includes memory obtained by calls to + * @cf_malloc(). + **/ +void cf_delete_context(struct cf_context *cc); + +/** + * Make the given configuration context current and return the previously + * active context. Both the new and the old context may be NULL. + **/ +struct cf_context *cf_switch_context(struct cf_context *cc); + +/*** + * [[conf_load]] + * Safe configuration loading + * ~~~~~~~~~~~~~~~~~~~~~~~~~~ + * + * These functions can be used to to safely load or reload configuration. + */ + +/** + * Load configuration from @file. + * Returns a non-zero value upon error. In that case, all changes to the + * configuration specified in the file are undone. + **/ +int cf_load(const char *file); + +/** + * Reload configuration from @file, replace the old one. + * If @file is NULL, reload all loaded configuration files and re-apply + * bits of configuration passed to @cf_set(). + * Returns a non-zero value upon error. In that case, all configuration + * settings are rolled back to the state before calling this function. + **/ +int cf_reload(const char *file); + +/** + * Parse some part of configuration passed in @string. + * The syntax is the same as in the <>. + * Returns a non-zero value upon error. In that case, all changes to the + * configuration specified by the already executed parts of the string + * are undone. + **/ +int cf_set(const char *string); + +/** + * Sometimes, the configuration is split to multiple files and when only + * some of the are loaded, the settings are not consistent -- for example, + * they might have been rejected by a commit hook, because a mandatory setting + * is missing. + * + * This function opens a configuration group, in which multiple files can be + * loaded and all commit hooks are deferred until the group is closed. + **/ +void cf_open_group(void); + +/** + * Close a group opened by @cf_open_group(). Returns a non-zero value upon error, + * which usually means that a commit hook has failed. + **/ +int cf_close_group(void); + +/** + * Return all configuration items to their initial state before loading the + * configuration file. If journalling is disabled, it does nothing. + **/ +void cf_revert(void); + /*** === Data types [[conf_types]] ***/ enum cf_class { /** Class of the configuration item. **/ @@ -40,7 +167,7 @@ struct fastbuf; * @cf_journal_block() on the overwritten memory block. It returns an error * message or NULL if everything is all right. **/ -typedef char *cf_parser(uns number, char **pars, void *ptr); +typedef char *cf_parser(uint number, char **pars, void *ptr); /** * A parser function for user-defined types gets a string and a pointer to * the destination variable. It must store the value within [ptr,ptr+size), @@ -70,7 +197,7 @@ typedef void cf_dumper1(struct fastbuf *fb, void *ptr); typedef char *cf_copier(void *dest, void *src); struct cf_user_type { /** Structure to store information about user-defined variable type. **/ - uns size; // of the parsed attribute + uint size; // of the parsed attribute char *name; // name of the type (for dumping) cf_parser1 *parser; // how to parse it cf_dumper1 *dumper; // how to dump the type @@ -92,12 +219,12 @@ struct cf_item { /** Single configuration item. **/ }; struct cf_section { /** A section. **/ - uns size; // 0 for a global block, sizeof(struct) for a section + uint size; // 0 for a global block, sizeof(struct) for a section cf_hook *init; // fills in default values (no need to bzero) cf_hook *commit; // verifies parsed data (optional) cf_copier *copy; // copies values from another instance (optional, no need to copy basic attributes) struct cf_item *cfg; // CC_END-terminated array of items - uns flags; // for internal use only + uint flags; // for internal use only }; /*** @@ -129,16 +256,16 @@ struct cf_section { /** A section. **/ * struct list_node { * cnode n; // This one is for the list itself * char *name; - * uns value; + * uint value; * }; * - * struct clist nodes; + * static struct clist nodes; * * static struct cf_section node = { * CF_TYPE(struct list_node), * CF_ITEMS { * CF_STRING("name", PTR_TO(struct list_node, name)), - * CF_UNS("value", PTR_TO(struct list_node, value)), + * CF_UINT("value", PTR_TO(struct list_node, value)), * CF_END * } * }; @@ -148,7 +275,7 @@ struct cf_section { /** A section. **/ * CF_END * }; * - * You could use <> or <> + * You could use <> or <> * macros to create arrays. */ #define CF_TYPE(s) .size = sizeof(s) @@ -215,20 +342,26 @@ struct cf_section { /** A section. **/ * * @c -- count. **/ #define CF_INT(n,p) CF_STATIC(n,p,INT,int,1) /** Single `int` value. **/ -#define CF_INT_ARY(n,p,c) CF_STATIC(n,p,INT,int,c) /** Static array of `int` s. **/ -#define CF_INT_DYN(n,p,c) CF_DYNAMIC(n,p,INT,int,c) /** Dynamic array of `int` s. **/ -#define CF_UNS(n,p) CF_STATIC(n,p,INT,uns,1) /** Single `uns` (`unsigned`) value. **/ -#define CF_UNS_ARY(n,p,c) CF_STATIC(n,p,INT,uns,c) /** Static array of `uns` es. **/ -#define CF_UNS_DYN(n,p,c) CF_DYNAMIC(n,p,INT,uns,c) /** Dynamic array of `uns` es. **/ +#define CF_INT_ARY(n,p,c) CF_STATIC(n,p,INT,int,c) /** Static array of integers. **/ +#define CF_INT_DYN(n,p,c) CF_DYNAMIC(n,p,INT,int,c) /** Dynamic array of integers. **/ +#define CF_UINT(n,p) CF_STATIC(n,p,INT,uint,1) /** Single `uint` (`unsigned`) value. **/ +#define CF_UINT_ARY(n,p,c) CF_STATIC(n,p,INT,uint,c) /** Static array of unsigned integers. **/ +#define CF_UINT_DYN(n,p,c) CF_DYNAMIC(n,p,INT,uint,c) /** Dynamic array of unsigned integers. **/ #define CF_U64(n,p) CF_STATIC(n,p,U64,u64,1) /** Single unsigned 64bit integer (`u64`). **/ -#define CF_U64_ARY(n,p,c) CF_STATIC(n,p,U64,u64,c) /** Static array of `u64` s. **/ -#define CF_U64_DYN(n,p,c) CF_DYNAMIC(n,p,U64,u64,c) /** Dynamic array of `u64` s. **/ +#define CF_U64_ARY(n,p,c) CF_STATIC(n,p,U64,u64,c) /** Static array of u64s. **/ +#define CF_U64_DYN(n,p,c) CF_DYNAMIC(n,p,U64,u64,c) /** Dynamic array of u64s. **/ #define CF_DOUBLE(n,p) CF_STATIC(n,p,DOUBLE,double,1) /** Single instance of `double`. **/ -#define CF_DOUBLE_ARY(n,p,c) CF_STATIC(n,p,DOUBLE,double,c) /** Static array of `double` s. **/ -#define CF_DOUBLE_DYN(n,p,c) CF_DYNAMIC(n,p,DOUBLE,double,c) /** Dynamic array of `double` s. **/ +#define CF_DOUBLE_ARY(n,p,c) CF_STATIC(n,p,DOUBLE,double,c) /** Static array of doubles. **/ +#define CF_DOUBLE_DYN(n,p,c) CF_DYNAMIC(n,p,DOUBLE,double,c) /** Dynamic array of doubles. **/ #define CF_IP(n,p) CF_STATIC(n,p,IP,u32,1) /** Single IPv4 address. **/ #define CF_IP_ARY(n,p,c) CF_STATIC(n,p,IP,u32,c) /** Static array of IP addresses. **/. #define CF_IP_DYN(n,p,c) CF_DYNAMIC(n,p,IP,u32,c) /** Dynamic array of IP addresses. **/ + +/* FIXME: Backwards compatibility only, should not be used at is will be removed soon. */ +#define CF_UNS CF_UINT +#define CF_UNS_ARY CF_UINT_ARY +#define CF_UNS_DYN CF_UINT_DYN + /** * A string. * You provide a pointer to a `char *` variable and it will fill it with @@ -297,28 +430,28 @@ struct cf_section { /** A section. **/ **/ #define CF_ANY_NUM -0x7fffffff -#define DARY_LEN(a) ((uns*)a)[-1] /** Length of an dynamic array. **/ -#define DARY_ALLOC(type,len,val...) ((struct { uns l; type a[len]; }) { .l = len, .a = { val } }).a - // creates a static instance of a dynamic array +#define DARY_LEN(a) GARY_SIZE(a) /** Length of an dynamic array. An alias for `GARY_SIZE`. **/ /*** * [[alloc]] * Memory allocation * ~~~~~~~~~~~~~~~~~ * - * Uses <> for efficiency and journal recovery. - * You should use these routines when implementing custom parsers. + * Each configuration context has one or more <>, where all + * data related to the configuration are stored. + * + * The following set of functions allocate from these pools. The allocated memory + * is valid as long as the current configuration (when the configuration file is + * reloaded or rolled back, or the context is deleted, it gets lost). + * + * Memory allocated from within custom parsers should be allocated from the pools. + * + * Please note that the pool is not guaranteed to exist before you call cf_load(), + * cf_set(), or cf_getopt() on the particular context. ***/ -struct mempool; -/** - * A <> for configuration parser needs. - * Memory allocated from here is valid as long as the current config is loaded - * (if you allocate some memory and rollback the transaction or you load some - * other configuration, it gets lost). - **/ -extern struct mempool *cf_pool; -void *cf_malloc(uns size); /** Returns @size bytes of memory. Allocates from <>. **/ -void *cf_malloc_zero(uns size); /** Like @cf_malloc(), but zeroes the memory. **/ +struct mempool *cf_get_pool(void); /** Return a pointer to the current configuration pool. **/ +void *cf_malloc(uint size); /** Returns @size bytes of memory allocated from the current configuration pool. **/ +void *cf_malloc_zero(uint size); /** Like @cf_malloc(), but zeroes the memory. **/ char *cf_strdup(const char *s); /** Copy a string into @cf_malloc()ed memory. **/ char *cf_printf(const char *fmt, ...) FORMAT_CHECK(printf,1,2); /** printf() into @cf_malloc()ed memory. **/ @@ -327,9 +460,23 @@ char *cf_printf(const char *fmt, ...) FORMAT_CHECK(printf,1,2); /** printf() int * Undo journal * ~~~~~~~~~~~~ * - * For error recovery when <>. + * The configuration system uses a simple journaling mechanism, which makes + * it possible to undo changes to configuration. A typical example is loading + * of configuration by cf_load(): internally, it creates a transaction, applies + * all changes specified by the configuration and if one of them fails, the whole + * journal is replayed to restore the whole original state. Similarly, cf_reload() + * uses the journal to switch between configurations. + * + * In most cases, you need not care about the journal, except when you need + * to change some data from a <>, or if you want to call cf_modify_item() and then + * undo the changes. ***/ -extern uns cf_need_journal; /** Is the journal needed? If you do not reload configuration, you set this to 0 and gain a little more performance and free memory. **/ +/** + * This function can be used to disable the whole journalling mechanism. + * It saves some memory, but it makes undoing of configuration changes impossible, + * which breaks for example cf_reload(). + **/ +void cf_set_journalling(int enable); /** * When a block of memory is about to be changed, put the old value * into journal with this function. You need to call it from a <> @@ -337,8 +484,33 @@ extern uns cf_need_journal; /** Is the journal needed? If you do not reload conf * <> do not need to call it, it is called * before them. **/ -void cf_journal_block(void *ptr, uns len); -#define CF_JOURNAL_VAR(var) cf_journal_block(&(var), sizeof(var)) // Store single value into journal. +void cf_journal_block(void *ptr, uint len); +#define CF_JOURNAL_VAR(var) cf_journal_block(&(var), sizeof(var)) // Store a single value into the journal + +struct cf_journal_item; /** Opaque identifier of the journal state. **/ +/** + * Starts a new transaction. It returns the current state so you can + * get back to it. The @new_pool parameter tells if a new memory pool + * should be created and used from now. + **/ +struct cf_journal_item *cf_journal_new_transaction(uint new_pool); +/** + * Marks current state as a complete transaction. The @new_pool + * parameter tells if the transaction was created with new memory pool + * (the parameter must be the same as the one with + * @cf_journal_new_transaction() was called with). The @oldj parameter + * is the journal state returned from last + * @cf_journal_new_transaction() call. + **/ +void cf_journal_commit_transaction(uint new_pool, struct cf_journal_item *oldj); +/** + * Returns to an old journal state, reverting anything the current + * transaction did. The @new_pool parameter must be the same as the + * one you used when you created the transaction. The @oldj parameter + * is the journal state you got from @cf_journal_new_transaction() -- + * it is the state to return to. + **/ +void cf_journal_rollback_transaction(uint new_pool, struct cf_journal_item *oldj); /*** * [[declare]] @@ -353,8 +525,17 @@ void cf_journal_block(void *ptr, uns len); * If @allow_unknown is set to 0 and a variable not described in @sec * is found in the configuration file, it produces an error. * If you set it to 1, all such variables are ignored. + * + * Please note that a single section definition cannot be used in multiple + * configuration contexts simultaneously. **/ -void cf_declare_section(const char *name, struct cf_section *sec, uns allow_unknown); +void cf_declare_section(const char *name, struct cf_section *sec, uint allow_unknown); +/** + * Like @cf_declare_section(), but instead of item pointers, the section + * contains offsets relative to @ptr. In other words, it does the same + * as `CF_SECTION`, but for top-level sections. + **/ +void cf_declare_rel_section(const char *name, struct cf_section *sec, void *ptr, uint allow_unknown); /** * If you have a section in a structure and you want to initialize it * (eg. if you want a copy of default values outside the configuration), @@ -362,7 +543,7 @@ void cf_declare_section(const char *name, struct cf_section *sec, uns allow_unkn * * This is used mostly internally. You probably do not need it. **/ -void cf_init_section(const char *name, struct cf_section *sec, void *ptr, uns do_bzero); +void cf_init_section(const char *name, struct cf_section *sec, void *ptr, uint do_bzero); /*** * [[bparser]] @@ -379,5 +560,56 @@ char *cf_parse_u64(const char *str, u64 *ptr); /** Parser for 64 unsigned integ char *cf_parse_double(const char *str, double *ptr); /** Parser for doubles. **/ char *cf_parse_ip(const char *p, u32 *varp); /** Parser for IP addresses. **/ -#endif +/*** + * [[conf_direct]] + * Direct access + * ~~~~~~~~~~~~~ + * + * Direct access to configuration items. + * You probably should not need this, but in your do, you have to handle + * <> yourself. + ***/ + +/** + * List of operations used on items. + * This macro is used to generate internal source code, + * but you may be interested in the list of operations it creates. + * + * Each operation corresponds to the same-named operation + * described in <>. + **/ +#define CF_OPERATIONS T(CLOSE) T(SET) T(CLEAR) T(ALL) \ + T(APPEND) T(PREPEND) T(REMOVE) T(EDIT) T(AFTER) T(BEFORE) T(COPY) T(RESET) + /* Closing brace finishes previous block. + * Basic attributes (static, dynamic, parsed) can be used with SET. + * Dynamic arrays can be used with SET, APPEND, PREPEND. + * Sections can be used with SET. + * Lists can be used with everything. */ +#define T(x) OP_##x, +enum cf_operation { CF_OPERATIONS }; /** Allowed operations on items. See <> for list (they have an `OP_` prefix -- it means you use `OP_SET` instead of just `SET`). **/ +#undef T + +/** + * Searches for a configuration item called @name. + * If it is found, it is copied into @item and NULL is returned. + * Otherwise, an error is returned and @item is zeroed. + **/ +char *cf_find_item(const char *name, struct cf_item *item); +/** + * Performs a single operation on a given item. + **/ +char *cf_modify_item(struct cf_item *item, enum cf_operation op, int number, char **pars); + +/*** + * [[conf_dump]] + * Debug dumping + * ~~~~~~~~~~~~~ + ***/ +struct fastbuf; +/** + * Write the current state of all configuration items into @fb. + **/ +void cf_dump_sections(struct fastbuf *fb); + +#endif