NAME¶
rtalloc1_fib
,
rtalloc_ign_fib
,
rtalloc_fib
—
look up a route in the kernel routing table
SYNOPSIS¶
#include
<sys/types.h>
#include
<sys/socket.h>
#include
<net/route.h>
struct rtentry *
rtalloc1_fib
(
struct
sockaddr *dst,
int report,
u_long flags,
u_int fibnum);
void
rtalloc_fib
(
struct
route *ro,
u_int
fibnum);
void
rtalloc_ign_fib
(
struct
route *ro,
u_long flags,
u_int fibnum);
RTFREE_LOCKED
(
struct
rt_entry *rt);
RTFREE
(
struct
rt_entry *rt);
RT_LOCK
(
struct
rt_entry *rt);
RT_UNLOCK
(
struct
rt_entry *rt);
RT_ADDREF
(
struct
rt_entry *rt);
RT_REMREF
(
struct
rt_entry *rt);
RO_RTFREE
(
struct
route *ro);
void
rtfree
(
struct
rt_entry *rt);
struct rtentry *
rtalloc1
(
struct
sockaddr *dst,
int report,
u_long flags);
void
rtalloc
(
struct
route *ro);
void
rtalloc_ign
(
struct
route *ro,
u_long flags);
options RADIX_MPATH
DESCRIPTION¶
The kernel uses a radix tree structure to manage routes for the networking
subsystem. If compiled with
options
RADIX_MPATH
kernel may maintain several independent forwarding
information databases (FIBs). The
rtalloc
()
family of routines is used by protocols to query these structures for a route
corresponding to a particular end-node address, and to cause certain protocol-
and interface-specific actions to take place.
The
rtalloc1_fib
() function is the most
general form of
rtalloc
(), and all of the
other forms are implemented as calls to it. It takes a
struct sockaddr * directly as the
dst argument. The second argument,
report, controls whether the routing sockets
are notified when a lookup fails. The third argument,
flags, is a combination of the following
values:
The last argument
fibnum specifies number of
forwarding information database (FIB) on which the lookup should be performed.
In case of success the
rtalloc1_fib
()
function returns a pointer to a locked
struct
rtentry with an additional reference.
The
rtalloc_fib
() is the most simple variant.
Its main argument is
ro, a pointer to a
struct route, which is defined as follows:
struct route {
struct rtentry *ro_rt;
struct llentry *ro_lle;
struct sockaddr ro_dst;
};
Thus, this function can only be used for address families which are smaller than
the default
struct sockaddr. Before calling
rtalloc_fib
() for the first time, callers
should ensure that unused bits of the structure are set to zero. The second
argument
fibnum is FIB number. In case of
success of the
rtalloc_fib
() the
ro_rt points to a valid and unlocked
rtentry(9), which has an additional reference put
on it, freeing which is responsibility of the caller. On subsequent calls,
rtalloc_fib
() returns without performing a
lookup if
ro->ro_rt is non-null and the
RTF_UP
flag is set in the rtentry's
rt_flags field.
The
rtalloc_ign_fib
() function is the same as
the
rtalloc_fib
(), but there is additional
flags argument, which is same as in
rtalloc1_fib
().
The
RTFREE_LOCKED
() macro is used to unref
and possibly free a locked routing entry with one our reference, for example
previously allocated by
rtalloc1_fib
().
The
RTFREE
() macro is used to unref and
possibly free an unlocked route entries with one our reference, for example
previously allocated by
rtalloc_fib
() or
rtalloc_ign_fib
().
Both
RTFREE_LOCKED
() and
RTFREE
() macros decrement the reference
count on the routing table entry, and proceed with actual freeing if the
reference count has reached zero.
The
RT_LOCK
() macro is used to lock a routing
table entry.
The
RT_UNLOCK
() macro is used to unlock a
routing table entry.
The
RT_ADDREF
() macro increments the
reference count on a previously locked route entry. It should be used whenever
a reference to an
rtentry(9) is going to be
stored outside the routing table.
The
RT_REMREF
() macro decrements the
reference count on a previously locked route entry. Its usage is contrary to
RT_ADDREF
().
The
RO_RTFREE
() macro is used to free route
entry that is referenced by struct route. At certain circumstances the latter
may not hold a reference on rtentry, and
RO_RTFREE
() treats such routes correctly.
The
rtfree
() function does the actual free of
the routing table entry, and shouldn't be called directly by facilities, that
just perform routing table lookups.
LEGACY INTERFACE¶
Prior to introduction of multiple routing tables functions did not require the
u_int fibnum argument. Legacy
rtalloc1
(),
rtalloc
() and
rtalloc_ign
() functions are kept for
compatibility, and are equivalent to calling new interface with
fibnum argument equal to
0, which implies default forwarding table.
RETURN VALUES¶
The
rtalloc1_fib
() function returns a pointer
to a locked routing-table entry if it succeeds, otherwise a null pointer. The
rtalloc_fib
() and
rtalloc_ign_fib
() functions do not return a
value, but they fill in the
*ro_rt member of
the
*ro argument with a pointer to an
unlocked routing-table entry if they succeed, otherwise a null pointer. In a
case of success all functions put a reference on the routing-table entry,
freeing of which is responsibility of the caller. Lack of a route should in
most cases be translated to the
errno(2) value
EHOSTUNREACH
.
SEE ALSO¶
route(4),
rtentry(9)
HISTORY¶
The
rtalloc
facility first appeared in
4.2BSD, although with much different internals. The
rtalloc_ign
() function and the
flags argument to
rtalloc1
() first appeared in
FreeBSD 2.0. Routing table locking was introduced in
FreeBSD 5.2. Multiple routing tables were introduced
in
FreeBSD 8.0.
AUTHORS¶
The original version of this manual page was written by
Garrett Wollman. It was significantly
updated by
Gleb Smirnoff.