<!doctype birddoc system>

<!--
    BIRD: Programmer's Documentation

    Copyright (c) 2000 Martin Mares <mj@ucw.cz>
 -->

<book>
<progdoc>

<title>BIRD Programmer's Documentation
<author>
Ondrej Filip <it/&lt;feela@network.cz&gt;/,
Pavel Machek <it/&lt;pavel@ucw.cz&gt;/,
Martin Mares <it/&lt;mj@ucw.cz&gt;/
</author>

<abstract>
This document contains programmer's documentation for the BIRD Internet Routing Daemon project.
</abstract>

<!-- Table of contents -->
<toc>

<!-- Begin the document -->
<chapt>BIRD Design

<sect>Introduction

<p>This document describes the internal workings of BIRD, its architecture,
design decisions and rationale behind them. It also contains documentation on
all the essential components of the system and their interfaces.

<p>Routing daemons are complicated things which need to act in real time
to complex sequences of external events, respond correctly even to the most erroneous behavior
of their environment and still handle enormous amount of data with reasonable
speed. Due to all of this, their design is very tricky as one needs to carefully
balance between efficiency, stability and (last, but not least) simplicity of
the program and it would be possible to write literally hundreds of pages about
all of these issues. In accordance to the famous quote of Anton Chekhov "Shortness
is a sister of talent", we've tried to write a much shorter document highlighting
the most important stuff and leaving the boring technical details better explained
by the program source itself together with comments contained therein.

<sect>Design goals

<p>When planning the architecture of BIRD, we've taken a close look at the other existing routing
daemons and also at some of the operating systems used on dedicated routers, gathered all important
features and added lots of new ones to overcome their shortcomings and to better match the requirements
of routing in today's Internet: IPv6, policy routing, route filtering and so on. From this
planning, the following set of design goals has arisen:

<itemize>

<item><it>Support all the standard routing protocols and make it easy to add new ones.</it>
This leads to modularity and clean separation between the core and the protocols.

<item><it>Support both IPv4 and IPv6 in the same source tree, re-using most of the code.</it>
This leads to abstraction of IP addresses and operations on them.

<item><it>Minimize OS dependent code to make porting as easy as possible.</it>
Unfortunately, such code cannot be avoided at all as the details of communication with
the IP stack differ from OS to OS and they often vary even between different
versions of the same OS. But we can isolate such code in special modules and
do the porting by changing or replacing just these modules.
Also, don't rely on specific features of various operating systems, but be able
to make use of them if they are available.

<item><it>Allow multiple routing tables.</it>
Easily solvable by abstracting out routing tables and the corresponding operations.

<item><it>Offer powerful route filtering.</it>
There already were several attempts to incorporate route filters to a dynamic router,
but most of them have used simple sequences of filtering rules which were very inflexible
and hard to use for non-trivial filters. We've decided to employ a simple loop-free
programming language having access to all the route attributes and being able to
modify the most of them.

<item><it>Support easy configuration and re-configuration.</it>
Most routers use a simple configuration language designed ad hoc with no structure at all
and allow online changes of configuration by using their command-line interface, thus
any complex re-configurations are hard to achieve without replacing the configuration
file and restarting the whole router. We've decided to use a more general approach: to
have a configuration defined in a context-free language with blocks and nesting, to
perform all configuration changes by editing the configuration file, but to be able
to read the new configuration and smoothly adapt to it without disturbing parts of
the routing process which are not affected by the change.

<item><it>Be able to be controlled online.</it>
In addition to the online reconfiguration, a routing daemon should be able to communicate
with the user and with many other programs (primarily scripts used for network maintenance)
in order to make it possible to inspect contents of routing tables, status of all
routing protocols and also to control their behavior (disable, enable or reset a protocol without restarting all the others). To achieve
this, we implement a simple command-line protocol based on those used by FTP and SMTP
(that is textual commands and textual replies accompanied by a numeric code which makes
them both readable to a human and easy to recognize in software).

<item><it>Respond to all events in real time.</it>
A typical solution to this problem is to use lots of threads to separate the workings
of all the routing protocols and also of the user interface parts and to hope that
the scheduler will assign time to them in a fair enough manner. This is surely a good
solution, but we have resisted the temptation and preferred to avoid the overhead of threading
and the large number of locks involved and preferred a event driven architecture with
our own scheduling of events. An unpleasant consequence of such an approach
is that long lasting tasks must be split to more parts linked by special
events or timers to make the CPU available for other tasks as well.

</itemize>

<sect>Architecture

<p>The requirements set above have lead to a simple modular architecture containing
the following types of modules:

<descrip>

<tagp>Core modules</tagp> implement the core functions of BIRD: taking care
of routing tables, keeping protocol status, interacting with the user using
the Command-Line Interface (to be called CLI in the rest of this document)
etc.

<tagp>Library modules</tagp> form a large set of various library functions
implementing several data abstractions, utility functions and also functions
which are a part of the standard libraries on some systems, but missing on other
ones.

<tagp>Resource management modules</tagp> take care of resources, their allocation
and automatic freeing when the module having requested shuts itself down.

<tagp>Configuration modules</tagp> are fragments of lexical analyzer,
grammar rules and the corresponding snippets of C code. For each group
of code modules (core, each protocol, filters) there exist a configuration
module taking care of all the related configuration stuff.

<tagp>The filter</tagp> implements the route filtering language.

<tagp>Protocol modules</tagp> implement the individual routing protocols.

<tagp>System-dependent modules</tagp> implement the interface between BIRD
and specific operating systems.

<tagp>The client</tagp> is a simple program providing an easy, though friendly
interface to the CLI.

</descrip>

<sect>Implementation

<p>BIRD has been written in GNU C. We've considered using C++, but we've
preferred the simplicity and straightforward nature of C which gives us fine
control over all implementation details and on the other hand enough
instruments to build the abstractions we need.

<p>The modules are statically linked to produce a single executable file
(except for the client which stands on its own).

<p>The building process is controlled by a set of Makefiles for GNU Make,
intermixed with several Perl and shell scripts.

<p>The initial configuration of the daemon, detection of system features
and selection of the right modules to include for the particular OS
and the set of protocols the user has chosen is performed by a configure
script generated by GNU Autoconf.

<p>The parser of the configuration is generated by the GNU Bison.

<p>The documentation is generated using <file/SGMLtools/ with our own DTD
and mapping rules which produce both an online version in HTML and
a neatly formatted one for printing (first converted
from SGML to &latex; and then processed by &tex; and <file/dvips/ to
get a PostScript file).

<p>The comments from C sources which form a part of the programmer's
documentation are extracted using a modified version of the <file/kernel-doc/
tool.

<p>If you want to work on BIRD, it's highly recommended to configure it
with a <tt/--enable-debug/ switch which enables some internal consistency
checks and it also links BIRD with a memory allocation checking library
if you have one (either <tt/efence/ or <tt/dmalloc/).

<!--
LocalWords:  IPv IP CLI snippets Perl Autoconf SGMLtools DTD SGML dvips
LocalWords:  PostScript
 -->
