Commit 3d675cdb authored by Martin Mareš's avatar Martin Mareš

More documentation.

parent aaaff776
......@@ -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
/*
* 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)
{
......
......@@ -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)
{
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment