* UCW Library -- Configuration files
*
* (c) 2001--2006 Robert Spalek <robert@ucw.cz>
- * (c) 2003--2006 Martin Mares <mj@ucw.cz>
+ * (c) 2003--2012 Martin Mares <mj@ucw.cz>
*
* This software may be freely distributed and used according to the terms
* of the GNU Lesser General Public License.
#ifndef _UCW_CONF_H
#define _UCW_CONF_H
+#include <ucw/clists.h>
+
+#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 <<config:,configuration file>>.
+ * 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. **/
* uns value;
* };
*
- * struct clist nodes;
+ * static struct clist nodes;
*
* static struct cf_section node = {
* CF_TYPE(struct list_node),
* CF_END
* };
*
- * You could use <<def_CF_STATIC,`def_CF_STATIC`>> or <<def_CF_DYNAMIC,`def_CF_DYNAMIC`>>
+ * You could use <<def_CF_STATIC,`CF_STATIC`>> or <<def_CF_DYNAMIC,`CF_DYNAMIC`>>
* macros to create arrays.
*/
#define CF_TYPE(s) .size = sizeof(s)
#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
+#define DARY_ALLOC(type,len,val...) ((struct { byte pad[ALIGN_TO(sizeof(uns), CPU_STRUCT_ALIGN) - sizeof(uns)]; uns l; type a[len]; }) { .l = len, .a = { val } }).a
// creates a static instance of a dynamic array
/***
* Memory allocation
* ~~~~~~~~~~~~~~~~~
*
- * Uses <<mempool:,memory pools>> for efficiency and journal recovery.
- * You should use these routines when implementing custom parsers.
+ * Each configuration context has one or more <<mempool:,memory pools>>, 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 <<mempool:type_mempool,memory pool>> 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 <<var_cf_pool,`cf_pool`>>. **/
+struct mempool *cf_get_pool(void); /** Return a pointer to the current configuration pool. **/
+void *cf_malloc(uns size); /** Returns @size bytes of memory allocated from the current configuration pool. **/
void *cf_malloc_zero(uns 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. **/
* Undo journal
* ~~~~~~~~~~~~
*
- * For error recovery when <<reload,reloading configuration>>.
+ * 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 <<hooks,hook>>, 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 <<hooks,commit hook>>
* 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.
+#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(uns 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(uns 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(uns new_pool, struct cf_journal_item *oldj);
/***
* [[declare]]
* 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);
+/**
+ * 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, uns 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),
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
+ * <<journal,journalling>> 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 <<config:operations,configuration syntax>>.
+ **/
+#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 <<def_CF_OPERATIONS,`CF_OPERATIONS`>> 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
projects / libucw.git / blobdiff