diff options
Diffstat (limited to 'conf/conf.c')
| -rw-r--r-- | conf/conf.c | 110 |
1 files changed, 110 insertions, 0 deletions
diff --git a/conf/conf.c b/conf/conf.c index dd716424..e2a003d3 100644 --- a/conf/conf.c +++ b/conf/conf.c @@ -6,6 +6,37 @@ * Can be freely distributed and used under the terms of the GNU GPL. */ +/** + * DOC: Configuration manager + * + * Configuration of BIRD is complex, but straightforward. There exist three + * modules taking care of the configuration: config manager (which takes care + * of storage of config information and controls switching between configs), + * lexical analyser and parser. + * + * The configuration manager stores each config as a &config structure + * accompanied by a linear pool from which all information associated + * with the config and pointed to by the &config structure is allocated. + * + * There can exist up four different configurations at one time: an active + * one (pointed to by @config), configuration we are just switching from + * (@old_config), one queued for the next reconfiguration (@future_config; + * if it's non-%NULL and the user wants to reconfigure once again, we just + * free the previous queued config and replace it with the new one) and + * finally a config being parsed (@new_config). + * + * Loading of new configuration is very simple: just call config_alloc() + * to get a new &config structure, then use config_parse() to parse a + * configuration file and fill all information in the structure + * and finally ask the config manager to switch to the new + * config by calling config_commit(). + * + * CLI commands are parsed in a very similar way -- there is also a stripped-down + * &config structure associated with them and they are lexed and parsed by the + * same functions, only a special fake token is prepended before the command + * text to make the parser recognize only the rules corresponding to CLI commands. + */ + #include <setjmp.h> #include <stdarg.h> @@ -29,6 +60,14 @@ static event *config_event; int shutting_down; bird_clock_t boot_time; +/** + * config_alloc - allocate a new configuration + * @name: name of the config + * + * This function creates new &config structure, attaches a resource + * pool and a linear memory pool to it and makes it available for + * further use. Returns a pointer to the structure. + */ struct config * config_alloc(byte *name) { @@ -45,6 +84,19 @@ config_alloc(byte *name) return c; } +/** + * config_parse - parse a configuration + * @c: configuration + * + * config_parse() reads input by calling a hook function pointed to + * by @cf_read_hook and parses it according to the configuration + * grammar. It also calls all the preconfig and postconfig hooks + * before resp. after parsing. + * + * Result: 1 if the config has been parsed successfully, 0 if any + * error has occured (such as anybody calling cf_error()) and + * the @err_msg field has been set to the error message. + */ int config_parse(struct config *c) { @@ -66,6 +118,13 @@ config_parse(struct config *c) return 1; } +/** + * cli_parse - parse a CLI command + * @c: temporary config structure + * + * cli_parse() is similar to config_parse(), but instead of a configuration, + * it parses a CLI command. See the CLI module for more information. + */ int cli_parse(struct config *c) { @@ -79,6 +138,13 @@ cli_parse(struct config *c) return 1; } +/** + * config_free - free a configuration + * @c: configuration to be freed + * + * This function takes a &config structure and frees all resources + * associated with it. + */ void config_free(struct config *c) { @@ -169,6 +235,27 @@ config_done(void *unused) } } +/** + * config_commit - commit a configuration + * @c: new configuration + * + * When a configuration is parsed and prepared for use, the + * config_commit() function starts the process of reconfiguration. + * It checks whether there is already a reconfiguration in progress + * in which case it just queues the new config for later processing. + * Else it notifies all modules about the new configuration by calling + * their commit() functions which can either accept it immediately + * or call config_add_obstacle() to report that they need some time + * to complete the reconfiguration. After all such obstacles are removed + * using config_del_obstacle(), the old configuration is freed and + * everything runs according to the new one. + * + * Result: %CONF_DONE if the configuration has been accepted immediately, + * %CONF_PROGRESS if it will take some time to switch to it, %CONF_QUEUED + * if it's been queued due to another reconfiguration being in progress now + * or %CONF_SHUTDOWN if BIRD is in shutdown mode and no new configurations + * are accepted. + */ int config_commit(struct config *c) { @@ -208,6 +295,12 @@ config_commit(struct config *c) return CONF_PROGRESS; } +/** + * order_shutdown - order BIRD shutdown + * + * This function initiates shutdown of BIRD. It's accomplished by asking + * for switching to an empty configuration. + */ void order_shutdown(void) { @@ -225,6 +318,14 @@ order_shutdown(void) shutting_down = 1; } +/** + * cf_error - report a configuration error + * @msg: printf-like format string + * + * cf_error() can be called during execution of config_parse(), that is + * from the parser, a preconfig hook or a postconfig hook, to report an + * error in the configuration. + */ void cf_error(char *msg, ...) { @@ -239,6 +340,15 @@ cf_error(char *msg, ...) longjmp(conf_jmpbuf, 1); } +/** + * cfg_strdup - copy a string to config memory + * @c: string to copy + * + * cfg_strdup() creates a new copy of the string in the memory + * pool associated with the configuration being currently parsed. + * It's often used when a string literal occurs in the configuration + * and we want to preserve it for further use. + */ char * cfg_strdup(char *c) { |