bb978628ec
- Describe how RT_FREE actually works. Grammar check: ru Reviewed by: sam MFC after: 1 month
267 lines
6.6 KiB
Groff
267 lines
6.6 KiB
Groff
.\"
|
|
.\" Copyright 1996 Massachusetts Institute of Technology
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software and
|
|
.\" its documentation for any purpose and without fee is hereby
|
|
.\" granted, provided that both the above copyright notice and this
|
|
.\" permission notice appear in all copies, that both the above
|
|
.\" copyright notice and this permission notice appear in all
|
|
.\" supporting documentation, and that the name of M.I.T. not be used
|
|
.\" in advertising or publicity pertaining to distribution of the
|
|
.\" software without specific, written prior permission. M.I.T. makes
|
|
.\" no representations about the suitability of this software for any
|
|
.\" purpose. It is provided "as is" without express or implied
|
|
.\" warranty.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS
|
|
.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
|
|
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
|
|
.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
|
|
.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
|
|
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.Dd October 11, 2004
|
|
.Os
|
|
.Dt RTALLOC 9
|
|
.Sh NAME
|
|
.Nm rtalloc ,
|
|
.Nm rtalloc_ign ,
|
|
.Nm rtalloc1 ,
|
|
.Nm rtfree
|
|
.Nd look up a route in the kernel routing table
|
|
.Sh SYNOPSIS
|
|
.In sys/types.h
|
|
.In sys/socket.h
|
|
.In net/route.h
|
|
.Ft void
|
|
.Fn rtalloc "struct route *ro"
|
|
.Ft void
|
|
.Fn rtalloc_ign "struct route *ro" "u_long flags"
|
|
.Ft "struct rtentry *"
|
|
.Fn rtalloc1 "struct sockaddr *sa" "int report" "u_long flags"
|
|
.Ft void
|
|
.Fn rtfree "struct rt_entry *rt"
|
|
.Fn RTFREE "struct rt_entry *rt"
|
|
.Fn RT_LOCK "struct rt_entry *rt"
|
|
.Fn RT_UNLOCK "struct rt_entry *rt"
|
|
.Fn RT_ADDREF "struct rt_entry *rt"
|
|
.Fn RT_REMREF "struct rt_entry *rt"
|
|
.Sh DESCRIPTION
|
|
The kernel uses a radix tree structure to manage routes for the
|
|
networking subsystem.
|
|
The
|
|
.Fn rtalloc
|
|
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.
|
|
.\" XXX - -mdoc should contain a standard request for getting em and
|
|
.\" en dashes.
|
|
.Pp
|
|
When a route with the flag
|
|
.Dv RTF_CLONING
|
|
is retrieved, and the action of this flag is not masked, the
|
|
.Nm
|
|
facility automatically generates a new route using information in the
|
|
old route as a template, and
|
|
sends an
|
|
.Dv RTM_RESOLVE
|
|
message to the appropriate interface-address route-management routine
|
|
.Pq Fn ifa->ifa_rtrequest .
|
|
This generated route is called
|
|
.Em cloned ,
|
|
and has
|
|
.Dv RTF_WASCLONED
|
|
flag set.
|
|
.Dv RTF_PRCLONING
|
|
flag is obsolete and thus ignored by facility.
|
|
If the
|
|
.Dv RTF_XRESOLVE
|
|
flag is set, then the
|
|
.Dv RTM_RESOLVE
|
|
message is sent instead on the
|
|
.Xr route 4
|
|
socket interface, requesting that an external program resolve the
|
|
address in question and modify the route appropriately.
|
|
.Pp
|
|
The default interface is
|
|
.Fn rtalloc .
|
|
Its only argument is
|
|
.Fa ro ,
|
|
a pointer to a
|
|
.Dq Li "struct route" ,
|
|
which is defined as follows:
|
|
.Bd -literal -offset indent
|
|
struct route {
|
|
struct sockaddr ro_dst;
|
|
struct rtentry *ro_rt;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
Thus, this function can only be used for address families which are
|
|
smaller than the default
|
|
.Dq Li "struct sockaddr" .
|
|
Before calling
|
|
.Fn rtalloc
|
|
for the first time, callers should ensure that unused bits of the
|
|
structure are set to zero.
|
|
On subsequent calls,
|
|
.Fn rtalloc
|
|
returns without performing a lookup if
|
|
.Fa ro->ro_rt
|
|
is non-null and the
|
|
.Dv RTF_UP
|
|
flag is set in the route's
|
|
.Li rt_flags
|
|
field.
|
|
.Pp
|
|
The
|
|
.Fn rtalloc_ign
|
|
interface can be used when the default actions of
|
|
.Fn rtalloc
|
|
in the presence of the
|
|
.Dv RTF_CLONING
|
|
flag is undesired.
|
|
The
|
|
.Fa ro
|
|
argument is the same as
|
|
.Fn rtalloc ,
|
|
but there is additionally a
|
|
.Fa flags
|
|
argument, which lists the flags in the route which are to be
|
|
.Em ignored
|
|
(in most cases this is
|
|
.Dv RTF_CLONING
|
|
flag).
|
|
Both
|
|
.Fn rtalloc
|
|
and
|
|
.Fn rtalloc_ign
|
|
functions return a pointer to an unlocked
|
|
.Vt "struct rtentry" .
|
|
.Pp
|
|
The
|
|
.Fn rtalloc1
|
|
function is the most general form of
|
|
.Fn rtalloc
|
|
(and both of the other forms are implemented as calls to rtalloc1).
|
|
It does not use the
|
|
.Dq Li "struct route" ,
|
|
and is therefore suitable for address families which require more
|
|
space than is in a traditional
|
|
.Dq Li "struct sockaddr" .
|
|
Instead, it takes a
|
|
.Dq Li "struct sockaddr *"
|
|
directly as the
|
|
.Fa sa
|
|
argument.
|
|
The second argument,
|
|
.Fa report ,
|
|
controls whether
|
|
.Dv RTM_RESOLVE
|
|
requests are sent to the lower layers when an
|
|
.Dv RTF_CLONING
|
|
or
|
|
.Dv 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,
|
|
.Fa flags ,
|
|
is a set of flags to ignore, as in
|
|
.Fn rtalloc_ign .
|
|
The
|
|
.Fn rtalloc1
|
|
function returns a pointer to a locked
|
|
.Vt "struct rtentry" .
|
|
.Pp
|
|
The
|
|
.Fn rtfree
|
|
function frees a locked route entry, e.g., a previously allocated by
|
|
.Fn rtalloc1 .
|
|
.Pp
|
|
The
|
|
.Fn RTFREE
|
|
macro is used to free unlocked route entries, previously allocated by
|
|
.Fn rtalloc
|
|
or
|
|
.Fn rtalloc_ign .
|
|
The
|
|
.Fn RTFREE
|
|
macro decrements the reference count on the routing table entry (see below),
|
|
and frees it if the reference count has reached zero.
|
|
.Pp
|
|
The preferred usage is allocating a route using
|
|
.Fn rtalloc
|
|
or
|
|
.Fn rtalloc_ign
|
|
and freeing using
|
|
.Fn RTFREE .
|
|
.Pp
|
|
The
|
|
.Fn RT_LOCK
|
|
macro is used to lock a routing table entry.
|
|
The
|
|
.Fn RT_UNLOCK
|
|
macro is used to unlock a routing table entry.
|
|
.Pp
|
|
The
|
|
.Fn RT_ADDREF
|
|
macro increments the reference count on a previously locked route entry.
|
|
The
|
|
.Fn RT_REMREF
|
|
macro decrements the reference count on a previously locked route entry.
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn rtalloc ,
|
|
.Fn rtalloc_ign
|
|
and
|
|
.Fn rtfree
|
|
functions do not return a value.
|
|
The
|
|
.Fn 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
|
|
.Xr errno 2
|
|
value
|
|
.Er EHOSTUNREACH .
|
|
.Sh SEE ALSO
|
|
.Xr route 4 ,
|
|
.Xr rtentry 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
facility first appeared in
|
|
.Bx 4.2 ,
|
|
although with much different internals.
|
|
The
|
|
.Fn rtalloc_ign
|
|
function and the
|
|
.Fa flags
|
|
argument to
|
|
.Fn rtalloc1
|
|
first appeared in
|
|
.Fx 2.0 .
|
|
Routing table locking was introduced in
|
|
.Fx 5.2 .
|
|
.Sh AUTHORS
|
|
This manual page was written by
|
|
.An Garrett Wollman ,
|
|
as were the changes to implement
|
|
.Dv RTF_PRCLONING
|
|
and the
|
|
.Fn rtalloc_ign
|
|
function and the
|
|
.Fa flags
|
|
argument to
|
|
.Fn rtalloc1 .
|