<chapt>Core
<sect>Forwarding Information Base
<p>
   <p>
   FIB is a data structure designed for storage of routes indexed by their
   network prefixes. It supports insertion, deletion, searching by prefix,
   `routing' (in CIDR sense, that is searching for a longest prefix matching
   a given IP address) and (which makes the structure very tricky to implement)
   asynchronous reading, that is enumerating the contents of a FIB while other
   modules add, modify or remove entries.
   <p>
   Internally, each FIB is represented as a collection of nodes of type <struct/fib_node/
   indexed using a sophisticated hashing mechanism.
   We use two-stage hashing where we calculate a 16-bit primary hash key independent
   on hash table size and then we just divide the primary keys modulo table size
   to get a real hash key used for determining the bucket containing the node.
   The lists of nodes in each bucket are sorted according to the primary hash
   key, hence if we keep the total number of buckets to be a power of two,
   re-hashing of the structure keeps the relative order of the nodes.
   <p>
   To get the asynchronous reading consistent over node deletions, we need to
   keep a list of readers for each node. When a node gets deleted, its readers
   are automatically moved to the next node in the table.
   <p>
   Basic FIB operations are performed by functions defined by this module,
   enumerating of FIB contents is accomplished by using the <func/FIB_WALK()/ macro
   or <func/FIB_ITERATE_START()/ if you want to do it asynchronously.


<function><p><type>void</type>
<funcdef>fib_init</funcdef>
(<type>struct fib *</type> <param>f</param>, <type>pool *</type> <param>p</param>, <type>unsigned</type> <param>node_size</param>, <type>unsigned</type> <param>hash_order</param>, <type>fib_init_func</type> <param>init</param>) --     initialize a new FIB

<funcsect>Arguments
<p><descrip>
<tagp><type>struct fib *</type> <param>f</param></tagp>
    the FIB to be initialized (the structure itself being allocated by the caller)
<tagp><type>pool *</type> <param>p</param></tagp>
    pool to allocate the nodes in
<tagp><type>unsigned</type> <param>node_size</param></tagp>
    node size to be used (each node consists of a standard header <struct/fib_node/
   followed by user data)
<tagp><type>unsigned</type> <param>hash_order</param></tagp>
    initial hash order (a binary logarithm of hash table size), 0 to use default order
   (recommended)
<tagp><type>fib_init_func</type> <param>init</param></tagp>
    pointer a function to be called to initialize a newly created node
</descrip>
<funcsect>Description
<p>
   This function initializes a newly allocated FIB and prepares it for use.
</function>
<function><p><type>void *</type>
<funcdef>fib_find</funcdef>
(<type>struct fib *</type> <param>f</param>, <type>ip_addr *</type> <param>a</param>, <type>int</type> <param>len</param>) --     search for FIB node by prefix

<funcsect>Arguments
<p><descrip>
<tagp><type>struct fib *</type> <param>f</param></tagp>
    FIB to search in
<tagp><type>ip_addr *</type> <param>a</param></tagp>
    pointer to IP address of the prefix
<tagp><type>int</type> <param>len</param></tagp>
    prefix length
</descrip>
<funcsect>Description
<p>
   Search for a FIB node corresponding to the given prefix, return
   a pointer to it or <const/NULL/ if no such node exists.
</function>
<function><p><type>void *</type>
<funcdef>fib_get</funcdef>
(<type>struct fib *</type> <param>f</param>, <type>ip_addr *</type> <param>a</param>, <type>int</type> <param>len</param>) --     find or create a FIB node

<funcsect>Arguments
<p><descrip>
<tagp><type>struct fib *</type> <param>f</param></tagp>
    FIB to work with
<tagp><type>ip_addr *</type> <param>a</param></tagp>
    pointer to IP address of the prefix
<tagp><type>int</type> <param>len</param></tagp>
    prefix length
</descrip>
<funcsect>Description
<p>
   Search for a FIB node corresponding to the given prefix and
   return a pointer to it. If no such node exists, create it.
</function>
<function><p><type>void *</type>
<funcdef>fib_route</funcdef>
(<type>struct fib *</type> <param>f</param>, <type>ip_addr</type> <param>a</param>, <type>int</type> <param>len</param>) --     CIDR routing lookup

<funcsect>Arguments
<p><descrip>
<tagp><type>struct fib *</type> <param>f</param></tagp>
    FIB to search in
<tagp><type>ip_addr</type> <param>a</param></tagp>
    pointer to IP address of the prefix
<tagp><type>int</type> <param>len</param></tagp>
    prefix length
</descrip>
<funcsect>Description
<p>
   Search for a FIB node with longest prefix matching the given
   network, that is a node which a CIDR router would use for routing
   that network.
</function>
<function><p><type>void</type>
<funcdef>fib_delete</funcdef>
(<type>struct fib *</type> <param>f</param>, <type>void *</type> <param>E</param>) --     delete a FIB node

<funcsect>Arguments
<p><descrip>
<tagp><type>struct fib *</type> <param>f</param></tagp>
    FIB to delete from
<tagp><type>void *</type> <param>E</param></tagp>
    entry to delete
</descrip>
<funcsect>Description
<p>
   This function removes the given entry from the FIB,
   taking care of all the asynchronous readers by shifting
   them to the next node in the canonical reading order.
</function>
<function><p><type>void</type>
<funcdef>fib_free</funcdef>
(<type>struct fib *</type> <param>f</param>) --     delete a FIB

<funcsect>Arguments
<p><descrip>
<tagp><type>struct fib *</type> <param>f</param></tagp>
    FIB to be deleted
</descrip>
<funcsect>Description
<p>
   This function deletes a FIB -- it frees all memory associated
   with it and all its entries.
</function>
<function><p><type>void</type>
<funcdef>fib_check</funcdef>
(<type>struct fib *</type> <param>f</param>) --     audit a FIB

<funcsect>Arguments
<p><descrip>
<tagp><type>struct fib *</type> <param>f</param></tagp>
    FIB to be checked
</descrip>
<funcsect>Description
<p>
   This debugging function audits a FIB by checking its internal consistency.
   Use when you suspect somebody of corrupting innocent data structures.
</function>
<sect>Routing tables
<p>
   <p>
   Routing tables are probably the most important structures BIRD uses. They
   hold all the information about known networks, the associated routes and
   their attributes.
   <p>
   There are multiple routing tables (a primary one together with any
   number of secondary ones if requested by the configuration). Each table
   is basically a FIB containing entries describing the individual
   destination networks. For each network (represented by structure <struct/net/),
   there is a one-way linked list of route entries (<struct/rte/), the first entry
   on the list being the best one (i.e., the one we currently use
   for routing), the order of the other ones is undetermined.
   <p>
   The <struct/rte/ contains information specific to the route (preference, protocol
   metrics, time of last modification etc.) and a pointer to a <struct/rta/ structure
   (see the route attribute module for a precise explanation) holding the
   remaining route attributes which are expected to be shared by multiple
   routes in order to conserve memory.


<function><p><type>rte *</type>
<funcdef>rte_find</funcdef>
(<type>net *</type> <param>net</param>, <type>struct proto *</type> <param>p</param>) --     find a route

<funcsect>Arguments
<p><descrip>
<tagp><type>net *</type> <param>net</param></tagp>
    network node
<tagp><type>struct proto *</type> <param>p</param></tagp>
    protocol
</descrip>
<funcsect>Description
<p>
   The <func/rte_find()/ function returns a route for destination <param/net/
   which belongs has been defined by protocol <param/p/.
</function>
<function><p><type>rte *</type>
<funcdef>rte_get_temp</funcdef>
(<type>rta *</type> <param>a</param>) --     get a temporary <struct/rte/

<funcsect>Arguments
<p><descrip>
<tagp><type>rta *</type> <param>a</param></tagp>
    attributes to assign to the new route (a <struct/rta/; in case it's
   un-cached, <func/rte_update()/ will create a cached copy automatically)
</descrip>
<funcsect>Description
<p>
   Create a temporary <struct/rte/ and bind it with the attributes <param/a/.
   Also set route preference to the default preference set for
   the protocol.
</function>
<function><p><type>void</type>
<funcdef>rte_announce</funcdef>
(<type>rtable *</type> <param>tab</param>, <type>net *</type> <param>net</param>, <type>rte *</type> <param>new</param>, <type>rte *</type> <param>old</param>, <type>ea_list *</type> <param>tmpa</param>) --     announce a routing table change

<funcsect>Arguments
<p><descrip>
<tagp><type>rtable *</type> <param>tab</param></tagp>
    table the route has been added to
<tagp><type>net *</type> <param>net</param></tagp>
    network in question
<tagp><type>rte *</type> <param>new</param></tagp>
    the new route to be announced
<tagp><type>rte *</type> <param>old</param></tagp>
    previous optimal route for the same network
<tagp><type>ea_list *</type> <param>tmpa</param></tagp>
    a list of temporary attributes belonging to the new route
</descrip>
<funcsect>Description
<p>
   This function gets a routing table update and announces it
   to all protocols connected to the same table by their announcement hooks.
   <p>
   For each such protocol, we first call its <func/import_control()/ hook which
   performs basic checks on the route (each protocol has a right to veto
   or force accept of the route before any filter is asked) and adds default
   values of attributes specific to the new protocol (metrics, tags etc.).
   Then it consults the protocol's export filter and if it accepts the
   route, the <func/rt_notify()/ hook of the protocol gets called.
</function>
<function><p><type>void</type>
<funcdef>rte_free</funcdef>
(<type>rte *</type> <param>e</param>) --     delete a <struct/rte/

<funcsect>Arguments
<p><descrip>
<tagp><type>rte *</type> <param>e</param></tagp>
    <struct/rte/ to be deleted
</descrip>
<funcsect>Description
<p>
   <func/rte_free()/ deletes the given <struct/rte/ from the routing table it's linked to.
</function>
<function><p><type>void</type>
<funcdef>rte_update</funcdef>
(<type>rtable *</type> <param>table</param>, <type>net *</type> <param>net</param>, <type>struct proto *</type> <param>p</param>, <type>rte *</type> <param>new</param>) --     enter a new update to a routing table

<funcsect>Arguments
<p><descrip>
<tagp><type>rtable *</type> <param>table</param></tagp>
    table to be updated
<tagp><type>net *</type> <param>net</param></tagp>
    network node
<tagp><type>struct proto *</type> <param>p</param></tagp>
    protocol submitting the update
<tagp><type>rte *</type> <param>new</param></tagp>
    a <struct/rte/ representing the new route or <const/NULL/ for route removal.
</descrip>
<funcsect>Description
<p>
   This function is called by the routing protocols whenever they discover
   a new route or wish to update/remove an existing route. The right announcement
   sequence is to build route attributes first (either un-cached with <param/aflags/ set
   to zero or a cached one using <func/rta_lookup()/; in this case please note that
   you need to increase the use count of the attributes yourself by calling
   <func/rta_clone()/), call <func/rte_get_temp()/ to obtain a temporary <struct/rte/, fill in all
   the appropriate data and finally submit the new <struct/rte/ by calling <func/rte_update()/.
   <p>
   When <func/rte_update()/ gets any route, it automatically validates it (checks,
   whether the network and next hop address are valid IP addresses and also
   whether a normal routing protocol doesn't try to smuggle a host or link
   scope route to the table), converts all protocol dependent attributes stored
   in the <struct/rte/ to temporary extended attributes, consults import filters of the
   protocol to see if the route should be accepted and/or its attributes modified,
   stores the temporary attributes back to the <struct/rte/.
   <p>
   Now, having a "public" version of the route, we
   automatically find any old route defined by the protocol <param/p/
   for network <param/n/, replace it by the new one (or removing it if <param/new/ is <const/NULL/),
   recalculate the optimal route for this destination and finally broadcast
   the change (if any) to all routing protocols by calling <func/rte_announce()/.
   <p>
   All memory used for attribute lists and other temporary allocations is taken
   from a special linear pool <param/rte_update_pool/ and freed when <func/rte_update()/
   finishes.
</function>
<function><p><type>void</type>
<funcdef>rte_dump</funcdef>
(<type>rte *</type> <param>e</param>) --     dump a route

<funcsect>Arguments
<p><descrip>
<tagp><type>rte *</type> <param>e</param></tagp>
    <struct/rte/ to be dumped
</descrip>
<funcsect>Description
<p>
   This functions dumps contents of a <struct/rte/ to debug output.
</function>
<function><p><type>void</type>
<funcdef>rt_dump</funcdef>
(<type>rtable *</type> <param>t</param>) --     dump a routing table

<funcsect>Arguments
<p><descrip>
<tagp><type>rtable *</type> <param>t</param></tagp>
    routing table to be dumped
</descrip>
<funcsect>Description
<p>
   This function dumps contents of a given routing table to debug output.
</function>
<function><p><type>void</type>
<funcdef>rt_dump_all</funcdef>
(<param>void</param>) --     dump all routing tables

<funcsect>Description
<p>
   <p>
   This function dumps contents of all routing tables to debug output.
</function>
<function><p><type>void</type>
<funcdef>rt_init</funcdef>
(<param>void</param>) --     initialize routing tables

<funcsect>Description
<p>
   <p>
   This function is called during BIRD startup. It initializes the
   routing table module.
</function>
<function><p><type>void</type>
<funcdef>rt_prune</funcdef>
(<type>rtable *</type> <param>tab</param>) --     prune a routing table

<funcsect>Arguments
<p><descrip>
<tagp><type>rtable *</type> <param>tab</param></tagp>
    routing table to be pruned
</descrip>
<funcsect>Description
<p>
   This function is called whenever a protocol shuts down. It scans
   the routing table and removes all routes belonging to inactive
   protocols and also stale network entries.
</function>
<function><p><type>void</type>
<funcdef>rt_prune_all</funcdef>
(<param>void</param>) --     prune all routing tables

<funcsect>Description
<p>
   <p>
   This function calls <func/rt_prune()/ for all known routing tables.
</function>
<function><p><type>void</type>
<funcdef>rt_lock_table</funcdef>
(<type>rtable *</type> <param>r</param>) --     lock a routing table

<funcsect>Arguments
<p><descrip>
<tagp><type>rtable *</type> <param>r</param></tagp>
    routing table to be locked
</descrip>
<funcsect>Description
<p>
   Lock a routing table, because it's in use by a protocol,
   preventing it from being freed when it gets undefined in a new
   configuration.
</function>
<function><p><type>void</type>
<funcdef>rt_unlock_table</funcdef>
(<type>rtable *</type> <param>r</param>) --     unlock a routing table

<funcsect>Arguments
<p><descrip>
<tagp><type>rtable *</type> <param>r</param></tagp>
    routing table to be unlocked
</descrip>
<funcsect>Description
<p>
   Unlock a routing table formerly locked by <func/rt_lock_table()/,
   that is decrease its use count and delete it if it's scheduled
   for deletion by configuration changes.
</function>
<function><p><type>void</type>
<funcdef>rt_commit</funcdef>
(<type>struct config *</type> <param>new</param>, <type>struct config *</type> <param>old</param>) --     commit new routing table configuration

<funcsect>Arguments
<p><descrip>
<tagp><type>struct config *</type> <param>new</param></tagp>
    new configuration
<tagp><type>struct config *</type> <param>old</param></tagp>
    original configuration or <const/NULL/ if it's boot time config
</descrip>
<funcsect>Description
<p>
   Scan differences between <param/old/ and <param/new/ configuration and modify
   the routing tables according to these changes. If <param/new/ defines a
   previously unknown table, create it, if it omits a table existing
   in <param/old/, schedule it for deletion (it gets deleted when all protocols
   disconnect from it by calling <func/rt_unlock_table()/), if it exists
   in both configurations, leave it unchanged.
</function>
<function><p><type>int</type>
<funcdef>rt_feed_baby</funcdef>
(<type>struct proto *</type> <param>p</param>) --     advertise routes to a new protocol

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
    protocol to be fed
</descrip>
<funcsect>Description
<p>
   This function performs one pass of advertisement of routes to a newly
   initialized protocol. It's called by the protocol code as long as it
   has something to do. (We avoid transferring all the routes in single
   pass in order not to monopolize CPU time.)
</function>
<function><p><type>void</type>
<funcdef>rt_feed_baby_abort</funcdef>
(<type>struct proto *</type> <param>p</param>) --     abort protocol feeding

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
    protocol
</descrip>
<funcsect>Description
<p>
   This function is called by the protocol code when the protocol
   stops or ceases to exist before the last iteration of <func/rt_feed_baby()/
   has finished.
</function>
<function><p><type>net *</type>
<funcdef>net_find</funcdef>
(<type>rtable *</type> <param>tab</param>, <type>ip_addr</type> <param>addr</param>, <type>unsigned</type> <param>len</param>) --     find a network entry

<funcsect>Arguments
<p><descrip>
<tagp><type>rtable *</type> <param>tab</param></tagp>
    a routing table
<tagp><type>ip_addr</type> <param>addr</param></tagp>
    address of the network
<tagp><type>unsigned</type> <param>len</param></tagp>
    length of the network prefix
</descrip>
<funcsect>Description
<p>
   <func/net_find()/ looks up the given network in routing table <param/tab/ and
   returns a pointer to its <struct/net/ entry or <const/NULL/ if no such network
   exists.
</function>
<function><p><type>net *</type>
<funcdef>net_get</funcdef>
(<type>rtable *</type> <param>tab</param>, <type>ip_addr</type> <param>addr</param>, <type>unsigned</type> <param>len</param>) --     obtain a network entry

<funcsect>Arguments
<p><descrip>
<tagp><type>rtable *</type> <param>tab</param></tagp>
    a routing table
<tagp><type>ip_addr</type> <param>addr</param></tagp>
    address of the network
<tagp><type>unsigned</type> <param>len</param></tagp>
    length of the network prefix
</descrip>
<funcsect>Description
<p>
   <func/net_get()/ looks up the given network in routing table <param/tab/ and
   returns a pointer to its <struct/net/ entry. If no such entry exists, it's
   created.
</function>
<function><p><type>rte *</type>
<funcdef>rte_cow</funcdef>
(<type>rte *</type> <param>r</param>) --     copy a route for writing

<funcsect>Arguments
<p><descrip>
<tagp><type>rte *</type> <param>r</param></tagp>
    a route entry to be copied
</descrip>
<funcsect>Description
<p>
   <func/rte_cow()/ takes a <struct/rte/ and prepares it for modification. The exact action
   taken depends on the flags of the <struct/rte/ -- if it's a temporary entry, it's
   just returned unchanged, else a new temporary entry with the same contents
   is created.
   <p>
   The primary use of this function is inside the filter machinery -- when
   a filter wants to modify <struct/rte/ contents (to change the preference or to
   attach another set of attributes), it must ensure that the <struct/rte/ is not
   shared with anyone else (and especially that it isn't stored in any routing
   table).
<funcsect>Result
<p>
    a pointer to the new writable <struct/rte/.
</function>
<sect>Route attribute cache
<p>
   <p>
   Each route entry carries a set of route attributes. Several of them
   vary from route to route, but most attributes are usually common
   for a large number of routes. To conserve memory, we've decided to
   store only the varying ones directly in the <struct/rte/ and hold the rest
   in a special structure called <struct/rta/ which is shared among all the
   <struct/rte/'s with these attributes.
   <p>
   Each <struct/rta/ contains all the static attributes of the route (i.e.,
   those which are always present) as structure members and a list of
   dynamic attributes represented by a linked list of <struct/ea_list/
   structures, each of them consisting of an array of <struct/eattr/'s containing
   the individual attributes. An attribute can be specified more than once
   in the <struct/ea_list/ chain and in such case the first occurrence overrides
   the others. This semantics is used especially when someone (for example
   a filter) wishes to alter values of several dynamic attributes, but
   it wants to preserve the original attribute lists maintained by
   another module.
   <p>
   Each <struct/eattr/ contains an attribute identifier (split to protocol ID and
   per-protocol attribute ID), protocol dependent flags, a type code (consisting
   of several bit fields describing attribute characteristics) and either an
   embedded 32-bit value or a pointer to a <struct/adata/ structure holding attribute
   contents.
   <p>
   There exist two variants of <struct/rta/'s -- cached and un-cached ones. Un-cached
   <struct/rta/'s can have arbitrarily complex structure of <struct/ea_list/'s and they
   can be modified by any module in the route processing chain. Cached
   <struct/rta/'s have their attribute lists normalized (that means at most one
   <struct/ea_list/ is present and its values are sorted in order to speed up
   searching), they are stored in a hash table to make fast lookup possible
   and they are provided with a use count to allow sharing.
   <p>
   Routing tables always contain only cached <struct/rta/'s.


<function><p><type>eattr *</type>
<funcdef>ea_find</funcdef>
(<type>ea_list *</type> <param>e</param>, <type>unsigned</type> <param>id</param>) --     find an extended attribute

<funcsect>Arguments
<p><descrip>
<tagp><type>ea_list *</type> <param>e</param></tagp>
    attribute list to search in
<tagp><type>unsigned</type> <param>id</param></tagp>
    attribute ID to search for
</descrip>
<funcsect>Description
<p>
   Given an extended attribute list, <func/ea_find()/ searches for a first
   occurrence of an attribute with specified ID, returning either a pointer
   to its <struct/eattr/ structure or <const/NULL/ if no such attribute exists.
</function>
<function><p><type>int</type>
<funcdef>ea_get_int</funcdef>
(<type>ea_list *</type> <param>e</param>, <type>unsigned</type> <param>id</param>, <type>int</type> <param>def</param>) --     fetch an integer attribute

<funcsect>Arguments
<p><descrip>
<tagp><type>ea_list *</type> <param>e</param></tagp>
    attribute list
<tagp><type>unsigned</type> <param>id</param></tagp>
    attribute ID
<tagp><type>int</type> <param>def</param></tagp>
    default value
</descrip>
<funcsect>Description
<p>
   This function is a shortcut for retrieving a value of an integer attribute
   by calling <func/ea_find()/ to find the attribute, extracting its value or returning
   a provided default if no such attribute is present.
</function>
<function><p><type>void</type>
<funcdef>ea_sort</funcdef>
(<type>ea_list *</type> <param>e</param>) --     sort an attribute list

<funcsect>Arguments
<p><descrip>
<tagp><type>ea_list *</type> <param>e</param></tagp>
    list to be sorted
</descrip>
<funcsect>Description
<p>
   This function takes a <struct/ea_list/ chain and sorts the attributes
   within each of its entries.
   <p>
   If an attribute occurs multiple times in a single <struct/ea_list/,
   <func/ea_sort()/ leaves only the first (the only significant) occurrence.
</function>
<function><p><type>unsigned</type>
<funcdef>ea_scan</funcdef>
(<type>ea_list *</type> <param>e</param>) --     estimate attribute list size

<funcsect>Arguments
<p><descrip>
<tagp><type>ea_list *</type> <param>e</param></tagp>
    attribute list
</descrip>
<funcsect>Description
<p>
   This function calculates an upper bound of the size of
   a given <struct/ea_list/ after merging with <func/ea_merge()/.
</function>
<function><p><type>void</type>
<funcdef>ea_merge</funcdef>
(<type>ea_list *</type> <param>e</param>, <type>ea_list *</type> <param>t</param>) --     merge segments of an attribute list

<funcsect>Arguments
<p><descrip>
<tagp><type>ea_list *</type> <param>e</param></tagp>
    attribute list
<tagp><type>ea_list *</type> <param>t</param></tagp>
    buffer to store the result to
</descrip>
<funcsect>Description
<p>
   This function takes a possibly multi-segment attribute list
   and merges all of its segments to one.
   <p>
   The primary use of this function is for <struct/ea_list/ normalization:
   first call <func/ea_scan()/ to determine how much memory will the result
   take, then allocate a buffer (usually using <func/alloca()/), merge the
   segments with <func/ea_merge()/ and finally sort and prune the result
   by calling <func/ea_sort()/.
</function>
<function><p><type>int</type>
<funcdef>ea_same</funcdef>
(<type>ea_list *</type> <param>x</param>, <type>ea_list *</type> <param>y</param>) --     compare two <struct/ea_list/'s

<funcsect>Arguments
<p><descrip>
<tagp><type>ea_list *</type> <param>x</param></tagp>
    attribute list
<tagp><type>ea_list *</type> <param>y</param></tagp>
    attribute list
</descrip>
<funcsect>Description
<p>
   <func/ea_same()/ compares two normalized attribute lists <param/x/ and <param/y/ and returns
   1 if they contain the same attributes, 0 otherwise.
</function>
<function><p><type>void</type>
<funcdef>ea_format</funcdef>
(<type>eattr *</type> <param>e</param>, <type>byte *</type> <param>buf</param>) --     format an <struct/eattr/ for printing

<funcsect>Arguments
<p><descrip>
<tagp><type>eattr *</type> <param>e</param></tagp>
    attribute to be formatted
<tagp><type>byte *</type> <param>buf</param></tagp>
    destination buffer of size <const/EA_FORMAT_BUF_SIZE/
</descrip>
<funcsect>Description
<p>
   This function takes an extended attribute represented by its
   <struct/eattr/ structure and formats it nicely for printing according
   to the type information.
   <p>
   If the protocol defining the attribute provides its own
   <func/get_attr()/ hook, it's consulted first.
</function>
<function><p><type>void</type>
<funcdef>ea_dump</funcdef>
(<type>ea_list *</type> <param>e</param>) --     dump an extended attribute

<funcsect>Arguments
<p><descrip>
<tagp><type>ea_list *</type> <param>e</param></tagp>
    attribute to be dumped
</descrip>
<funcsect>Description
<p>
   <func/ea_dump()/ dumps contents of the extended attribute given to
   the debug output.
</function>
<function><p><type>unsigned int</type>
<funcdef>ea_hash</funcdef>
(<type>ea_list *</type> <param>e</param>) --     calculate an <struct/ea_list/ hash key

<funcsect>Arguments
<p><descrip>
<tagp><type>ea_list *</type> <param>e</param></tagp>
    attribute list
</descrip>
<funcsect>Description
<p>
   <func/ea_hash()/ takes an extended attribute list and calculated a hopefully
   uniformly distributed hash value from its contents.
</function>
<function><p><type>ea_list *</type>
<funcdef>ea_append</funcdef>
(<type>ea_list *</type> <param>to</param>, <type>ea_list *</type> <param>what</param>) --     concatenate <struct/ea_list/'s

<funcsect>Arguments
<p><descrip>
<tagp><type>ea_list *</type> <param>to</param></tagp>
    destination list (can be <const/NULL/)
<tagp><type>ea_list *</type> <param>what</param></tagp>
    list to be appended (can be <const/NULL/)
</descrip>
<funcsect>Description
<p>
   This function appends the <struct/ea_list/ <param/what/ at the end of
   <struct/ea_list/ <param/to/ and returns a pointer to the resulting list.
</function>
<function><p><type>rta *</type>
<funcdef>rta_lookup</funcdef>
(<type>rta *</type> <param>o</param>) --     look up a <struct/rta/ in attribute cache

<funcsect>Arguments
<p><descrip>
<tagp><type>rta *</type> <param>o</param></tagp>
    a un-cached <struct/rta/
</descrip>
<funcsect>Description
<p>
   <func/rta_lookup()/ gets an un-cached <struct/rta/ structure and returns its cached
   counterpart. It starts with examining the attribute cache to see whether
   there exists a matching entry. If such an entry exists, it's returned and
   its use count is incremented, else a new entry is created with use count
   set to 1.
   <p>
   The extended attribute lists attached to the <struct/rta/ are automatically
   converted to the normalized form.
</function>
<function><p><type>void</type>
<funcdef>rta_dump</funcdef>
(<type>rta *</type> <param>a</param>) --     dump route attributes

<funcsect>Arguments
<p><descrip>
<tagp><type>rta *</type> <param>a</param></tagp>
    attribute structure to dump
</descrip>
<funcsect>Description
<p>
   This function takes a <struct/rta/ and dumps its contents to the debug output.
</function>
<function><p><type>void</type>
<funcdef>rta_dump_all</funcdef>
(<param>void</param>) --     dump attribute cache

<funcsect>Description
<p>
   <p>
   This function dumps the whole contents of route attribute cache
   to the debug output.
</function>
<function><p><type>void</type>
<funcdef>rta_init</funcdef>
(<param>void</param>) --     initialize route attribute cache

<funcsect>Description
<p>
   <p>
   This function is called during initialization of the routing
   table module to set up the internals of the attribute cache.
</function>
<function><p><type>rta *</type>
<funcdef>rta_clone</funcdef>
(<type>rta *</type> <param>r</param>) --     clone route attributes

<funcsect>Arguments
<p><descrip>
<tagp><type>rta *</type> <param>r</param></tagp>
    a <struct/rta/ to be cloned
</descrip>
<funcsect>Description
<p>
   <func/rta_clone()/ takes a cached <struct/rta/ and returns its identical cached
   copy. Currently it works by just returning the original <struct/rta/ with
   its use count incremented.
</function>
<function><p><type>void</type>
<funcdef>rta_free</funcdef>
(<type>rta *</type> <param>r</param>) --     free route attributes

<funcsect>Arguments
<p><descrip>
<tagp><type>rta *</type> <param>r</param></tagp>
    a <struct/rta/ to be freed
</descrip>
<funcsect>Description
<p>
   If you stop using a <struct/rta/ (for example when deleting a route which uses
   it), you need to call <func/rta_free()/ to notify the attribute cache the
   attribute is no longer in use and can be freed if you were the last
   user (which <func/rta_free()/ tests by inspecting the use count).
</function>
<!--
	BIRD Programmer's Guide: Protocols

	(c) 2000 Martin Mares <mj@ucw.cz>
-->

<sect>Routing protocols

<sect1>Introduction

<p>The routing protocols are the bird's heart and a fine amount of code
is dedicated to their management and for providing support functions to them.
(-: Actually, this is the reason why the directory with sources of the core
code is called <tt/nest/ :-).

<p>When talking about protocols, one need to distinguish between <em/protocols/
and protocol <em/instances/. A protocol exists exactly once, not depending on whether
it's configured or not and it can have an arbitrary number of instances corresponding
to its "incarnations" requested by the configuration file. Each instance is completely
autonomous, has its own configuration, its own status, its own set of routes and its
own set of interfaces it works on.

<p>A protocol is represented by a <struct/protocol/ structure containing all the basic
information (protocol name, default settings and pointers to most of the protocol
hooks). All these structures are linked in the <param/protocol_list/ list.

<p>Each instance has its own <struct/proto/ structure describing all its properties: protocol
type, configuration, a resource pool where all resources belonging to the instance
live, various protocol attributes (take a look at the declaration of <struct/proto/ in
<tt/protocol.h/), protocol states (see below for what do they mean), connections
to routing tables, filters attached to the protocol
and finally a set of pointers to the rest of protocol hooks (they
are the same for all instances of the protocol, but in order to avoid extra
indirections when calling the hooks from the fast path, they are stored directly
in <struct/proto/). The instance is always linked in both the global instance list
(<param/proto_list/) and a per-status list (either <param/active_proto_list/ for
running protocols, <param/initial_proto_list/ for protocols being initialized or
<param/flush_proto_list/ when the protocol is being shut down).

<p>The protocol hooks are described in the next chapter, for more information about
configuration of protocols, please refer to the configuration chapter and also
to the description of the <func/proto_commit/ function.

<sect1>Protocol states

<p>As startup and shutdown of each protocol are complex processes which can be affected
by lots of external events (user's actions, reconfigurations, behavior of neighboring routers etc.),
we have decided to supervise them by a pair of simple state machines -- the protocol
state machine and a core state machine.

<p>The <em/protocol state machine/ corresponds to internal state of the protocol
and the protocol can alter its state whenever it wants to. There are
the following states:

<descrip>
	<tag/PS_DOWN/ The protocol is down and waits for being woken up by calling its
	start() hook.
	<tag/PS_START/ The protocol is waiting for connection with the rest of the
	network. It's active, it has resources allocated, but it still doesn't want
	any routes since it doesn't know what to do with them.
	<tag/PS_UP/ The protocol is up and running. It communicates with the core,
	delivers routes to tables and wants to hear announcement about route changes.
	<tag/PS_STOP/ The protocol has been shut down (either by being asked by the
	core code to do so or due to having encountered a protocol error).
</descrip>

<p>Unless the protocol is in the <tt/PS_DOWN/ state, it can decide to change
its state by calling the <func/proto_notify_state/ function.

<p>At any time, the core code can ask the protocol to shut itself down by calling its stop() hook.

<p>The <em/core state machine/ takes care of the core view of protocol state.
The states are traversed according to changes of the protocol state machine, but
sometimes the transitions are delayed if the core needs to finish some actions
(for example sending of new routes to the protocol) before proceeding to the
new state. There are the following core states:

<descrip>
	<tag/FS_HUNGRY/ The protocol is down, it doesn't have any routes and
	doesn't want them.
	<tag/FS_FEEDING/ The protocol has reached the <tt/PS_UP/ state, but
	we are still busy sending the initial set of routes to it.
	<tag/FS_HAPPY/ The protocol is up and has complete routing information.
	<tag/FS_FLUSHING/ The protocol is shutting down (it's in either <tt/PS_STOP/
	or <tt/PS_DOWN/ state) and we're flushing all of its routes from the
	routing tables.
</descrip>

<sect1>Functions of the protocol module

<p>The protocol module provides the following functions:
<function><p><type>void *</type>
<funcdef>proto_new</funcdef>
(<type>struct proto_config *</type> <param>c</param>, <type>unsigned</type> <param>size</param>) --  create a new protocol instance

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto_config *</type> <param>c</param></tagp>
 protocol configuration
<tagp><type>unsigned</type> <param>size</param></tagp>
 size of protocol data structure (each protocol instance is represented by
a structure starting with generic part [struct <struct/proto/] and continued
with data specific to the protocol)
</descrip>
<funcsect>Description
<p>
When a new configuration has been read in, the core code starts
initializing all the protocol instances configured by calling their
<func/init()/ hooks with the corresponding instance configuration. The initialization
code of the protocol is expected to create a new instance according to the
configuration by calling this function and then modifying the default settings
to values wanted by the protocol.
</function>
<function><p><type>struct announce_hook *</type>
<funcdef>proto_add_announce_hook</funcdef>
(<type>struct proto *</type> <param>p</param>, <type>struct rtable *</type> <param>t</param>) --  connect protocol to a routing table

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
 protocol instance
<tagp><type>struct rtable *</type> <param>t</param></tagp>
 routing table to connect to
</descrip>
<funcsect>Description
<p>
This function creates a connection between the protocol instance <param/p/
and the routing table <param/t/, making the protocol hear all changes in
the table.
<p>
Unless you want to listen to multiple routing tables (as the Pipe
protocol does), you needn't to worry about this function since the
connection to the protocol's primary routing table is initialized
automatically by the core code.
</function>
<function><p><type>void *</type>
<funcdef>proto_config_new</funcdef>
(<type>struct protocol *</type> <param>pr</param>, <type>unsigned</type> <param>size</param>) --  create a new protocol configuration

<funcsect>Arguments
<p><descrip>
<tagp><type>struct protocol *</type> <param>pr</param></tagp>
 protocol the configuration will belong to
<tagp><type>unsigned</type> <param>size</param></tagp>
 size of the structure including generic data
</descrip>
<funcsect>Description
<p>
Whenever the configuration file says that a new instance
of a routing protocol should be created, the parser calls
<func/proto_config_new()/ to create a configuration entry for this
instance (a structure staring with the <struct/proto_config/ header
containing all the generic items followed by protocol-specific
ones). Also, the configuration entry gets added to the list
of protocol instances kept in the configuration.
</function>
<function><p><type>void</type>
<funcdef>protos_preconfig</funcdef>
(<type>struct config *</type> <param>c</param>) --  pre-configuration processing

<funcsect>Arguments
<p><descrip>
<tagp><type>struct config *</type> <param>c</param></tagp>
 new configuration
</descrip>
<funcsect>Description
<p>
This function calls the <func/preconfig()/ hooks of all routing
protocols available to prepare them for reading of the new
configuration.
</function>
<function><p><type>void</type>
<funcdef>protos_postconfig</funcdef>
(<type>struct config *</type> <param>c</param>) --  post-configuration processing

<funcsect>Arguments
<p><descrip>
<tagp><type>struct config *</type> <param>c</param></tagp>
 new configuration
</descrip>
<funcsect>Description
<p>
This function calls the <func/postconfig()/ hooks of all protocol
instances specified in configuration <param/c/.
</function>
<function><p><type>void</type>
<funcdef>protos_commit</funcdef>
(<type>struct config *</type> <param>new</param>, <type>struct config *</type> <param>old</param>, <type>int</type> <param>force_reconfig</param>) --  commit new protocol configuration

<funcsect>Arguments
<p><descrip>
<tagp><type>struct config *</type> <param>new</param></tagp>
 new configuration
<tagp><type>struct config *</type> <param>old</param></tagp>
 old configuration or <const/NULL/ if it's boot time config
<tagp><type>int</type> <param>force_reconfig</param></tagp>
 force restart of all protocols (used for example
when the router ID changes)
</descrip>
<funcsect>Description
<p>
Scan differences between <param/old/ and <param/new/ configuration and adjust all
protocol instances to conform to the new configuration.
<p>
When a protocol exists in the new configuration, but it doesn't in the
original one, it's immediately started. When a collision with the other
running protocol would arise, the new protocol will be temporarily stopped
by the locking mechanism.
<p>
When a protocol exists in the old configuration, but it doesn't in the
new one, it's shut down and deleted after the shutdown completes.
<p>
When a protocol exists in both configurations, the core decides whether
it's possible to reconfigure it dynamically (it checks all the core properties
of the protocol and if they match, it asks the <func/reconfigure()/ hook of the
protocol to see if the protocol is able to switch to the new configuration).
If it isn't possible, the protocol is shut down and a new instance is started
with the new configuration after the shutdown is completed.
</function>
<function><p><type>void</type>
<funcdef>protos_dump_all</funcdef>
(<param>void</param>) --  dump status of all protocols

<funcsect>Description
<p>
<p>
This function dumps status of all existing protocol instances to the
debug output. It involves printing of general status information
such as protocol states, its position on the protocol lists
and also calling of a <func/dump()/ hook of the protocol to print
the internals.
</function>
<function><p><type>void</type>
<funcdef>proto_build</funcdef>
(<type>struct protocol *</type> <param>p</param>) --  make a single protocol available

<funcsect>Arguments
<p><descrip>
<tagp><type>struct protocol *</type> <param>p</param></tagp>
 the protocol
</descrip>
<funcsect>Description
<p>
After the platform specific initialization code uses <func/protos_build()/
to add all the standard protocols, it should call <func/proto_build()/ for
all platform specific protocols to inform the core that they exist.
</function>
<function><p><type>void</type>
<funcdef>protos_build</funcdef>
(<param>void</param>) --  build a protocol list

<funcsect>Description
<p>
<p>
This function is called during BIRD startup to insert
all standard protocols to the global protocol list. Insertion
of platform specific protocols (such as the kernel syncer)
is in the domain of competence of the platform dependent
startup code.
</function>
<function><p><type>void</type>
<funcdef>proto_notify_state</funcdef>
(<type>struct proto *</type> <param>p</param>, <type>unsigned</type> <param>ps</param>) --  notify core about protocol state change

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
 protocol the state of which has changed
<tagp><type>unsigned</type> <param>ps</param></tagp>
 the new status
</descrip>
<funcsect>Description
<p>
Whenever a state of a protocol changes due to some event internal
to the protocol (i.e., not inside a <func/start()/ or <func/shutdown()/ hook),
it should immediately notify the core about the change by calling
<func/proto_notify_state()/ which will write the new state to the <struct/proto/
structure and take all the actions necessary to adapt to the new
state.
</function>
<sect>Protocol hooks
<p>
   <p>
   Each protocol can provide a rich set of hook functions referred to by pointers
   in either the <struct/proto/ or <struct/protocol/ structure. They are called by the core whenever
   it wants the protocol to perform some action or to notify the protocol about
   any change of its environment. All of the hooks can be set to <const/NULL/ which means
   to ignore the change or to take a default action.


<function><p><type>void</type>
<funcdef>preconfig</funcdef>
(<type>struct protocol *</type> <param>p</param>, <type>struct config *</type> <param>c</param>) --     protocol preconfiguration

<funcsect>Arguments
<p><descrip>
<tagp><type>struct protocol *</type> <param>p</param></tagp>
    a routing protocol
<tagp><type>struct config *</type> <param>c</param></tagp>
    new configuration
</descrip>
<funcsect>Description
<p>
   The <func/preconfig()/ hook is called before parsing of a new configuration.
</function>
<function><p><type>void</type>
<funcdef>postconfig</funcdef>
(<type>struct proto_config *</type> <param>c</param>) --     instance post-configuration

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto_config *</type> <param>c</param></tagp>
    instance configuration
</descrip>
<funcsect>Description
<p>
   The <func/postconfig()/ hook is called for each configured instance after
   parsing of the new configuration is finished.
</function>
<function><p><type>struct proto *</type>
<funcdef>init</funcdef>
(<type>struct proto_config *</type> <param>c</param>) --     initialize an instance

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto_config *</type> <param>c</param></tagp>
    instance configuration
</descrip>
<funcsect>Description
<p>
   The <func/init()/ hook is called by the core to create a protocol instance
   according to supplied protocol configuration.
<funcsect>Result
<p>
    a pointer to the instance created
</function>
<function><p><type>int</type>
<funcdef>reconfigure</funcdef>
(<type>struct proto *</type> <param>p</param>, <type>struct proto_config *</type> <param>c</param>) --     request instance reconfiguration

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
    an instance
<tagp><type>struct proto_config *</type> <param>c</param></tagp>
    new configuration
</descrip>
<funcsect>Description
<p>
   The core calls the <func/reconfigure()/ hook whenever it wants to ask the
   protocol for switching to a new configuration. If the reconfiguration
   is possible, the hook returns 1. Otherwise, it returns 0 and the core
   will shut down the instance and start a new one with the new configuration.
   <p>
   After the protocol confirms reconfiguration, it must no longer keep any
   references to the old configuration since the memory it's stored in can
   be re-used at any time.
</function>
<function><p><type>void</type>
<funcdef>dump</funcdef>
(<type>struct proto *</type> <param>p</param>) --     dump protocol state

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
    an instance
</descrip>
<funcsect>Description
<p>
   This hook dumps the complete state of the instance to the
   debug output.
</function>
<function><p><type>void</type>
<funcdef>dump_attrs</funcdef>
(<type>rte *</type> <param>e</param>) --     dump protocol-dependent attributes

<funcsect>Arguments
<p><descrip>
<tagp><type>rte *</type> <param>e</param></tagp>
    a route entry
</descrip>
<funcsect>Description
<p>
   This hook dumps all attributes in the <struct/rte/ which belong to this
   protocol to the debug output.
</function>
<function><p><type>int</type>
<funcdef>start</funcdef>
(<type>struct proto *</type> <param>p</param>) --     request instance startup

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
    protocol instance
</descrip>
<funcsect>Description
<p>
   The <func/start()/ hook is called by the core when it wishes to start
   the instance.
<funcsect>Result
<p>
    new protocol state
</function>
<function><p><type>int</type>
<funcdef>shutdown</funcdef>
(<type>struct proto *</type> <param>p</param>) --     request instance shutdown

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
    protocol instance
</descrip>
<funcsect>Description
<p>
   The <func/stop()/ hook is called by the core when it wishes to shut
   the instance down for some reason.
<funcsect>Returns
<p>
    new protocol state
</function>
<function><p><type>void</type>
<funcdef>get_status</funcdef>
(<type>struct proto *</type> <param>p</param>, <type>byte *</type> <param>buf</param>) --     get instance status

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
    protocol instance
<tagp><type>byte *</type> <param>buf</param></tagp>
    buffer to be filled with the status string
</descrip>
<funcsect>Description
<p>
   This hook is called by the core if it wishes to obtain an brief one-line user friendly
   representation of the status of the instance to be printed by the &lt;cf/show protocols/
   command.
</function>
<function><p><type>void</type>
<funcdef>get_route_info</funcdef>
(<type>rte *</type> <param>e</param>, <type>byte *</type> <param>buf</param>, <type>ea_list *</type> <param>attrs</param>) --     get route information

<funcsect>Arguments
<p><descrip>
<tagp><type>rte *</type> <param>e</param></tagp>
    a route entry
<tagp><type>byte *</type> <param>buf</param></tagp>
    buffer to be filled with the resulting string
<tagp><type>ea_list *</type> <param>attrs</param></tagp>
    extended attributes of the route
</descrip>
<funcsect>Description
<p>
   This hook is called to fill the buffer <param/buf/ with a brief user friendly
   representation of metrics of a route belonging to this protocol.
</function>
<function><p><type>int</type>
<funcdef>get_attr</funcdef>
(<type>eattr *</type> <param>a</param>, <type>byte *</type> <param>buf</param>) --     get attribute information

<funcsect>Arguments
<p><descrip>
<tagp><type>eattr *</type> <param>a</param></tagp>
    an extended attribute
<tagp><type>byte *</type> <param>buf</param></tagp>
    buffer to be filled with attribute information
</descrip>
<funcsect>Description
<p>
   The <func/get_attr()/ hook is called by the core to obtain a user friendly
   representation of an extended route attribute. It can either leave
   the whole conversion to the core (by returning <const/GA_UNKNOWN/), fill
   in only attribute name (and let the core format the attribute value
   automatically according to the type field; by returning <const/GA_NAME/)
   or doing the whole conversion (used in case the value requires extra
   care; return <const/GA_FULL/).
</function>
<function><p><type>void</type>
<funcdef>if_notify</funcdef>
(<type>struct proto *</type> <param>p</param>, <type>unsigned</type> <param>flags</param>, <type>struct iface *</type> <param>i</param>) --     notify instance about interface changes

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
    protocol instance
<tagp><type>unsigned</type> <param>flags</param></tagp>
    interface change flags
<tagp><type>struct iface *</type> <param>i</param></tagp>
    the interface in question
</descrip>
<funcsect>Description
<p>
   This hook is called whenever any network interface changes its status.
   The change is described by a combination of status bits (<const/IF_CHANGE_xxx/)
   in the <param/flags/ parameter.
</function>
<function><p><type>void</type>
<funcdef>ifa_notify</funcdef>
(<type>struct proto *</type> <param>p</param>, <type>unsigned</type> <param>flags</param>, <type>struct ifa *</type> <param>a</param>) --     notify instance about interface address changes

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
    protocol instance
<tagp><type>unsigned</type> <param>flags</param></tagp>
    address change flags
<tagp><type>struct ifa *</type> <param>a</param></tagp>
    the interface address
</descrip>
<funcsect>Description
<p>
   This hook is called to notify the protocol instance about an interface
   acquiring or losing one of its addresses. The change is described by
   a combination of status bits (<const/IF_CHANGE_xxx/) in the <param/flags/ parameter.
</function>
<function><p><type>void</type>
<funcdef>rt_notify</funcdef>
(<type>struct proto *</type> <param>p</param>, <type>net *</type> <param>net</param>, <type>rte *</type> <param>new</param>, <type>rte *</type> <param>old</param>, <type>ea_list *</type> <param>attrs</param>) --     notify instance about routing table change

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
    protocol instance
<tagp><type>net *</type> <param>net</param></tagp>
    a network entry
<tagp><type>rte *</type> <param>new</param></tagp>
    new optimal route for the network
<tagp><type>rte *</type> <param>old</param></tagp>
    old optimal route for the network
<tagp><type>ea_list *</type> <param>attrs</param></tagp>
    extended attributes associated with the <param/new/ entry
</descrip>
<funcsect>Description
<p>
   The <func/rt_notify()/ hook is called to inform the protocol instance about
   changes in the routing table it's connected to, that is a route <param/old/
   belonging to network <param/net/ being replaced by a new route <param/new/ with
   extended attributes <param/attrs/. Either <param/new/ or <param/old/ or both can be <const/NULL/
   if the corresponding route doesn't exist.
</function>
<function><p><type>void</type>
<funcdef>neigh_notify</funcdef>
(<type>neighbor *</type> <param>neigh</param>) --     notify instance about neighbor status change

<funcsect>Arguments
<p><descrip>
<tagp><type>neighbor *</type> <param>neigh</param></tagp>
    a neighbor cache entry
</descrip>
<funcsect>Description
<p>
   The <func/neigh_notify()/ hook is called by the neighbor cache whenever
   a neighbor changes its state, that is it gets disconnected or a
   sticky neighbor gets connected.
</function>
<function><p><type>ea_list *</type>
<funcdef>make_tmp_attrs</funcdef>
(<type>rte *</type> <param>e</param>, <type>struct linpool *</type> <param>pool</param>) --     convert embedded attributes to temporary ones

<funcsect>Arguments
<p><descrip>
<tagp><type>rte *</type> <param>e</param></tagp>
    route entry
<tagp><type>struct linpool *</type> <param>pool</param></tagp>
    linear pool to allocate attribute memory in
</descrip>
<funcsect>Description
<p>
   This hook is called by the routing table functions if they need
   to convert the protocol attributes embedded directly in the <struct/rte/
   to temporary extended attributes in order to distribute them
   to other protocols or to filters. <func/make_tmp_attrs()/ creates
   an <struct/ea_list/ in the linear pool <param/pool/, fills it with values of the
   temporary attributes and returns a pointer to it.
</function>
<function><p><type>void</type>
<funcdef>store_tmp_attrs</funcdef>
(<type>rte *</type> <param>e</param>, <type>ea_list *</type> <param>attrs</param>) --     convert temporary attributes to embedded ones

<funcsect>Arguments
<p><descrip>
<tagp><type>rte *</type> <param>e</param></tagp>
    route entry
<tagp><type>ea_list *</type> <param>attrs</param></tagp>
    temporary attributes to be converted
</descrip>
<funcsect>Description
<p>
   This hook is an exact opposite of <func/make_tmp_attrs()/ -- it takes
   a list of extended attributes and converts them to attributes
   embedded in the <struct/rte/ corresponding to this protocol.
   <p>
   You must be prepared for any of the attributes being missing
   from the list and use default values instead.
</function>
<function><p><type>int</type>
<funcdef>import_control</funcdef>
(<type>struct proto *</type> <param>p</param>, <type>rte **</type> <param>e</param>, <type>ea_list **</type> <param>attrs</param>, <type>struct linpool *</type> <param>pool</param>) --     pre-filtering decisions on route import

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
    protocol instance the route is going to be imported to
<tagp><type>rte **</type> <param>e</param></tagp>
    the route in question
<tagp><type>ea_list **</type> <param>attrs</param></tagp>
    extended attributes of the route
<tagp><type>struct linpool *</type> <param>pool</param></tagp>
    linear pool for allocation of all temporary data
</descrip>
<funcsect>Description
<p>
   The <func/import_control()/ hook is called as the first step of a exporting
   a route from a routing table to the protocol instance. It can modify
   route attributes and force acceptance or rejection of the route regardless
   of user-specified filters. See <func/rte_announce()/ for a complete description
   of the route distribution process.
   <p>
   The standard use of this hook is to reject routes having originated
   from the same instance and to set default values of the protocol's metrics.
<funcsect>Result
<p>
    -1 if the route has to be accepted, 1 if rejected and 0 if it
   should be passed to the filters.
</function>
<function><p><type>int</type>
<funcdef>rte_better</funcdef>
(<type>rte *</type> <param>new</param>, <type>rte *</type> <param>old</param>) --     compare metrics of two routes

<funcsect>Arguments
<p><descrip>
<tagp><type>rte *</type> <param>new</param></tagp>
    the new route
<tagp><type>rte *</type> <param>old</param></tagp>
    the original route
</descrip>
<funcsect>Description
<p>
   This hook gets called when the routing table contains two routes
   for the same network which have originated from different instances
   of a single protocol and it wants to select which one is preferred
   over the other one. Protocols usually decide according to route metrics.
<funcsect>Result
<p>
    1 if <param/new/ is better (more preferred) than <param/old/, 0 otherwise.
</function>
<function><p><type>int</type>
<funcdef>rte_same</funcdef>
(<type>rte *</type> <param>e1</param>, <type>rte *</type> <param>e2</param>) --     compare two routes

<funcsect>Arguments
<p><descrip>
<tagp><type>rte *</type> <param>e1</param></tagp>
    route
<tagp><type>rte *</type> <param>e2</param></tagp>
    route
</descrip>
<funcsect>Description
<p>
   The <func/rte_same()/ hook tests whether the routes <param/e1/ and <param/e2/ belonging
   to the same protocol instance have identical contents. Contents of
   <struct/rta/, all the extended attributes and <struct/rte/ preference are checked
   by the core code, no need to take care of them here.
<funcsect>Result
<p>
    1 if <param/e1/ is identical to <param/e2/, 0 otherwise.
</function>
<function><p><type>void</type>
<funcdef>rte_insert</funcdef>
(<type>net *</type> <param>n</param>, <type>rte *</type> <param>e</param>) --     notify instance about route insertion

<funcsect>Arguments
<p><descrip>
<tagp><type>net *</type> <param>n</param></tagp>
    network
<tagp><type>rte *</type> <param>e</param></tagp>
    route
</descrip>
<funcsect>Description
<p>
   This hook is called whenever a <struct/rte/ belonging to the instance
   is accepted for insertion to a routing table.
   <p>
   Please avoid using this function in new protocols.
</function>
<function><p><type>void</type>
<funcdef>rte_remove</funcdef>
(<type>net *</type> <param>n</param>, <type>rte *</type> <param>e</param>) --     notify instance about route removal

<funcsect>Arguments
<p><descrip>
<tagp><type>net *</type> <param>n</param></tagp>
    network
<tagp><type>rte *</type> <param>e</param></tagp>
    route
</descrip>
<funcsect>Description
<p>
   This hook is called whenever a <struct/rte/ belonging to the instance
   is removed from a routing table.
   <p>
   Please avoid using this function in new protocols.
</function>
<sect>Interfaces
<p>
   <p>
   The interface module keeps track of all network interfaces in the
   system and their addresses.
   <p>
   Each interface is represented by an <struct/iface/ structure which carries
   interface capability flags (<const/IF_MULTIACCESS/, <const/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 <struct/ifa/.
   <p>
   The interface module keeps a `soft-up' state for each <struct/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.


