diff options
| -rw-r--r-- | nest/Doc | 4 | ||||
| -rw-r--r-- | nest/cli.c | 69 | ||||
| -rw-r--r-- | nest/iface.c | 97 |
3 files changed, 167 insertions, 3 deletions
@@ -5,7 +5,7 @@ S rt-attr.c D prog-proto.sgml S proto.c S proto-hooks.c +S iface.c S neighbor.c -#S cli.c -#S iface.c +S cli.c S locks.c @@ -1,11 +1,54 @@ /* * BIRD Internet Routing Daemon -- Command-Line Interface * - * (c) 1999 Martin Mares <mj@ucw.cz> + * (c) 1999--2000 Martin Mares <mj@ucw.cz> * * Can be freely distributed and used under the terms of the GNU GPL. */ +/** + * DOC: Command line interface + * + * This module takes care of the BIRD's command-line interface (CLI). + * The CLI exists to provide a way to control BIRD remotely and to inspect + * its status. It uses a very simple textual protocol over a stream + * connection provided by the platform dependent code (on UNIX systems, + * it's a UNIX domain socket). + * + * Each session of the CLI consists of a sequence of request and replies, + * slightly resembling the FTP and SMTP protocols. + * Requests are commands encoded as a single line of text, replies are + * sequences of lines starting with a four-digit code followed by either + * a space (if it's the last line of the reply) or a minus sign (when the + * reply is going to continue with the next line), the rest of the line + * contains a textual message semantics of which depends on the numeric + * code. If a reply line has the same code as the previous one and it's + * a continuation line, the whole prefix can be replaced by a single + * white space character. + * + * Reply codes starting with 0 describe `action successfully completed' messages, + * 1 means `table entry', 8 `runtime error' and 9 `syntax error'. + * + * Each CLI session is internally represented by a &cli structure and a + * resource pool containing all resources associated with the connection, + * so that it can be easily freed whenever the connection closes, not depending + * on the current state of command processing. + * + * The CLI commands are declared as a part of the configuration grammar + * by using the CF_CLI() macro. When a command is received, it's processed + * by the same lexical analyser and parser as used for the configuration, but + * it's switched to a special mode by prepending a fake token to the text, + * so that it uses only the CLI command rules. Then the parser invokes + * an execution routine corresponding to the command, which either constructs + * the whole reply and returns or (in case it expects the reply will be long) + * it prints a partial reply and asks the CLI module (using the @cont hook) + * to call it again when the output will be transferred to the user. + * + * The @this_cli variable points to a &cli structure of the session being + * currently parsed, but it's of course available only in command handlers + * not entered using the @cont hook. + */ + #include "nest/bird.h" #include "nest/cli.h" #include "conf/conf.h" @@ -41,6 +84,24 @@ cli_alloc_out(cli *c, int size) return o->wpos - size; } +/** + * cli_printf - send reply to a CLI connection + * @c: CLI connection + * @code: numeric code of the reply, negative for continuation lines + * @msg: a printf()-like formatting string. + * + * This function send a single line of reply to a given CLI connection. + * In works in all aspects like bsprintf() except that it automatically + * prepends the reply line prefix. + * + * Please note that if the connection can be already busy sending some + * data in which case cli_printf() stores the output to a temporary buffer, + * so please avoid sending a large batch of replies without waiting + * for the buffers to be flushed. + * + * If you want to write to the current CLI output, you can use the cli_msg() + * macro instead. + */ void cli_printf(cli *c, int code, char *msg, ...) { @@ -320,6 +381,12 @@ cli_free(cli *c) rfree(c->pool); } +/** + * cli_init - initialize the CLI module + * + * This function is called during BIRD startup to initialize + * the internal data structures of the CLI module. + */ void cli_init(void) { diff --git a/nest/iface.c b/nest/iface.c index 16961bf..e6adc08 100644 --- a/nest/iface.c +++ b/nest/iface.c @@ -6,6 +6,23 @@ * Can be freely distributed and used under the terms of the GNU GPL. */ +/** + * DOC: Interfaces + * + * The interface module keeps track of all network interfaces in the + * system and their addresses. + * + * Each interface is represented by an &iface structure which carries + * interface capability flags (%IF_MULTIACCESS, %IF_BROADCAST etc.), + * MTU, interface name and index and finally a linked list of network + * prefixes assigned to the interface, each one represented by + * struct &ifa. + * + * The interface module keeps a `soft-up' state for each &iface which + * is a conjunction of link being up, the interface being of a `sane' + * type and at least one IP address assigned to it. + */ + #undef LOCAL_DEBUG #include "nest/bird.h" @@ -22,6 +39,12 @@ static void auto_router_id(void); list iface_list; +/** + * ifa_dump - dump interface address + * @a: interface address descriptor + * + * This function dumps contents of an &ifa to the debug output. + */ void ifa_dump(struct ifa *a) { @@ -31,6 +54,13 @@ ifa_dump(struct ifa *a) (a->flags & IA_UNNUMBERED) ? " UNNUM" : ""); } +/** + * if_dump - dump interface + * @i: interface to dump + * + * This function dumps all information associated with a given + * network interface to the debug output. + */ void if_dump(struct iface *i) { @@ -65,6 +95,12 @@ if_dump(struct iface *i) } } +/** + * if_dump_all - dump all interfaces + * + * This function dumps information about all known network + * interfaces to the debug output. + */ void if_dump_all(void) { @@ -200,6 +236,22 @@ if_change_flags(struct iface *i, unsigned flags) if_notify_change((i->flags & IF_UP) ? IF_CHANGE_UP : IF_CHANGE_DOWN, i); } +/** + * if_update - update interface status + * @new: new interface status + * + * if_update() is called by the low-level platform dependent code + * whenever it notices an interface change. + * + * There exist two types of interface updates: synchronous and asynchronous + * ones. In the synchronous case, the low-level code calls if_start_update(), + * scans all interfaces reported by the OS, uses if_update() and ifa_update() + * to pass them to the core and then it finishes the update sequence by + * calling if_end_update(). When working asynchronously, the sysdep code + * calls if_update() and ifa_update() whenever it notices a change. + * + * if_update() will automatically notify all other modules about the change. + */ struct iface * if_update(struct iface *new) { @@ -284,6 +336,13 @@ if_end_update(void) } } +/** + * if_feed_baby - advertise interfaces to a new protocol + * @p: protocol to feed + * + * When a new protocol starts, this function sends it a series + * of notifications about all existing interfaces. + */ void if_feed_baby(struct proto *p) { @@ -302,6 +361,14 @@ if_feed_baby(struct proto *p) } } +/** + * if_find_by_index - find interface by ifindex + * @idx: ifindex + * + * This function finds an &iface structure corresponding to an interface + * of the given index @idx. Returns a pointer to the structure or %NULL + * if no such structure exists. + */ struct iface * if_find_by_index(unsigned idx) { @@ -313,6 +380,14 @@ if_find_by_index(unsigned idx) return NULL; } +/** + * if_find_by_name - find interface by name + * @name: interface name + * + * This function finds an &iface structure corresponding to an interface + * of the given name @name. Returns a pointer to the structure or %NULL + * if no such structure exists. + */ struct iface * if_find_by_name(char *name) { @@ -347,6 +422,14 @@ ifa_recalc_primary(struct iface *i) return res; } +/** + * ifa_update - update interface address + * @a: new interface address + * + * This function adds address information to a network + * interface. It's called by the platform dependent code during + * the interface update process described under if_update(). + */ struct ifa * ifa_update(struct ifa *a) { @@ -388,6 +471,14 @@ ifa_update(struct ifa *a) return b; } +/** + * ifa_delete - remove interface address + * @a: interface address + * + * This function removes address information from a network + * interface. It's called by the platform dependent code during + * the interface update process described under if_update(). + */ void ifa_delete(struct ifa *a) { @@ -434,6 +525,12 @@ auto_router_id(void) #endif } +/** + * if_init - initialize interface module + * + * This function is called during BIRD startup to initialize + * all data structures of the interface module. + */ void if_init(void) { |