X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;ds=sidebyside;f=ucw%2Fgetopt.h;h=6263d47fb6df6acd8e19968216cab5cd9614efbf;hb=5de81f1debc4341fb3af4e756b0a18e196d5ba13;hp=18788b41d822ba77db519cb88dc788b01c080433;hpb=eb12540e29b13b6d7e956fbe03aa86164408dd82;p=libucw.git diff --git a/ucw/getopt.h b/ucw/getopt.h index 18788b41..6263d47f 100644 --- a/ucw/getopt.h +++ b/ucw/getopt.h @@ -11,8 +11,8 @@ #ifndef _UCW_GETOPT_H #define _UCW_GETOPT_H -#ifdef CONFIG_OWN_GETOPT -#include "ucw/getopt/getopt-sh.h" +#ifdef CONFIG_UCW_OWN_GETOPT +#include #else #include #endif @@ -28,13 +28,17 @@ void reset_getopt(void); /** If you want to start parsing of the arguments from */ /** - * The default config (DEFAULT_CONFIG config option) or NULL if already loaded. + * The default config (as set by `CONFIG_UCW_DEFAULT_CONFIG`) or NULL if already loaded. * You can set it to something else manually. */ -extern char *cf_def_file; /* DEFAULT_CONFIG; NULL if already loaded */ -extern char *cf_env_file; /* ENV_VAR_CONFIG */ +extern char *cf_def_file; +/** + * Name of environment variable that can override what configuration is loaded. + * Defaults to `CONFIG_UCW_ENV_VAR_CONFIG`. + **/ +extern char *cf_env_file; int cf_reload(const char *file); /** Reload configuration from @file, replace the old one. **/ -int cf_load(const char *file); /** Load configuration from @file. **/ +int cf_load(const char *file); /** Load configuration from @file. If @file is NULL, reload all loaded configuration files. **/ /** * Parse some part of configuration passed in @string. * The syntax is the same as in the <>. @@ -50,15 +54,23 @@ int cf_set(const char *string); * You probably should not need this. ***/ +/** + * 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(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 }; +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 struct cf_item; @@ -68,7 +80,9 @@ struct cf_item; * Otherwise, an error is returned and @item is zeroed. **/ char *cf_find_item(const char *name, struct cf_item *item); -// TODO What does this do? +/** + * Performs a single operation on a given item. + **/ char *cf_modify_item(struct cf_item *item, enum cf_operation op, int number, char **pars); /*** @@ -87,12 +101,37 @@ void cf_dump_sections(struct fastbuf *fb); * [[conf_journal]] * Journaling control * ~~~~~~~~~~~~~~~~~~ + * + * The configuration system uses journaling to safely reload + * configuration. It begins a transaction and tries to load the + * configuration. If it fails, it restores the original state. + * + * The behaviour of journal is described in <>. ***/ -struct cf_journal_item; -// TODO +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); /*** @@ -128,7 +167,7 @@ void cf_journal_rollback_transaction(uns new_pool, struct cf_journal_item *oldj) "-C, --config filename\t" CF_USAGE_TAB "Override the default configuration file\n\ -S, --set sec.item=val\t" CF_USAGE_TAB "Manual setting of a configuration item\n" CF_USAGE_DEBUG -#ifdef CONFIG_DEBUG +#ifdef CONFIG_UCW_DEBUG #define CF_LONG_OPTS_DEBUG { "dumpconfig", 0, 0, 0x64436667 } , #define CF_USAGE_DEBUG " --dumpconfig\t" CF_USAGE_TAB "Dump program configuration\n" #else @@ -136,18 +175,18 @@ void cf_journal_rollback_transaction(uns new_pool, struct cf_journal_item *oldj) #define CF_USAGE_DEBUG #endif -/*** +/** * Takes care of parsing the command-line arguments, loading the * default configuration file (<>) and processing * configuration options. The calling convention is the same as with GNU getopt_long(), * but you must prefix your own short/long options by the - * <> or <>or + * <> or <> or * pass <> if there are no long options. * - * The default configuration file can be overwriten by the --config options, + * The default configuration file can be overwritten by the --config options, * which must come first. During parsing of all other options, the configuration * is already available. - ***/ + **/ int cf_getopt(int argc, char * const argv[], const char *short_opts, const struct option *long_opts, int *long_index); #endif