<function><p><type>void</type>
<funcdef>ifa_dump</funcdef>
(<type>struct ifa *</type> <param>a</param>) --     dump interface address

<funcsect>Arguments
<p><descrip>
<tagp><type>struct ifa *</type> <param>a</param></tagp>
    interface address descriptor
</descrip>
<funcsect>Description
<p>
   This function dumps contents of an <struct/ifa/ to the debug output.
</function>
<function><p><type>void</type>
<funcdef>if_dump</funcdef>
(<type>struct iface *</type> <param>i</param>) --     dump interface

<funcsect>Arguments
<p><descrip>
<tagp><type>struct iface *</type> <param>i</param></tagp>
    interface to dump
</descrip>
<funcsect>Description
<p>
   This function dumps all information associated with a given
   network interface to the debug output.
</function>
<function><p><type>void</type>
<funcdef>if_dump_all</funcdef>
(<param>void</param>) --     dump all interfaces

<funcsect>Description
<p>
   <p>
   This function dumps information about all known network
   interfaces to the debug output.
</function>
<function><p><type>struct iface *</type>
<funcdef>if_update</funcdef>
(<type>struct iface *</type> <param>new</param>) --     update interface status

<funcsect>Arguments
<p><descrip>
<tagp><type>struct iface *</type> <param>new</param></tagp>
    new interface status
</descrip>
<funcsect>Description
<p>
   <func/if_update()/ is called by the low-level platform dependent code
   whenever it notices an interface change.
   <p>
   There exist two types of interface updates -- synchronous and asynchronous
   ones. In the synchronous case, the low-level code calls <func/if_start_update()/,
   scans all interfaces reported by the OS, uses <func/if_update()/ and <func/ifa_update()/
   to pass them to the core and then it finishes the update sequence by
   calling <func/if_end_update()/. When working asynchronously, the sysdep code
   calls <func/if_update()/ and <func/ifa_update()/ whenever it notices a change.
   <p>
   <func/if_update()/ will automatically notify all other modules about the change.
</function>
<function><p><type>void</type>
<funcdef>if_feed_baby</funcdef>
(<type>struct proto *</type> <param>p</param>) --     advertise interfaces to a new protocol

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
    protocol to feed
</descrip>
<funcsect>Description
<p>
   When a new protocol starts, this function sends it a series
   of notifications about all existing interfaces.
</function>
<function><p><type>struct iface *</type>
<funcdef>if_find_by_index</funcdef>
(<type>unsigned</type> <param>idx</param>) --     find interface by ifindex

<funcsect>Arguments
<p><descrip>
<tagp><type>unsigned</type> <param>idx</param></tagp>
    ifindex
</descrip>
<funcsect>Description
<p>
   This function finds an <struct/iface/ structure corresponding to an interface
   of the given index <param/idx/. Returns a pointer to the structure or <const/NULL/
   if no such structure exists.
</function>
<function><p><type>struct iface *</type>
<funcdef>if_find_by_name</funcdef>
(<type>char *</type> <param>name</param>) --     find interface by name

<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>name</param></tagp>
    interface name
</descrip>
<funcsect>Description
<p>
   This function finds an <struct/iface/ structure corresponding to an interface
   of the given name <param/name/. Returns a pointer to the structure or <const/NULL/
   if no such structure exists.
</function>
<function><p><type>struct ifa *</type>
<funcdef>ifa_update</funcdef>
(<type>struct ifa *</type> <param>a</param>) --     update interface address

<funcsect>Arguments
<p><descrip>
<tagp><type>struct ifa *</type> <param>a</param></tagp>
    new interface address
</descrip>
<funcsect>Description
<p>
   This function adds address information to a network
   interface. It's called by the platform dependent code during
   the interface update process described under <func/if_update()/.
</function>
<function><p><type>void</type>
<funcdef>ifa_delete</funcdef>
(<type>struct ifa *</type> <param>a</param>) --     remove interface address

