NAME
rtalloc,
rtalloc_ign, rtalloc1
— look up a route in the kernel
routing table
SYNOPSIS
#include
<sys/types.h>
#include <sys/socket.h>
#include <net/route.h>
void
rtalloc(struct
route *ro);
void
rtalloc_ign(struct
route *ro, u_long
flags);
struct rtentry *
rtalloc1(struct
sockaddr *sa, int
report, u_long
flags);
DESCRIPTION
The kernel uses a radix tree structure to manage routes for the networking subsystem. Thertalloc()
family of routines is used by protocols to query this structure for a route
corresponding to a particular end-node address, and to cause certain protocol-
and interface-specific actions to take place.
When a route with the flag
RTF_CLONING or RTF_PRCLONING
is retrieved, and the action of those flags is not masked, the
rtalloc facility automatically generates a new route
using information in the old route as a template, and in the case of
RTF_CLONING, sends an
RTM_RESOLVE message to the appropriate
interface-address route-management routine
(ifa->ifa_rtrequest()).
RTF_PRCLONING routes are assumed to be managed by
the protocol family and no resolution requests are made, but all routes
generated by the cloning process retain a reference to the route from which
they were generated. If the RTF_XRESOLVE flag is
set, then the RTM_RESOLVE message is sent instead on
the route(4) socket interface, requesting that an external program
resolve the address in question and modify the route appropriately.
The default interface is
rtalloc().
Its only argument is ro, a pointer to a
“struct route”, which is defined as
follows:
struct route {
struct sockaddr ro_dst;
struct rtentry *ro_rt;
};
struct sockaddr”. Before
calling rtalloc() for the first time, callers should
ensure that unused bits of the structure are set to zero. On subsequent calls,
rtalloc() returns without performing a lookup if
ro->ro_rt is non-null and the
RTF_UP flag is set in the route's
rt_flags field.
The
rtalloc_ign()
interface can be used when the default actions of
rtalloc() in the presence of the
RTF_CLONING and
RTF_PRCLONING flags are undesired. The
ro argument is the same as
rtalloc(), but there is additionally a
flags argument, which lists the flags in the route
which are to be
ignored
(ordinarily, one or both of RTF_CLONING or
RTF_PRCLONING).
The
rtalloc1()
function is the most general form of rtalloc() (and
both of the other forms are implemented as calls to rtalloc1). It does not
use the “struct route”, and is
therefore suitable for address families which require more space than is in
a traditional “struct sockaddr”.
Instead, it takes a “struct sockaddr
*” directly as the sa argument. The
second argument, report, controls whether
RTM_RESOLVE requests are sent to the lower layers
when an RTF_CLONING or
RTF_PRCLONING route is cloned. Ordinarily a value of
one should be passed, except in the processing of those lower layers which
use the cloning facility. The third argument, flags,
is a set of flags to ignore, as in
rtalloc_ign().
RETURN VALUES
The rtalloc() and
rtalloc_ign() functions do not return a value. The
rtalloc1() function returns a pointer to a
routing-table entry if it succeeds, otherwise a null pointer. Lack of a
route should in most cases be translated to the
errno(2) value EHOSTUNREACH.
SEE ALSO
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.
AUTHORS
This manual page was written by Garrett
Wollman, as were the changes to implement
RTF_PRCLONING and the
rtalloc_ign() function and the
flags argument to
rtalloc1().