Annotation of embedaddon/bird/doc/prog-2.html, revision 1.1.1.2

1.1       misho       1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
                      2: <HTML>
                      3: <HEAD>
                      4:  <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 1.0.9">
                      5:  <TITLE>BIRD Programmer's Documentation: Core</TITLE>
                      6:  <LINK HREF="prog-3.html" REL=next>
                      7:  <LINK HREF="prog-1.html" REL=previous>
                      8:  <LINK HREF="prog.html#toc2" REL=contents>
                      9: </HEAD>
                     10: <BODY>
                     11: <A HREF="prog-3.html">Next</A>
                     12: <A HREF="prog-1.html">Previous</A>
                     13: <A HREF="prog.html#toc2">Contents</A>
                     14: <HR>
                     15: <H2><A NAME="s2">2.</A> <A HREF="prog.html#toc2">Core</A></H2>
                     16: 
                     17: <H2><A NAME="ss2.1">2.1</A> <A HREF="prog.html#toc2.1">Forwarding Information Base</A>
                     18: </H2>
                     19: 
                     20: <P>
                     21: <P>FIB is a data structure designed for storage of routes indexed by their
                     22: network prefixes. It supports insertion, deletion, searching by prefix,
                     23: `routing' (in CIDR sense, that is searching for a longest prefix matching
                     24: a given IP address) and (which makes the structure very tricky to implement)
                     25: asynchronous reading, that is enumerating the contents of a FIB while other
                     26: modules add, modify or remove entries.
                     27: <P>Internally, each FIB is represented as a collection of nodes of type <I>fib_node</I>
                     28: indexed using a sophisticated hashing mechanism.
                     29: We use two-stage hashing where we calculate a 16-bit primary hash key independent
                     30: on hash table size and then we just divide the primary keys modulo table size
                     31: to get a real hash key used for determining the bucket containing the node.
                     32: The lists of nodes in each bucket are sorted according to the primary hash
                     33: key, hence if we keep the total number of buckets to be a power of two,
                     34: re-hashing of the structure keeps the relative order of the nodes.
                     35: <P>To get the asynchronous reading consistent over node deletions, we need to
                     36: keep a list of readers for each node. When a node gets deleted, its readers
                     37: are automatically moved to the next node in the table.
                     38: <P>Basic FIB operations are performed by functions defined by this module,
                     39: enumerating of FIB contents is accomplished by using the <B>FIB_WALK()</B> macro
                     40: or <B>FIB_ITERATE_START()</B> if you want to do it asynchronously.
1.1.1.2 ! misho      41: <P>For simple iteration just place the body of the loop between <B>FIB_WALK()</B> and
        !            42: <B>FIB_WALK_END()</B>. You can't modify the FIB during the iteration (you can modify
        !            43: data in the node, but not add or remove nodes).
        !            44: <P>If you need more freedom, you can use the FIB_ITERATE_*() group of macros.
        !            45: First, you initialize an iterator with <B>FIB_ITERATE_INIT()</B>. Then you can put
        !            46: the loop body in between <B>FIB_ITERATE_START()</B> and <B>FIB_ITERATE_END()</B>. In
        !            47: addition, the iteration can be suspended by calling <B>FIB_ITERATE_PUT()</B>.
        !            48: This'll link the iterator inside the FIB. While suspended, you may modify the
        !            49: FIB, exit the current function, etc. To resume the iteration, enter the loop
        !            50: again. You can use <B>FIB_ITERATE_UNLINK()</B> to unlink the iterator (while
        !            51: iteration is suspended) in cases like premature end of FIB iteration.
        !            52: <P>Note that the iterator must not be destroyed when the iteration is suspended,
        !            53: the FIB would then contain a pointer to invalid memory. Therefore, after each
        !            54: <B>FIB_ITERATE_INIT()</B> or <B>FIB_ITERATE_PUT()</B> there must be either
        !            55: <B>FIB_ITERATE_START()</B> or <B>FIB_ITERATE_UNLINK()</B> before the iterator is destroyed.
1.1       misho      56: <P>
                     57: <P><HR><H3>Function</H3>
                     58: <P><I>void</I>
                     59: <B>fib_init</B>
                     60: (<I>struct fib *</I> <B>f</B>, <I>pool *</I> <B>p</B>, <I>unsigned</I> <B>node_size</B>, <I>unsigned</I> <B>hash_order</B>, <I>fib_init_func</I> <B>init</B>) --     initialize a new FIB
                     61: <P>
                     62: <H3>Arguments</H3>
                     63: <P>
                     64: <DL>
                     65: <DT><I>struct fib *</I> <B>f</B><DD><P>the FIB to be initialized (the structure itself being allocated by the caller)
                     66: <DT><I>pool *</I> <B>p</B><DD><P>pool to allocate the nodes in
                     67: <DT><I>unsigned</I> <B>node_size</B><DD><P>node size to be used (each node consists of a standard header <I>fib_node</I>
                     68: followed by user data)
                     69: <DT><I>unsigned</I> <B>hash_order</B><DD><P>initial hash order (a binary logarithm of hash table size), 0 to use default order
                     70: (recommended)
                     71: <DT><I>fib_init_func</I> <B>init</B><DD><P>pointer a function to be called to initialize a newly created node
                     72: </DL>
                     73: <H3>Description</H3>
                     74: <P>This function initializes a newly allocated FIB and prepares it for use.
                     75: 
                     76: 
                     77: <HR><H3>Function</H3>
                     78: <P><I>void *</I>
                     79: <B>fib_find</B>
                     80: (<I>struct fib *</I> <B>f</B>, <I>ip_addr *</I> <B>a</B>, <I>int</I> <B>len</B>) --     search for FIB node by prefix
                     81: <P>
                     82: <H3>Arguments</H3>
                     83: <P>
                     84: <DL>
                     85: <DT><I>struct fib *</I> <B>f</B><DD><P>FIB to search in
                     86: <DT><I>ip_addr *</I> <B>a</B><DD><P>pointer to IP address of the prefix
                     87: <DT><I>int</I> <B>len</B><DD><P>prefix length
                     88: </DL>
                     89: <H3>Description</H3>
                     90: <P>Search for a FIB node corresponding to the given prefix, return
                     91: a pointer to it or <I>NULL</I> if no such node exists.
                     92: 
                     93: 
                     94: <HR><H3>Function</H3>
                     95: <P><I>void *</I>
                     96: <B>fib_get</B>
                     97: (<I>struct fib *</I> <B>f</B>, <I>ip_addr *</I> <B>a</B>, <I>int</I> <B>len</B>) --     find or create a FIB node
                     98: <P>
                     99: <H3>Arguments</H3>
                    100: <P>
                    101: <DL>
                    102: <DT><I>struct fib *</I> <B>f</B><DD><P>FIB to work with
                    103: <DT><I>ip_addr *</I> <B>a</B><DD><P>pointer to IP address of the prefix
                    104: <DT><I>int</I> <B>len</B><DD><P>prefix length
                    105: </DL>
                    106: <H3>Description</H3>
                    107: <P>Search for a FIB node corresponding to the given prefix and
                    108: return a pointer to it. If no such node exists, create it.
                    109: 
                    110: 
                    111: <HR><H3>Function</H3>
                    112: <P><I>void *</I>
                    113: <B>fib_route</B>
                    114: (<I>struct fib *</I> <B>f</B>, <I>ip_addr</I> <B>a</B>, <I>int</I> <B>len</B>) --     CIDR routing lookup
                    115: <P>
                    116: <H3>Arguments</H3>
                    117: <P>
                    118: <DL>
                    119: <DT><I>struct fib *</I> <B>f</B><DD><P>FIB to search in
                    120: <DT><I>ip_addr</I> <B>a</B><DD><P>pointer to IP address of the prefix
                    121: <DT><I>int</I> <B>len</B><DD><P>prefix length
                    122: </DL>
                    123: <H3>Description</H3>
                    124: <P>Search for a FIB node with longest prefix matching the given
                    125: network, that is a node which a CIDR router would use for routing
                    126: that network.
                    127: 
                    128: 
                    129: <HR><H3>Function</H3>
                    130: <P><I>void</I>
                    131: <B>fib_delete</B>
                    132: (<I>struct fib *</I> <B>f</B>, <I>void *</I> <B>E</B>) --     delete a FIB node
                    133: <P>
                    134: <H3>Arguments</H3>
                    135: <P>
                    136: <DL>
                    137: <DT><I>struct fib *</I> <B>f</B><DD><P>FIB to delete from
                    138: <DT><I>void *</I> <B>E</B><DD><P>entry to delete
                    139: </DL>
                    140: <H3>Description</H3>
                    141: <P>This function removes the given entry from the FIB,
                    142: taking care of all the asynchronous readers by shifting
                    143: them to the next node in the canonical reading order.
                    144: 
                    145: 
                    146: <HR><H3>Function</H3>
                    147: <P><I>void</I>
                    148: <B>fib_free</B>
                    149: (<I>struct fib *</I> <B>f</B>) --     delete a FIB
                    150: <P>
                    151: <H3>Arguments</H3>
                    152: <P>
                    153: <DL>
                    154: <DT><I>struct fib *</I> <B>f</B><DD><P>FIB to be deleted
                    155: </DL>
                    156: <H3>Description</H3>
                    157: <P>This function deletes a FIB -- it frees all memory associated
                    158: with it and all its entries.
                    159: 
                    160: 
                    161: <HR><H3>Function</H3>
                    162: <P><I>void</I>
                    163: <B>fib_check</B>
                    164: (<I>struct fib *</I> <B>f</B>) --     audit a FIB
                    165: <P>
                    166: <H3>Arguments</H3>
                    167: <P>
                    168: <DL>
                    169: <DT><I>struct fib *</I> <B>f</B><DD><P>FIB to be checked
                    170: </DL>
                    171: <H3>Description</H3>
                    172: <P>This debugging function audits a FIB by checking its internal consistency.
                    173: Use when you suspect somebody of corrupting innocent data structures.
                    174: 
                    175: <H2><A NAME="ss2.2">2.2</A> <A HREF="prog.html#toc2.2">Routing tables</A>
                    176: </H2>
                    177: 
                    178: <P>
                    179: <P>Routing tables are probably the most important structures BIRD uses. They
                    180: hold all the information about known networks, the associated routes and
                    181: their attributes.
                    182: <P>There are multiple routing tables (a primary one together with any
                    183: number of secondary ones if requested by the configuration). Each table
                    184: is basically a FIB containing entries describing the individual
                    185: destination networks. For each network (represented by structure <I>net</I>),
                    186: there is a one-way linked list of route entries (<I>rte</I>), the first entry
                    187: on the list being the best one (i.e., the one we currently use
                    188: for routing), the order of the other ones is undetermined.
                    189: <P>The <I>rte</I> contains information specific to the route (preference, protocol
                    190: metrics, time of last modification etc.) and a pointer to a <I>rta</I> structure
                    191: (see the route attribute module for a precise explanation) holding the
                    192: remaining route attributes which are expected to be shared by multiple
                    193: routes in order to conserve memory.
                    194: <P>
                    195: <P><HR><H3>Function</H3>
                    196: <P><I>rte *</I>
                    197: <B>rte_find</B>
                    198: (<I>net *</I> <B>net</B>, <I>struct rte_src *</I> <B>src</B>) --     find a route
                    199: <P>
                    200: <H3>Arguments</H3>
                    201: <P>
                    202: <DL>
                    203: <DT><I>net *</I> <B>net</B><DD><P>network node
                    204: <DT><I>struct rte_src *</I> <B>src</B><DD><P>route source
                    205: </DL>
                    206: <H3>Description</H3>
                    207: <P>The <B>rte_find()</B> function returns a route for destination <B>net</B>
                    208: which is from route source <B>src</B>.
                    209: 
                    210: 
                    211: <HR><H3>Function</H3>
                    212: <P><I>rte *</I>
                    213: <B>rte_get_temp</B>
                    214: (<I>rta *</I> <B>a</B>) --     get a temporary <I>rte</I>
                    215: <P>
                    216: <H3>Arguments</H3>
                    217: <P>
                    218: <DL>
                    219: <DT><I>rta *</I> <B>a</B><DD><P>attributes to assign to the new route (a <I>rta</I>; in case it's
                    220: un-cached, <B>rte_update()</B> will create a cached copy automatically)
                    221: </DL>
                    222: <H3>Description</H3>
                    223: <P>Create a temporary <I>rte</I> and bind it with the attributes <B>a</B>.
                    224: Also set route preference to the default preference set for
                    225: the protocol.
                    226: 
                    227: 
                    228: <HR><H3>Function</H3>
                    229: <P><I>rte *</I>
                    230: <B>rte_cow_rta</B>
                    231: (<I>rte *</I> <B>r</B>, <I>linpool *</I> <B>lp</B>) --     get a private writable copy of <I>rte</I> with writable <I>rta</I>
                    232: <P>
                    233: <H3>Arguments</H3>
                    234: <P>
                    235: <DL>
                    236: <DT><I>rte *</I> <B>r</B><DD><P>a route entry to be copied
                    237: <DT><I>linpool *</I> <B>lp</B><DD><P>a linpool from which to allocate <I>rta</I>
                    238: </DL>
                    239: <H3>Description</H3>
                    240: <P><B>rte_cow_rta()</B> takes a <I>rte</I> and prepares it and associated <I>rta</I> for
                    241: modification. There are three possibilities: First, both <I>rte</I> and <I>rta</I> are
                    242: private copies, in that case they are returned unchanged.  Second, <I>rte</I> is
                    243: private copy, but <I>rta</I> is cached, in that case <I>rta</I> is duplicated using
                    244: <B>rta_do_cow()</B>. Third, both <I>rte</I> is shared and <I>rta</I> is cached, in that case
                    245: both structures are duplicated by <B>rte_do_cow()</B> and <B>rta_do_cow()</B>.
                    246: <P>Note that in the second case, cached <I>rta</I> loses one reference, while private
                    247: copy created by <B>rta_do_cow()</B> is a shallow copy sharing indirect data (eattrs,
                    248: nexthops, ...) with it. To work properly, original shared <I>rta</I> should have
                    249: another reference during the life of created private copy.
                    250: <H3>Result</H3>
                    251: <P>a pointer to the new writable <I>rte</I> with writable <I>rta</I>.
                    252: 
                    253: 
                    254: <HR><H3>Function</H3>
                    255: <P><I>void</I>
                    256: <B>rte_announce</B>
                    257: (<I>rtable *</I> <B>tab</B>, <I>unsigned</I> <B>type</B>, <I>net *</I> <B>net</B>, <I>rte *</I> <B>new</B>, <I>rte *</I> <B>old</B>, <I>rte *</I> <B>new_best</B>, <I>rte *</I> <B>old_best</B>, <I>rte *</I> <B>before_old</B>) --     announce a routing table change
                    258: <P>
                    259: <H3>Arguments</H3>
                    260: <P>
                    261: <DL>
                    262: <DT><I>rtable *</I> <B>tab</B><DD><P>table the route has been added to
                    263: <DT><I>unsigned</I> <B>type</B><DD><P>type of route announcement (RA_OPTIMAL or RA_ANY)
                    264: <DT><I>net *</I> <B>net</B><DD><P>network in question
                    265: <DT><I>rte *</I> <B>new</B><DD><P>the new route to be announced
                    266: <DT><I>rte *</I> <B>old</B><DD><P>the previous route for the same network
                    267: <DT><I>rte *</I> <B>new_best</B><DD><P>the new best route for the same network
                    268: <DT><I>rte *</I> <B>old_best</B><DD><P>the previous best route for the same network
                    269: <DT><I>rte *</I> <B>before_old</B><DD><P>The previous route before <B>old</B> for the same network.
                    270: If <B>before_old</B> is NULL <B>old</B> was the first.
                    271: </DL>
                    272: <H3>Description</H3>
                    273: <P>This function gets a routing table update and announces it
                    274: to all protocols that acccepts given type of route announcement
                    275: and are connected to the same table by their announcement hooks.
                    276: <P>Route announcement of type <I>RA_OPTIMAL</I> si generated when optimal
                    277: route (in routing table <B>tab</B>) changes. In that case <B>old</B> stores the
                    278: old optimal route.
                    279: <P>Route announcement of type <I>RA_ANY</I> si generated when any route (in
                    280: routing table <B>tab</B>) changes In that case <B>old</B> stores the old route
                    281: from the same protocol.
                    282: <P>For each appropriate protocol, we first call its <B>import_control()</B>
                    283: hook which performs basic checks on the route (each protocol has a
                    284: right to veto or force accept of the route before any filter is
                    285: asked) and adds default values of attributes specific to the new
                    286: protocol (metrics, tags etc.).  Then it consults the protocol's
                    287: export filter and if it accepts the route, the <B>rt_notify()</B> hook of
                    288: the protocol gets called.
                    289: 
                    290: 
                    291: <HR><H3>Function</H3>
                    292: <P><I>void</I>
                    293: <B>rte_free</B>
                    294: (<I>rte *</I> <B>e</B>) --     delete a <I>rte</I>
                    295: <P>
                    296: <H3>Arguments</H3>
                    297: <P>
                    298: <DL>
                    299: <DT><I>rte *</I> <B>e</B><DD><P><I>rte</I> to be deleted
                    300: </DL>
                    301: <H3>Description</H3>
                    302: <P><B>rte_free()</B> deletes the given <I>rte</I> from the routing table it's linked to.
                    303: 
                    304: 
                    305: <HR><H3>Function</H3>
                    306: <P><I>void</I>
                    307: <B>rte_update2</B>
                    308: (<I>struct announce_hook *</I> <B>ah</B>, <I>net *</I> <B>net</B>, <I>rte *</I> <B>new</B>, <I>struct rte_src *</I> <B>src</B>) --     enter a new update to a routing table
                    309: <P>
                    310: <H3>Arguments</H3>
                    311: <P>
                    312: <DL>
                    313: <DT><I>struct announce_hook *</I> <B>ah</B><DD><P>pointer to table announce hook
                    314: <DT><I>net *</I> <B>net</B><DD><P>network node
                    315: <DT><I>rte *</I> <B>new</B><DD><P>a <I>rte</I> representing the new route or <I>NULL</I> for route removal.
                    316: <DT><I>struct rte_src *</I> <B>src</B><DD><P>protocol originating the update
                    317: </DL>
                    318: <H3>Description</H3>
                    319: <P>This function is called by the routing protocols whenever they discover
                    320: a new route or wish to update/remove an existing route. The right announcement
                    321: sequence is to build route attributes first (either un-cached with <B>aflags</B> set
                    322: to zero or a cached one using <B>rta_lookup()</B>; in this case please note that
                    323: you need to increase the use count of the attributes yourself by calling
                    324: <B>rta_clone()</B>), call <B>rte_get_temp()</B> to obtain a temporary <I>rte</I>, fill in all
                    325: the appropriate data and finally submit the new <I>rte</I> by calling <B>rte_update()</B>.
                    326: <P><B>src</B> specifies the protocol that originally created the route and the meaning
                    327: of protocol-dependent data of <B>new</B>. If <B>new</B> is not <I>NULL</I>, <B>src</B> have to be the
                    328: same value as <B>new</B>-&gt;attrs-&gt;proto. <B>p</B> specifies the protocol that called
                    329: <B>rte_update()</B>. In most cases it is the same protocol as <B>src</B>. <B>rte_update()</B>
                    330: stores <B>p</B> in <B>new</B>-&gt;sender;
                    331: <P>When <B>rte_update()</B> gets any route, it automatically validates it (checks,
                    332: whether the network and next hop address are valid IP addresses and also
                    333: whether a normal routing protocol doesn't try to smuggle a host or link
                    334: scope route to the table), converts all protocol dependent attributes stored
                    335: in the <I>rte</I> to temporary extended attributes, consults import filters of the
                    336: protocol to see if the route should be accepted and/or its attributes modified,
                    337: stores the temporary attributes back to the <I>rte</I>.
                    338: <P>Now, having a "public" version of the route, we
                    339: automatically find any old route defined by the protocol <B>src</B>
                    340: for network <B>n</B>, replace it by the new one (or removing it if <B>new</B> is <I>NULL</I>),
                    341: recalculate the optimal route for this destination and finally broadcast
                    342: the change (if any) to all routing protocols by calling <B>rte_announce()</B>.
                    343: <P>All memory used for attribute lists and other temporary allocations is taken
                    344: from a special linear pool <B>rte_update_pool</B> and freed when <B>rte_update()</B>
                    345: finishes.
                    346: 
                    347: 
                    348: <HR><H3>Function</H3>
                    349: <P><I>void</I>
                    350: <B>rt_refresh_begin</B>
                    351: (<I>rtable *</I> <B>t</B>, <I>struct announce_hook *</I> <B>ah</B>) --     start a refresh cycle
                    352: <P>
                    353: <H3>Arguments</H3>
                    354: <P>
                    355: <DL>
                    356: <DT><I>rtable *</I> <B>t</B><DD><P>related routing table
                    357: <DT><I>struct announce_hook *</I> <B>ah</B><DD><P>related announce hook 
                    358: </DL>
                    359: <H3>Description</H3>
                    360: <P>This function starts a refresh cycle for given routing table and announce
                    361: hook. The refresh cycle is a sequence where the protocol sends all its valid
                    362: routes to the routing table (by <B>rte_update()</B>). After that, all protocol
                    363: routes (more precisely routes with <B>ah</B> as <B>sender</B>) not sent during the
                    364: refresh cycle but still in the table from the past are pruned. This is
                    365: implemented by marking all related routes as stale by REF_STALE flag in
                    366: <B>rt_refresh_begin()</B>, then marking all related stale routes with REF_DISCARD
                    367: flag in <B>rt_refresh_end()</B> and then removing such routes in the prune loop.
                    368: 
                    369: 
                    370: <HR><H3>Function</H3>
                    371: <P><I>void</I>
                    372: <B>rt_refresh_end</B>
                    373: (<I>rtable *</I> <B>t</B>, <I>struct announce_hook *</I> <B>ah</B>) --     end a refresh cycle
                    374: <P>
                    375: <H3>Arguments</H3>
                    376: <P>
                    377: <DL>
                    378: <DT><I>rtable *</I> <B>t</B><DD><P>related routing table
                    379: <DT><I>struct announce_hook *</I> <B>ah</B><DD><P>related announce hook 
                    380: </DL>
                    381: <H3>Description</H3>
                    382: <P>This function starts a refresh cycle for given routing table and announce
                    383: hook. See <B>rt_refresh_begin()</B> for description of refresh cycles.
                    384: 
                    385: 
                    386: <HR><H3>Function</H3>
                    387: <P><I>void</I>
                    388: <B>rte_dump</B>
                    389: (<I>rte *</I> <B>e</B>) --     dump a route
                    390: <P>
                    391: <H3>Arguments</H3>
                    392: <P>
                    393: <DL>
                    394: <DT><I>rte *</I> <B>e</B><DD><P><I>rte</I> to be dumped
                    395: </DL>
                    396: <H3>Description</H3>
                    397: <P>This functions dumps contents of a <I>rte</I> to debug output.
                    398: 
                    399: 
                    400: <HR><H3>Function</H3>
                    401: <P><I>void</I>
                    402: <B>rt_dump</B>
                    403: (<I>rtable *</I> <B>t</B>) --     dump a routing table
                    404: <P>
                    405: <H3>Arguments</H3>
                    406: <P>
                    407: <DL>
                    408: <DT><I>rtable *</I> <B>t</B><DD><P>routing table to be dumped
                    409: </DL>
                    410: <H3>Description</H3>
                    411: <P>This function dumps contents of a given routing table to debug output.
                    412: 
                    413: 
                    414: <HR><H3>Function</H3>
                    415: <P><I>void</I>
                    416: <B>rt_dump_all</B>
                    417: (<B>void</B>) --     dump all routing tables
                    418: <P>
                    419: <H3>Description</H3>
                    420: <P>
                    421: <P>This function dumps contents of all routing tables to debug output.
                    422: 
                    423: 
                    424: <HR><H3>Function</H3>
                    425: <P><I>void</I>
                    426: <B>rt_init</B>
                    427: (<B>void</B>) --     initialize routing tables
                    428: <P>
                    429: <H3>Description</H3>
                    430: <P>
                    431: <P>This function is called during BIRD startup. It initializes the
                    432: routing table module.
                    433: 
                    434: 
                    435: <HR><H3>Function</H3>
                    436: <P><I>int</I>
                    437: <B>rt_prune_table</B>
                    438: (<I>rtable *</I> <B>tab</B>) --     prune a routing table
                    439: <P>
                    440: <H3>Arguments</H3>
                    441: <P>
                    442: <DL>
                    443: <DT><I>rtable *</I> <B>tab</B><DD><P>a routing table for pruning
                    444: </DL>
                    445: <H3>Description</H3>
                    446: <P>This function scans the routing table <B>tab</B> and removes routes belonging to
                    447: flushing protocols, discarded routes and also stale network entries, in a
                    448: similar fashion like <B>rt_prune_loop()</B>. Returns 1 when all such routes are
                    449: pruned. Contrary to <B>rt_prune_loop()</B>, this function is not a part of the
                    450: protocol flushing loop, but it is called from <B>rt_event()</B> for just one routing
                    451: table.
                    452: <P>Note that <B>rt_prune_table()</B> and <B>rt_prune_loop()</B> share (for each table) the
                    453: prune state (<B>prune_state</B>) and also the pruning iterator (<B>prune_fit</B>).
                    454: 
                    455: 
                    456: <HR><H3>Function</H3>
                    457: <P><I>int</I>
                    458: <B>rt_prune_loop</B>
                    459: (<B>void</B>) --     prune routing tables
                    460: <P>
                    461: <H3>Description</H3>
                    462: <P>
                    463: <P>The prune loop scans routing tables and removes routes belonging to flushing
                    464: protocols, discarded routes and also stale network entries. Returns 1 when
                    465: all such routes are pruned. It is a part of the protocol flushing loop.
                    466: 
                    467: 
                    468: <HR><H3>Function</H3>
                    469: <P><I>void</I>
                    470: <B>rt_lock_table</B>
                    471: (<I>rtable *</I> <B>r</B>) --     lock a routing table
                    472: <P>
                    473: <H3>Arguments</H3>
                    474: <P>
                    475: <DL>
                    476: <DT><I>rtable *</I> <B>r</B><DD><P>routing table to be locked
                    477: </DL>
                    478: <H3>Description</H3>
                    479: <P>Lock a routing table, because it's in use by a protocol,
                    480: preventing it from being freed when it gets undefined in a new
                    481: configuration.
                    482: 
                    483: 
                    484: <HR><H3>Function</H3>
                    485: <P><I>void</I>
                    486: <B>rt_unlock_table</B>
                    487: (<I>rtable *</I> <B>r</B>) --     unlock a routing table
                    488: <P>
                    489: <H3>Arguments</H3>
                    490: <P>
                    491: <DL>
                    492: <DT><I>rtable *</I> <B>r</B><DD><P>routing table to be unlocked
                    493: </DL>
                    494: <H3>Description</H3>
                    495: <P>Unlock a routing table formerly locked by <B>rt_lock_table()</B>,
                    496: that is decrease its use count and delete it if it's scheduled
                    497: for deletion by configuration changes.
                    498: 
                    499: 
                    500: <HR><H3>Function</H3>
                    501: <P><I>void</I>
                    502: <B>rt_commit</B>
                    503: (<I>struct config *</I> <B>new</B>, <I>struct config *</I> <B>old</B>) --     commit new routing table configuration
                    504: <P>
                    505: <H3>Arguments</H3>
                    506: <P>
                    507: <DL>
                    508: <DT><I>struct config *</I> <B>new</B><DD><P>new configuration
                    509: <DT><I>struct config *</I> <B>old</B><DD><P>original configuration or <I>NULL</I> if it's boot time config
                    510: </DL>
                    511: <H3>Description</H3>
                    512: <P>Scan differences between <B>old</B> and <B>new</B> configuration and modify
                    513: the routing tables according to these changes. If <B>new</B> defines a
                    514: previously unknown table, create it, if it omits a table existing
                    515: in <B>old</B>, schedule it for deletion (it gets deleted when all protocols
                    516: disconnect from it by calling <B>rt_unlock_table()</B>), if it exists
                    517: in both configurations, leave it unchanged.
                    518: 
                    519: 
                    520: <HR><H3>Function</H3>
                    521: <P><I>int</I>
                    522: <B>rt_feed_baby</B>
                    523: (<I>struct proto *</I> <B>p</B>) --     advertise routes to a new protocol
                    524: <P>
                    525: <H3>Arguments</H3>
                    526: <P>
                    527: <DL>
                    528: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol to be fed
                    529: </DL>
                    530: <H3>Description</H3>
                    531: <P>This function performs one pass of advertisement of routes to a newly
                    532: initialized protocol. It's called by the protocol code as long as it
                    533: has something to do. (We avoid transferring all the routes in single
                    534: pass in order not to monopolize CPU time.)
                    535: 
                    536: 
                    537: <HR><H3>Function</H3>
                    538: <P><I>void</I>
                    539: <B>rt_feed_baby_abort</B>
                    540: (<I>struct proto *</I> <B>p</B>) --     abort protocol feeding
                    541: <P>
                    542: <H3>Arguments</H3>
                    543: <P>
                    544: <DL>
                    545: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol
                    546: </DL>
                    547: <H3>Description</H3>
                    548: <P>This function is called by the protocol code when the protocol
                    549: stops or ceases to exist before the last iteration of <B>rt_feed_baby()</B>
                    550: has finished.
                    551: 
                    552: 
                    553: <HR><H3>Function</H3>
                    554: <P><I>net *</I>
                    555: <B>net_find</B>
                    556: (<I>rtable *</I> <B>tab</B>, <I>ip_addr</I> <B>addr</B>, <I>unsigned</I> <B>len</B>) --     find a network entry
                    557: <P>
                    558: <H3>Arguments</H3>
                    559: <P>
                    560: <DL>
                    561: <DT><I>rtable *</I> <B>tab</B><DD><P>a routing table
                    562: <DT><I>ip_addr</I> <B>addr</B><DD><P>address of the network
                    563: <DT><I>unsigned</I> <B>len</B><DD><P>length of the network prefix
                    564: </DL>
                    565: <H3>Description</H3>
                    566: <P><B>net_find()</B> looks up the given network in routing table <B>tab</B> and
                    567: returns a pointer to its <I>net</I> entry or <I>NULL</I> if no such network
                    568: exists.
                    569: 
                    570: 
                    571: <HR><H3>Function</H3>
                    572: <P><I>net *</I>
                    573: <B>net_get</B>
                    574: (<I>rtable *</I> <B>tab</B>, <I>ip_addr</I> <B>addr</B>, <I>unsigned</I> <B>len</B>) --     obtain a network entry
                    575: <P>
                    576: <H3>Arguments</H3>
                    577: <P>
                    578: <DL>
                    579: <DT><I>rtable *</I> <B>tab</B><DD><P>a routing table
                    580: <DT><I>ip_addr</I> <B>addr</B><DD><P>address of the network
                    581: <DT><I>unsigned</I> <B>len</B><DD><P>length of the network prefix
                    582: </DL>
                    583: <H3>Description</H3>
                    584: <P><B>net_get()</B> looks up the given network in routing table <B>tab</B> and
                    585: returns a pointer to its <I>net</I> entry. If no such entry exists, it's
                    586: created.
                    587: 
                    588: 
                    589: <HR><H3>Function</H3>
                    590: <P><I>rte *</I>
                    591: <B>rte_cow</B>
                    592: (<I>rte *</I> <B>r</B>) --     copy a route for writing
                    593: <P>
                    594: <H3>Arguments</H3>
                    595: <P>
                    596: <DL>
                    597: <DT><I>rte *</I> <B>r</B><DD><P>a route entry to be copied
                    598: </DL>
                    599: <H3>Description</H3>
                    600: <P><B>rte_cow()</B> takes a <I>rte</I> and prepares it for modification. The exact action
                    601: taken depends on the flags of the <I>rte</I> -- if it's a temporary entry, it's
                    602: just returned unchanged, else a new temporary entry with the same contents
                    603: is created.
                    604: <P>The primary use of this function is inside the filter machinery -- when
                    605: a filter wants to modify <I>rte</I> contents (to change the preference or to
                    606: attach another set of attributes), it must ensure that the <I>rte</I> is not
                    607: shared with anyone else (and especially that it isn't stored in any routing
                    608: table).
                    609: <H3>Result</H3>
                    610: <P>a pointer to the new writable <I>rte</I>.
                    611: 
                    612: <H2><A NAME="ss2.3">2.3</A> <A HREF="prog.html#toc2.3">Route attribute cache</A>
                    613: </H2>
                    614: 
                    615: <P>
                    616: <P>Each route entry carries a set of route attributes. Several of them
                    617: vary from route to route, but most attributes are usually common
                    618: for a large number of routes. To conserve memory, we've decided to
                    619: store only the varying ones directly in the <I>rte</I> and hold the rest
                    620: in a special structure called <I>rta</I> which is shared among all the
                    621: <I>rte</I>'s with these attributes.
                    622: <P>Each <I>rta</I> contains all the static attributes of the route (i.e.,
                    623: those which are always present) as structure members and a list of
                    624: dynamic attributes represented by a linked list of <I>ea_list</I>
                    625: structures, each of them consisting of an array of <I>eattr</I>'s containing
                    626: the individual attributes. An attribute can be specified more than once
                    627: in the <I>ea_list</I> chain and in such case the first occurrence overrides
                    628: the others. This semantics is used especially when someone (for example
                    629: a filter) wishes to alter values of several dynamic attributes, but
                    630: it wants to preserve the original attribute lists maintained by
                    631: another module.
                    632: <P>Each <I>eattr</I> contains an attribute identifier (split to protocol ID and
                    633: per-protocol attribute ID), protocol dependent flags, a type code (consisting
                    634: of several bit fields describing attribute characteristics) and either an
                    635: embedded 32-bit value or a pointer to a <I>adata</I> structure holding attribute
                    636: contents.
                    637: <P>There exist two variants of <I>rta</I>'s -- cached and un-cached ones. Un-cached
                    638: <I>rta</I>'s can have arbitrarily complex structure of <I>ea_list</I>'s and they
                    639: can be modified by any module in the route processing chain. Cached
                    640: <I>rta</I>'s have their attribute lists normalized (that means at most one
                    641: <I>ea_list</I> is present and its values are sorted in order to speed up
                    642: searching), they are stored in a hash table to make fast lookup possible
                    643: and they are provided with a use count to allow sharing.
                    644: <P>Routing tables always contain only cached <I>rta</I>'s.
                    645: <P>
                    646: <P><HR><H3>Function</H3>
                    647: <P><I>struct mpnh *</I>
                    648: <B>mpnh_merge</B>
                    649: (<I>struct mpnh *</I> <B>x</B>, <I>struct mpnh *</I> <B>y</B>, <I>int</I> <B>rx</B>, <I>int</I> <B>ry</B>, <I>int</I> <B>max</B>, <I>linpool *</I> <B>lp</B>) --     merge nexthop lists
                    650: <P>
                    651: <H3>Arguments</H3>
                    652: <P>
                    653: <DL>
                    654: <DT><I>struct mpnh *</I> <B>x</B><DD><P>list 1
                    655: <DT><I>struct mpnh *</I> <B>y</B><DD><P>list 2
                    656: <DT><I>int</I> <B>rx</B><DD><P>reusability of list <B>x</B>
                    657: <DT><I>int</I> <B>ry</B><DD><P>reusability of list <B>y</B>
                    658: <DT><I>int</I> <B>max</B><DD><P>max number of nexthops
                    659: <DT><I>linpool *</I> <B>lp</B><DD><P>linpool for allocating nexthops
                    660: </DL>
                    661: <H3>Description</H3>
                    662: <P>The <B>mpnh_merge()</B> function takes two nexthop lists <B>x</B> and <B>y</B> and merges them,
                    663: eliminating possible duplicates. The input lists must be sorted and the
                    664: result is sorted too. The number of nexthops in result is limited by <B>max</B>.
                    665: New nodes are allocated from linpool <B>lp</B>.
                    666: <P>The arguments <B>rx</B> and <B>ry</B> specify whether corresponding input lists may be
                    667: consumed by the function (i.e. their nodes reused in the resulting list), in
                    668: that case the caller should not access these lists after that. To eliminate
                    669: issues with deallocation of these lists, the caller should use some form of
                    670: bulk deallocation (e.g. stack or linpool) to free these nodes when the
                    671: resulting list is no longer needed. When reusability is not set, the
                    672: corresponding lists are not modified nor linked from the resulting list.
                    673: 
                    674: 
                    675: <HR><H3>Function</H3>
                    676: <P><I>eattr *</I>
                    677: <B>ea_find</B>
                    678: (<I>ea_list *</I> <B>e</B>, <I>unsigned</I> <B>id</B>) --     find an extended attribute
                    679: <P>
                    680: <H3>Arguments</H3>
                    681: <P>
                    682: <DL>
                    683: <DT><I>ea_list *</I> <B>e</B><DD><P>attribute list to search in
                    684: <DT><I>unsigned</I> <B>id</B><DD><P>attribute ID to search for
                    685: </DL>
                    686: <H3>Description</H3>
                    687: <P>Given an extended attribute list, <B>ea_find()</B> searches for a first
                    688: occurrence of an attribute with specified ID, returning either a pointer
                    689: to its <I>eattr</I> structure or <I>NULL</I> if no such attribute exists.
                    690: 
                    691: 
                    692: <HR><H3>Function</H3>
                    693: <P><I>eattr *</I>
                    694: <B>ea_walk</B>
                    695: (<I>struct ea_walk_state *</I> <B>s</B>, <I>uint</I> <B>id</B>, <I>uint</I> <B>max</B>) --     walk through extended attributes
                    696: <P>
                    697: <H3>Arguments</H3>
                    698: <P>
                    699: <DL>
                    700: <DT><I>struct ea_walk_state *</I> <B>s</B><DD><P>walk state structure
                    701: <DT><I>uint</I> <B>id</B><DD><P>start of attribute ID interval
                    702: <DT><I>uint</I> <B>max</B><DD><P>length of attribute ID interval
                    703: </DL>
                    704: <H3>Description</H3>
                    705: <P>Given an extended attribute list, <B>ea_walk()</B> walks through the list looking
                    706: for first occurrences of attributes with ID in specified interval from <B>id</B> to
                    707: (<B>id</B> + <B>max</B> - 1), returning pointers to found <I>eattr</I> structures, storing its
                    708: walk state in <B>s</B> for subsequent calls.
                    709: <P>The function <B>ea_walk()</B> is supposed to be called in a loop, with initially
                    710: zeroed walk state structure <B>s</B> with filled the initial extended attribute
                    711: list, returning one found attribute in each call or <I>NULL</I> when no other
                    712: attribute exists. The extended attribute list or the arguments should not be
                    713: modified between calls. The maximum value of <B>max</B> is 128.
                    714: 
                    715: 
                    716: <HR><H3>Function</H3>
                    717: <P><I>int</I>
                    718: <B>ea_get_int</B>
                    719: (<I>ea_list *</I> <B>e</B>, <I>unsigned</I> <B>id</B>, <I>int</I> <B>def</B>) --     fetch an integer attribute
                    720: <P>
                    721: <H3>Arguments</H3>
                    722: <P>
                    723: <DL>
                    724: <DT><I>ea_list *</I> <B>e</B><DD><P>attribute list
                    725: <DT><I>unsigned</I> <B>id</B><DD><P>attribute ID
                    726: <DT><I>int</I> <B>def</B><DD><P>default value
                    727: </DL>
                    728: <H3>Description</H3>
                    729: <P>This function is a shortcut for retrieving a value of an integer attribute
                    730: by calling <B>ea_find()</B> to find the attribute, extracting its value or returning
                    731: a provided default if no such attribute is present.
                    732: 
                    733: 
                    734: <HR><H3>Function</H3>
                    735: <P><I>void</I>
                    736: <B>ea_sort</B>
                    737: (<I>ea_list *</I> <B>e</B>) --     sort an attribute list
                    738: <P>
                    739: <H3>Arguments</H3>
                    740: <P>
                    741: <DL>
                    742: <DT><I>ea_list *</I> <B>e</B><DD><P>list to be sorted
                    743: </DL>
                    744: <H3>Description</H3>
                    745: <P>This function takes a <I>ea_list</I> chain and sorts the attributes
                    746: within each of its entries.
                    747: <P>If an attribute occurs multiple times in a single <I>ea_list</I>,
                    748: <B>ea_sort()</B> leaves only the first (the only significant) occurrence.
                    749: 
                    750: 
                    751: <HR><H3>Function</H3>
                    752: <P><I>unsigned</I>
                    753: <B>ea_scan</B>
                    754: (<I>ea_list *</I> <B>e</B>) --     estimate attribute list size
                    755: <P>
                    756: <H3>Arguments</H3>
                    757: <P>
                    758: <DL>
                    759: <DT><I>ea_list *</I> <B>e</B><DD><P>attribute list
                    760: </DL>
                    761: <H3>Description</H3>
                    762: <P>This function calculates an upper bound of the size of
                    763: a given <I>ea_list</I> after merging with <B>ea_merge()</B>.
                    764: 
                    765: 
                    766: <HR><H3>Function</H3>
                    767: <P><I>void</I>
                    768: <B>ea_merge</B>
                    769: (<I>ea_list *</I> <B>e</B>, <I>ea_list *</I> <B>t</B>) --     merge segments of an attribute list
                    770: <P>
                    771: <H3>Arguments</H3>
                    772: <P>
                    773: <DL>
                    774: <DT><I>ea_list *</I> <B>e</B><DD><P>attribute list
                    775: <DT><I>ea_list *</I> <B>t</B><DD><P>buffer to store the result to
                    776: </DL>
                    777: <H3>Description</H3>
                    778: <P>This function takes a possibly multi-segment attribute list
                    779: and merges all of its segments to one.
                    780: <P>The primary use of this function is for <I>ea_list</I> normalization:
                    781: first call <B>ea_scan()</B> to determine how much memory will the result
                    782: take, then allocate a buffer (usually using <B>alloca()</B>), merge the
                    783: segments with <B>ea_merge()</B> and finally sort and prune the result
                    784: by calling <B>ea_sort()</B>.
                    785: 
                    786: 
                    787: <HR><H3>Function</H3>
                    788: <P><I>int</I>
                    789: <B>ea_same</B>
                    790: (<I>ea_list *</I> <B>x</B>, <I>ea_list *</I> <B>y</B>) --     compare two <I>ea_list</I>'s
                    791: <P>
                    792: <H3>Arguments</H3>
                    793: <P>
                    794: <DL>
                    795: <DT><I>ea_list *</I> <B>x</B><DD><P>attribute list
                    796: <DT><I>ea_list *</I> <B>y</B><DD><P>attribute list
                    797: </DL>
                    798: <H3>Description</H3>
                    799: <P><B>ea_same()</B> compares two normalized attribute lists <B>x</B> and <B>y</B> and returns
                    800: 1 if they contain the same attributes, 0 otherwise.
                    801: 
                    802: 
                    803: <HR><H3>Function</H3>
                    804: <P><I>void</I>
                    805: <B>ea_show</B>
                    806: (<I>struct cli *</I> <B>c</B>, <I>eattr *</I> <B>e</B>) --     print an <I>eattr</I> to CLI
                    807: <P>
                    808: <H3>Arguments</H3>
                    809: <P>
                    810: <DL>
                    811: <DT><I>struct cli *</I> <B>c</B><DD><P>destination CLI
                    812: <DT><I>eattr *</I> <B>e</B><DD><P>attribute to be printed
                    813: </DL>
                    814: <H3>Description</H3>
                    815: <P>This function takes an extended attribute represented by its <I>eattr</I>
                    816: structure and prints it to the CLI according to the type information.
                    817: <P>If the protocol defining the attribute provides its own
                    818: <B>get_attr()</B> hook, it's consulted first.
                    819: 
                    820: 
                    821: <HR><H3>Function</H3>
                    822: <P><I>void</I>
                    823: <B>ea_dump</B>
                    824: (<I>ea_list *</I> <B>e</B>) --     dump an extended attribute
                    825: <P>
                    826: <H3>Arguments</H3>
                    827: <P>
                    828: <DL>
                    829: <DT><I>ea_list *</I> <B>e</B><DD><P>attribute to be dumped
                    830: </DL>
                    831: <H3>Description</H3>
                    832: <P><B>ea_dump()</B> dumps contents of the extended attribute given to
                    833: the debug output.
                    834: 
                    835: 
                    836: <HR><H3>Function</H3>
                    837: <P><I>uint</I>
                    838: <B>ea_hash</B>
                    839: (<I>ea_list *</I> <B>e</B>) --     calculate an <I>ea_list</I> hash key
                    840: <P>
                    841: <H3>Arguments</H3>
                    842: <P>
                    843: <DL>
                    844: <DT><I>ea_list *</I> <B>e</B><DD><P>attribute list
                    845: </DL>
                    846: <H3>Description</H3>
                    847: <P><B>ea_hash()</B> takes an extended attribute list and calculated a hopefully
                    848: uniformly distributed hash value from its contents.
                    849: 
                    850: 
                    851: <HR><H3>Function</H3>
                    852: <P><I>ea_list *</I>
                    853: <B>ea_append</B>
                    854: (<I>ea_list *</I> <B>to</B>, <I>ea_list *</I> <B>what</B>) --     concatenate <I>ea_list</I>'s
                    855: <P>
                    856: <H3>Arguments</H3>
                    857: <P>
                    858: <DL>
                    859: <DT><I>ea_list *</I> <B>to</B><DD><P>destination list (can be <I>NULL</I>)
                    860: <DT><I>ea_list *</I> <B>what</B><DD><P>list to be appended (can be <I>NULL</I>)
                    861: </DL>
                    862: <H3>Description</H3>
                    863: <P>This function appends the <I>ea_list</I> <B>what</B> at the end of
                    864: <I>ea_list</I> <B>to</B> and returns a pointer to the resulting list.
                    865: 
                    866: 
                    867: <HR><H3>Function</H3>
                    868: <P><I>rta *</I>
                    869: <B>rta_lookup</B>
                    870: (<I>rta *</I> <B>o</B>) --     look up a <I>rta</I> in attribute cache
                    871: <P>
                    872: <H3>Arguments</H3>
                    873: <P>
                    874: <DL>
                    875: <DT><I>rta *</I> <B>o</B><DD><P>a un-cached <I>rta</I>
                    876: </DL>
                    877: <H3>Description</H3>
                    878: <P><B>rta_lookup()</B> gets an un-cached <I>rta</I> structure and returns its cached
                    879: counterpart. It starts with examining the attribute cache to see whether
                    880: there exists a matching entry. If such an entry exists, it's returned and
                    881: its use count is incremented, else a new entry is created with use count
                    882: set to 1.
                    883: <P>The extended attribute lists attached to the <I>rta</I> are automatically
                    884: converted to the normalized form.
                    885: 
                    886: 
                    887: <HR><H3>Function</H3>
                    888: <P><I>void</I>
                    889: <B>rta_dump</B>
                    890: (<I>rta *</I> <B>a</B>) --     dump route attributes
                    891: <P>
                    892: <H3>Arguments</H3>
                    893: <P>
                    894: <DL>
                    895: <DT><I>rta *</I> <B>a</B><DD><P>attribute structure to dump
                    896: </DL>
                    897: <H3>Description</H3>
                    898: <P>This function takes a <I>rta</I> and dumps its contents to the debug output.
                    899: 
                    900: 
                    901: <HR><H3>Function</H3>
                    902: <P><I>void</I>
                    903: <B>rta_dump_all</B>
                    904: (<B>void</B>) --     dump attribute cache
                    905: <P>
                    906: <H3>Description</H3>
                    907: <P>
                    908: <P>This function dumps the whole contents of route attribute cache
                    909: to the debug output.
                    910: 
                    911: 
                    912: <HR><H3>Function</H3>
                    913: <P><I>void</I>
                    914: <B>rta_init</B>
                    915: (<B>void</B>) --     initialize route attribute cache
                    916: <P>
                    917: <H3>Description</H3>
                    918: <P>
                    919: <P>This function is called during initialization of the routing
                    920: table module to set up the internals of the attribute cache.
                    921: 
                    922: 
                    923: <HR><H3>Function</H3>
                    924: <P><I>rta *</I>
                    925: <B>rta_clone</B>
                    926: (<I>rta *</I> <B>r</B>) --     clone route attributes
                    927: <P>
                    928: <H3>Arguments</H3>
                    929: <P>
                    930: <DL>
                    931: <DT><I>rta *</I> <B>r</B><DD><P>a <I>rta</I> to be cloned
                    932: </DL>
                    933: <H3>Description</H3>
                    934: <P><B>rta_clone()</B> takes a cached <I>rta</I> and returns its identical cached
                    935: copy. Currently it works by just returning the original <I>rta</I> with
                    936: its use count incremented.
                    937: 
                    938: 
                    939: <HR><H3>Function</H3>
                    940: <P><I>void</I>
                    941: <B>rta_free</B>
                    942: (<I>rta *</I> <B>r</B>) --     free route attributes
                    943: <P>
                    944: <H3>Arguments</H3>
                    945: <P>
                    946: <DL>
                    947: <DT><I>rta *</I> <B>r</B><DD><P>a <I>rta</I> to be freed
                    948: </DL>
                    949: <H3>Description</H3>
                    950: <P>If you stop using a <I>rta</I> (for example when deleting a route which uses
                    951: it), you need to call <B>rta_free()</B> to notify the attribute cache the
                    952: attribute is no longer in use and can be freed if you were the last
                    953: user (which <B>rta_free()</B> tests by inspecting the use count).
                    954: 
                    955: <P>
                    956: <H2><A NAME="ss2.4">2.4</A> <A HREF="prog.html#toc2.4">Routing protocols</A>
                    957: </H2>
                    958: 
                    959: <H3>Introduction</H3>
                    960: 
                    961: <P>The routing protocols are the bird's heart and a fine amount of code
                    962: is dedicated to their management and for providing support functions to them.
                    963: (-: Actually, this is the reason why the directory with sources of the core
                    964: code is called <CODE>nest</CODE> :-).
                    965: <P>
                    966: <P>When talking about protocols, one need to distinguish between <EM>protocols</EM>
                    967: and protocol <EM>instances</EM>. A protocol exists exactly once, not depending on whether
                    968: it's configured or not and it can have an arbitrary number of instances corresponding
                    969: to its "incarnations" requested by the configuration file. Each instance is completely
                    970: autonomous, has its own configuration, its own status, its own set of routes and its
                    971: own set of interfaces it works on.
                    972: <P>
                    973: <P>A protocol is represented by a <I>protocol</I> structure containing all the basic
                    974: information (protocol name, default settings and pointers to most of the protocol
                    975: hooks). All these structures are linked in the <B>protocol_list</B> list.
                    976: <P>
                    977: <P>Each instance has its own <I>proto</I> structure describing all its properties: protocol
                    978: type, configuration, a resource pool where all resources belonging to the instance
                    979: live, various protocol attributes (take a look at the declaration of <I>proto</I> in
                    980: <CODE>protocol.h</CODE>), protocol states (see below for what do they mean), connections
                    981: to routing tables, filters attached to the protocol
                    982: and finally a set of pointers to the rest of protocol hooks (they
                    983: are the same for all instances of the protocol, but in order to avoid extra
                    984: indirections when calling the hooks from the fast path, they are stored directly
                    985: in <I>proto</I>). The instance is always linked in both the global instance list
                    986: (<B>proto_list</B>) and a per-status list (either <B>active_proto_list</B> for
                    987: running protocols, <B>initial_proto_list</B> for protocols being initialized or
                    988: <B>flush_proto_list</B> when the protocol is being shut down).
                    989: <P>
                    990: <P>The protocol hooks are described in the next chapter, for more information about
                    991: configuration of protocols, please refer to the configuration chapter and also
                    992: to the description of the <B>proto_commit</B> function.
                    993: <P>
                    994: <H3>Protocol states</H3>
                    995: 
                    996: <P>As startup and shutdown of each protocol are complex processes which can be affected
                    997: by lots of external events (user's actions, reconfigurations, behavior of neighboring routers etc.),
                    998: we have decided to supervise them by a pair of simple state machines -- the protocol
                    999: state machine and a core state machine.
                   1000: <P>
                   1001: <P>The <EM>protocol state machine</EM> corresponds to internal state of the protocol
                   1002: and the protocol can alter its state whenever it wants to. There are
                   1003: the following states:
                   1004: <P>
                   1005: <DL>
                   1006: <DT><CODE>PS_DOWN</CODE><DD><P>The protocol is down and waits for being woken up by calling its
                   1007: start() hook.
                   1008: <DT><CODE>PS_START</CODE><DD><P>The protocol is waiting for connection with the rest of the
                   1009: network. It's active, it has resources allocated, but it still doesn't want
                   1010: any routes since it doesn't know what to do with them.
                   1011: <DT><CODE>PS_UP</CODE><DD><P>The protocol is up and running. It communicates with the core,
                   1012: delivers routes to tables and wants to hear announcement about route changes.
                   1013: <DT><CODE>PS_STOP</CODE><DD><P>The protocol has been shut down (either by being asked by the
                   1014: core code to do so or due to having encountered a protocol error).
                   1015: </DL>
                   1016: <P>
                   1017: <P>Unless the protocol is in the <CODE>PS_DOWN</CODE> state, it can decide to change
                   1018: its state by calling the <B>proto_notify_state</B> function.
                   1019: <P>
                   1020: <P>At any time, the core code can ask the protocol to shut itself down by calling its stop() hook.
                   1021: <P>
                   1022: <P>The <EM>core state machine</EM> takes care of the core view of protocol state.
                   1023: The states are traversed according to changes of the protocol state machine, but
                   1024: sometimes the transitions are delayed if the core needs to finish some actions
                   1025: (for example sending of new routes to the protocol) before proceeding to the
                   1026: new state. There are the following core states:
                   1027: <P>
                   1028: <DL>
                   1029: <DT><CODE>FS_HUNGRY</CODE><DD><P>The protocol is down, it doesn't have any routes and
                   1030: doesn't want them.
                   1031: <DT><CODE>FS_FEEDING</CODE><DD><P>The protocol has reached the <CODE>PS_UP</CODE> state, but
                   1032: we are still busy sending the initial set of routes to it.
                   1033: <DT><CODE>FS_HAPPY</CODE><DD><P>The protocol is up and has complete routing information.
                   1034: <DT><CODE>FS_FLUSHING</CODE><DD><P>The protocol is shutting down (it's in either <CODE>PS_STOP</CODE>
                   1035: or <CODE>PS_DOWN</CODE> state) and we're flushing all of its routes from the
                   1036: routing tables.
                   1037: </DL>
                   1038: <P>
                   1039: <H3>Functions of the protocol module</H3>
                   1040: 
                   1041: <P>The protocol module provides the following functions:
                   1042: <HR><H3>Function</H3>
                   1043: <P><I>void *</I>
                   1044: <B>proto_new</B>
                   1045: (<I>struct proto_config *</I> <B>c</B>, <I>unsigned</I> <B>size</B>) --  create a new protocol instance
                   1046: <P>
                   1047: <H3>Arguments</H3>
                   1048: <P>
                   1049: <DL>
                   1050: <DT><I>struct proto_config *</I> <B>c</B><DD><P>protocol configuration
                   1051: <DT><I>unsigned</I> <B>size</B><DD><P>size of protocol data structure (each protocol instance is represented by
                   1052: a structure starting with generic part [struct <I>proto</I>] and continued
                   1053: with data specific to the protocol)
                   1054: </DL>
                   1055: <H3>Description</H3>
                   1056: <P>When a new configuration has been read in, the core code starts
                   1057: initializing all the protocol instances configured by calling their
                   1058: <B>init()</B> hooks with the corresponding instance configuration. The initialization
                   1059: code of the protocol is expected to create a new instance according to the
                   1060: configuration by calling this function and then modifying the default settings
                   1061: to values wanted by the protocol.
                   1062: 
                   1063: 
                   1064: <HR><H3>Function</H3>
                   1065: <P><I>struct announce_hook *</I>
                   1066: <B>proto_add_announce_hook</B>
                   1067: (<I>struct proto *</I> <B>p</B>, <I>struct rtable *</I> <B>t</B>, <I>struct proto_stats *</I> <B>stats</B>) --  connect protocol to a routing table
                   1068: <P>
                   1069: <H3>Arguments</H3>
                   1070: <P>
                   1071: <DL>
                   1072: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
                   1073: <DT><I>struct rtable *</I> <B>t</B><DD><P>routing table to connect to
                   1074: <DT><I>struct proto_stats *</I> <B>stats</B><DD><P>per-table protocol statistics
                   1075: </DL>
                   1076: <H3>Description</H3>
                   1077: <P>This function creates a connection between the protocol instance <B>p</B> and the
                   1078: routing table <B>t</B>, making the protocol hear all changes in the table.
                   1079: <P>The announce hook is linked in the protocol ahook list. Announce hooks are
                   1080: allocated from the routing table resource pool and when protocol accepts
                   1081: routes also in the table ahook list. The are linked to the table ahook list
                   1082: and unlinked from it depending on export_state (in <B>proto_want_export_up()</B> and
                   1083: <B>proto_want_export_down()</B>) and they are automatically freed after the protocol
                   1084: is flushed (in <B>proto_fell_down()</B>).
                   1085: <P>Unless you want to listen to multiple routing tables (as the Pipe protocol
                   1086: does), you needn't to worry about this function since the connection to the
                   1087: protocol's primary routing table is initialized automatically by the core
                   1088: code.
                   1089: 
                   1090: 
                   1091: <HR><H3>Function</H3>
                   1092: <P><I>struct announce_hook *</I>
                   1093: <B>proto_find_announce_hook</B>
                   1094: (<I>struct proto *</I> <B>p</B>, <I>struct rtable *</I> <B>t</B>) --  find announce hooks
                   1095: <P>
                   1096: <H3>Arguments</H3>
                   1097: <P>
                   1098: <DL>
                   1099: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
                   1100: <DT><I>struct rtable *</I> <B>t</B><DD><P>routing table
                   1101: </DL>
                   1102: <H3>Description</H3>
                   1103: <P>Returns pointer to announce hook or NULL
                   1104: 
                   1105: 
                   1106: <HR><H3>Function</H3>
                   1107: <P><I>void *</I>
                   1108: <B>proto_config_new</B>
                   1109: (<I>struct protocol *</I> <B>pr</B>, <I>int</I> <B>class</B>) --  create a new protocol configuration
                   1110: <P>
                   1111: <H3>Arguments</H3>
                   1112: <P>
                   1113: <DL>
                   1114: <DT><I>struct protocol *</I> <B>pr</B><DD><P>protocol the configuration will belong to
                   1115: <DT><I>int</I> <B>class</B><DD><P>SYM_PROTO or SYM_TEMPLATE
                   1116: </DL>
                   1117: <H3>Description</H3>
                   1118: <P>Whenever the configuration file says that a new instance
                   1119: of a routing protocol should be created, the parser calls
                   1120: <B>proto_config_new()</B> to create a configuration entry for this
                   1121: instance (a structure staring with the <I>proto_config</I> header
                   1122: containing all the generic items followed by protocol-specific
                   1123: ones). Also, the configuration entry gets added to the list
                   1124: of protocol instances kept in the configuration.
                   1125: <P>The function is also used to create protocol templates (when class
                   1126: SYM_TEMPLATE is specified), the only difference is that templates
                   1127: are not added to the list of protocol instances and therefore not
                   1128: initialized during <B>protos_commit()</B>).
                   1129: 
                   1130: 
                   1131: <HR><H3>Function</H3>
                   1132: <P><I>void</I>
                   1133: <B>proto_copy_config</B>
                   1134: (<I>struct proto_config *</I> <B>dest</B>, <I>struct proto_config *</I> <B>src</B>) --  copy a protocol configuration
                   1135: <P>
                   1136: <H3>Arguments</H3>
                   1137: <P>
                   1138: <DL>
                   1139: <DT><I>struct proto_config *</I> <B>dest</B><DD><P>destination protocol configuration
                   1140: <DT><I>struct proto_config *</I> <B>src</B><DD><P>source protocol configuration
                   1141: </DL>
                   1142: <H3>Description</H3>
                   1143: <P>Whenever a new instance of a routing protocol is created from the
                   1144: template, <B>proto_copy_config()</B> is called to copy a content of
                   1145: the source protocol configuration to the new protocol configuration.
                   1146: Name, class and a node in protos list of <B>dest</B> are kept intact.
                   1147: <B>copy_config()</B> protocol hook is used to copy protocol-specific data.
                   1148: 
                   1149: 
                   1150: <HR><H3>Function</H3>
                   1151: <P><I>void</I>
                   1152: <B>protos_preconfig</B>
                   1153: (<I>struct config *</I> <B>c</B>) --  pre-configuration processing
                   1154: <P>
                   1155: <H3>Arguments</H3>
                   1156: <P>
                   1157: <DL>
                   1158: <DT><I>struct config *</I> <B>c</B><DD><P>new configuration
                   1159: </DL>
                   1160: <H3>Description</H3>
                   1161: <P>This function calls the <B>preconfig()</B> hooks of all routing
                   1162: protocols available to prepare them for reading of the new
                   1163: configuration.
                   1164: 
                   1165: 
                   1166: <HR><H3>Function</H3>
                   1167: <P><I>void</I>
                   1168: <B>protos_postconfig</B>
                   1169: (<I>struct config *</I> <B>c</B>) --  post-configuration processing
                   1170: <P>
                   1171: <H3>Arguments</H3>
                   1172: <P>
                   1173: <DL>
                   1174: <DT><I>struct config *</I> <B>c</B><DD><P>new configuration
                   1175: </DL>
                   1176: <H3>Description</H3>
                   1177: <P>This function calls the <B>postconfig()</B> hooks of all protocol
                   1178: instances specified in configuration <B>c</B>. The hooks are not
                   1179: called for protocol templates.
                   1180: 
                   1181: 
                   1182: <HR><H3>Function</H3>
                   1183: <P><I>void</I>
                   1184: <B>protos_commit</B>
                   1185: (<I>struct config *</I> <B>new</B>, <I>struct config *</I> <B>old</B>, <I>int</I> <B>force_reconfig</B>, <I>int</I> <B>type</B>) --  commit new protocol configuration
                   1186: <P>
                   1187: <H3>Arguments</H3>
                   1188: <P>
                   1189: <DL>
                   1190: <DT><I>struct config *</I> <B>new</B><DD><P>new configuration
                   1191: <DT><I>struct config *</I> <B>old</B><DD><P>old configuration or <I>NULL</I> if it's boot time config
                   1192: <DT><I>int</I> <B>force_reconfig</B><DD><P>force restart of all protocols (used for example
                   1193: when the router ID changes)
                   1194: <DT><I>int</I> <B>type</B><DD><P>type of reconfiguration (RECONFIG_SOFT or RECONFIG_HARD)
                   1195: </DL>
                   1196: <H3>Description</H3>
                   1197: <P>Scan differences between <B>old</B> and <B>new</B> configuration and adjust all
                   1198: protocol instances to conform to the new configuration.
                   1199: <P>When a protocol exists in the new configuration, but it doesn't in the
                   1200: original one, it's immediately started. When a collision with the other
                   1201: running protocol would arise, the new protocol will be temporarily stopped
                   1202: by the locking mechanism.
                   1203: <P>When a protocol exists in the old configuration, but it doesn't in the
                   1204: new one, it's shut down and deleted after the shutdown completes.
                   1205: <P>When a protocol exists in both configurations, the core decides
                   1206: whether it's possible to reconfigure it dynamically - it checks all
                   1207: the core properties of the protocol (changes in filters are ignored
                   1208: if type is RECONFIG_SOFT) and if they match, it asks the
                   1209: <B>reconfigure()</B> hook of the protocol to see if the protocol is able
                   1210: to switch to the new configuration.  If it isn't possible, the
                   1211: protocol is shut down and a new instance is started with the new
                   1212: configuration after the shutdown is completed.
                   1213: 
                   1214: <H2><A NAME="ss2.5">2.5</A> <A HREF="prog.html#toc2.5">Graceful restart recovery</A>
                   1215: </H2>
                   1216: 
                   1217: <P>
                   1218: <P>Graceful restart of a router is a process when the routing plane (e.g. BIRD)
                   1219: restarts but both the forwarding plane (e.g kernel routing table) and routing
                   1220: neighbors keep proper routes, and therefore uninterrupted packet forwarding
                   1221: is maintained.
                   1222: <P>BIRD implements graceful restart recovery by deferring export of routes to
                   1223: protocols until routing tables are refilled with the expected content. After
                   1224: start, protocols generate routes as usual, but routes are not propagated to
                   1225: them, until protocols report that they generated all routes. After that,
                   1226: graceful restart recovery is finished and the export (and the initial feed)
                   1227: to protocols is enabled.
                   1228: <P>When graceful restart recovery need is detected during initialization, then
                   1229: enabled protocols are marked with <B>gr_recovery</B> flag before start. Such
                   1230: protocols then decide how to proceed with graceful restart, participation is
                   1231: voluntary. Protocols could lock the recovery by <B>proto_graceful_restart_lock()</B>
                   1232: (stored in <B>gr_lock</B> flag), which means that they want to postpone the end of
                   1233: the recovery until they converge and then unlock it. They also could set
                   1234: <B>gr_wait</B> before advancing to <I>PS_UP</I>, which means that the core should defer
                   1235: route export to that protocol until the end of the recovery. This should be
                   1236: done by protocols that expect their neigbors to keep the proper routes
                   1237: (kernel table, BGP sessions with BGP graceful restart capability).
                   1238: <P>The graceful restart recovery is finished when either all graceful restart
                   1239: locks are unlocked or when graceful restart wait timer fires.
                   1240: <P>
                   1241: <P><HR><H3>Function</H3>
                   1242: <P><I>void</I>
                   1243: <B>graceful_restart_recovery</B>
                   1244: (<B>void</B>) --     request initial graceful restart recovery
                   1245: <P>
                   1246: <H3>Graceful restart recovery</H3>
                   1247: <P>
                   1248: <P>Called by the platform initialization code if the need for recovery
                   1249: after graceful restart is detected during boot. Have to be called
                   1250: before <B>protos_commit()</B>.
                   1251: 
                   1252: 
                   1253: <HR><H3>Function</H3>
                   1254: <P><I>void</I>
                   1255: <B>graceful_restart_init</B>
                   1256: (<B>void</B>) --     initialize graceful restart
                   1257: <P>
                   1258: <H3>Description</H3>
                   1259: <P>
                   1260: <P>When graceful restart recovery was requested, the function starts an active
                   1261: phase of the recovery and initializes graceful restart wait timer. The
                   1262: function have to be called after <B>protos_commit()</B>.
                   1263: 
                   1264: 
                   1265: <HR><H3>Function</H3>
                   1266: <P><I>void</I>
                   1267: <B>graceful_restart_done</B>
                   1268: (<I>struct timer *t</I> <B>UNUSED</B>) --     finalize graceful restart
                   1269: <P>
                   1270: <H3>Arguments</H3>
                   1271: <P>
                   1272: <DL>
                   1273: <DT><I>struct timer *t</I> <B>UNUSED</B><DD><P>-- undescribed --
                   1274: </DL>
                   1275: <H3>Description</H3>
                   1276: <P>When there are no locks on graceful restart, the functions finalizes the
                   1277: graceful restart recovery. Protocols postponing route export until the end of
                   1278: the recovery are awakened and the export to them is enabled. All other
                   1279: related state is cleared. The function is also called when the graceful
                   1280: restart wait timer fires (but there are still some locks).
                   1281: 
                   1282: 
                   1283: <HR><H3>Function</H3>
                   1284: <P><I>void</I>
                   1285: <B>proto_graceful_restart_lock</B>
                   1286: (<I>struct proto *</I> <B>p</B>) --     lock graceful restart by protocol
                   1287: <P>
                   1288: <H3>Arguments</H3>
                   1289: <P>
                   1290: <DL>
                   1291: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
                   1292: </DL>
                   1293: <H3>Description</H3>
                   1294: <P>This function allows a protocol to postpone the end of graceful restart
                   1295: recovery until it converges. The lock is removed when the protocol calls
                   1296: <B>proto_graceful_restart_unlock()</B> or when the protocol is stopped.
                   1297: <P>The function have to be called during the initial phase of graceful restart
                   1298: recovery and only for protocols that are part of graceful restart (i.e. their
                   1299: <B>gr_recovery</B> is set), which means it should be called from protocol start
                   1300: hooks.
                   1301: 
                   1302: 
                   1303: <HR><H3>Function</H3>
                   1304: <P><I>void</I>
                   1305: <B>proto_graceful_restart_unlock</B>
                   1306: (<I>struct proto *</I> <B>p</B>) --     unlock graceful restart by protocol
                   1307: <P>
                   1308: <H3>Arguments</H3>
                   1309: <P>
                   1310: <DL>
                   1311: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
                   1312: </DL>
                   1313: <H3>Description</H3>
                   1314: <P>This function unlocks a lock from <B>proto_graceful_restart_lock()</B>. It is also
                   1315: automatically called when the lock holding protocol went down.
                   1316: 
                   1317: 
                   1318: <HR><H3>Function</H3>
                   1319: <P><I>void</I>
                   1320: <B>protos_dump_all</B>
                   1321: (<B>void</B>) --     dump status of all protocols
                   1322: <P>
                   1323: <H3>Description</H3>
                   1324: <P>
                   1325: <P>This function dumps status of all existing protocol instances to the
                   1326: debug output. It involves printing of general status information
                   1327: such as protocol states, its position on the protocol lists
                   1328: and also calling of a <B>dump()</B> hook of the protocol to print
                   1329: the internals.
                   1330: 
                   1331: 
                   1332: <HR><H3>Function</H3>
                   1333: <P><I>void</I>
                   1334: <B>proto_build</B>
                   1335: (<I>struct protocol *</I> <B>p</B>) --     make a single protocol available
                   1336: <P>
                   1337: <H3>Arguments</H3>
                   1338: <P>
                   1339: <DL>
                   1340: <DT><I>struct protocol *</I> <B>p</B><DD><P>the protocol
                   1341: </DL>
                   1342: <H3>Description</H3>
                   1343: <P>After the platform specific initialization code uses <B>protos_build()</B>
                   1344: to add all the standard protocols, it should call <B>proto_build()</B> for
                   1345: all platform specific protocols to inform the core that they exist.
                   1346: 
                   1347: 
                   1348: <HR><H3>Function</H3>
                   1349: <P><I>void</I>
                   1350: <B>protos_build</B>
                   1351: (<B>void</B>) --     build a protocol list
                   1352: <P>
                   1353: <H3>Description</H3>
                   1354: <P>
                   1355: <P>This function is called during BIRD startup to insert
                   1356: all standard protocols to the global protocol list. Insertion
                   1357: of platform specific protocols (such as the kernel syncer)
                   1358: is in the domain of competence of the platform dependent
                   1359: startup code.
                   1360: 
                   1361: 
                   1362: <HR><H3>Function</H3>
                   1363: <P><I>void</I>
1.1.1.2 ! misho    1364: <B>proto_set_message</B>
        !          1365: (<I>struct proto *</I> <B>p</B>, <I>char *</I> <B>msg</B>, <I>int</I> <B>len</B>) --     set administrative message to protocol
        !          1366: <P>
        !          1367: <H3>Arguments</H3>
        !          1368: <P>
        !          1369: <DL>
        !          1370: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol
        !          1371: <DT><I>char *</I> <B>msg</B><DD><P>message
        !          1372: <DT><I>int</I> <B>len</B><DD><P>message length (-1 for NULL-terminated string)
        !          1373: </DL>
        !          1374: <H3>Description</H3>
        !          1375: <P>The function sets administrative message (string) related to protocol state
        !          1376: change. It is called by the nest code for manual enable/disable/restart
        !          1377: commands all routes to the protocol, and by protocol-specific code when the
        !          1378: protocol state change is initiated by the protocol. Using NULL message clears
        !          1379: the last message. The message string may be either NULL-terminated or with an
        !          1380: explicit length.
        !          1381: 
        !          1382: 
        !          1383: <HR><H3>Function</H3>
        !          1384: <P><I>void</I>
1.1       misho    1385: <B>proto_request_feeding</B>
                   1386: (<I>struct proto *</I> <B>p</B>) --     request feeding routes to the protocol
                   1387: <P>
                   1388: <H3>Arguments</H3>
                   1389: <P>
                   1390: <DL>
                   1391: <DT><I>struct proto *</I> <B>p</B><DD><P>given protocol 
                   1392: </DL>
                   1393: <H3>Description</H3>
                   1394: <P>Sometimes it is needed to send again all routes to the
                   1395: protocol. This is called feeding and can be requested by this
                   1396: function. This would cause protocol export state transition
                   1397: to ES_FEEDING (during feeding) and when completed, it will
                   1398: switch back to ES_READY. This function can be called even
                   1399: when feeding is already running, in that case it is restarted.
                   1400: 
                   1401: 
                   1402: <HR><H3>Function</H3>
                   1403: <P><I>void</I>
                   1404: <B>proto_notify_limit</B>
                   1405: (<I>struct announce_hook *</I> <B>ah</B>, <I>struct proto_limit *</I> <B>l</B>, <I>int</I> <B>dir</B>, <I>u32</I> <B>rt_count</B>)
                   1406: <H3>Arguments</H3>
                   1407: <P>
                   1408: <DL>
                   1409: <DT><I>struct announce_hook *</I> <B>ah</B><DD><P>announce hook
                   1410: <DT><I>struct proto_limit *</I> <B>l</B><DD><P>limit being hit
                   1411: <DT><I>int</I> <B>dir</B><DD><P>limit direction (PLD_*)
                   1412: <DT><I>u32</I> <B>rt_count</B><DD><P>the number of routes 
                   1413: </DL>
                   1414: <H3>Description</H3>
                   1415: <P>The function is called by the route processing core when limit <B>l</B>
                   1416: is breached. It activates the limit and tooks appropriate action
                   1417: according to <B>l</B>-&gt;action.
                   1418: 
                   1419: 
                   1420: <HR><H3>Function</H3>
                   1421: <P><I>void</I>
                   1422: <B>proto_notify_state</B>
                   1423: (<I>struct proto *</I> <B>p</B>, <I>unsigned</I> <B>ps</B>) --     notify core about protocol state change
                   1424: <P>
                   1425: <H3>Arguments</H3>
                   1426: <P>
                   1427: <DL>
                   1428: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol the state of which has changed
                   1429: <DT><I>unsigned</I> <B>ps</B><DD><P>the new status
                   1430: </DL>
                   1431: <H3>Description</H3>
                   1432: <P>Whenever a state of a protocol changes due to some event internal
                   1433: to the protocol (i.e., not inside a <B>start()</B> or <B>shutdown()</B> hook),
                   1434: it should immediately notify the core about the change by calling
                   1435: <B>proto_notify_state()</B> which will write the new state to the <I>proto</I>
                   1436: structure and take all the actions necessary to adapt to the new
                   1437: state. State change to PS_DOWN immediately frees resources of protocol
                   1438: and might execute start callback of protocol; therefore,
                   1439: it should be used at tail positions of protocol callbacks.
                   1440: 
                   1441: <H2><A NAME="ss2.6">2.6</A> <A HREF="prog.html#toc2.6">Protocol hooks</A>
                   1442: </H2>
                   1443: 
                   1444: <P>
                   1445: <P>Each protocol can provide a rich set of hook functions referred to by pointers
                   1446: in either the <I>proto</I> or <I>protocol</I> structure. They are called by the core whenever
                   1447: it wants the protocol to perform some action or to notify the protocol about
                   1448: any change of its environment. All of the hooks can be set to <I>NULL</I> which means
                   1449: to ignore the change or to take a default action.
                   1450: <P>
                   1451: <P><HR><H3>Function</H3>
                   1452: <P><I>void</I>
                   1453: <B>preconfig</B>
                   1454: (<I>struct protocol *</I> <B>p</B>, <I>struct config *</I> <B>c</B>) --     protocol preconfiguration
                   1455: <P>
                   1456: <H3>Arguments</H3>
                   1457: <P>
                   1458: <DL>
                   1459: <DT><I>struct protocol *</I> <B>p</B><DD><P>a routing protocol
                   1460: <DT><I>struct config *</I> <B>c</B><DD><P>new configuration
                   1461: </DL>
                   1462: <H3>Description</H3>
                   1463: <P>The <B>preconfig()</B> hook is called before parsing of a new configuration.
                   1464: 
                   1465: 
                   1466: <HR><H3>Function</H3>
                   1467: <P><I>void</I>
                   1468: <B>postconfig</B>
                   1469: (<I>struct proto_config *</I> <B>c</B>) --     instance post-configuration
                   1470: <P>
                   1471: <H3>Arguments</H3>
                   1472: <P>
                   1473: <DL>
                   1474: <DT><I>struct proto_config *</I> <B>c</B><DD><P>instance configuration
                   1475: </DL>
                   1476: <H3>Description</H3>
                   1477: <P>The <B>postconfig()</B> hook is called for each configured instance after
                   1478: parsing of the new configuration is finished.
                   1479: 
                   1480: 
                   1481: <HR><H3>Function</H3>
                   1482: <P><I>struct proto *</I>
                   1483: <B>init</B>
                   1484: (<I>struct proto_config *</I> <B>c</B>) --     initialize an instance
                   1485: <P>
                   1486: <H3>Arguments</H3>
                   1487: <P>
                   1488: <DL>
                   1489: <DT><I>struct proto_config *</I> <B>c</B><DD><P>instance configuration
                   1490: </DL>
                   1491: <H3>Description</H3>
                   1492: <P>The <B>init()</B> hook is called by the core to create a protocol instance
                   1493: according to supplied protocol configuration.
                   1494: <H3>Result</H3>
                   1495: <P>a pointer to the instance created
                   1496: 
                   1497: 
                   1498: <HR><H3>Function</H3>
                   1499: <P><I>int</I>
                   1500: <B>reconfigure</B>
                   1501: (<I>struct proto *</I> <B>p</B>, <I>struct proto_config *</I> <B>c</B>) --     request instance reconfiguration
                   1502: <P>
                   1503: <H3>Arguments</H3>
                   1504: <P>
                   1505: <DL>
                   1506: <DT><I>struct proto *</I> <B>p</B><DD><P>an instance
                   1507: <DT><I>struct proto_config *</I> <B>c</B><DD><P>new configuration
                   1508: </DL>
                   1509: <H3>Description</H3>
                   1510: <P>The core calls the <B>reconfigure()</B> hook whenever it wants to ask the
                   1511: protocol for switching to a new configuration. If the reconfiguration
                   1512: is possible, the hook returns 1. Otherwise, it returns 0 and the core
                   1513: will shut down the instance and start a new one with the new configuration.
                   1514: <P>After the protocol confirms reconfiguration, it must no longer keep any
                   1515: references to the old configuration since the memory it's stored in can
                   1516: be re-used at any time.
                   1517: 
                   1518: 
                   1519: <HR><H3>Function</H3>
                   1520: <P><I>void</I>
                   1521: <B>dump</B>
                   1522: (<I>struct proto *</I> <B>p</B>) --     dump protocol state
                   1523: <P>
                   1524: <H3>Arguments</H3>
                   1525: <P>
                   1526: <DL>
                   1527: <DT><I>struct proto *</I> <B>p</B><DD><P>an instance
                   1528: </DL>
                   1529: <H3>Description</H3>
                   1530: <P>This hook dumps the complete state of the instance to the
                   1531: debug output.
                   1532: 
                   1533: 
                   1534: <HR><H3>Function</H3>
                   1535: <P><I>void</I>
                   1536: <B>dump_attrs</B>
                   1537: (<I>rte *</I> <B>e</B>) --     dump protocol-dependent attributes
                   1538: <P>
                   1539: <H3>Arguments</H3>
                   1540: <P>
                   1541: <DL>
                   1542: <DT><I>rte *</I> <B>e</B><DD><P>a route entry
                   1543: </DL>
                   1544: <H3>Description</H3>
                   1545: <P>This hook dumps all attributes in the <I>rte</I> which belong to this
                   1546: protocol to the debug output.
                   1547: 
                   1548: 
                   1549: <HR><H3>Function</H3>
                   1550: <P><I>int</I>
                   1551: <B>start</B>
                   1552: (<I>struct proto *</I> <B>p</B>) --     request instance startup
                   1553: <P>
                   1554: <H3>Arguments</H3>
                   1555: <P>
                   1556: <DL>
                   1557: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
                   1558: </DL>
                   1559: <H3>Description</H3>
                   1560: <P>The <B>start()</B> hook is called by the core when it wishes to start
                   1561: the instance. Multitable protocols should lock their tables here.
                   1562: <H3>Result</H3>
                   1563: <P>new protocol state
                   1564: 
                   1565: 
                   1566: <HR><H3>Function</H3>
                   1567: <P><I>int</I>
                   1568: <B>shutdown</B>
                   1569: (<I>struct proto *</I> <B>p</B>) --     request instance shutdown
                   1570: <P>
                   1571: <H3>Arguments</H3>
                   1572: <P>
                   1573: <DL>
                   1574: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
                   1575: </DL>
                   1576: <H3>Description</H3>
                   1577: <P>The <B>stop()</B> hook is called by the core when it wishes to shut
                   1578: the instance down for some reason.
                   1579: <H3>Returns</H3>
                   1580: <P>new protocol state
                   1581: 
                   1582: 
                   1583: <HR><H3>Function</H3>
                   1584: <P><I>void</I>
                   1585: <B>cleanup</B>
                   1586: (<I>struct proto *</I> <B>p</B>) --     request instance cleanup
                   1587: <P>
                   1588: <H3>Arguments</H3>
                   1589: <P>
                   1590: <DL>
                   1591: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
                   1592: </DL>
                   1593: <H3>Description</H3>
                   1594: <P>The <B>cleanup()</B> hook is called by the core when the protocol became
                   1595: hungry/down, i.e. all protocol ahooks and routes are flushed.
                   1596: Multitable protocols should unlock their tables here.
                   1597: 
                   1598: 
                   1599: <HR><H3>Function</H3>
                   1600: <P><I>void</I>
                   1601: <B>get_status</B>
                   1602: (<I>struct proto *</I> <B>p</B>, <I>byte *</I> <B>buf</B>) --     get instance status
                   1603: <P>
                   1604: <H3>Arguments</H3>
                   1605: <P>
                   1606: <DL>
                   1607: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
                   1608: <DT><I>byte *</I> <B>buf</B><DD><P>buffer to be filled with the status string
                   1609: </DL>
                   1610: <H3>Description</H3>
                   1611: <P>This hook is called by the core if it wishes to obtain an brief one-line user friendly
                   1612: representation of the status of the instance to be printed by the &lt;cf/show protocols/
                   1613: command.
                   1614: 
                   1615: 
                   1616: <HR><H3>Function</H3>
                   1617: <P><I>void</I>
                   1618: <B>get_route_info</B>
                   1619: (<I>rte *</I> <B>e</B>, <I>byte *</I> <B>buf</B>, <I>ea_list *</I> <B>attrs</B>) --     get route information
                   1620: <P>
                   1621: <H3>Arguments</H3>
                   1622: <P>
                   1623: <DL>
                   1624: <DT><I>rte *</I> <B>e</B><DD><P>a route entry
                   1625: <DT><I>byte *</I> <B>buf</B><DD><P>buffer to be filled with the resulting string
                   1626: <DT><I>ea_list *</I> <B>attrs</B><DD><P>extended attributes of the route
                   1627: </DL>
                   1628: <H3>Description</H3>
                   1629: <P>This hook is called to fill the buffer <B>buf</B> with a brief user friendly
                   1630: representation of metrics of a route belonging to this protocol.
                   1631: 
                   1632: 
                   1633: <HR><H3>Function</H3>
                   1634: <P><I>int</I>
                   1635: <B>get_attr</B>
                   1636: (<I>eattr *</I> <B>a</B>, <I>byte *</I> <B>buf</B>, <I>int</I> <B>buflen</B>) --     get attribute information
                   1637: <P>
                   1638: <H3>Arguments</H3>
                   1639: <P>
                   1640: <DL>
                   1641: <DT><I>eattr *</I> <B>a</B><DD><P>an extended attribute
                   1642: <DT><I>byte *</I> <B>buf</B><DD><P>buffer to be filled with attribute information
                   1643: <DT><I>int</I> <B>buflen</B><DD><P>a length of the <B>buf</B> parameter
                   1644: </DL>
                   1645: <H3>Description</H3>
                   1646: <P>The <B>get_attr()</B> hook is called by the core to obtain a user friendly
                   1647: representation of an extended route attribute. It can either leave
                   1648: the whole conversion to the core (by returning <I>GA_UNKNOWN</I>), fill
                   1649: in only attribute name (and let the core format the attribute value
                   1650: automatically according to the type field; by returning <I>GA_NAME</I>)
                   1651: or doing the whole conversion (used in case the value requires extra
                   1652: care; return <I>GA_FULL</I>).
                   1653: 
                   1654: 
                   1655: <HR><H3>Function</H3>
                   1656: <P><I>void</I>
                   1657: <B>if_notify</B>
                   1658: (<I>struct proto *</I> <B>p</B>, <I>unsigned</I> <B>flags</B>, <I>struct iface *</I> <B>i</B>) --     notify instance about interface changes
                   1659: <P>
                   1660: <H3>Arguments</H3>
                   1661: <P>
                   1662: <DL>
                   1663: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
                   1664: <DT><I>unsigned</I> <B>flags</B><DD><P>interface change flags
                   1665: <DT><I>struct iface *</I> <B>i</B><DD><P>the interface in question
                   1666: </DL>
                   1667: <H3>Description</H3>
                   1668: <P>This hook is called whenever any network interface changes its status.
                   1669: The change is described by a combination of status bits (<I>IF_CHANGE_xxx</I>)
                   1670: in the <B>flags</B> parameter.
                   1671: 
                   1672: 
                   1673: <HR><H3>Function</H3>
                   1674: <P><I>void</I>
                   1675: <B>ifa_notify</B>
                   1676: (<I>struct proto *</I> <B>p</B>, <I>unsigned</I> <B>flags</B>, <I>struct ifa *</I> <B>a</B>) --     notify instance about interface address changes
                   1677: <P>
                   1678: <H3>Arguments</H3>
                   1679: <P>
                   1680: <DL>
                   1681: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
                   1682: <DT><I>unsigned</I> <B>flags</B><DD><P>address change flags
                   1683: <DT><I>struct ifa *</I> <B>a</B><DD><P>the interface address
                   1684: </DL>
                   1685: <H3>Description</H3>
                   1686: <P>This hook is called to notify the protocol instance about an interface
                   1687: acquiring or losing one of its addresses. The change is described by
                   1688: a combination of status bits (<I>IF_CHANGE_xxx</I>) in the <B>flags</B> parameter.
                   1689: 
                   1690: 
                   1691: <HR><H3>Function</H3>
                   1692: <P><I>void</I>
                   1693: <B>rt_notify</B>
                   1694: (<I>struct proto *</I> <B>p</B>, <I>net *</I> <B>net</B>, <I>rte *</I> <B>new</B>, <I>rte *</I> <B>old</B>, <I>ea_list *</I> <B>attrs</B>) --     notify instance about routing table change
                   1695: <P>
                   1696: <H3>Arguments</H3>
                   1697: <P>
                   1698: <DL>
                   1699: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
                   1700: <DT><I>net *</I> <B>net</B><DD><P>a network entry
                   1701: <DT><I>rte *</I> <B>new</B><DD><P>new route for the network
                   1702: <DT><I>rte *</I> <B>old</B><DD><P>old route for the network
                   1703: <DT><I>ea_list *</I> <B>attrs</B><DD><P>extended attributes associated with the <B>new</B> entry
                   1704: </DL>
                   1705: <H3>Description</H3>
                   1706: <P>The <B>rt_notify()</B> hook is called to inform the protocol instance about
                   1707: changes in the connected routing table <B>table</B>, that is a route <B>old</B>
                   1708: belonging to network <B>net</B> being replaced by a new route <B>new</B> with
                   1709: extended attributes <B>attrs</B>. Either <B>new</B> or <B>old</B> or both can be <I>NULL</I>
                   1710: if the corresponding route doesn't exist.
                   1711: <P>If the type of route announcement is RA_OPTIMAL, it is an
                   1712: announcement of optimal route change, <B>new</B> stores the new optimal
                   1713: route and <B>old</B> stores the old optimal route.
                   1714: <P>If the type of route announcement is RA_ANY, it is an announcement
                   1715: of any route change, <B>new</B> stores the new route and <B>old</B> stores the
                   1716: old route from the same protocol.
                   1717: <P><B>p</B>-&gt;accept_ra_types specifies which kind of route announcements
                   1718: protocol wants to receive.
                   1719: 
                   1720: 
                   1721: <HR><H3>Function</H3>
                   1722: <P><I>void</I>
                   1723: <B>neigh_notify</B>
                   1724: (<I>neighbor *</I> <B>neigh</B>) --     notify instance about neighbor status change
                   1725: <P>
                   1726: <H3>Arguments</H3>
                   1727: <P>
                   1728: <DL>
                   1729: <DT><I>neighbor *</I> <B>neigh</B><DD><P>a neighbor cache entry
                   1730: </DL>
                   1731: <H3>Description</H3>
                   1732: <P>The <B>neigh_notify()</B> hook is called by the neighbor cache whenever
                   1733: a neighbor changes its state, that is it gets disconnected or a
                   1734: sticky neighbor gets connected.
                   1735: 
                   1736: 
                   1737: <HR><H3>Function</H3>
                   1738: <P><I>ea_list *</I>
                   1739: <B>make_tmp_attrs</B>
                   1740: (<I>rte *</I> <B>e</B>, <I>struct linpool *</I> <B>pool</B>) --     convert embedded attributes to temporary ones
                   1741: <P>
                   1742: <H3>Arguments</H3>
                   1743: <P>
                   1744: <DL>
                   1745: <DT><I>rte *</I> <B>e</B><DD><P>route entry
                   1746: <DT><I>struct linpool *</I> <B>pool</B><DD><P>linear pool to allocate attribute memory in
                   1747: </DL>
                   1748: <H3>Description</H3>
                   1749: <P>This hook is called by the routing table functions if they need
                   1750: to convert the protocol attributes embedded directly in the <I>rte</I>
                   1751: to temporary extended attributes in order to distribute them
                   1752: to other protocols or to filters. <B>make_tmp_attrs()</B> creates
                   1753: an <I>ea_list</I> in the linear pool <B>pool</B>, fills it with values of the
                   1754: temporary attributes and returns a pointer to it.
                   1755: 
                   1756: 
                   1757: <HR><H3>Function</H3>
                   1758: <P><I>void</I>
                   1759: <B>store_tmp_attrs</B>
                   1760: (<I>rte *</I> <B>e</B>, <I>ea_list *</I> <B>attrs</B>) --     convert temporary attributes to embedded ones
                   1761: <P>
                   1762: <H3>Arguments</H3>
                   1763: <P>
                   1764: <DL>
                   1765: <DT><I>rte *</I> <B>e</B><DD><P>route entry
                   1766: <DT><I>ea_list *</I> <B>attrs</B><DD><P>temporary attributes to be converted
                   1767: </DL>
                   1768: <H3>Description</H3>
                   1769: <P>This hook is an exact opposite of <B>make_tmp_attrs()</B> -- it takes
                   1770: a list of extended attributes and converts them to attributes
                   1771: embedded in the <I>rte</I> corresponding to this protocol.
                   1772: <P>You must be prepared for any of the attributes being missing
                   1773: from the list and use default values instead.
                   1774: 
                   1775: 
                   1776: <HR><H3>Function</H3>
                   1777: <P><I>int</I>
                   1778: <B>import_control</B>
                   1779: (<I>struct proto *</I> <B>p</B>, <I>rte **</I> <B>e</B>, <I>ea_list **</I> <B>attrs</B>, <I>struct linpool *</I> <B>pool</B>) --     pre-filtering decisions on route import
                   1780: <P>
                   1781: <H3>Arguments</H3>
                   1782: <P>
                   1783: <DL>
                   1784: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance the route is going to be imported to
                   1785: <DT><I>rte **</I> <B>e</B><DD><P>the route in question
                   1786: <DT><I>ea_list **</I> <B>attrs</B><DD><P>extended attributes of the route
                   1787: <DT><I>struct linpool *</I> <B>pool</B><DD><P>linear pool for allocation of all temporary data
                   1788: </DL>
                   1789: <H3>Description</H3>
                   1790: <P>The <B>import_control()</B> hook is called as the first step of a exporting
                   1791: a route from a routing table to the protocol instance. It can modify
                   1792: route attributes and force acceptance or rejection of the route regardless
                   1793: of user-specified filters. See <B>rte_announce()</B> for a complete description
                   1794: of the route distribution process.
                   1795: <P>The standard use of this hook is to reject routes having originated
                   1796: from the same instance and to set default values of the protocol's metrics.
                   1797: <H3>Result</H3>
                   1798: <P>1 if the route has to be accepted, -1 if rejected and 0 if it
                   1799: should be passed to the filters.
                   1800: 
                   1801: 
                   1802: <HR><H3>Function</H3>
                   1803: <P><I>int</I>
                   1804: <B>rte_recalculate</B>
                   1805: (<I>struct rtable *</I> <B>table</B>, <I>struct network *</I> <B>net</B>, <I>struct rte *</I> <B>new</B>, <I>struct rte *</I> <B>old</B>, <I>struct rte *</I> <B>old_best</B>) --     prepare routes for comparison
                   1806: <P>
                   1807: <H3>Arguments</H3>
                   1808: <P>
                   1809: <DL>
                   1810: <DT><I>struct rtable *</I> <B>table</B><DD><P>a routing table 
                   1811: <DT><I>struct network *</I> <B>net</B><DD><P>a network entry
                   1812: <DT><I>struct rte *</I> <B>new</B><DD><P>new route for the network
                   1813: <DT><I>struct rte *</I> <B>old</B><DD><P>old route for the network
                   1814: <DT><I>struct rte *</I> <B>old_best</B><DD><P>old best route for the network (may be NULL)
                   1815: </DL>
                   1816: <H3>Description</H3>
                   1817: <P>This hook is called when a route change (from <B>old</B> to <B>new</B> for a
                   1818: <B>net</B> entry) is propagated to a <B>table</B>. It may be used to prepare
                   1819: routes for comparison by <B>rte_better()</B> in the best route
                   1820: selection. <B>new</B> may or may not be in <B>net</B>-&gt;routes list,
                   1821: <B>old</B> is not there.
                   1822: <H3>Result</H3>
                   1823: <P>1 if the ordering implied by <B>rte_better()</B> changes enough
                   1824: that full best route calculation have to be done, 0 otherwise.
                   1825: 
                   1826: 
                   1827: <HR><H3>Function</H3>
                   1828: <P><I>int</I>
                   1829: <B>rte_better</B>
                   1830: (<I>rte *</I> <B>new</B>, <I>rte *</I> <B>old</B>) --     compare metrics of two routes
                   1831: <P>
                   1832: <H3>Arguments</H3>
                   1833: <P>
                   1834: <DL>
                   1835: <DT><I>rte *</I> <B>new</B><DD><P>the new route
                   1836: <DT><I>rte *</I> <B>old</B><DD><P>the original route
                   1837: </DL>
                   1838: <H3>Description</H3>
                   1839: <P>This hook gets called when the routing table contains two routes
                   1840: for the same network which have originated from different instances
                   1841: of a single protocol and it wants to select which one is preferred
                   1842: over the other one. Protocols usually decide according to route metrics.
                   1843: <H3>Result</H3>
                   1844: <P>1 if <B>new</B> is better (more preferred) than <B>old</B>, 0 otherwise.
                   1845: 
                   1846: 
                   1847: <HR><H3>Function</H3>
                   1848: <P><I>int</I>
                   1849: <B>rte_same</B>
                   1850: (<I>rte *</I> <B>e1</B>, <I>rte *</I> <B>e2</B>) --     compare two routes
                   1851: <P>
                   1852: <H3>Arguments</H3>
                   1853: <P>
                   1854: <DL>
                   1855: <DT><I>rte *</I> <B>e1</B><DD><P>route
                   1856: <DT><I>rte *</I> <B>e2</B><DD><P>route
                   1857: </DL>
                   1858: <H3>Description</H3>
                   1859: <P>The <B>rte_same()</B> hook tests whether the routes <B>e1</B> and <B>e2</B> belonging
                   1860: to the same protocol instance have identical contents. Contents of
                   1861: <I>rta</I>, all the extended attributes and <I>rte</I> preference are checked
                   1862: by the core code, no need to take care of them here.
                   1863: <H3>Result</H3>
                   1864: <P>1 if <B>e1</B> is identical to <B>e2</B>, 0 otherwise.
                   1865: 
                   1866: 
                   1867: <HR><H3>Function</H3>
                   1868: <P><I>void</I>
                   1869: <B>rte_insert</B>
                   1870: (<I>net *</I> <B>n</B>, <I>rte *</I> <B>e</B>) --     notify instance about route insertion
                   1871: <P>
                   1872: <H3>Arguments</H3>
                   1873: <P>
                   1874: <DL>
                   1875: <DT><I>net *</I> <B>n</B><DD><P>network
                   1876: <DT><I>rte *</I> <B>e</B><DD><P>route
                   1877: </DL>
                   1878: <H3>Description</H3>
                   1879: <P>This hook is called whenever a <I>rte</I> belonging to the instance
                   1880: is accepted for insertion to a routing table.
                   1881: <P>Please avoid using this function in new protocols.
                   1882: 
                   1883: 
                   1884: <HR><H3>Function</H3>
                   1885: <P><I>void</I>
                   1886: <B>rte_remove</B>
                   1887: (<I>net *</I> <B>n</B>, <I>rte *</I> <B>e</B>) --     notify instance about route removal
                   1888: <P>
                   1889: <H3>Arguments</H3>
                   1890: <P>
                   1891: <DL>
                   1892: <DT><I>net *</I> <B>n</B><DD><P>network
                   1893: <DT><I>rte *</I> <B>e</B><DD><P>route
                   1894: </DL>
                   1895: <H3>Description</H3>
                   1896: <P>This hook is called whenever a <I>rte</I> belonging to the instance
                   1897: is removed from a routing table.
                   1898: <P>Please avoid using this function in new protocols.
                   1899: 
                   1900: <H2><A NAME="ss2.7">2.7</A> <A HREF="prog.html#toc2.7">Interfaces</A>
                   1901: </H2>
                   1902: 
                   1903: <P>
                   1904: <P>The interface module keeps track of all network interfaces in the
                   1905: system and their addresses.
                   1906: <P>Each interface is represented by an <I>iface</I> structure which carries
                   1907: interface capability flags (<I>IF_MULTIACCESS</I>, <I>IF_BROADCAST</I> etc.),
                   1908: MTU, interface name and index and finally a linked list of network
                   1909: prefixes assigned to the interface, each one represented by
                   1910: struct <I>ifa</I>.
                   1911: <P>The interface module keeps a `soft-up' state for each <I>iface</I> which
                   1912: is a conjunction of link being up, the interface being of a `sane'
                   1913: type and at least one IP address assigned to it.
                   1914: <P>
                   1915: <P><HR><H3>Function</H3>
                   1916: <P><I>void</I>
                   1917: <B>ifa_dump</B>
                   1918: (<I>struct ifa *</I> <B>a</B>) --     dump interface address
                   1919: <P>
                   1920: <H3>Arguments</H3>
                   1921: <P>
                   1922: <DL>
                   1923: <DT><I>struct ifa *</I> <B>a</B><DD><P>interface address descriptor
                   1924: </DL>
                   1925: <H3>Description</H3>
                   1926: <P>This function dumps contents of an <I>ifa</I> to the debug output.
                   1927: 
                   1928: 
                   1929: <HR><H3>Function</H3>
                   1930: <P><I>void</I>
                   1931: <B>if_dump</B>
                   1932: (<I>struct iface *</I> <B>i</B>) --     dump interface
                   1933: <P>
                   1934: <H3>Arguments</H3>
                   1935: <P>
                   1936: <DL>
                   1937: <DT><I>struct iface *</I> <B>i</B><DD><P>interface to dump
                   1938: </DL>
                   1939: <H3>Description</H3>
                   1940: <P>This function dumps all information associated with a given
                   1941: network interface to the debug output.
                   1942: 
                   1943: 
                   1944: <HR><H3>Function</H3>
                   1945: <P><I>void</I>
                   1946: <B>if_dump_all</B>
                   1947: (<B>void</B>) --     dump all interfaces
                   1948: <P>
                   1949: <H3>Description</H3>
                   1950: <P>
                   1951: <P>This function dumps information about all known network
                   1952: interfaces to the debug output.
                   1953: 
                   1954: 
                   1955: <HR><H3>Function</H3>
                   1956: <P><I>void</I>
                   1957: <B>if_delete</B>
                   1958: (<I>struct iface *</I> <B>old</B>) --     remove interface
                   1959: <P>
                   1960: <H3>Arguments</H3>
                   1961: <P>
                   1962: <DL>
                   1963: <DT><I>struct iface *</I> <B>old</B><DD><P>interface
                   1964: </DL>
                   1965: <H3>Description</H3>
                   1966: <P>This function is called by the low-level platform dependent code
                   1967: whenever it notices an interface disappears. It is just a shorthand
                   1968: for <B>if_update()</B>.
                   1969: 
                   1970: 
                   1971: <HR><H3>Function</H3>
                   1972: <P><I>struct iface *</I>
                   1973: <B>if_update</B>
                   1974: (<I>struct iface *</I> <B>new</B>) --     update interface status
                   1975: <P>
                   1976: <H3>Arguments</H3>
                   1977: <P>
                   1978: <DL>
                   1979: <DT><I>struct iface *</I> <B>new</B><DD><P>new interface status
                   1980: </DL>
                   1981: <H3>Description</H3>
                   1982: <P><B>if_update()</B> is called by the low-level platform dependent code
                   1983: whenever it notices an interface change.
                   1984: <P>There exist two types of interface updates -- synchronous and asynchronous
                   1985: ones. In the synchronous case, the low-level code calls <B>if_start_update()</B>,
                   1986: scans all interfaces reported by the OS, uses <B>if_update()</B> and <B>ifa_update()</B>
                   1987: to pass them to the core and then it finishes the update sequence by
                   1988: calling <B>if_end_update()</B>. When working asynchronously, the sysdep code
                   1989: calls <B>if_update()</B> and <B>ifa_update()</B> whenever it notices a change.
                   1990: <P><B>if_update()</B> will automatically notify all other modules about the change.
                   1991: 
                   1992: 
                   1993: <HR><H3>Function</H3>
                   1994: <P><I>void</I>
                   1995: <B>if_feed_baby</B>
                   1996: (<I>struct proto *</I> <B>p</B>) --     advertise interfaces to a new protocol
                   1997: <P>
                   1998: <H3>Arguments</H3>
                   1999: <P>
                   2000: <DL>
                   2001: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol to feed
                   2002: </DL>
                   2003: <H3>Description</H3>
                   2004: <P>When a new protocol starts, this function sends it a series
                   2005: of notifications about all existing interfaces.
                   2006: 
                   2007: 
                   2008: <HR><H3>Function</H3>
                   2009: <P><I>struct iface *</I>
                   2010: <B>if_find_by_index</B>
                   2011: (<I>unsigned</I> <B>idx</B>) --     find interface by ifindex
                   2012: <P>
                   2013: <H3>Arguments</H3>
                   2014: <P>
                   2015: <DL>
                   2016: <DT><I>unsigned</I> <B>idx</B><DD><P>ifindex
                   2017: </DL>
                   2018: <H3>Description</H3>
                   2019: <P>This function finds an <I>iface</I> structure corresponding to an interface
                   2020: of the given index <B>idx</B>. Returns a pointer to the structure or <I>NULL</I>
                   2021: if no such structure exists.
                   2022: 
                   2023: 
                   2024: <HR><H3>Function</H3>
                   2025: <P><I>struct iface *</I>
                   2026: <B>if_find_by_name</B>
                   2027: (<I>char *</I> <B>name</B>) --     find interface by name
                   2028: <P>
                   2029: <H3>Arguments</H3>
                   2030: <P>
                   2031: <DL>
                   2032: <DT><I>char *</I> <B>name</B><DD><P>interface name
                   2033: </DL>
                   2034: <H3>Description</H3>
                   2035: <P>This function finds an <I>iface</I> structure corresponding to an interface
                   2036: of the given name <B>name</B>. Returns a pointer to the structure or <I>NULL</I>
                   2037: if no such structure exists.
                   2038: 
                   2039: 
                   2040: <HR><H3>Function</H3>
                   2041: <P><I>struct ifa *</I>
                   2042: <B>ifa_update</B>
                   2043: (<I>struct ifa *</I> <B>a</B>) --     update interface address
                   2044: <P>
                   2045: <H3>Arguments</H3>
                   2046: <P>
                   2047: <DL>
                   2048: <DT><I>struct ifa *</I> <B>a</B><DD><P>new interface address
                   2049: </DL>
                   2050: <H3>Description</H3>
                   2051: <P>This function adds address information to a network
                   2052: interface. It's called by the platform dependent code during
                   2053: the interface update process described under <B>if_update()</B>.
                   2054: 
                   2055: 
                   2056: <HR><H3>Function</H3>
                   2057: <P><I>void</I>
                   2058: <B>ifa_delete</B>
                   2059: (<I>struct ifa *</I> <B>a</B>) --     remove interface address
                   2060: <P>
                   2061: <H3>Arguments</H3>
                   2062: <P>
                   2063: <DL>
                   2064: <DT><I>struct ifa *</I> <B>a</B><DD><P>interface address
                   2065: </DL>
                   2066: <H3>Description</H3>
                   2067: <P>This function removes address information from a network
                   2068: interface. It's called by the platform dependent code during
                   2069: the interface update process described under <B>if_update()</B>.
                   2070: 
                   2071: 
                   2072: <HR><H3>Function</H3>
                   2073: <P><I>void</I>
                   2074: <B>if_init</B>
                   2075: (<B>void</B>) --     initialize interface module
                   2076: <P>
                   2077: <H3>Description</H3>
                   2078: <P>
                   2079: <P>This function is called during BIRD startup to initialize
                   2080: all data structures of the interface module.
                   2081: 
                   2082: <H2><A NAME="ss2.8">2.8</A> <A HREF="prog.html#toc2.8">Neighbor cache</A>
                   2083: </H2>
                   2084: 
                   2085: <P>
                   2086: <P>Most routing protocols need to associate their internal state data with
                   2087: neighboring routers, check whether an address given as the next hop
                   2088: attribute of a route is really an address of a directly connected host
                   2089: and which interface is it connected through. Also, they often need to
                   2090: be notified when a neighbor ceases to exist or when their long awaited
                   2091: neighbor becomes connected. The neighbor cache is there to solve all
                   2092: these problems.
                   2093: <P>The neighbor cache maintains a collection of neighbor entries. Each
                   2094: entry represents one IP address corresponding to either our directly
                   2095: connected neighbor or our own end of the link (when the scope of the
                   2096: address is set to <I>SCOPE_HOST</I>) together with per-neighbor data belonging to a
                   2097: single protocol.
                   2098: <P>Active entries represent known neighbors and are stored in a hash
                   2099: table (to allow fast retrieval based on the IP address of the node) and
                   2100: two linked lists: one global and one per-interface (allowing quick
                   2101: processing of interface change events). Inactive entries exist only
                   2102: when the protocol has explicitly requested it via the <I>NEF_STICKY</I>
                   2103: flag because it wishes to be notified when the node will again become
                   2104: a neighbor. Such entries are enqueued in a special list which is walked
1.1.1.2 ! misho    2105: whenever an interface changes its state to up. Neighbor entry VRF
        !          2106: association is implied by respective protocol.
1.1       misho    2107: <P>When a neighbor event occurs (a neighbor gets disconnected or a sticky
                   2108: inactive neighbor becomes connected), the protocol hook <B>neigh_notify()</B>
                   2109: is called to advertise the change.
                   2110: <P>
                   2111: <P><HR><H3>Function</H3>
                   2112: <P><I>neighbor *</I>
                   2113: <B>neigh_find</B>
                   2114: (<I>struct proto *</I> <B>p</B>, <I>ip_addr *</I> <B>a</B>, <I>unsigned</I> <B>flags</B>) --     find or create a neighbor entry.
                   2115: <P>
                   2116: <H3>Arguments</H3>
                   2117: <P>
                   2118: <DL>
                   2119: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol which asks for the entry.
                   2120: <DT><I>ip_addr *</I> <B>a</B><DD><P>pointer to IP address of the node to be searched for.
                   2121: <DT><I>unsigned</I> <B>flags</B><DD><P>0 or <I>NEF_STICKY</I> if you want to create a sticky entry.
                   2122: </DL>
                   2123: <H3>Description</H3>
                   2124: <P>Search the neighbor cache for a node with given IP address. If
                   2125: it's found, a pointer to the neighbor entry is returned. If no
                   2126: such entry exists and the node is directly connected on
                   2127: one of our active interfaces, a new entry is created and returned
                   2128: to the caller with protocol-dependent fields initialized to zero.
                   2129: If the node is not connected directly or *<B>a</B> is not a valid unicast
                   2130: IP address, <B>neigh_find()</B> returns <I>NULL</I>.
                   2131: 
                   2132: 
                   2133: <HR><H3>Function</H3>
                   2134: <P><I>void</I>
                   2135: <B>neigh_dump</B>
                   2136: (<I>neighbor *</I> <B>n</B>) --     dump specified neighbor entry.
                   2137: <P>
                   2138: <H3>Arguments</H3>
                   2139: <P>
                   2140: <DL>
                   2141: <DT><I>neighbor *</I> <B>n</B><DD><P>the entry to dump
                   2142: </DL>
                   2143: <H3>Description</H3>
                   2144: <P>This functions dumps the contents of a given neighbor entry
                   2145: to debug output.
                   2146: 
                   2147: 
                   2148: <HR><H3>Function</H3>
                   2149: <P><I>void</I>
                   2150: <B>neigh_dump_all</B>
                   2151: (<B>void</B>) --     dump all neighbor entries.
                   2152: <P>
                   2153: <H3>Description</H3>
                   2154: <P>
                   2155: <P>This function dumps the contents of the neighbor cache to
                   2156: debug output.
                   2157: 
                   2158: 
                   2159: <HR><H3>Function</H3>
                   2160: <P><I>void</I>
                   2161: <B>neigh_if_up</B>
                   2162: (<I>struct iface *</I> <B>i</B>)
                   2163: <H3>Arguments</H3>
                   2164: <P>
                   2165: <DL>
                   2166: <DT><I>struct iface *</I> <B>i</B><DD><P>interface in question
                   2167: </DL>
                   2168: <H3>Description</H3>
                   2169: <P>Tell the neighbor cache that a new interface became up.
                   2170: <P>The neighbor cache wakes up all inactive sticky neighbors with
                   2171: addresses belonging to prefixes of the interface <B>i</B>.
                   2172: 
                   2173: 
                   2174: <HR><H3>Function</H3>
                   2175: <P><I>void</I>
                   2176: <B>neigh_if_down</B>
                   2177: (<I>struct iface *</I> <B>i</B>) --     notify neighbor cache about interface down event
                   2178: <P>
                   2179: <H3>Arguments</H3>
                   2180: <P>
                   2181: <DL>
                   2182: <DT><I>struct iface *</I> <B>i</B><DD><P>the interface in question
                   2183: </DL>
                   2184: <H3>Description</H3>
                   2185: <P>Notify the neighbor cache that an interface has ceased to exist.
                   2186: <P>It causes all entries belonging to neighbors connected to this interface
                   2187: to be flushed.
                   2188: 
                   2189: 
                   2190: <HR><H3>Function</H3>
                   2191: <P><I>void</I>
                   2192: <B>neigh_if_link</B>
                   2193: (<I>struct iface *</I> <B>i</B>) --     notify neighbor cache about interface link change
                   2194: <P>
                   2195: <H3>Arguments</H3>
                   2196: <P>
                   2197: <DL>
                   2198: <DT><I>struct iface *</I> <B>i</B><DD><P>the interface in question
                   2199: </DL>
                   2200: <H3>Description</H3>
                   2201: <P>Notify the neighbor cache that an interface changed link state.
                   2202: All owners of neighbor entries connected to this interface are
                   2203: notified.
                   2204: 
                   2205: 
                   2206: <HR><H3>Function</H3>
                   2207: <P><I>void</I>
                   2208: <B>neigh_ifa_update</B>
                   2209: (<I>struct ifa *</I> <B>a</B>)
                   2210: <H3>Arguments</H3>
                   2211: <P>
                   2212: <DL>
                   2213: <DT><I>struct ifa *</I> <B>a</B><DD><P>interface address in question
                   2214: </DL>
                   2215: <H3>Description</H3>
                   2216: <P>Tell the neighbor cache that an address was added or removed.
                   2217: <P>The neighbor cache wakes up all inactive sticky neighbors with
                   2218: addresses belonging to prefixes of the interface belonging to <B>ifa</B>
                   2219: and causes all unreachable neighbors to be flushed.
                   2220: 
                   2221: 
                   2222: <HR><H3>Function</H3>
                   2223: <P><I>void</I>
                   2224: <B>neigh_prune</B>
                   2225: (<B>void</B>) --     prune neighbor cache
                   2226: <P>
                   2227: <H3>Description</H3>
                   2228: <P>
                   2229: <P><B>neigh_prune()</B> examines all neighbor entries cached and removes those
                   2230: corresponding to inactive protocols. It's called whenever a protocol
                   2231: is shut down to get rid of all its heritage.
                   2232: 
                   2233: 
                   2234: <HR><H3>Function</H3>
                   2235: <P><I>void</I>
                   2236: <B>neigh_init</B>
                   2237: (<I>pool *</I> <B>if_pool</B>) --     initialize the neighbor cache.
                   2238: <P>
                   2239: <H3>Arguments</H3>
                   2240: <P>
                   2241: <DL>
                   2242: <DT><I>pool *</I> <B>if_pool</B><DD><P>resource pool to be used for neighbor entries.
                   2243: </DL>
                   2244: <H3>Description</H3>
                   2245: <P>This function is called during BIRD startup to initialize
                   2246: the neighbor cache module.
                   2247: 
                   2248: <H2><A NAME="ss2.9">2.9</A> <A HREF="prog.html#toc2.9">Command line interface</A>
                   2249: </H2>
                   2250: 
                   2251: <P>
                   2252: <P>This module takes care of the BIRD's command-line interface (CLI).
                   2253: The CLI exists to provide a way to control BIRD remotely and to inspect
                   2254: its status. It uses a very simple textual protocol over a stream
                   2255: connection provided by the platform dependent code (on UNIX systems,
                   2256: it's a UNIX domain socket).
                   2257: <P>Each session of the CLI consists of a sequence of request and replies,
                   2258: slightly resembling the FTP and SMTP protocols.
                   2259: Requests are commands encoded as a single line of text, replies are
                   2260: sequences of lines starting with a four-digit code followed by either
                   2261: a space (if it's the last line of the reply) or a minus sign (when the
                   2262: reply is going to continue with the next line), the rest of the line
                   2263: contains a textual message semantics of which depends on the numeric
                   2264: code. If a reply line has the same code as the previous one and it's
                   2265: a continuation line, the whole prefix can be replaced by a single
                   2266: white space character.
                   2267: <P>Reply codes starting with 0 stand for `action successfully completed' messages,
                   2268: 1 means `table entry', 8 `runtime error' and 9 `syntax error'.
                   2269: <P>Each CLI session is internally represented by a <I>cli</I> structure and a
                   2270: resource pool containing all resources associated with the connection,
                   2271: so that it can be easily freed whenever the connection gets closed, not depending
                   2272: on the current state of command processing.
                   2273: <P>The CLI commands are declared as a part of the configuration grammar
                   2274: by using the <CODE>CF_CLI</CODE> macro. When a command is received, it is processed
                   2275: by the same lexical analyzer and parser as used for the configuration, but
                   2276: it's switched to a special mode by prepending a fake token to the text,
                   2277: so that it uses only the CLI command rules. Then the parser invokes
                   2278: an execution routine corresponding to the command, which either constructs
                   2279: the whole reply and returns it back or (in case it expects the reply will be long)
                   2280: it prints a partial reply and asks the CLI module (using the <B>cont</B> hook)
                   2281: to call it again when the output is transferred to the user.
                   2282: <P>The <B>this_cli</B> variable points to a <I>cli</I> structure of the session being
                   2283: currently parsed, but it's of course available only in command handlers
                   2284: not entered using the <B>cont</B> hook.
                   2285: <P>TX buffer management works as follows: At cli.tx_buf there is a
                   2286: list of TX buffers (struct cli_out), cli.tx_write is the buffer
                   2287: currently used by the producer (<B>cli_printf()</B>, <B>cli_alloc_out()</B>) and
                   2288: cli.tx_pos is the buffer currently used by the consumer
                   2289: (<B>cli_write()</B>, in system dependent code). The producer uses
                   2290: cli_out.wpos ptr as the current write position and the consumer
                   2291: uses cli_out.outpos ptr as the current read position. When the
                   2292: producer produces something, it calls <B>cli_write_trigger()</B>. If there
                   2293: is not enough space in the current buffer, the producer allocates
                   2294: the new one. When the consumer processes everything in the buffer
                   2295: queue, it calls <B>cli_written()</B>, tha frees all buffers (except the
                   2296: first one) and schedules cli.event .
                   2297: <P>
                   2298: <P><HR><H3>Function</H3>
                   2299: <P><I>void</I>
                   2300: <B>cli_printf</B>
                   2301: (<I>cli *</I> <B>c</B>, <I>int</I> <B>code</B>, <I>char *</I> <B>msg</B>, <I>...</I> <B>...</B>) --     send reply to a CLI connection
                   2302: <P>
                   2303: <H3>Arguments</H3>
                   2304: <P>
                   2305: <DL>
                   2306: <DT><I>cli *</I> <B>c</B><DD><P>CLI connection
                   2307: <DT><I>int</I> <B>code</B><DD><P>numeric code of the reply, negative for continuation lines
                   2308: <DT><I>char *</I> <B>msg</B><DD><P>a <B>printf()</B>-like formatting string.
                   2309: <DT><I>...</I> <B>...</B><DD><P>variable arguments
                   2310: </DL>
                   2311: <H3>Description</H3>
                   2312: <P>This function send a single line of reply to a given CLI connection.
                   2313: In works in all aspects like <B>bsprintf()</B> except that it automatically
                   2314: prepends the reply line prefix.
                   2315: <P>Please note that if the connection can be already busy sending some
                   2316: data in which case <B>cli_printf()</B> stores the output to a temporary buffer,
                   2317: so please avoid sending a large batch of replies without waiting
                   2318: for the buffers to be flushed.
                   2319: <P>If you want to write to the current CLI output, you can use the <B>cli_msg()</B>
                   2320: macro instead.
                   2321: 
                   2322: 
                   2323: <HR><H3>Function</H3>
                   2324: <P><I>void</I>
                   2325: <B>cli_init</B>
                   2326: (<B>void</B>) --     initialize the CLI module
                   2327: <P>
                   2328: <H3>Description</H3>
                   2329: <P>
                   2330: <P>This function is called during BIRD startup to initialize
                   2331: the internal data structures of the CLI module.
                   2332: 
                   2333: <H2><A NAME="ss2.10">2.10</A> <A HREF="prog.html#toc2.10">Object locks</A>
                   2334: </H2>
                   2335: 
                   2336: <P>
                   2337: <P>The lock module provides a simple mechanism for avoiding conflicts between
                   2338: various protocols which would like to use a single physical resource (for
                   2339: example a network port). It would be easy to say that such collisions can
                   2340: occur only when the user specifies an invalid configuration and therefore
                   2341: he deserves to get what he has asked for, but unfortunately they can also
                   2342: arise legitimately when the daemon is reconfigured and there exists (although
                   2343: for a short time period only) an old protocol instance being shut down and a new one
                   2344: willing to start up on the same interface.
                   2345: <P>The solution is very simple: when any protocol wishes to use a network port
                   2346: or some other non-shareable resource, it asks the core to lock it and it doesn't
                   2347: use the resource until it's notified that it has acquired the lock.
                   2348: <P>Object locks are represented by <I>object_lock</I> structures which are in turn a
                   2349: kind of resource. Lockable resources are uniquely determined by resource type
                   2350: (<I>OBJLOCK_UDP</I> for a UDP port etc.), IP address (usually a broadcast or
                   2351: multicast address the port is bound to), port number, interface and optional
                   2352: instance ID.
                   2353: <P>
                   2354: <P><HR><H3>Function</H3>
                   2355: <P><I>struct object_lock *</I>
                   2356: <B>olock_new</B>
                   2357: (<I>pool *</I> <B>p</B>) --     create an object lock
                   2358: <P>
                   2359: <H3>Arguments</H3>
                   2360: <P>
                   2361: <DL>
                   2362: <DT><I>pool *</I> <B>p</B><DD><P>resource pool to create the lock in.
                   2363: </DL>
                   2364: <H3>Description</H3>
                   2365: <P>The <B>olock_new()</B> function creates a new resource of type <I>object_lock</I>
                   2366: and returns a pointer to it. After filling in the structure, the caller
                   2367: should call <B>olock_acquire()</B> to do the real locking.
                   2368: 
                   2369: 
                   2370: <HR><H3>Function</H3>
                   2371: <P><I>void</I>
                   2372: <B>olock_acquire</B>
                   2373: (<I>struct object_lock *</I> <B>l</B>) --     acquire a lock
                   2374: <P>
                   2375: <H3>Arguments</H3>
                   2376: <P>
                   2377: <DL>
                   2378: <DT><I>struct object_lock *</I> <B>l</B><DD><P>the lock to acquire
                   2379: </DL>
                   2380: <H3>Description</H3>
                   2381: <P>This function attempts to acquire exclusive access to the non-shareable
                   2382: resource described by the lock <B>l</B>. It returns immediately, but as soon
                   2383: as the resource becomes available, it calls the <B>hook()</B> function set up
                   2384: by the caller.
                   2385: <P>When you want to release the resource, just <B>rfree()</B> the lock.
                   2386: 
                   2387: 
                   2388: <HR><H3>Function</H3>
                   2389: <P><I>void</I>
                   2390: <B>olock_init</B>
                   2391: (<B>void</B>) --     initialize the object lock mechanism
                   2392: <P>
                   2393: <H3>Description</H3>
                   2394: <P>
                   2395: <P>This function is called during BIRD startup. It initializes
                   2396: all the internal data structures of the lock module.
                   2397: 
                   2398: <HR>
                   2399: <A HREF="prog-3.html">Next</A>
                   2400: <A HREF="prog-1.html">Previous</A>
                   2401: <A HREF="prog.html#toc2">Contents</A>
                   2402: </BODY>
                   2403: </HTML>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>