<funcsect>Arguments
<p><descrip>
<tagp><type>struct ifa *</type> <param>a</param></tagp>
    interface address
</descrip>
<funcsect>Description
<p>
   This function removes address information from a network
   interface. It's called by the platform dependent code during
   the interface update process described under <func/if_update()/.
</function>
<function><p><type>void</type>
<funcdef>if_init</funcdef>
(<param>void</param>) --     initialize interface module

<funcsect>Description
<p>
   <p>
   This function is called during BIRD startup to initialize
   all data structures of the interface module.
</function>
<sect>Neighbor cache
<p>
   <p>
   Most routing protocols need to associate their internal state data with
   neighboring routers, check whether an address given as the next hop
   attribute of a route is really an address of a directly connected host
   and which interface is it connected through. Also, they often need to
   be notified when a neighbor ceases to exist or when their long awaited
   neighbor becomes connected. The neighbor cache is there to solve all
   these problems.
   <p>
   The neighbor cache maintains a collection of neighbor entries. Each
   entry represents one IP address corresponding to either our directly
   connected neighbor or our own end of the link (when the scope of the
   address is set to <const/SCOPE_HOST/) together with per-neighbor data belonging to a
   single protocol.
   <p>
   Active entries represent known neighbors and are stored in a hash
   table (to allow fast retrieval based on the IP address of the node) and
   two linked lists: one global and one per-interface (allowing quick
   processing of interface change events). Inactive entries exist only
   when the protocol has explicitly requested it via the <const/NEF_STICKY/
   flag because it wishes to be notified when the node will again become
   a neighbor. Such entries are enqueued in a special list which is walked
   whenever an interface changes its state to up.
   <p>
   When a neighbor event occurs (a neighbor gets disconnected or a sticky
   inactive neighbor becomes connected), the protocol hook <func/neigh_notify()/
   is called to advertise the change.


<function><p><type>neighbor *</type>
<funcdef>neigh_find</funcdef>
(<type>struct proto *</type> <param>p</param>, <type>ip_addr *</type> <param>a</param>, <type>unsigned</type> <param>flags</param>) --     find or create a neighbor entry.

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
    protocol which asks for the entry.
<tagp><type>ip_addr *</type> <param>a</param></tagp>
    pointer to IP address of the node to be searched for.
<tagp><type>unsigned</type> <param>flags</param></tagp>
    0 or <const/NEF_STICKY/ if you want to create a sticky entry.
</descrip>
<funcsect>Description
<p>
   Search the neighbor cache for a node with given IP address. If
   it's found, a pointer to the neighbor entry is returned. If no
   such entry exists and the node is directly connected on
   one of our active interfaces, a new entry is created and returned
   to the caller with protocol-dependent fields initialized to zero.
   If the node is not connected directly or *<param/a/ is not a valid unicast
   IP address, <func/neigh_find()/ returns <const/NULL/.
</function>
<function><p><type>void</type>
<funcdef>neigh_dump</funcdef>
(<type>neighbor *</type> <param>n</param>) --     dump specified neighbor entry.

<funcsect>Arguments
<p><descrip>
<tagp><type>neighbor *</type> <param>n</param></tagp>
    the entry to dump
</descrip>
<funcsect>Description
<p>
   This functions dumps the contents of a given neighbor entry
   to debug output.
</function>
<function><p><type>void</type>
<funcdef>neigh_dump_all</funcdef>
(<param>void</param>) --     dump all neighbor entries.

<funcsect>Description
<p>
   <p>
   This function dumps the contents of the neighbor cache to
   debug output.
</function>
<function><p><type>void</type>
<funcdef>neigh_if_up</funcdef>
(<type>struct iface *</type> <param>i</param>)
<funcsect>Arguments
<p><descrip>
<tagp><type>struct iface *</type> <param>i</param></tagp>
    interface in question
</descrip>
<funcsect>Description
<p>
   Tell the neighbor cache that a new interface became up.
   <p>
   The neighbor cache wakes up all inactive sticky neighbors with
   addresses belonging to prefixes of the interface <param/i/.
</function>
<function><p><type>void</type>
<funcdef>neigh_if_down</funcdef>
(<type>struct iface *</type> <param>i</param>) --     notify neighbor cache about interface down event

<funcsect>Arguments
<p><descrip>
<tagp><type>struct iface *</type> <param>i</param></tagp>
    the interface in question
</descrip>
<funcsect>Description
<p>
   Notify the neighbor cache that an interface has ceased to exist.
   <p>
   It causes all entries belonging to neighbors connected to this interface
   to be flushed.
</function>
<function><p><type>void</type>
<funcdef>neigh_prune</funcdef>
(<param>void</param>) --     prune neighbor cache

<funcsect>Description
<p>
   <p>
   <func/neigh_prune()/ examines all neighbor entries cached and removes those
   corresponding to inactive protocols. It's called whenever a protocol
   is shut down to get rid of all its heritage.
</function>
<function><p><type>void</type>
<funcdef>neigh_init</funcdef>
(<type>pool *</type> <param>if_pool</param>) --     initialize the neighbor cache.

<funcsect>Arguments
<p><descrip>
<tagp><type>pool *</type> <param>if_pool</param></tagp>
    resource pool to be used for neighbor entries.
</descrip>
<funcsect>Description
<p>
   This function is called during BIRD startup to initialize
   the neighbor cache module.
</function>
<sect>Command line interface
<p>
   <p>
   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).
   <p>
   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.
   <p>
   Reply codes starting with 0 stand for `action successfully completed' messages,
   1 means `table entry', 8 `runtime error' and 9 `syntax error'.
   <p>
   Each CLI session is internally represented by a <struct/cli/ structure and a
   resource pool containing all resources associated with the connection,
   so that it can be easily freed whenever the connection gets closed, not depending
   on the current state of command processing.
   <p>
   The CLI commands are declared as a part of the configuration grammar
   by using the <tt>CF_CLI</tt> macro. When a command is received, it is processed
   by the same lexical analyzer 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 it back or (in case it expects the reply will be long)
   it prints a partial reply and asks the CLI module (using the <param/cont/ hook)
   to call it again when the output is transferred to the user.
   <p>
   The <param/this_cli/ variable points to a <struct/cli/ structure of the session being
   currently parsed, but it's of course available only in command handlers
   not entered using the <param/cont/ hook.


<function><p><type>void</type>
<funcdef>cli_printf</funcdef>
(<type>cli *</type> <param>c</param>, <type>int</type> <param>code</param>, <type>char *</type> <param>msg</param>, <type>...</type> <param>...</param>) --     send reply to a CLI connection

<funcsect>Arguments
<p><descrip>
<tagp><type>cli *</type> <param>c</param></tagp>
    CLI connection
<tagp><type>int</type> <param>code</param></tagp>
    numeric code of the reply, negative for continuation lines
<tagp><type>char *</type> <param>msg</param></tagp>
    a <func/printf()/-like formatting string.
<tagp><type>...</type> <param>...</param></tagp>
   variable arguments
</descrip>
<funcsect>Description
<p>
   This function send a single line of reply to a given CLI connection.
   In works in all aspects like <func/bsprintf()/ except that it automatically
   prepends the reply line prefix.
   <p>
   Please note that if the connection can be already busy sending some
   data in which case <func/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.
   <p>
   If you want to write to the current CLI output, you can use the <func/cli_msg()/
   macro instead.
</function>
<function><p><type>void</type>
<funcdef>cli_init</funcdef>
(<param>void</param>) --     initialize the CLI module

<funcsect>Description
<p>
   <p>
   This function is called during BIRD startup to initialize
   the internal data structures of the CLI module.
</function>
<sect>Object locks
<p>
   <p>
   The lock module provides a simple mechanism for avoiding conflicts between
   various protocols which would like to use a single physical resource (for
   example a network port). It would be easy to say that such collisions can
   occur only when the user specifies an invalid configuration and therefore
   he deserves to get what he has asked for, but unfortunately they can also
   arise legitimately when the daemon is reconfigured and there exists (although
   for a short time period only) an old protocol instance being shut down and a new one
   willing to start up on the same interface.
   <p>
   The solution is very simple: when any protocol wishes to use a network port
   or some other non-shareable resource, it asks the core to lock it and it doesn't
   use the resource until it's notified that it has acquired the lock.
   <p>
   Object locks are represented by <struct/object_lock/ structures which are in turn a kind of
   resource. Lockable resources are uniquely determined by resource type
   (<const/OBJLOCK_UDP/ for a UDP port etc.), IP address (usually a broadcast or
   multicast address the port is bound to), port number and interface.


<function><p><type>struct object_lock *</type>
<funcdef>olock_new</funcdef>
(<type>pool *</type> <param>p</param>) --     create an object lock

<funcsect>Arguments
<p><descrip>
<tagp><type>pool *</type> <param>p</param></tagp>
    resource pool to create the lock in.
</descrip>
<funcsect>Description
<p>
   The <func/olock_new()/ function creates a new resource of type <struct/object_lock/
   and returns a pointer to it. After filling in the structure, the caller
   should call <func/olock_acquire()/ to do the real locking.
</function>
<function><p><type>void</type>
<funcdef>olock_acquire</funcdef>
(<type>struct object_lock *</type> <param>l</param>) --     acquire a lock

<funcsect>Arguments
<p><descrip>
<tagp><type>struct object_lock *</type> <param>l</param></tagp>
    the lock to acquire
</descrip>
<funcsect>Description
<p>
   This function attempts to acquire exclusive access to the non-shareable
   resource described by the lock <param/l/. It returns immediately, but as soon
   as the resource becomes available, it calls the <func/hook()/ function set up
   by the caller.
   <p>
   When you want to release the resource, just <func/rfree()/ the lock.
</function>
<function><p><type>void</type>
<funcdef>olock_init</funcdef>
(<param>void</param>) --     initialize the object lock mechanism

<funcsect>Description
<p>
   <p>
   This function is called during BIRD startup. It initializes
   all the internal data structures of the lock module.
</function>
<chapt>Configuration
<sect>Configuration manager
<p>
   <p>
   Configuration of BIRD is complex, yet straightforward. There are three
   modules taking care of the configuration: config manager (which takes care
   of storage of the config information and controls switching between configs),
   lexical analyzer and parser.
   <p>
   The configuration manager stores each config as a <struct/config/ structure
   accompanied by a linear pool from which all information associated
   with the config and pointed to by the <struct/config/ structure is allocated.
   <p>
   There can exist up to four different configurations at one time: an active
   one (pointed to by <param/config/), configuration we are just switching from
   (<param/old_config/), one queued for the next reconfiguration (<param/future_config/;
   if it's non-<const/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 (<param/new_config/).
   <p>
   Loading of new configuration is very simple: just call <func/config_alloc()/
   to get a new <struct/config/ structure, then use <func/config_parse()/ to parse a
   configuration file and fill all fields of the structure
   and finally ask the config manager to switch to the new
   config by calling <func/config_commit()/.
   <p>
   CLI commands are parsed in a very similar way -- there is also a stripped-down
   <struct/config/ structure associated with them and they are lex-ed 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.


<function><p><type>struct config *</type>
<funcdef>config_alloc</funcdef>
(<type>byte *</type> <param>name</param>) --     allocate a new configuration

<funcsect>Arguments
<p><descrip>
<tagp><type>byte *</type> <param>name</param></tagp>
    name of the config
</descrip>
<funcsect>Description
<p>
   This function creates new <struct/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.
</function>
<function><p><type>int</type>
<funcdef>config_parse</funcdef>
(<type>struct config *</type> <param>c</param>) --     parse a configuration

<funcsect>Arguments
<p><descrip>
<tagp><type>struct config *</type> <param>c</param></tagp>
    configuration
</descrip>
<funcsect>Description
<p>
   <func/config_parse()/ reads input by calling a hook function pointed to
   by <param/cf_read_hook/ and parses it according to the configuration
   grammar. It also calls all the preconfig and postconfig hooks
   before, resp. after parsing.
<funcsect>Result
<p>
    1 if the config has been parsed successfully, 0 if any
   error has occurred (such as anybody calling <func/cf_error()/) and
   the <param/err_msg/ field has been set to the error message.
</function>
<function><p><type>int</type>
<funcdef>cli_parse</funcdef>
(<type>struct config *</type> <param>c</param>) --     parse a CLI command

<funcsect>Arguments
<p><descrip>
<tagp><type>struct config *</type> <param>c</param></tagp>
    temporary config structure
</descrip>
<funcsect>Description
<p>
   <func/cli_parse()/ is similar to <func/config_parse()/, but instead of a configuration,
   it parses a CLI command. See the CLI module for more information.
</function>
<function><p><type>void</type>
<funcdef>config_free</funcdef>
(<type>struct config *</type> <param>c</param>) --     free a configuration

<funcsect>Arguments
<p><descrip>
<tagp><type>struct config *</type> <param>c</param></tagp>
    configuration to be freed
</descrip>
<funcsect>Description
<p>
   This function takes a <struct/config/ structure and frees all resources
   associated with it.
</function>
<function><p><type>int</type>
<funcdef>config_commit</funcdef>
(<type>struct config *</type> <param>c</param>) --     commit a configuration

<funcsect>Arguments
<p><descrip>
<tagp><type>struct config *</type> <param>c</param></tagp>
    new configuration
</descrip>
<funcsect>Description
<p>
   When a configuration is parsed and prepared for use, the
   <func/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 <func/commit()/ functions which can either accept it immediately
   or call <func/config_add_obstacle()/ to report that they need some time
   to complete the reconfiguration. After all such obstacles are removed
   using <func/config_del_obstacle()/, the old configuration is freed and
   everything runs according to the new one.
<funcsect>Result
<p>
    <const/CONF_DONE/ if the configuration has been accepted immediately,
   <const/CONF_PROGRESS/ if it will take some time to switch to it, <const/CONF_QUEUED/
   if it's been queued due to another reconfiguration being in progress now
   or <const/CONF_SHUTDOWN/ if BIRD is in shutdown mode and no new configurations
   are accepted.
</function>
<function><p><type>void</type>
<funcdef>order_shutdown</funcdef>
(<param>void</param>) --     order BIRD shutdown

<funcsect>Description
<p>
   <p>
   This function initiates shutdown of BIRD. It's accomplished by asking
   for switching to an empty configuration.
</function>
<function><p><type>void</type>
<funcdef>cf_error</funcdef>
(<type>char *</type> <param>msg</param>, <type>...</type> <param>...</param>) --     report a configuration error

<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>msg</param></tagp>
    printf-like format string
<tagp><type>...</type> <param>...</param></tagp>
   variable arguments
</descrip>
<funcsect>Description
<p>
   <func/cf_error()/ can be called during execution of <func/config_parse()/, that is
   from the parser, a preconfig hook or a postconfig hook, to report an
   error in the configuration.
</function>
<function><p><type>char *</type>
<funcdef>cfg_strdup</funcdef>
(<type>char *</type> <param>c</param>) --     copy a string to config memory

<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>c</param></tagp>
    string to copy
</descrip>
<funcsect>Description
<p>
   <func/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.
</function>
<sect>Lexical analyzer
<p>
   <p>
   The lexical analyzer used for configuration files and CLI commands
   is generated using the <tt>flex</tt> tool accompanied by a couple of
   functions maintaining the hash tables containing information about
   symbols and keywords.
   <p>
   Each symbol is represented by a <struct/symbol/ structure containing name
   of the symbol, its lexical scope, symbol class (<const/SYM_PROTO/ for a name of a protocol,
   <const/SYM_NUMBER/ for a numeric constant etc.) and class dependent data.
   When an unknown symbol is encountered, it's automatically added to the
   symbol table with class <const/SYM_VOID/.
   <p>
   The keyword tables are generated from the grammar templates
   using the <tt>gen_keywords.m4</tt> script.


<function><p><type>struct symbol *</type>
<funcdef>cf_find_symbol</funcdef>
(<type>byte *</type> <param>c</param>) --     find a symbol by name

<funcsect>Arguments
<p><descrip>
<tagp><type>byte *</type> <param>c</param></tagp>
    symbol name
</descrip>
<funcsect>Description
<p>
   This functions searches the symbol table for a symbol of given
   name. First it examines the current scope, then the second recent
   one and so on until it either finds the symbol and returns a pointer
   to its <struct/symbol/ structure or reaches the end of the scope chain
   and returns <const/NULL/ to signify no match.
</function>
<function><p><type>struct symbol *</type>
<funcdef>cf_define_symbol</funcdef>
(<type>struct symbol *</type> <param>sym</param>, <type>int</type> <param>type</param>, <type>void *</type> <param>def</param>) --     define meaning of a symbol

<funcsect>Arguments
<p><descrip>
<tagp><type>struct symbol *</type> <param>sym</param></tagp>
    symbol to be defined
<tagp><type>int</type> <param>type</param></tagp>
    symbol class to assign
<tagp><type>void *</type> <param>def</param></tagp>
    class dependent data
</descrip>
<funcsect>Description
<p>
   Defines new meaning of a symbol. If the symbol is an undefined
   one (<const/SYM_VOID/), it's just re-defined to the new type. If it's defined
   in different scope, a new symbol in current scope is created and the
   meaning is assigned to it. If it's already defined in the current scope,
   an error is reported via <func/cf_error()/.
<funcsect>Result
<p>
    Pointer to the newly defined symbol. If we are in the top-level
   scope, it's the same <param/sym/ as passed to the function.
</function>
<function><p><type>void</type>
<funcdef>cf_lex_init</funcdef>
(<type>int</type> <param>is_cli</param>) --     initialize the lexer

<funcsect>Arguments
<p><descrip>
<tagp><type>int</type> <param>is_cli</param></tagp>
    true if we're going to parse CLI command, false for configuration
</descrip>
<funcsect>Description
<p>
   <func/cf_lex_init()/ initializes the lexical analyzer and prepares it for
   parsing of a new input.
</function>
<function><p><type>void</type>
<funcdef>cf_push_scope</funcdef>
(<type>struct symbol *</type> <param>sym</param>) --     enter new scope

<funcsect>Arguments
<p><descrip>
<tagp><type>struct symbol *</type> <param>sym</param></tagp>
    symbol representing scope name
</descrip>
<funcsect>Description
<p>
   If we want to enter a new scope to process declarations inside
   a nested block, we can just call <func/cf_push_scope()/ to push a new
   scope onto the scope stack which will cause all new symbols to be
   defined in this scope and all existing symbols to be sought for
   in all scopes stored on the stack.
</function>
<function><p><type>void</type>
<funcdef>cf_pop_scope</funcdef>
(<param>void</param>) --     leave a scope

<funcsect>Description
<p>
   <p>
   <func/cf_pop_scope()/ pops the topmost scope from the scope stack,
   leaving all its symbols in the symbol table, but making them
   invisible to the rest of the config.
</function>
<function><p><type>char *</type>
<funcdef>cf_symbol_class_name</funcdef>
(<type>struct symbol *</type> <param>sym</param>) --     get name of a symbol class

<funcsect>Arguments
<p><descrip>
<tagp><type>struct symbol *</type> <param>sym</param></tagp>
    symbol
</descrip>
<funcsect>Description
<p>
   This function returns a string representing the class
   of the given symbol.
</function>
<sect>Parser
<p>
   <p>
   Both the configuration and CLI commands are analyzed using a syntax
   driven parser generated by the <tt>bison</tt> tool from a grammar which
   is constructed from information gathered from grammar snippets by
   the <tt>gen_parser.m4</tt> script.
   <p>
   Grammar snippets are files (usually with extension <tt>.Y</tt>) contributed
   by various BIRD modules in order to provide information about syntax of their
   configuration and their CLI commands. Each snipped consists of several
   sections, each of them starting with a special keyword: <tt>CF_HDR</tt> for
   a list of <tt>#include</tt> directives needed by the C code, <tt>CF_DEFINES</tt>
   for a list of C declarations, <tt>CF_DECLS</tt> for <tt>bison</tt> declarations
   including keyword definitions specified as <tt>CF_KEYWORDS</tt>, <tt>CF_GRAMMAR</tt>
   for the grammar rules, <tt>CF_CODE</tt> for auxiliary C code and finally
   <tt>CF_END</tt> at the end of the snippet.
   <p>
   To create references between the snippets, it's possible to define
   multi-part rules by utilizing the <tt>CF_ADDTO</tt> macro which adds a new
   alternative to a multi-part rule.
   <p>
   CLI commands are defined using a <tt>CF_CLI</tt> macro. Its parameters are:
   the list of keywords determining the command, the list of parameters,
   help text for the parameters and help text for the command.
   <p>
   Values of <tt>enum</tt> filter types can be defined using <tt>CF_ENUM</tt> with
   the following parameters: name of filter type, prefix common for all
   literals of this type and names of all the possible values.


<chapt>Filters
<sect>Filters
<p>
   <p>
   You can find sources of the filter language in <tt>filter/</tt>
   directory. File <tt>filter/config.Y</tt> contains filter grammar and basically translates
   the source from user into a tree of <struct/f_inst/ structures. These trees are
   later interpreted using code in <tt>filter/filter.c</tt>.
   <p>
   A filter is represented by a tree of <struct/f_inst/ structures, one structure per
   "instruction". Each <struct/f_inst/ contains <param/code/, <param/aux/ value which is
   usually the data type this instruction operates on and two generic
   arguments (<param/a1/, <param/a2/). Some instructions contain pointer(s) to other
   instructions in their (<param/a1/, <param/a2/) fields.
   <p>
   Filters use a <struct/f_val/ structure for their data. Each <struct/f_val/
   contains type and value (types are constants prefixed with <const/T_/). Few
   of the types are special; <const/T_RETURN/ can be or-ed with a type to indicate
   that return from a function or from the whole filter should be
   forced. Important thing about <struct/f_val/'s is that they may be copied
   with a simple <tt>=</tt>. That's fine for all currently defined types: strings
   are read-only (and therefore okay), paths are copied for each
   operation (okay too).


<function><p><type>int</type>
<funcdef>val_compare</funcdef>
(<type>struct f_val</type> <param>v1</param>, <type>struct f_val</type> <param>v2</param>) --     compare two values

<funcsect>Arguments
<p><descrip>
<tagp><type>struct f_val</type> <param>v1</param></tagp>
    first value
<tagp><type>struct f_val</type> <param>v2</param></tagp>
    second value
</descrip>
<funcsect>Description
<p>
   Compares two values and returns -1, 0, 1 on &lt;, =, &gt; or 999 on error.
   Tree module relies on this giving consistent results so that it can
   build balanced trees.
</function>
<function><p><type>int</type>
<funcdef>val_in_range</funcdef>
(<type>struct f_val</type> <param>v1</param>, <type>struct f_val</type> <param>v2</param>) --     implement <tt>~</tt> operator

<funcsect>Arguments
<p><descrip>
<tagp><type>struct f_val</type> <param>v1</param></tagp>
    element
<tagp><type>struct f_val</type> <param>v2</param></tagp>
    set
</descrip>
<funcsect>Description
<p>
   Checks if <param/v1/ is element (<tt>~</tt> operator) of <param/v2/. Sets are internally represented as balanced trees, see
   <tt>tree.c</tt> module (this is not limited to sets, but for non-set cases, <func/val_simple_in_range()/ is called early).
</function>
<function><p><type>struct f_val</type>
<funcdef>interpret</funcdef>
(<type>struct f_inst *</type> <param>what</param>)
<funcsect>Arguments
<p><descrip>
<tagp><type>struct f_inst *</type> <param>what</param></tagp>
    filter to interpret
</descrip>
<funcsect>Description
<p>
   Interpret given tree of filter instructions. This is core function
   of filter system and does all the hard work.
<funcsect>Each instruction has 4 fields
<p>
    code (which is instruction code),
   aux (which is extension to instruction code, typically type),
   arg1 and arg2 - arguments. Depending on instruction, arguments
   are either integers, or pointers to instruction trees. Common 
   instructions like +, that have two expressions as arguments use
   TWOARGS macro to get both of them evaluated.
   <p>
   <struct/f_val/ structures are copied around, so there are no problems with
   memory managment.
</function>
<function><p><type>int</type>
<funcdef>f_run</funcdef>
(<type>struct filter *</type> <param>filter</param>, <type>struct rte **</type> <param>rte</param>, <type>struct ea_list **</type> <param>tmp_attrs</param>, <type>struct linpool *</type> <param>tmp_pool</param>, <type>int</type> <param>flags</param>) --     external entry point to filters

<funcsect>Arguments
<p><descrip>
<tagp><type>struct filter *</type> <param>filter</param></tagp>
    pointer to filter to run
<tagp><type>struct rte **</type> <param>rte</param></tagp>
    pointer to pointer to <struct/rte/ being filtered. When route is modified, this is changed with <func/rte_cow()/.
<tagp><type>struct ea_list **</type> <param>tmp_attrs</param></tagp>
    where to store newly generated temporary attributes
<tagp><type>struct linpool *</type> <param>tmp_pool</param></tagp>
    all filter allocations go from this pool
<tagp><type>int</type> <param>flags</param></tagp>
    flags
</descrip>
</function>
<function><p><type>int</type>
<funcdef>filter_same</funcdef>
(<type>struct filter *</type> <param>new</param>, <type>struct filter *</type> <param>old</param>) --     compare two filters

<funcsect>Arguments
<p><descrip>
<tagp><type>struct filter *</type> <param>new</param></tagp>
    first filter to be compared
<tagp><type>struct filter *</type> <param>old</param></tagp>
    second filter to be compared, notice that this filter is
   damaged while comparing.
</descrip>
<funcsect>Description
<p>
   Returns 1 in case filters are same, otherwise 0. If there are
   underlying bugs, it will rather say 0 on same filters than say
   1 on different.
</function>
<function><p><type>struct f_tree *</type>
<funcdef>find_tree</funcdef>
(<type>struct f_tree *</type> <param>t</param>, <type>struct f_val</type> <param>val</param>)
<funcsect>Arguments
<p><descrip>
<tagp><type>struct f_tree *</type> <param>t</param></tagp>
 tree to search in
<tagp><type>struct f_val</type> <param>val</param></tagp>
 value to find
</descrip>
<funcsect>Description
<p>
Search for given value in the tree. I relies on fact that sorted tree is populated
by <struct/f_val/ structures (that can be compared by <func/val_compare()/). In each node of tree, 
either single value (then t-&gt;from==t-&gt;to) or range is present.
<p>
Both set matching and <tt><func/switch()/ { }</tt> construction is implemented using this function,
thus both are as fast as they can be.
</function>
<function><p><type>struct f_tree *</type>
<funcdef>build_tree</funcdef>
(<type>struct f_tree *</type> <param>from</param>)
<funcsect>Arguments
<p><descrip>
<tagp><type>struct f_tree *</type> <param>from</param></tagp>
 degenerated tree (linked by <param/tree/-&gt;left) to be transformed into form suitable for <func/find_tree()/
</descrip>
<funcsect>Description
<p>
Transforms denerated tree into balanced tree.
</function>
<function><p><type>int</type>
<funcdef>same_tree</funcdef>
(<type>struct f_tree *</type> <param>t1</param>, <type>struct f_tree *</type> <param>t2</param>)
<funcsect>Arguments
<p><descrip>
<tagp><type>struct f_tree *</type> <param>t1</param></tagp>
 first tree to be compared
<tagp><type>struct f_tree *</type> <param>t2</param></tagp>
 second one
</descrip>
<funcsect>Description
<p>
Compares two trees and returns 1 if they are same
</function>
<chapt>Protocols
<sect>Border Gateway Protocol
<p>
   <p>
   The BGP protocol is implemented in three parts: <tt>bgp.c</tt> which takes care of the
   connection and most of the interface with BIRD core, <tt>packets.c</tt> handling
   both incoming and outgoing BGP packets and <tt>attrs.c</tt> containing functions for
   manipulation with BGP attribute lists.
   <p>
   As opposed to the other existing routing daemons, BIRD has a sophisticated core
   architecture which is able to keep all the information needed by BGP in the
   primary routing table, therefore no complex data structures like a central
   BGP table are needed. This increases memory footprint of a BGP router with
   many connections, but not too much and, which is more important, it makes
   BGP much easier to implement.
   <p>
   Each instance of BGP (corresponding to a single BGP peer) is described by a <struct/bgp_proto/
   structure to which are attached individual connections represented by <struct/bgp_connection/
   (usually, there exists only one connection, but during BGP session setup, there
   can be more of them). The connections are handled according to the BGP state machine
   defined in the RFC with all the timers and all the parameters configurable.
   <p>
   In incoming direction, we listen on the connection's socket and each time we receive
   some input, we pass it to <func/bgp_rx()/. It decodes packet headers and the markers and
   passes complete packets to <func/bgp_rx_packet()/ which distributes the packet according
   to its type.
   <p>
   In outgoing direction, we gather all the routing updates and sort them to buckets
   (<struct/bgp_bucket/) according to their attributes (we keep a hash table for fast comparison
   of <struct/rta/'s and a <struct/fib/ which helps us to find if we already have another route for
   the same destination queued for sending, so that we can replace it with the new one
   immediately instead of sending both updates). There also exists a special bucket holding
   all the route withdrawals which cannot be queued anywhere else as they don't have any
   attributes. If we have any packet to send (due to either new routes or the connection
   tracking code wanting to send a Open, Keepalive or Notification message), we call
   <func/bgp_schedule_packet()/ which sets the corresponding bit in a <param/packet_to_send/
   bit field in <struct/bgp_conn/ and as soon as the transmit socket buffer becomes empty,
   we call <func/bgp_fire_tx()/. It inspects state of all the packet type bits and calls
   the corresponding <func/bgp_create_xx()/ functions, eventually rescheduling the same packet
   type if we have more data of the same type to send.
   <p>
   The processing of attributes consists of two functions: <func/bgp_decode_attrs()/ for checking
   of the attribute blocks and translating them to the language of BIRD's extended attributes
   and <func/bgp_encode_attrs()/ which does the converse. Both functions are built around a
   <param/bgp_attr_table/ array describing all important characteristics of all known attributes.
   Unknown transitive attributes are attached to the route as <const/EAF_TYPE_OPAQUE/ byte streams.


<function><p><type>void</type>
<funcdef>bgp_start_timer</funcdef>
(<type>timer *</type> <param>t</param>, <type>int</type> <param>value</param>) --     start a BGP timer

<funcsect>Arguments
<p><descrip>
<tagp><type>timer *</type> <param>t</param></tagp>
    timer
<tagp><type>int</type> <param>value</param></tagp>
    time to fire (0 to disable the timer)
</descrip>
<funcsect>Description
<p>
   This functions calls <func/tm_start()/ on <param/t/ with time <param/value/ and the
   amount of randomization suggested by the BGP standard. Please use
   it for all BGP timers.
</function>
<function><p><type>void</type>
<funcdef>bgp_close_conn</funcdef>
(<type>struct bgp_conn *</type> <param>conn</param>) --     close a BGP connection

<funcsect>Arguments
<p><descrip>
<tagp><type>struct bgp_conn *</type> <param>conn</param></tagp>
    connection to close
</descrip>
<funcsect>Description
<p>
   This function takes a connection described by the <struct/bgp_conn/ structure,
   closes its socket and frees all resources associated with it.
   <p>
   If the connection is being closed due to a protocol error, adjust
   the connection restart timer as well according to the error recovery
   policy set in the configuration.
   <p>
   If the connection was marked as primary, it shuts down the protocol as well.
</function>
<function><p><type>void</type>
<funcdef>bgp_connect</funcdef>
(<type>struct bgp_proto *</type> <param>p</param>) --     initiate an outgoing connection

<funcsect>Arguments
<p><descrip>
<tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
    BGP instance
</descrip>
<funcsect>Description
<p>
   The <func/bgp_connect()/ function creates a new <struct/bgp_conn/ and initiates
   a TCP connection to the peer. The rest of connection setup is governed
   by the BGP state machine as described in the standard.
</function>
<function><p><type>int</type>
<funcdef>bgp_incoming_connection</funcdef>
(<type>sock *</type> <param>sk</param>, <type>int dummy</type> <param>UNUSED</param>) --     handle an incoming connection

<funcsect>Arguments
<p><descrip>
<tagp><type>sock *</type> <param>sk</param></tagp>
    TCP socket
<tagp><type>int dummy</type> <param>UNUSED</param></tagp>
   -- undescribed --
</descrip>
<funcsect>Description
<p>
   This function serves as a socket hook for accepting of new BGP
   connections. It searches a BGP instance corresponding to the peer
   which has connected and if such an instance exists, it creates a
   <struct/bgp_conn/ structure, attaches it to the instance and either sends
   an Open message or (if there already is an active connection) it
   closes the new connection by sending a Notification message.
</function>
<function><p><type>void</type>
<funcdef>bgp_error</funcdef>
(<type>struct bgp_conn *</type> <param>c</param>, <type>unsigned</type> <param>code</param>, <type>unsigned</type> <param>subcode</param>, <type>byte *</type> <param>data</param>, <type>int</type> <param>len</param>) --     report a protocol error

<funcsect>Arguments
<p><descrip>
<tagp><type>struct bgp_conn *</type> <param>c</param></tagp>
    connection
<tagp><type>unsigned</type> <param>code</param></tagp>
    error code (according to the RFC)
<tagp><type>unsigned</type> <param>subcode</param></tagp>
    error sub-code
<tagp><type>byte *</type> <param>data</param></tagp>
    data to be passed in the Notification message
<tagp><type>int</type> <param>len</param></tagp>
    length of the data
</descrip>
<funcsect>Description
<p>
   <func/bgp_error()/ sends a notification packet to tell the other side that a protocol
   error has occurred (including the data considered erroneous if possible) and
   closes the connection.
</function>
<function><p><type>int</type>
<funcdef>bgp_fire_tx</funcdef>
(<type>struct bgp_conn *</type> <param>conn</param>) --  transmit packets

<funcsect>Arguments
<p><descrip>
<tagp><type>struct bgp_conn *</type> <param>conn</param></tagp>
 connection
</descrip>
<funcsect>Description
<p>
Whenever the transmit buffers of the underlying TCP connection
are free and we have any packets queued for sending, the socket functions
call <func/bgp_fire_tx()/ which takes care of selecting the highest priority packet
queued (Notification &gt; Keepalive &gt; Open &gt; Update), assembling its header
and body and sending it to the connection.
</function>
<function><p><type>void</type>
<funcdef>bgp_schedule_packet</funcdef>
(<type>struct bgp_conn *</type> <param>conn</param>, <type>int</type> <param>type</param>) --  schedule a packet for transmission

<funcsect>Arguments
<p><descrip>
<tagp><type>struct bgp_conn *</type> <param>conn</param></tagp>
 connection
<tagp><type>int</type> <param>type</param></tagp>
 packet type
</descrip>
<funcsect>Description
<p>
Schedule a packet of type <param/type/ to be sent as soon as possible.
</function>
<function><p><type>void</type>
<funcdef>bgp_rx_packet</funcdef>
(<type>struct bgp_conn *</type> <param>conn</param>, <type>byte *</type> <param>pkt</param>, <type>unsigned</type> <param>len</param>) --  handle a received packet

<funcsect>Arguments
<p><descrip>
<tagp><type>struct bgp_conn *</type> <param>conn</param></tagp>
 BGP connection
<tagp><type>byte *</type> <param>pkt</param></tagp>
 start of the packet
<tagp><type>unsigned</type> <param>len</param></tagp>
 packet size
</descrip>
<funcsect>Description
<p>
<func/bgp_rx_packet()/ takes a newly received packet and calls the corresponding
packet handler according to the packet type.
</function>
<function><p><type>int</type>
<funcdef>bgp_rx</funcdef>
(<type>sock *</type> <param>sk</param>, <type>int</type> <param>size</param>) --  handle received data

<funcsect>Arguments
<p><descrip>
<tagp><type>sock *</type> <param>sk</param></tagp>
 socket
<tagp><type>int</type> <param>size</param></tagp>
 amount of data received
</descrip>
<funcsect>Description
<p>
<func/bgp_rx()/ is called by the socket layer whenever new data arrive from
the underlying TCP connection. It assembles the data fragments to packets,
checks their headers and framing and passes complete packets to
<func/bgp_rx_packet()/.
</function>
<function><p><type>unsigned int</type>
<funcdef>bgp_encode_attrs</funcdef>
(<type>byte *</type> <param>w</param>, <type>ea_list *</type> <param>attrs</param>, <type>int</type> <param>remains</param>) --  encode BGP attributes

<funcsect>Arguments
<p><descrip>
<tagp><type>byte *</type> <param>w</param></tagp>
 buffer
<tagp><type>ea_list *</type> <param>attrs</param></tagp>
 a list of extended attributes
<tagp><type>int</type> <param>remains</param></tagp>
 remaining space in the buffer
</descrip>
<funcsect>Description
<p>
The <func/bgp_encode_attrs()/ function takes a list of extended attributes
and converts it to its BGP representation (a part of an Update message).
<funcsect>Result
<p>
 Length of the attribute block generated.
</function>
<function><p><type>struct rta *</type>
<funcdef>bgp_decode_attrs</funcdef>
(<type>struct bgp_conn *</type> <param>conn</param>, <type>byte *</type> <param>attr</param>, <type>unsigned int</type> <param>len</param>, <type>struct linpool *</type> <param>pool</param>, <type>int</type> <param>mandatory</param>) --  check and decode BGP attributes

<funcsect>Arguments
<p><descrip>
<tagp><type>struct bgp_conn *</type> <param>conn</param></tagp>
 connection
<tagp><type>byte *</type> <param>attr</param></tagp>
 start of attribute block
<tagp><type>unsigned int</type> <param>len</param></tagp>
 length of attribute block
<tagp><type>struct linpool *</type> <param>pool</param></tagp>
 linear pool to make all the allocations in
<tagp><type>int</type> <param>mandatory</param></tagp>
 1 iff presence of mandatory attributes has to be checked
</descrip>
<funcsect>Description
<p>
This function takes a BGP attribute block (a part of an Update message), checks
its consistency and converts it to a list of BIRD route attributes represented
by a <struct/rta/.
</function>
<sect>Open Shortest Path First (OSPF)
<p>
   <p>
   The OSPF protocol is quite complicated and its complex implemenation is
   split to many files. In <tt>ospf.c</tt>, you will find mainly the interface
   for communication with the core (e.g., reconfiguration hooks, shutdown
   and initialisation and so on). In <tt>packet.c</tt>, you will find various
   functions for sending and receiving generic OSPF packets. There are
   also routines for authentication and checksumming. File <tt>iface.c</tt> contains
   the interface state machine and functions for allocation and deallocation of OSPF's
   interface data structures. Source <tt>neighbor.c</tt> includes the neighbor state
   machine and functions for election of Designated Router and Backup
   Designated router. In <tt>hello.c</tt>, there are routines for sending
   and receiving of hello packets as well as functions for maintaining
   wait times and the inactivity timer. Files <tt>lsreq.c</tt>, <tt>lsack.c</tt>, <tt>dbdes.c</tt>
   contain functions for sending and receiving of link-state requests,
   link-state acknowledgements and database descriptions respectively.
   In <tt>lsupd.c</tt>, there are functions for sending and receiving
   of link-state updates and also the flooding algorithm. Source <tt>topology.c</tt> is
   a place where routines for searching LSAs in the link-state database,
   adding and deleting them reside, there also are functions for originating
   of various types of LSAs (router LSA, net LSA, external LSA). File <tt>rt.c</tt>
   contains routines for calculating the routing table. <tt>lsalib.c</tt> is a set
   of various functions for working with the LSAs (endianity conversions,
   calculation of checksum etc.).
   <p>
   One instance of the protocol is able to hold LSA databases for
   multiple OSPF areas, to exchange routing information between
   multiple neighbors and to calculate the routing tables. The core
   structure is <struct/proto_ospf/ to which multiple <struct/ospf_area/ and
   <struct/ospf_iface/ structures are connected. <struct/ospf_area/ is also connected to
   <struct/top_hash_graph/ which is a dynamic hashing structure that
   describes the link-state database. It allows fast search, addition
   and deletion. Each LSA is kept in two pieces: header and body. Both of them are
   kept in the endianity of the CPU.
   <p>
   The heart beat of ospf is <func/ospf_disp()/. It is called at regular intervals
   (<struct/proto_ospf/-&gt;tick). It is responsible for aging and flushing of LSAs in
   the database, for routing table calculaction and it call <func/area_disp()/ of every
   ospf_area.
   <p>
   The function <func/area_disp()/ is
   responsible for late originating of router LSA and network LSA
   and for cleanup after routing table calculation process in
   the area.
   To every <struct/ospf_iface/, we connect one or more
   <struct/ospf_neighbor/'s -- a structure containing many timers and queues
   for building adjacency and for exchange of routing messages.
   <p>
   BIRD's OSPF implementation respects RFC2328 in every detail, but
   some of internal algorithms do differ. The RFC recommends making a snapshot
   of the link-state database when a new adjacency is forming and sending
   the database description packets based on the information in this 
   snapshot. The database can be quite large in some networks, so
   rather we walk through a <struct/slist/ structure which allows us to
   continue even if the actual LSA we were working with is deleted. New
   LSAs are added at the tail of this <struct/slist/.
   <p>
   We also don't keep a separate OSPF routing table, because the core
   helps us by being able to recognize when a route is updated
   to an identical one and it suppresses the update automatically.
   Due to this, we can flush all the routes we've recalculated and
   also those we've deleted to the core's routing table and the
   core will take care of the rest. This simplifies the process
   and conserves memory.


<function><p><type>void</type>
<funcdef>area_disp</funcdef>
(<type>struct ospf_area *</type> <param>oa</param>) --     invokes origination of

<funcsect>Arguments
<p><descrip>
<tagp><type>struct ospf_area *</type> <param>oa</param></tagp>
    ospf area
</descrip>
<funcsect>Open Shortest Path First (OSPF)
<p>
   router LSA and routing table cleanup
<funcsect>Description
<p>
   It invokes aging and when <param/ospf_area/-&gt;origrt is set to 1, start
   function for origination of router LSA and network LSAs.
</function>
<function><p><type>void</type>
<funcdef>ospf_disp</funcdef>
(<type>timer *</type> <param>timer</param>) --     invokes routing table calctulation, aging and also <func/area_disp()/

<funcsect>Arguments
<p><descrip>
<tagp><type>timer *</type> <param>timer</param></tagp>
    timer usually called every <param/proto_ospf/-&gt;tick second, <param/timer/-&gt;data
   point to <param/proto_ospf/
</descrip>
</function>
<function><p><type>int</type>
<funcdef>ospf_import_control</funcdef>
(<type>struct proto *</type> <param>p</param>, <type>rte **</type> <param>new</param>, <type>ea_list **</type> <param>attrs</param>, <type>struct linpool *</type> <param>pool</param>) --     accept or reject new route from nest's routing table

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
    current instance of protocol
<tagp><type>rte **</type> <param>new</param></tagp>
    the new route
<tagp><type>ea_list **</type> <param>attrs</param></tagp>
    list of attributes
<tagp><type>struct linpool *</type> <param>pool</param></tagp>
    pool for allocation of attributes
</descrip>
<funcsect>Description
<p>
   Its quite simple. It does not accept our own routes and leaves the decision on
   import to the filters.
</function>
<function><p><type>int</type>
<funcdef>ospf_shutdown</funcdef>
(<type>struct proto *</type> <param>p</param>) --     Finish of OSPF instance

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
    current instance of protocol
</descrip>
<funcsect>Description
<p>
   RFC does not define any action that should be taken before router
   shutdown. To make my neighbors react as fast as possible, I send
   them hello packet with empty neighbor list. They should start
   their neighbor state machine with event <const/NEIGHBOR_1WAY/.
</function>
<function><p><type>int</type>
<funcdef>ospf_reconfigure</funcdef>
(<type>struct proto *</type> <param>p</param>, <type>struct proto_config *</type> <param>c</param>) --     reconfiguration hook

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
    current instance of protocol (with old configuration)
<tagp><type>struct proto_config *</type> <param>c</param></tagp>
    new configuration requested by user
</descrip>
<funcsect>Description
<p>
   This hook tries to be a little bit intelligent. Instance of OSPF
   will survive change of many constants like hello interval,
   password change, addition or deletion of some neighbor on
   nonbroadcast network, cost of interface, etc.
</function>
<function><p><type>void</type>
<funcdef>originate_rt_lsa</funcdef>
(<type>struct ospf_area *</type> <param>oa</param>) --  build new instance of router LSA

<funcsect>Arguments
<p><descrip>
<tagp><type>struct ospf_area *</type> <param>oa</param></tagp>
 ospf_area which is LSA built to
</descrip>
<funcsect>Description
<p>
It builds router LSA walking through all OSPF interfaces in
specified OSPF area. This function is mostly called from
<func/area_disp()/. Builds new LSA, increases sequence number (if old
instance exists) and sets age of LSA to zero.
</function>
<function><p><type>void</type>
<funcdef>originate_net_lsa</funcdef>
(<type>struct ospf_iface *</type> <param>ifa</param>) --  originates of deletes network LSA

<funcsect>Arguments
<p><descrip>
<tagp><type>struct ospf_iface *</type> <param>ifa</param></tagp>
 interface which is LSA originated for
</descrip>
<funcsect>Description
<p>
Interface counts number of adjacent neighbors. If this number is
lower than one or interface is not in state <const/OSPF_IS_DR/ it deletes
and premature ages instance of network LSA for specified interface.
In other case, new instance of network LSA is originated.
</function>
<function><p><type>int</type>
<funcdef>max_ext_lsa</funcdef>
(<type>unsigned</type> <param>pxlen</param>) --  calculate the maximum amount of external networks

<funcsect>Arguments
<p><descrip>
<tagp><type>unsigned</type> <param>pxlen</param></tagp>
 network prefix length
</descrip>
<funcsect>Description
<p>
This is a fix for the previous static use of MAXNETS which did
only work correct if MAXNETS &lt; possible IPs for given prefix.
This solution is kind of a hack as there can now only be one
route for /32 type entries but this is better than the crashes
I did experience whith close together /32 routes originating
on different hosts.
<funcsect>Description
<p>
This is a fix for the previous static use of MAXNETS which did
only work correct if MAXNETS &lt; possible IPs for given prefix.
This solution is kind of a hack as there can now only be one
route for /32 type entries but this is better than the crashes
I did experience whith close together /32 routes originating
on different hosts.
</function>
<function><p><type>void</type>
<funcdef>originate_ext_lsa</funcdef>
(<type>net *</type> <param>n</param>, <type>rte *</type> <param>e</param>, <type>struct proto_ospf *</type> <param>po</param>, <type>struct ea_list *</type> <param>attrs</param>) --  new route received from nest and filters

<funcsect>Arguments
<p><descrip>
<tagp><type>net *</type> <param>n</param></tagp>
 network prefix and mask
<tagp><type>rte *</type> <param>e</param></tagp>
 rte
<tagp><type>struct proto_ospf *</type> <param>po</param></tagp>
 current instance of OSPF
<tagp><type>struct ea_list *</type> <param>attrs</param></tagp>
 list of extended attributes
</descrip>
<funcsect>Description
<p>
If I receive a message that new route is installed, I try to originate an
external LSA. The LSA header of such LSA does not contain information about
prefix length, so if I have to originate multiple LSAs for route with
different prefixes I try to increment prefix id to find a "free" one.
<p>
The function also sets flag ebit. If it's the first time, the new router lsa
origination is necessary.
</function>
<function><p><type>struct top_graph *</type>
<funcdef>ospf_top_new</funcdef>
(<type>pool *</type> <param>pool</param>) --  allocated new topology database

<funcsect>Arguments
<p><descrip>
<tagp><type>pool *</type> <param>pool</param></tagp>
-- undescribed --
</descrip>
<funcsect>Description
<p>
This dynamically hashed structure is often used for keeping LSAs. Mainly
its used in <param/ospf_area/ structure.
</function>
<function><p><type>void</type>
<funcdef>neigh_chstate</funcdef>
(<type>struct ospf_neighbor *</type> <param>n</param>, <type>u8</type> <param>state</param>) --  handles changes related to new or lod state of neighbor

<funcsect>Arguments
<p><descrip>
<tagp><type>struct ospf_neighbor *</type> <param>n</param></tagp>
 OSPF neighbor
<tagp><type>u8</type> <param>state</param></tagp>
 new state
</descrip>
<funcsect>Description
<p>
Many actions have to be taken acording to a change of state of a neighbor. It
starts rxmt timers, call interface state machine etc.
</function>
<function><p><type>void</type>
<funcdef>ospf_neigh_sm</funcdef>
(<type>struct ospf_neighbor *</type> <param>n</param>, <type>int</type> <param>event</param>) --  ospf neighbor state machine

<funcsect>Arguments
<p><descrip>
<tagp><type>struct ospf_neighbor *</type> <param>n</param></tagp>
 neighor
<tagp><type>int</type> <param>event</param></tagp>
 actual event
</descrip>
<funcsect>Description
<p>
This part implements the neighbor state machine as described in 10.3 of
RFC 2328. The only difference is that state <const/NEIGHBOR_ATTEMPT/ is not
used. We discover neighbors on nonbroadcast networks in the
same way as on broadcast networks. The only difference is in
sending hello packets. These are sent to IPs listed in
<param/ospf_iface/-&gt;nbma_list .
</function>
<function><p><type>void</type>
<funcdef>bdr_election</funcdef>
(<type>struct ospf_iface *</type> <param>ifa</param>) --  (Backup) Designed Router election

<funcsect>Arguments
<p><descrip>
<tagp><type>struct ospf_iface *</type> <param>ifa</param></tagp>
 actual interface
</descrip>
<funcsect>Description
<p>
When the wait timer fires, it is time to elect (Backup) Designated Router.
Structure describing me is added to this list so every electing router
has the same list. Backup Designated Router is elected before Designated
Router. This process is described in 9.4 of RFC 2328.
</function>
<function><p><type>void</type>
<funcdef>ospf_iface_chstate</funcdef>
(<type>struct ospf_iface *</type> <param>ifa</param>, <type>u8</type> <param>state</param>) --  handle changes of interface state

<funcsect>Arguments
<p><descrip>
<tagp><type>struct ospf_iface *</type> <param>ifa</param></tagp>
 OSPF interface
<tagp><type>u8</type> <param>state</param></tagp>
 new state
</descrip>
<funcsect>Description
<p>
Many actions must be taken according to interface state changes. New network
LSAs must be originated, flushed, new multicast sockets to listen for messages for
<const/ALLDROUTERS/ have to be opened, etc.
</function>
<function><p><type>void</type>
<funcdef>ospf_iface_sm</funcdef>
(<type>struct ospf_iface *</type> <param>ifa</param>, <type>int</type> <param>event</param>) --  OSPF interface state machine

<funcsect>Arguments
<p><descrip>
<tagp><type>struct ospf_iface *</type> <param>ifa</param></tagp>
 OSPF interface
<tagp><type>int</type> <param>event</param></tagp>
 event comming to state machine
</descrip>
<funcsect>Description
<p>
This fully respects 9.3 of RFC 2328 except we don't use <const/LOOP/ state of
interface.
</function>
<function><p><type>int</type>
<funcdef>ospf_rx_hook</funcdef>
(<type>sock *</type> <param>sk</param>, <type>int</type> <param>size</param>)
<funcsect>Arguments
<p><descrip>
<tagp><type>sock *</type> <param>sk</param></tagp>
 socket we received the packet. Its ignored.
<tagp><type>int</type> <param>size</param></tagp>
 size of the packet
</descrip>
<funcsect>Description
<p>
This is the entry point for messages from neighbors. Many checks (like
authentication, checksums, size) are done before the packet is passed to
non generic functions.
</function>
<function><p><type>void</type>
<funcdef>ospf_age</funcdef>
(<type>struct proto_ospf *</type> <param>po</param>)
<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto_ospf *</type> <param>po</param></tagp>
 ospf protocol
</descrip>
<funcsect>Description
<p>
This function is periodicaly invoked from <func/ospf_disp()/. It computes the new
age of all LSAs and old (<param/age/ is higher than <const/LSA_MAXAGE/) LSAs are flushed
whenever possible. If an LSA originated by the router itself is older
than <const/LSREFRESHTIME/ a new instance is originated.
<p>
The RFC says that a router should check the checksum of every LSA to detect
hardware problems. BIRD does not do this to minimalize CPU utilization.
<p>
If routing table calculation is scheduled, it also invalidates the old routing
table calculation results.
</function>
<function><p><type>struct top_hash_entry *</type>
<funcdef>lsa_install_new</funcdef>
(<type>struct ospf_lsa_header *</type> <param>lsa</param>, <type>void *</type> <param>body</param>, <type>struct ospf_area *</type> <param>oa</param>) --  install new LSA into database

<funcsect>Arguments
<p><descrip>
<tagp><type>struct ospf_lsa_header *</type> <param>lsa</param></tagp>
 LSA header
<tagp><type>void *</type> <param>body</param></tagp>
 pointer to LSA body
<tagp><type>struct ospf_area *</type> <param>oa</param></tagp>
 current ospf_area
</descrip>
<funcsect>Description
<p>
This function ensures installing new LSA into LSA database. Old instance is
replaced. Several actions are taken to detect if new routing table
calculation is necessary. This is described in 13.2 of RFC 2328.
</function>
<function><p><type>void</type>
<funcdef>ospf_dbdes_send</funcdef>
(<type>struct ospf_neighbor *</type> <param>n</param>) --  transmit database description packet

<funcsect>Arguments
<p><descrip>
<tagp><type>struct ospf_neighbor *</type> <param>n</param></tagp>
 neighbor
</descrip>
<funcsect>Description
<p>
Sending of a database description packet is described in 10.6 of RFC 2328.
Reception of each packet is acknowledged in the sequence number of another.
When I send a packet to a neighbor I keep a copy in a buffer. If the neighbor
does not reply, I don't create a new packet but just send the content
of the buffer.
</function>
<function><p><type>void</type>
<funcdef>ospf_rt_spf</funcdef>
(<type>struct proto_ospf *</type> <param>po</param>) --  calculate internal routes

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto_ospf *</type> <param>po</param></tagp>
 OSPF protocol
</descrip>
<funcsect>Description
<p>
Calculation of internal paths in an area is described in 16.1 of RFC 2328.
It's based on Dijkstra's shortest path tree algorithms.
This function is invoked from <func/ospf_disp()/.
</function>
<function><p><type>void</type>
<funcdef>ospf_ext_spf</funcdef>
(<type>struct proto_ospf *</type> <param>po</param>) --  calculate external paths

<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto_ospf *</type> <param>po</param></tagp>
 protocol
</descrip>
<funcsect>Description
<p>
After routing table for any area is calculated, calculation of external
path is invoked. This process is described in 16.6 of RFC 2328.
Inter- and Intra-area paths are always prefered over externals.
</function>
<sect>Pipe
<p>
   <p>
   The Pipe protocol is very simple. It just connects to two routing tables
   using <func/proto_add_announce_hook()/ and whenever it receives a <func/rt_notify()/
   about a change in one of the tables, it converts it to a <func/rte_update()/
   in the other one.
   <p>
   To avoid pipe loops, Pipe keeps a `being updated' flag in each routing
   table.


<sect>Routing Information Protocol
<p>
   <p>
   RIP is a pretty simple protocol, so about a half of its code is interface
   with the core.
   <p>
   We maintain our own linked list of <struct/rip_entry/ structures -- it serves
   as our small routing table. RIP never adds to this linked list upon
   packet reception; instead, it lets the core know about data from the packet
   and waits for the core to call <func/rip_rte_notify()/.
   <p>
   Within <func/rip_tx()/, the list is
   walked and a packet is generated using <func/rip_tx_prepare()/. This gets
   tricky because we may need to send more than one packet to one
   destination. Struct <struct/rip_connection/ is used to hold context information such as how
   many of <struct/rip_entry/'s we have already sent and it's also used to protect
   against two concurrent sends to one destination. Each <struct/rip_interface/ has
   at most one <struct/rip_connection/.
   <p>
   We are not going to honor requests for sending part of
   routing table. That would need to turn split horizon off etc.  
   <p>
   About triggered updates, RFC says: when a triggered update was sent,
   don't send a new one for something between 1 and 5 seconds (and send one
   after that). We do something else: each 5 seconds,
   we look for any changed routes and broadcast them.


<function><p><type>void</type>
<funcdef>rip_timer</funcdef>
(<type>timer *</type> <param>t</param>)
<funcsect>Arguments
<p><descrip>
<tagp><type>timer *</type> <param>t</param></tagp>
    timer
</descrip>
<funcsect>Description
<p>
   Broadcast routing tables periodically (using rip_tx) and kill
   routes that are too old. RIP keeps a list of its own entries present
   in the core table by a linked list (functions <func/rip_rte_insert()/ and
   <func/rip_rte_delete()/ are responsible for that), it walks this list in the timer
   and in case an entry is too old, it is discarded.
</function>
<function><p><type>struct rip_interface *</type>
<funcdef>new_iface</funcdef>
(<type>struct proto *</type> <param>p</param>, <type>struct iface *</type> <param>new</param>, <type>unsigned long</type> <param>flags</param>, <type>struct iface_patt *</type> <param>patt</param>)
<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
    myself
<tagp><type>struct iface *</type> <param>new</param></tagp>
    interface to be created or <const/NULL/ if we are creating a magic
   socket. The magic socket is used for listening and also for
   sending requested responses.
<tagp><type>unsigned long</type> <param>flags</param></tagp>
    interface flags
<tagp><type>struct iface_patt *</type> <param>patt</param></tagp>
    pattern this interface matched, used for access to config options
</descrip>
<funcsect>Description
<p>
   Create an interface structure and start listening on the interface.
</function>
<sect>Static
<p>
   <p>
   The Static protocol is implemented in a straightforward way. It keeps
   two lists of static routes: one containing interface routes and one
   holding the remaining ones. Interface routes are inserted and removed according
   to interface events received from the core via the <func/if_notify()/ hook. Routes
   pointing to a neighboring router use a sticky node in the neighbor cache
   to be notified about gaining or losing the neighbor. Special
   routes like black holes or rejects are inserted all the time.
   <p>
   The only other thing worth mentioning is that when asked for reconfiguration,
   Static not only compares the two configurations, but it also calculates
   difference between the lists of static routes and it just inserts the
   newly added routes and removes the obsolete ones.


<sect>Direct
<p>
   <p>
   The Direct protocol works by converting all <func/ifa_notify()/ events it receives
   to <func/rte_update()/ calls for the corresponding network.


<!--
	BIRD Programmer's Guide: Sysdeps

	(c) 2000 Martin Mares <mj@ucw.cz>
-->

<chapt>System dependent parts

<sect>Introduction

<p>We've tried to make BIRD as portable as possible, but unfortunately
communication with the network stack differs from one OS to another,
so we need at least some OS specific code. The good news is that this
code is isolated in a small set of modules:

<descrip>
<tagp><tt/config.h/</tagp> is a header file with configuration information,
definition of the standard set of types and so on.
<tagp/Startup module/ controls BIRD startup. Common for a family of OS's (e.g.,
for all Unices).
<tagp/Logging module/ manages the system logs. [per OS family]
<tagp/IO module/ gives an implementation of sockets, timers and the
global event queue. [per OS family]
<tagp/KRT module/ implements the Kernel and Device protocols. This
is the most arcane part of the system dependent stuff and some
functions differ even between various releases of a single OS.
</descrip>
<sect>Logging
<p>
   <p>
   The Logging module offers a simple set of functions for writing
   messages to system logs and to the debug output. Message classes
   used by this module are described in <tt>birdlib.h</tt> and also in the
   user's manual.


<function><p><type>void</type>
<funcdef>log_msg</funcdef>
(<type>char *</type> <param>msg</param>, <type>...</type> <param>...</param>) --     log a message

<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>msg</param></tagp>
    printf-like formatting string with message class information
   prepended (<const/L_DEBUG/ to <const/L_BUG/, see <tt>lib/birdlib.h</tt>)
<tagp><type>...</type> <param>...</param></tagp>
   variable arguments
</descrip>
<funcsect>Description
<p>
   This function formats a message according to the format string <param/msg/
   and writes it to the corresponding log file (as specified in the
   configuration). Please note that the message is automatically
   formatted as a full line, no need to include <tt>\n</tt> inside.
</function>
<function><p><type>void</type>
<funcdef>bug</funcdef>
(<type>char *</type> <param>msg</param>, <type>...</type> <param>...</param>) --     report an internal error

<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>msg</param></tagp>
    a printf-like error message
<tagp><type>...</type> <param>...</param></tagp>
   variable arguments
</descrip>
<funcsect>Description
<p>
   This function logs an internal error and aborts execution
   of the program.
</function>
<function><p><type>void</type>
<funcdef>die</funcdef>
(<type>char *</type> <param>msg</param>, <type>...</type> <param>...</param>) --     report a fatal error

<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>msg</param></tagp>
    a printf-like error message
<tagp><type>...</type> <param>...</param></tagp>
   variable arguments
</descrip>
<funcsect>Description
<p>
   This function logs a fatal error and aborts execution
   of the program.
</function>
<function><p><type>void</type>
<funcdef>debug</funcdef>
(<type>char *</type> <param>msg</param>, <type>...</type> <param>...</param>) --     write to debug output

<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>msg</param></tagp>
    a printf-like message
<tagp><type>...</type> <param>...</param></tagp>
   variable arguments
</descrip>
<funcsect>Description
<p>
   This function formats the message <param/msg/ and prints it out
   to the debugging output. No newline character is appended.
</function>
<sect>Kernel synchronization
<p>
   <p>
   This system dependent module implements the Kernel and Device protocol,
   that is synchronization of interface lists and routing tables with the
   OS kernel.
   <p>
   The whole kernel synchronization is a bit messy and touches some internals
   of the routing table engine, because routing table maintenance is a typical
   example of the proverbial compatibility between different Unices and we want
   to keep the overhead of our KRT business as low as possible and avoid maintaining
   a local routing table copy.
   <p>
   The kernel syncer can work in three different modes (according to system config header):
   Either with a single routing table and single KRT protocol [traditional UNIX]
   or with many routing tables and separate KRT protocols for all of them
   or with many routing tables, but every scan including all tables, so we start
   separate KRT protocols which cooperate with each other  [Linux 2.2].
   In this case, we keep only a single scan timer.
   <p>
   We use FIB node flags in the routing table to keep track of route
   synchronization status. We also attach temporary <struct/rte/'s to the routing table,
   but it cannot do any harm to the rest of BIRD since table synchronization is
   an atomic process.
   <p>
   When starting up, we cheat by looking if there is another
   KRT instance to be initialized later and performing table scan
   only once for all the instances.


<chapt>Library functions
<sect>IP addresses
<p>
   <p>
   BIRD uses its own abstraction of IP address in order to share the same
   code for both IPv4 and IPv6. IP addresses are represented as entities
   of type <struct/ip_addr/ which are never to be treated as numbers and instead
   they must be manipulated using the following functions and macros.


<function><p><type>char *</type>
<funcdef>ip_scope_text</funcdef>
(<type>unsigned</type> <param>scope</param>) --     get textual representation of address scope

<funcsect>Arguments
<p><descrip>
<tagp><type>unsigned</type> <param>scope</param></tagp>
    scope (<const/SCOPE_xxx/)
</descrip>
<funcsect>Description
<p>
   Returns a pointer to a textual name of the scope given.
</function>
<function><p><type>int</type>
<funcdef>ipa_equal</funcdef>
(<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) --     compare two IP addresses for equality

<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
    IP address
<tagp><type>ip_addr</type> <param>y</param></tagp>
    IP address
</descrip>
<funcsect>Description
<p>
   <func/ipa_equal()/ returns 1 if <param/x/ and <param/y/ represent the same IP address, else 0.
</function>
<function><p><type>int</type>
<funcdef>ipa_nonzero</funcdef>
(<type>ip_addr</type> <param>x</param>) --     test if an IP address is defined

<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
    IP address
</descrip>
<funcsect>Description
<p>
   ipa_nonzero returns 1 if <param/x/ is a defined IP address (not all bits are zero),
   else 0.
   <p>
   The undefined all-zero address is reachable as a <tt>IPA_NONE</tt> macro.
</function>
<function><p><type>ip_addr</type>
<funcdef>ipa_and</funcdef>
(<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) --     compute bitwise and of two IP addresses

<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
    IP address
<tagp><type>ip_addr</type> <param>y</param></tagp>
    IP address
</descrip>
<funcsect>Description
<p>
   This function returns a bitwise and of <param/x/ and <param/y/. It's primarily
   used for network masking.
</function>
<function><p><type>ip_addr</type>
<funcdef>ipa_or</funcdef>
(<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) --     compute bitwise or of two IP addresses

<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
    IP address
<tagp><type>ip_addr</type> <param>y</param></tagp>
    IP address
</descrip>
<funcsect>Description
<p>
   This function returns a bitwise or of <param/x/ and <param/y/.
</function>
<function><p><type>ip_addr</type>
<funcdef>ipa_xor</funcdef>
(<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) --     compute bitwise xor of two IP addresses

<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
    IP address
<tagp><type>ip_addr</type> <param>y</param></tagp>
    IP address
</descrip>
<funcsect>Description
<p>
   This function returns a bitwise xor of <param/x/ and <param/y/.
</function>
<function><p><type>ip_addr</type>
<funcdef>ipa_not</funcdef>
(<type>ip_addr</type> <param>x</param>) --     compute bitwise negation of two IP addresses

<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
    IP address
</descrip>
<funcsect>Description
<p>
   This function returns a bitwise negation of <param/x/.
</function>
<function><p><type>ip_addr</type>
<funcdef>ipa_mkmask</funcdef>
(<type>int</type> <param>x</param>) --     create a netmask

<funcsect>Arguments
<p><descrip>
<tagp><type>int</type> <param>x</param></tagp>
    prefix length
</descrip>
<funcsect>Description
<p>
   This function returns an <struct/ip_addr/ corresponding of a netmask
   of an address prefix of size <param/x/.
</function>
<function><p><type>int</type>
<funcdef>ipa_mklen</funcdef>
(<type>ip_addr</type> <param>x</param>) --     calculate netmask length

<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
    IP address
</descrip>
<funcsect>Description
<p>
   This function checks whether <param/x/ represents a valid netmask and
   returns the size of the associate network prefix or -1 for invalid
   mask.
</function>
<function><p><type>int</type>
<funcdef>ipa_hash</funcdef>
(<type>ip_addr</type> <param>x</param>) --     hash IP addresses

<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
    IP address
</descrip>
<funcsect>Description
<p>
   <func/ipa_hash()/ returns a 16-bit hash value of the IP address <param/x/.
</function>
<function><p><type>void</type>
<funcdef>ipa_hton</funcdef>
(<type>ip_addr</type> <param>x</param>) --     convert IP address to network order

<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
    IP address
</descrip>
<funcsect>Description
<p>
   Converts the IP address <param/x/ to the network byte order.
   <p>
   Beware, this is a macro and it alters the argument!
</function>
<function><p><type>void</type>
<funcdef>ipa_ntoh</funcdef>
(<type>ip_addr</type> <param>x</param>) --     convert IP address to host order

<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
    IP address
</descrip>
<funcsect>Description
<p>
   Converts the IP address <param/x/ from the network byte order.
   <p>
   Beware, this is a macro and it alters the argument!
</function>
<function><p><type>int</type>
<funcdef>ipa_classify</funcdef>
(<type>ip_addr</type> <param>x</param>) --     classify an IP address

<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
    IP address
</descrip>
<funcsect>Description
<p>
   <func/ipa_classify()/ returns an address class of <param/x/, that is a bitwise or
   of address type (<const/IADDR_INVALID/, <const/IADDR_HOST/, <const/IADDR_BROADCAST/, <const/IADDR_MULTICAST/)
   with address scope (<const/SCOPE_HOST/ to <const/SCOPE_UNIVERSE/) or -1 (<const/IADDR_INVALID/)
   for an invalid address.
</function>
<function><p><type>ip_addr</type>
<funcdef>ipa_opposite</funcdef>
(<type>ip_addr</type> <param>x</param>) --     return address of point-to-point neighbor

<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
    IP address of our end of the link
</descrip>
<funcsect>Description
<p>
   <func/ipa_opposite()/ returns an address of the opposite end of a numbered
   point-to-point link.
   <p>
   This function is available in IPv4 version only.
</function>
<function><p><type>ip_addr</type>
<funcdef>ipa_classify</funcdef>
(<type>ip_addr</type> <param>x</param>) --     guess netmask according to address class

<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
    IP address
</descrip>
<funcsect>Description
<p>
   This function (available in IPv4 version only) returns a
   network mask according to the address class of <param/x/. Although
   classful addressing is nowadays obsolete, there still live
   routing protocols transferring no prefix lengths nor netmasks
   and this function could be useful to them.
</function>
<function><p><type>u32</type>
<funcdef>ipa_from_u32</funcdef>
(<type>ip_addr</type> <param>x</param>) --     convert IPv4 address to an integer

<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
    IP address
</descrip>
<funcsect>Description
<p>
   This function takes an IPv4 address and returns its numeric
   representation.
</function>
<function><p><type>ip_addr</type>
<funcdef>ipa_to_u32</funcdef>
(<type>u32</type> <param>x</param>) --     convert integer to IPv4 address

<funcsect>Arguments
<p><descrip>
<tagp><type>u32</type> <param>x</param></tagp>
    a 32-bit integer
</descrip>
<funcsect>Description
<p>
   <func/ipa_to_u32()/ takes a numeric representation of an IPv4 address
   and converts it to the corresponding <struct/ip_addr/.
</function>
<function><p><type>int</type>
<funcdef>ipa_compare</funcdef>
(<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) --     compare two IP addresses for order

<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
    IP address
<tagp><type>ip_addr</type> <param>y</param></tagp>
    IP address
</descrip>
<funcsect>Description
<p>
   The <func/ipa_compare()/ function takes two IP addresses and returns
   -1 if <param/x/ is less than <param/y/ in canonical ordering (lexicographical
   order of the bit strings), 1 if <param/x/ is greater than <param/y/ and 0
   if they are the same.
</function>
<function><p><type>ip_addr</type>
<funcdef>ipa_build</funcdef>
(<type>u32</type> <param>a1</param>, <type>u32</type> <param>a2</param>, <type>u32</type> <param>a3</param>, <type>u32</type> <param>a4</param>) --     build an IPv6 address from parts

<funcsect>Arguments
<p><descrip>
<tagp><type>u32</type> <param>a1</param></tagp>
    part #1
<tagp><type>u32</type> <param>a2</param></tagp>
    part #2
<tagp><type>u32</type> <param>a3</param></tagp>
    part #3
<tagp><type>u32</type> <param>a4</param></tagp>
    part #4
</descrip>
<funcsect>Description
<p>
   <func/ipa_build()/ takes <param/a1/ to <param/a4/ and assembles them to a single IPv6
   address. It's used for example when a protocol wants to bind its
   socket to a hard-wired multicast address.
</function>
<function><p><type>ip_addr</type>
<funcdef>ipa_absolutize</funcdef>
(<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) --     convert link scope IPv6 address to universe scope

<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
    link scope IPv6 address
<tagp><type>ip_addr</type> <param>y</param></tagp>
    universe scope IPv6 prefix of the interface
</descrip>
<funcsect>Description
<p>
   This function combines a link-scope IPv6 address <param/x/ with the universe
   scope prefix <param/x/ of the network assigned to an interface to get a
   universe scope form of <param/x/.
</function>
<function><p><type>char *</type>
<funcdef>ip_ntop</funcdef>
(<type>ip_addr</type> <param>a</param>, <type>char *</type> <param>buf</param>) --     convert IP address to textual representation

<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>a</param></tagp>
    IP address
<tagp><type>char *</type> <param>buf</param></tagp>
    buffer of size at least <const/STD_ADDRESS_P_LENGTH/
</descrip>
<funcsect>Description
<p>
   This function takes an IP address and creates its textual
   representation for presenting to the user.
</function>
<function><p><type>char *</type>
<funcdef>ip_ntox</funcdef>
(<type>ip_addr</type> <param>a</param>, <type>char *</type> <param>buf</param>) --     convert IP address to hexadecimal representation

<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>a</param></tagp>
    IP address
<tagp><type>char *</type> <param>buf</param></tagp>
    buffer of size at least <const/STD_ADDRESS_P_LENGTH/
</descrip>
<funcsect>Description
<p>
   This function takes an IP address and creates its hexadecimal
   textual representation. Primary use: debugging dumps.
</function>
<function><p><type>int</type>
<funcdef>ip_pton</funcdef>
(<type>char *</type> <param>a</param>, <type>ip_addr *</type> <param>o</param>) --     parse textual representation of IP address

<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>a</param></tagp>
    textual representation
<tagp><type>ip_addr *</type> <param>o</param></tagp>
    where to put the resulting address
</descrip>
<funcsect>Description
<p>
   This function parses a textual IP address representation and
   stores the decoded address to a variable pointed to by <param/o/.
   Returns 0 if a parse error has occurred, else 0.
</function>
<sect>Linked lists
<p>
   <p>
   The BIRD library provides a set of functions for operating on linked
   lists. The lists are internally represented as standard doubly linked
   lists with synthetic head and tail which makes all the basic operations
   run in constant time and contain no extra end-of-list checks. Each list
   is described by a <struct/list/ structure, nodes can have any format as long
   as they start with a <struct/node/ structure. If you want your nodes to belong
   to multiple lists at once, you can embed multiple <struct/node/ structures in them
   and use the <func/SKIP_BACK()/ macro to calculate a pointer to the start of the
   structure from a <struct/node/ pointer, but beware of obscurity.
   <p>
   There also exist safe linked lists (<struct/slist/, <struct/snode/ and all functions
   being prefixed with <tt>s_</tt>) which support asynchronous walking very
   similar to that used in the <struct/fib/ structure.


<function><p><type>LIST_INLINE void</type>
<funcdef>add_tail</funcdef>
(<type>list *</type> <param>l</param>, <type>node *</type> <param>n</param>) --     append a node to a list

<funcsect>Arguments
<p><descrip>
<tagp><type>list *</type> <param>l</param></tagp>
    linked list
<tagp><type>node *</type> <param>n</param></tagp>
    list node
</descrip>
<funcsect>Description
<p>
   <func/add_tail()/ takes a node <param/n/ and appends it at the end of the list <param/l/.
</function>
<function><p><type>LIST_INLINE void</type>
<funcdef>add_head</funcdef>
(<type>list *</type> <param>l</param>, <type>node *</type> <param>n</param>) --     prepend a node to a list

<funcsect>Arguments
<p><descrip>
<tagp><type>list *</type> <param>l</param></tagp>
    linked list
<tagp><type>node *</type> <param>n</param></tagp>
    list node
</descrip>
<funcsect>Description
<p>
   <func/add_head()/ takes a node <param/n/ and prepends it at the start of the list <param/l/.
</function>
<function><p><type>LIST_INLINE void</type>
<funcdef>insert_node</funcdef>
(<type>node *</type> <param>n</param>, <type>node *</type> <param>after</param>) --     insert a node to a list

<funcsect>Arguments
<p><descrip>
<tagp><type>node *</type> <param>n</param></tagp>
    a new list node
<tagp><type>node *</type> <param>after</param></tagp>
    a node of a list
</descrip>
<funcsect>Description
<p>
   Inserts a node <param/n/ to a linked list after an already inserted
   node <param/after/.
</function>
<function><p><type>LIST_INLINE void</type>
<funcdef>rem_node</funcdef>
(<type>node *</type> <param>n</param>) --     remove a node from a list

<funcsect>Arguments
<p><descrip>
<tagp><type>node *</type> <param>n</param></tagp>
    node to be removed
</descrip>
<funcsect>Description
<p>
   Removes a node <param/n/ from the list it's linked in.
</function>
<function><p><type>LIST_INLINE void</type>
<funcdef>init_list</funcdef>
(<type>list *</type> <param>l</param>) --     create an empty list

<funcsect>Arguments
<p><descrip>
<tagp><type>list *</type> <param>l</param></tagp>
    list
</descrip>
<funcsect>Description
<p>
   <func/init_list()/ takes a <struct/list/ structure and initializes its
   fields, so that it represents an empty list.
</function>
<function><p><type>LIST_INLINE void</type>
<funcdef>add_tail_list</funcdef>
(<type>list *</type> <param>to</param>, <type>list *</type> <param>l</param>) --     concatenate two lists

<funcsect>Arguments
<p><descrip>
<tagp><type>list *</type> <param>to</param></tagp>
    destination list
<tagp><type>list *</type> <param>l</param></tagp>
    source list
</descrip>
<funcsect>Description
<p>
   This function appends all elements of the list <param/l/ to
   the list <param/to/ in constant time.
</function>
<sect>Miscellaneous functions.
<p>


<function><p><type>int</type>
<funcdef>ipsum_verify</funcdef>
(<type>void *</type> <param>frag</param>, <type>unsigned</type> <param>len</param>, <type>...</type> <param>...</param>) --     verify an IP checksum

<funcsect>Arguments
<p><descrip>
<tagp><type>void *</type> <param>frag</param></tagp>
    first packet fragment
<tagp><type>unsigned</type> <param>len</param></tagp>
    length in bytes
<tagp><type>...</type> <param>...</param></tagp>
   variable arguments
</descrip>
<funcsect>Description
<p>
   This function verifies whether a given fragmented packet
   has correct one's complement checksum as used by the IP
   protocol.
   <p>
   It uses all the clever tricks described in RFC 1071 to speed
   up checksum calculation as much as possible.
<funcsect>Result
<p>
    1 if the checksum is correct, 0 else.
</function>
<function><p><type>u16</type>
<funcdef>ipsum_calculate</funcdef>
(<type>void *</type> <param>frag</param>, <type>unsigned</type> <param>len</param>, <type>...</type> <param>...</param>) --     compute an IP checksum

<funcsect>Arguments
<p><descrip>
<tagp><type>void *</type> <param>frag</param></tagp>
    first packet fragment
<tagp><type>unsigned</type> <param>len</param></tagp>
    length in bytes
<tagp><type>...</type> <param>...</param></tagp>
   variable arguments
</descrip>
<funcsect>Description
<p>
   This function calculates a one's complement checksum of a given fragmented
   packet.
   <p>
   It uses all the clever tricks described in RFC 1071 to speed
   up checksum calculation as much as possible.
</function>
<function><p><type>u32</type>
<funcdef>u32_mkmask</funcdef>
(<type>unsigned</type> <param>n</param>) --     create a bit mask

<funcsect>Arguments
<p><descrip>
<tagp><type>unsigned</type> <param>n</param></tagp>
    number of bits
</descrip>
<funcsect>Description
<p>
   <func/u32_mkmask()/ returns an unsigned 32-bit integer which binary
   representation consists of <param/n/ ones followed by zeroes.
</function>
<function><p><type>int</type>
<funcdef>u32_masklen</funcdef>
(<type>u32</type> <param>x</param>) --     calculate length of a bit mask

<funcsect>Arguments
<p><descrip>
<tagp><type>u32</type> <param>x</param></tagp>
    bit mask
</descrip>
<funcsect>Description
<p>
   This function checks whether the given integer <param/x/ represents
   a valid bit mask (binary representation contains first ones, then
   zeroes) and returns the number of ones or -1 if the mask is invalid.
</function>
<function><p><type>int</type>
<funcdef>patmatch</funcdef>
(<type>byte *</type> <param>p</param>, <type>byte *</type> <param>s</param>) --     match shell-like patterns

<funcsect>Arguments
<p><descrip>
<tagp><type>byte *</type> <param>p</param></tagp>
    pattern
<tagp><type>byte *</type> <param>s</param></tagp>
    string
</descrip>
<funcsect>Description
<p>
   <func/patmatch()/ returns whether given string <param/s/ matches the given shell-like
   pattern <param/p/. The patterns consist of characters (which are matched literally),
   question marks which match any single character, asterisks which match any
   (possibly empty) string of characters and backslashes which are used to
   escape any special characters and force them to be treated literally.
   <p>
   The matching process is not optimized with respect to time, so please
   avoid using this function for complex patterns.
</function>
<function><p><type>int</type>
<funcdef>bvsnprintf</funcdef>
(<type>char *</type> <param>buf</param>, <type>int</type> <param>size</param>, <type>const char *</type> <param>fmt</param>, <type>va_list</type> <param>args</param>) --     BIRD's <func/vsnprintf()/

<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>buf</param></tagp>
    destination buffer
<tagp><type>int</type> <param>size</param></tagp>
    size of the buffer
<tagp><type>const char *</type> <param>fmt</param></tagp>
    format string
<tagp><type>va_list</type> <param>args</param></tagp>
    a list of arguments to be formatted
</descrip>
<funcsect>Description
<p>
   This functions acts like ordinary <func/sprintf()/ except that it checks
   available space to avoid buffer overflows and it allows some more
<funcsect>format specifiers
<p>
    <tt><const/I/</tt> for formatting of IP addresses (any non-zero
   width is automatically replaced by standard IP address width which
   depends on whether we use IPv4 or IPv6; <tt>%#I</tt> gives hexadecimal format)
   and <tt><const/m/</tt> resp. <tt><const/M/</tt> for error messages (uses <func/strerror()/ to translate <param/errno/ code to
   message text). On the other hand, it doesn't support floating
   point numbers.
<funcsect>Result
<p>
    number of characters of the output string or -1 if
   the buffer space was insufficient.
</function>
<function><p><type>int</type>
<funcdef>bvsprintf</funcdef>
(<type>char *</type> <param>buf</param>, <type>const char *</type> <param>fmt</param>, <type>va_list</type> <param>args</param>) --     BIRD's <func/vsprintf()/

<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>buf</param></tagp>
    buffer
<tagp><type>const char *</type> <param>fmt</param></tagp>
    format string
<tagp><type>va_list</type> <param>args</param></tagp>
    a list of arguments to be formatted
</descrip>
<funcsect>Description
<p>
   This function is equivalent to <func/bvsnprintf()/ with an infinite
   buffer size. Please use carefully only when you are absolutely
   sure the buffer won't overflow.
</function>
<function><p><type>int</type>
<funcdef>bsprintf</funcdef>
(<type>char *</type> <param>buf</param>, <type>const char *</type> <param>fmt</param>, <type>...</type> <param>...</param>) --     BIRD's <func/sprintf()/

<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>buf</param></tagp>
    buffer
<tagp><type>const char *</type> <param>fmt</param></tagp>
    format string
<tagp><type>...</type> <param>...</param></tagp>
   variable arguments
</descrip>
<funcsect>Description
<p>
   This function is equivalent to <func/bvsnprintf()/ with an infinite
   buffer size and variable arguments instead of a <struct/va_list/.
   Please use carefully only when you are absolutely
   sure the buffer won't overflow.
</function>
<function><p><type>int</type>
<funcdef>bsnprintf</funcdef>
(<type>char *</type> <param>buf</param>, <type>int</type> <param>size</param>, <type>const char *</type> <param>fmt</param>, <type>...</type> <param>...</param>) --     BIRD's <func/snprintf()/

<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>buf</param></tagp>
    buffer
<tagp><type>int</type> <param>size</param></tagp>
    buffer size
<tagp><type>const char *</type> <param>fmt</param></tagp>
    format string
<tagp><type>...</type> <param>...</param></tagp>
   variable arguments
</descrip>
<funcsect>Description
<p>
   This function is equivalent to <func/bsnprintf()/ with variable arguments instead of a <struct/va_list/.
</function>
<function><p><type>void *</type>
<funcdef>xmalloc</funcdef>
(<type>unsigned</type> <param>size</param>) --     malloc with checking

<funcsect>Arguments
<p><descrip>
<tagp><type>unsigned</type> <param>size</param></tagp>
    block size
</descrip>
<funcsect>Description
<p>
   This function is equivalent to <func/malloc()/ except that in case of
   failure it calls <func/die()/ to quit the program instead of returning
   a <const/NULL/ pointer.
   <p>
   Wherever possible, please use the memory resources instead.
</function>
<!--
	BIRD Programmer's Guide: Resources

	(c) 2000 Martin Mares <mj@ucw.cz>
-->

<chapt>Resources

<sect>Introduction

<p>Most large software projects implemented in classical procedural
programming languages usually end up with lots of code taking care
of resource allocation and deallocation. Bugs in such code are often
very difficult to find, because they cause only `resource leakage',
that is keeping a lot of memory and other resources which nobody
references to.

<p>We've tried to solve this problem by employing a resource tracking
system which keeps track of all the resources allocated by all the
modules of BIRD, deallocates everything automatically when a module
shuts down and it is able to print out the list of resources and
the corresponding modules they are allocated by.

<p>Each allocated resource (from now we'll speak about allocated
resources only) is represented by a structure starting with a standard
header (struct <struct/resource/) consisting of a list node (resources are
often linked to various lists) and a pointer to <struct/resclass/ -- a resource
class structure pointing to functions implementing generic resource
operations (such as freeing of the resource) for the particular resource
type.

<p>There exist the following types of resources:

<itemize>
<item><it/Resource pools/ (<struct/pool/)
<item><it/Memory blocks/
<item><it/Linear memory pools/ (<struct/linpool/)
<item><it/Slabs/ (<struct/slab/)
<item><it/Events/ (<struct/event/) 
<item><it/Timers/ (<struct/timer/) 
<item><it/Sockets/ (<struct/socket/) 
</itemize>
<sect>Resource pools
<p>
   <p>
   Resource pools (<struct/pool/) are just containers holding a list of
   other resources. Freeing a pool causes all the listed resources
   to be freed as well. Each existing <struct/resource/ is linked to some pool
   except for a root pool which isn't linked anywhere, so all the
   resources form a tree structure with internal nodes corresponding
   to pools and leaves being the other resources.
   <p>
   Example: Almost all modules of BIRD have their private pool which
   is freed upon shutdown of the module.


<function><p><type>pool *</type>
<funcdef>rp_new</funcdef>
(<type>pool *</type> <param>p</param>, <type>char *</type> <param>name</param>) --     create a resource pool

<funcsect>Arguments
<p><descrip>
<tagp><type>pool *</type> <param>p</param></tagp>
    parent pool
<tagp><type>char *</type> <param>name</param></tagp>
    pool name (to be included in debugging dumps)
</descrip>
<funcsect>Description
<p>
   <func/rp_new()/ creates a new resource pool inside the specified
   parent pool.
</function>
<function><p><type>void</type>
<funcdef>rmove</funcdef>
(<type>void *</type> <param>res</param>, <type>pool *</type> <param>p</param>) --     move a resource

<funcsect>Arguments
<p><descrip>
<tagp><type>void *</type> <param>res</param></tagp>
    resource
<tagp><type>pool *</type> <param>p</param></tagp>
    pool to move the resource to
</descrip>
<funcsect>Description
<p>
   <func/rmove()/ moves a resource from one pool to another.
</function>
<function><p><type>void</type>
<funcdef>rfree</funcdef>
(<type>void *</type> <param>res</param>) --     free a resource

<funcsect>Arguments
<p><descrip>
<tagp><type>void *</type> <param>res</param></tagp>
    resource
</descrip>
<funcsect>Description
<p>
   <func/rfree()/ frees the given resource and all information associated
   with it. In case it's a resource pool, it also frees all the objects
   living inside the pool.
   <p>
   It works by calling a class-specific freeing function.
</function>
<function><p><type>void</type>
<funcdef>rdump</funcdef>
(<type>void *</type> <param>res</param>) --     dump a resource

<funcsect>Arguments
<p><descrip>
<tagp><type>void *</type> <param>res</param></tagp>
    resource
</descrip>
<funcsect>Description
<p>
   This function prints out all available information about the given
   resource to the debugging output.
   <p>
   It works by calling a class-specific dump function.
</function>
<function><p><type>void *</type>
<funcdef>ralloc</funcdef>
(<type>pool *</type> <param>p</param>, <type>struct resclass *</type> <param>c</param>) --     create a resource

<funcsect>Arguments
<p><descrip>
<tagp><type>pool *</type> <param>p</param></tagp>
    pool to create the resource in
<tagp><type>struct resclass *</type> <param>c</param></tagp>
    class of the new resource
</descrip>
<funcsect>Description
<p>
   This function is called by the resource classes to create a new
   resource of the specified class and link it to the given pool.
   Size of the resource structure is taken from the <param/size/ field
   of the <struct/resclass/.
</function>
<function><p><type>void</type>
<funcdef>rlookup</funcdef>
(<type>unsigned long</type> <param>a</param>) --     look up a memory location

<funcsect>Arguments
<p><descrip>
<tagp><type>unsigned long</type> <param>a</param></tagp>
    memory address
</descrip>
<funcsect>Description
<p>
   This function examines all existing resources to see whether
   the address <param/a/ is inside any resource. It's used for debugging
   purposes only.
   <p>
   It works by calling a class-specific lookup function for each
   resource.
</function>
<function><p><type>void</type>
<funcdef>resource_init</funcdef>
(<param>void</param>) --     initialize the resource manager

<funcsect>Description
<p>
   <p>
   This function is called during BIRD startup. It initializes
   all data structures of the resource manager and creates the
   root pool.
</function>
<sect>Memory blocks
<p>
   <p>
   Memory blocks are pieces of contiguous allocated memory.
   They are a bit non-standard since they are represented not by a pointer
   to <struct/resource/, but by a void pointer to the start of data of the
   memory block. All memory block functions know how to locate the header
   given the data pointer.
   <p>
   Example: All "unique" data structures such as hash tables are allocated
   as memory blocks.


<function><p><type>void *</type>
<funcdef>mb_alloc</funcdef>
(<type>pool *</type> <param>p</param>, <type>unsigned</type> <param>size</param>) --     allocate a memory block

<funcsect>Arguments
<p><descrip>
<tagp><type>pool *</type> <param>p</param></tagp>
    pool
<tagp><type>unsigned</type> <param>size</param></tagp>
    size of the block
</descrip>
<funcsect>Description
<p>
   <func/mb_alloc()/ allocates memory of a given size and creates
   a memory block resource representing this memory chunk
   in the pool <param/p/.
   <p>
   Please note that <func/mb_alloc()/ returns a pointer to the memory
   chunk, not to the resource, hence you have to free it using
   <func/mb_free()/, not <func/rfree()/.
</function>
<function><p><type>void *</type>
<funcdef>mb_allocz</funcdef>
(<type>pool *</type> <param>p</param>, <type>unsigned</type> <param>size</param>) --     allocate and clear a memory block

<funcsect>Arguments
<p><descrip>
<tagp><type>pool *</type> <param>p</param></tagp>
    pool
<tagp><type>unsigned</type> <param>size</param></tagp>
    size of the block
</descrip>
<funcsect>Description
<p>
   <func/mb_allocz()/ allocates memory of a given size, initializes it to
   zeroes and creates a memory block resource representing this memory
   chunk in the pool <param/p/.
   <p>
   Please note that <func/mb_alloc()/ returns a pointer to the memory
   chunk, not to the resource, hence you have to free it using
   <func/mb_free()/, not <func/rfree()/.
</function>
<function><p><type>void</type>
<funcdef>mb_free</funcdef>
(<type>void *</type> <param>m</param>) --     free a memory block

<funcsect>Arguments
<p><descrip>
<tagp><type>void *</type> <param>m</param></tagp>
    memory block
</descrip>
<funcsect>Description
<p>
   <func/mb_free()/ frees all memory associated with the block <param/m/.
</function>
<sect>Linear memory pools
<p>
   <p>
   Linear memory pools are collections of memory blocks which
   support very fast allocation of new blocks, but are able to free only
   the whole collection at once.
   <p>
   Example: Each configuration is described by a complex system of structures,
   linked lists and function trees which are all allocated from a single linear
   pool, thus they can be freed at once when the configuration is no longer used.


<function><p><type>linpool *</type>
<funcdef>lp_new</funcdef>
(<type>pool *</type> <param>p</param>, <type>unsigned</type> <param>blk</param>) --     create a new linear memory pool

<funcsect>Arguments
<p><descrip>
<tagp><type>pool *</type> <param>p</param></tagp>
    pool
<tagp><type>unsigned</type> <param>blk</param></tagp>
    block size
</descrip>
<funcsect>Description
<p>
   <func/lp_new()/ creates a new linear memory pool resource inside the pool <param/p/.
   The linear pool consists of a list of memory chunks of size at least
   <param/blk/.
</function>
<function><p><type>void *</type>
<funcdef>lp_alloc</funcdef>
(<type>linpool *</type> <param>m</param>, <type>unsigned</type> <param>size</param>) --     allocate memory from a <struct/linpool/

<funcsect>Arguments
<p><descrip>
<tagp><type>linpool *</type> <param>m</param></tagp>
    linear memory pool
<tagp><type>unsigned</type> <param>size</param></tagp>
    amount of memory
</descrip>
<funcsect>Description
<p>
   <func/lp_alloc()/ allocates <param/size/ bytes of memory from a <struct/linpool/ <param/m/
   and it returns a pointer to the allocated memory.
   <p>
   It works by trying to find free space in the last memory chunk
   associated with the <struct/linpool/ and creating a new chunk of the standard
   size (as specified during <func/lp_new()/) if the free space is too small
   to satisfy the allocation. If <param/size/ is too large to fit in a standard
   size chunk, an "overflow" chunk is created for it instead.
</function>
<function><p><type>void *</type>
<funcdef>lp_allocu</funcdef>
(<type>linpool *</type> <param>m</param>, <type>unsigned</type> <param>size</param>) --     allocate unaligned memory from a <struct/linpool/

<funcsect>Arguments
<p><descrip>
<tagp><type>linpool *</type> <param>m</param></tagp>
    linear memory pool
<tagp><type>unsigned</type> <param>size</param></tagp>
    amount of memory
</descrip>
<funcsect>Description
<p>
   <func/lp_allocu()/ allocates <param/size/ bytes of memory from a <struct/linpool/ <param/m/
   and it returns a pointer to the allocated memory. It doesn't
   attempt to align the memory block, giving a very efficient way
   how to allocate strings without any space overhead.
</function>
<function><p><type>void *</type>
<funcdef>lp_allocz</funcdef>
(<type>linpool *</type> <param>m</param>, <type>unsigned</type> <param>size</param>) --     allocate cleared memory from a <struct/linpool/

<funcsect>Arguments
<p><descrip>
<tagp><type>linpool *</type> <param>m</param></tagp>
    linear memory pool
<tagp><type>unsigned</type> <param>size</param></tagp>
    amount of memory
</descrip>
<funcsect>Description
<p>
   This function is identical to <func/lp_alloc()/ except that it
   clears the allocated memory block.
</function>
<function><p><type>void</type>
<funcdef>lp_flush</funcdef>
(<type>linpool *</type> <param>m</param>) --     flush a linear memory pool

<funcsect>Arguments
<p><descrip>
<tagp><type>linpool *</type> <param>m</param></tagp>
    linear memory pool
</descrip>
<funcsect>Description
<p>
   This function frees the whole contents of the given <struct/linpool/ <param/m/,
   but leaves the pool itself.
</function>
<sect>Slabs
<p>
   <p>
   Slabs are collections of memory blocks of a fixed size.
   They support very fast allocation and freeing of such blocks, prevent memory
   fragmentation and optimize L2 cache usage. Slabs have been invented by Jeff Bonwick
   and published in USENIX proceedings as `The Slab Allocator: An Object-Caching Kernel
   Memory Allocator'. Our implementation follows this article except that we don't use
   constructors and destructors.
   <p>
   When the <tt>DEBUGGING</tt> switch is turned on, we automatically fill all
   newly allocated and freed blocks with a special pattern to make detection
   of use of uninitialized or already freed memory easier.
   <p>
   Example: Nodes of a FIB are allocated from a per-FIB Slab.


<function><p><type>slab *</type>
<funcdef>sl_new</funcdef>
(<type>pool *</type> <param>p</param>, <type>unsigned</type> <param>size</param>) --     create a new Slab

<funcsect>Arguments
<p><descrip>
<tagp><type>pool *</type> <param>p</param></tagp>
    resource pool
<tagp><type>unsigned</type> <param>size</param></tagp>
    block size
</descrip>
<funcsect>Description
<p>
   This function creates a new Slab resource from which
   objects of size <param/size/ can be allocated.
</function>
<function><p><type>void *</type>
<funcdef>sl_alloc</funcdef>
(<type>slab *</type> <param>s</param>) --     allocate an object from Slab

<funcsect>Arguments
<p><descrip>
<tagp><type>slab *</type> <param>s</param></tagp>
    slab
</descrip>
<funcsect>Description
<p>
   <func/sl_alloc()/ allocates space for a single object from the
   Slab and returns a pointer to the object.
</function>
<function><p><type>void</type>
<funcdef>sl_free</funcdef>
(<type>slab *</type> <param>s</param>, <type>void *</type> <param>oo</param>) --     return a free object back to a Slab

<funcsect>Arguments
<p><descrip>
<tagp><type>slab *</type> <param>s</param></tagp>
    slab
<tagp><type>void *</type> <param>oo</param></tagp>
    object returned by <func/sl_alloc()/
</descrip>
<funcsect>Description
<p>
   This function frees memory associated with the object <param/oo/
   and returns it back to the Slab <param/s/.
</function>
<sect>Events
<p>
   <p>
   Events are there to keep track of deferred execution.
   Since BIRD is single-threaded, it requires long lasting tasks to be split to smaller
   parts, so that no module can monopolize the CPU. To split such a task, just create
   an <struct/event/ resource, point it to the function you want to have called and call <func/ev_schedule()/
   to ask the core to run the event when nothing more important requires attention.
   <p>
   You can also define your own event lists (the <struct/event_list/ structure), enqueue your
   events in them and explicitly ask to run them.


<function><p><type>event *</type>
<funcdef>ev_new</funcdef>
(<type>pool *</type> <param>p</param>) --     create a new event

<funcsect>Arguments
<p><descrip>
<tagp><type>pool *</type> <param>p</param></tagp>
    resource pool
</descrip>
<funcsect>Description
<p>
   This function creates a new event resource. To use it,
   you need to fill the structure fields and call <func/ev_schedule()/.
</function>
<function><p><type>void</type>
<funcdef>ev_run</funcdef>
(<type>event *</type> <param>e</param>) --     run an event

<funcsect>Arguments
<p><descrip>
<tagp><type>event *</type> <param>e</param></tagp>
    an event
</descrip>
<funcsect>Description
<p>
   This function explicitly runs the event <param/e/ (calls its hook
   function) and removes it from an event list if it's linked to any.
   <p>
   From the hook function, you can call <func/ev_enqueue()/ or <func/ev_schedule()/
   to re-add the event.
</function>
<function><p><type>void</type>
<funcdef>ev_enqueue</funcdef>
(<type>event_list *</type> <param>l</param>, <type>event *</type> <param>e</param>) --     enqueue an event

<funcsect>Arguments
<p><descrip>
<tagp><type>event_list *</type> <param>l</param></tagp>
    an event list
<tagp><type>event *</type> <param>e</param></tagp>
    an event
</descrip>
<funcsect>Description
<p>
   <func/ev_enqueue()/ stores the event <param/e/ to the specified event
   list <param/l/ which can be run by calling <func/ev_run_list()/.
</function>
<function><p><type>void</type>
<funcdef>ev_schedule</funcdef>
(<type>event *</type> <param>e</param>) --     schedule an event

<funcsect>Arguments
<p><descrip>
<tagp><type>event *</type> <param>e</param></tagp>
    an event
</descrip>
<funcsect>Description
<p>
   This function schedules an event by enqueueing it to a system-wide
   event list which is run by the platform dependent code whenever
   appropriate.
</function>
<function><p><type>int</type>
<funcdef>ev_run_list</funcdef>
(<type>event_list *</type> <param>l</param>) --     run an event list

<funcsect>Arguments
<p><descrip>
<tagp><type>event_list *</type> <param>l</param></tagp>
    an event list
</descrip>
<funcsect>Description
<p>
   This function calls <func/ev_run()/ for all events enqueued in the list <param/l/.
</function>
<sect>Timers
<p>
   <p>
   Timers are resources which represent a wish of a module to call
   a function at the specified time. The platform dependent code
   doesn't guarantee exact timing, only that a timer function
   won't be called before the requested time.
   <p>
   In BIRD, real time is represented by values of the <struct/bird_clock_t/ type
   which are integral numbers interpreted as a number of seconds since
   a fixed (but platform dependent) epoch. The current time can be read
   from a variable <param/now/ with reasonable accuracy.
   <p>
   Each timer is described by a <struct/timer/ structure containing a pointer
   to the handler function (<param/hook/), data private to this function (<param/data/),
   time the function should be called at (<param/expires/, 0 for inactive timers),
   for the other fields see <tt>timer.h</tt>.


<function><p><type>timer *</type>
<funcdef>tm_new</funcdef>
(<type>pool *</type> <param>p</param>) --     create a timer

<funcsect>Arguments
<p><descrip>
<tagp><type>pool *</type> <param>p</param></tagp>
    pool
</descrip>
<funcsect>Description
<p>
   This function creates a new timer resource and returns
   a pointer to it. To use the timer, you need to fill in
   the structure fields and call <func/tm_start()/ to start timing.
</function>
<function><p><type>void</type>
<funcdef>tm_start</funcdef>
(<type>timer *</type> <param>t</param>, <type>unsigned</type> <param>after</param>) --     start a timer

<funcsect>Arguments
<p><descrip>
<tagp><type>timer *</type> <param>t</param></tagp>
    timer
<tagp><type>unsigned</type> <param>after</param></tagp>
    number of seconds the timer should be run after
</descrip>
<funcsect>Description
<p>
   This function schedules the hook function of the timer to
   be called after <param/after/ seconds. If the timer has been already
   started, it's <param/expire/ time is replaced by the new value.
   <p>
   You can have set the <param/randomize/ field of <param/t/, the timeout
   will be increased by a random number of seconds chosen
   uniformly from range 0 .. <param/randomize/.
   <p>
   You can call <func/tm_start()/ from the handler function of the timer
   to request another run of the timer. Also, you can set the <param/recurrent/
   field to have the timer re-added automatically with the same timeout.
</function>
<function><p><type>void</type>
<funcdef>tm_stop</funcdef>
(<type>timer *</type> <param>t</param>) --     stop a timer

<funcsect>Arguments
<p><descrip>
<tagp><type>timer *</type> <param>t</param></tagp>
    timer
</descrip>
<funcsect>Description
<p>
   This function stops a timer. If the timer is already stopped,
   nothing happens.
</function>
<function><p><type>bird_clock_t</type>
<funcdef>tm_parse_datetime</funcdef>
(<type>char *</type> <param>x</param>) --     parse a date and time

<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>x</param></tagp>
    datetime string
</descrip>
<funcsect>Description
<p>
   <func/tm_parse_datetime()/ takes a textual representation of
   a date and time (dd-mm-yyyy hh:mm:ss)
   and converts it to the corresponding value of type <struct/bird_clock_t/.
</function>
<function><p><type>bird_clock_t</type>
<funcdef>tm_parse_date</funcdef>
(<type>char *</type> <param>x</param>) --     parse a date

<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>x</param></tagp>
    date string
</descrip>
<funcsect>Description
<p>
   <func/tm_parse_date()/ takes a textual representation of a date (dd-mm-yyyy)
   and converts it to the corresponding value of type <struct/bird_clock_t/.
</function>
<function><p><type>void</type>
<funcdef>tm_format_date</funcdef>
(<type>char *</type> <param>x</param>, <type>bird_clock_t</type> <param>t</param>) --     convert date to textual representation

<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>x</param></tagp>
    destination buffer of size <const/TM_DATE_BUFFER_SIZE/
<tagp><type>bird_clock_t</type> <param>t</param></tagp>
    time
</descrip>
<funcsect>Description
<p>
   This function formats the given time value <param/t/ to a textual
   date representation (dd-mm-yyyy).
</function>
<function><p><type>void</type>
<funcdef>tm_format_datetime</funcdef>
(<type>char *</type> <param>x</param>, <type>bird_clock_t</type> <param>t</param>) --     convert date and time to textual representation

<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>x</param></tagp>
    destination buffer of size <const/TM_DATETIME_BUFFER_SIZE/
<tagp><type>bird_clock_t</type> <param>t</param></tagp>
    time
</descrip>
<funcsect>Description
<p>
   This function formats the given time value <param/t/ to a textual
   date/time representation (dd-mm-yyyy hh:mm:ss).
</function>
<function><p><type>void</type>
<funcdef>tm_format_reltime</funcdef>
(<type>char *</type> <param>x</param>, <type>bird_clock_t</type> <param>t</param>) --     convert date and time to relative textual representation

<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>x</param></tagp>
    destination buffer of size <const/TM_RELTIME_BUFFER_SIZE/
<tagp><type>bird_clock_t</type> <param>t</param></tagp>
    time
</descrip>
<funcsect>Description
<p>
   This function formats the given time value <param/t/ to a short
   textual representation relative to the current time.
</function>
<sect>Sockets
<p>
   <p>
   Socket resources represent network connections. Their data structure (<struct/socket/)
   contains a lot of fields defining the exact type of the socket, the local and
   remote addresses and ports, pointers to socket buffers and finally pointers to
   hook functions to be called when new data have arrived to the receive buffer
   (<param/rx_hook/), when the contents of the transmit buffer have been transmitted
   (<param/tx_hook/) and when an error or connection close occurs (<param/err_hook/).
   <p>
   Freeing of sockets from inside socket hooks is perfectly safe.


<function><p><type>sock *</type>
<funcdef>sk_new</funcdef>
(<type>pool *</type> <param>p</param>) --     create a socket

<funcsect>Arguments
<p><descrip>
<tagp><type>pool *</type> <param>p</param></tagp>
    pool
</descrip>
<funcsect>Description
<p>
   This function creates a new socket resource. If you want to use it,
   you need to fill in all the required fields of the structure and
   call <func/sk_open()/ to do the actual opening of the socket.
</function>
<function><p><type>int</type>
<funcdef>sk_open</funcdef>
(<type>sock *</type> <param>s</param>) --     open a socket

<funcsect>Arguments
<p><descrip>
<tagp><type>sock *</type> <param>s</param></tagp>
    socket
</descrip>
<funcsect>Description
<p>
   This function takes a socket resource created by <func/sk_new()/ and
   initialized by the user and binds a corresponding network connection
   to it.
<funcsect>Result
<p>
    0 for success, -1 for an error.
</function>
<function><p><type>int</type>
<funcdef>sk_send</funcdef>
(<type>sock *</type> <param>s</param>, <type>unsigned</type> <param>len</param>) --     send data to a socket

<funcsect>Arguments
<p><descrip>
<tagp><type>sock *</type> <param>s</param></tagp>
    socket
<tagp><type>unsigned</type> <param>len</param></tagp>
    number of bytes to send
</descrip>
<funcsect>Description
<p>
   This function sends <param/len/ bytes of data prepared in the
   transmit buffer of the socket <param/s/ to the network connection.
   If the packet can be sent immediately, it does so and returns
   1, else it queues the packet for later processing, returns 0
   and calls the <param/tx_hook/ of the socket when the tranmission
   takes place.
</function>
<function><p><type>int</type>
<funcdef>sk_send_to</funcdef>
(<type>sock *</type> <param>s</param>, <type>unsigned</type> <param>len</param>, <type>ip_addr</type> <param>addr</param>, <type>unsigned</type> <param>port</param>) --     send data to a specific destination

<funcsect>Arguments
<p><descrip>
<tagp><type>sock *</type> <param>s</param></tagp>
    socket
<tagp><type>unsigned</type> <param>len</param></tagp>
    number of bytes to send
<tagp><type>ip_addr</type> <param>addr</param></tagp>
    IP address to send the packet to
<tagp><type>unsigned</type> <param>port</param></tagp>
    port to send the packet to
</descrip>
<funcsect>Description
<p>
   This is a <func/sk_send()/ replacement for connection-less packet sockets
   which allows destination of the packet to be chosen dynamically.
</function>

</book>
