mirror of
https://git.hardenedbsd.org/hardenedbsd/HardenedBSD.git
synced 2024-12-19 22:43:22 +01:00
Document what I believe to be the interface of rtalloc*.
This commit is contained in:
Garrett Wollman
parent
47ceb63687
commit
ad31211dc6
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=18810
@ -1,7 +1,7 @@
|
||||
# @(#)Makefile 8.1 (Berkeley) 6/5/93
|
||||
# $Id$
|
||||
|
||||
MAN9= at_shutdown.9 at_fork.9 at_exit.9 copy.9 devfs_add_devswf.9 \
|
||||
devfs_link.9 fetch.9 intro.9 sleep.9 spl.9 \
|
||||
devfs_link.9 fetch.9 intro.9 rtalloc.9 sleep.9 spl.9 \
|
||||
store.9 style.9 timeout.9
|
||||
|
||||
MLINKS+= copy.9 copyin.9 copy.9 copyout.9 copy.9 copystr.9 copy.9 copyinstr.9
|
||||
@ -9,6 +9,7 @@ MLINKS+= fetch.9 fubyte.9 fetch.9 fusword.9 fetch.9 fuswintr.9 fetch.9 fuword.9
|
||||
MLINKS+= at_shutdown.9 rm_at_shutdown.9
|
||||
MLINKS+= at_exit.9 rm_at_exit.9
|
||||
MLINKS+= at_fork.9 rm_at_fork.9
|
||||
MLINKS+= rtalloc.9 rtalloc_ign.9 rtalloc.9 rtalloc1.9
|
||||
MLINKS+= sleep.9 tsleep.9 sleep.9 wakeup.9
|
||||
MLINKS+= spl.9 splbio.9 spl.9 splclock.9 spl.9 splhigh.9 spl.9 splimp.9
|
||||
MLINKS+= spl.9 splnet.9 spl.9 splsoftclock.9 spl.9 splsofttty.9
|
||||
|
||||
200
share/man/man9/rtalloc.9
Normal file
200
share/man/man9/rtalloc.9
Normal file
@ -0,0 +1,200 @@
|
||||
.\"
|
||||
.\" 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.
|
||||
.\"
|
||||
.\" $Id$
|
||||
.Dd October 8, 1996
|
||||
.Os
|
||||
.Dt RTALLOC 9
|
||||
.Sh NAME
|
||||
.Nm rtalloc ,
|
||||
.Nm rtalloc_ign ,
|
||||
.Nm rtalloc1
|
||||
.Nd look up a route in the kernel routing table
|
||||
.Sh SYNOPSIS
|
||||
.Fd #include <sys/socket.h>
|
||||
.Fd #include <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"
|
||||
.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
|
||||
or
|
||||
.Dv RTF_PRCLONING
|
||||
is retrieved, and the action of those flags is not masked, the
|
||||
.Nm rtalloc
|
||||
facility automatically generates a new route using information in the
|
||||
old route as a template, and in the case of
|
||||
.Dv RTF_CLONING ,
|
||||
sends an
|
||||
.Dv RTM_RESOLVE
|
||||
message to the appropriate interface-address route-management routine
|
||||
.Pq Fn ifa->ifa_rtrequest .
|
||||
.Dv RTF_PRCLONING
|
||||
routes are assumed to be managed by the protcol 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
|
||||
.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
|
||||
.Ar 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
|
||||
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
|
||||
.Ar 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
|
||||
and
|
||||
.Dv RTF_PRCLONING
|
||||
flags are undesired. The
|
||||
.Ar ro
|
||||
argument is the same as
|
||||
.Fn rtalloc ,
|
||||
but there is additionally a
|
||||
.Ar flags
|
||||
argument, which lists the flags in the route which are to be
|
||||
.Em ignored
|
||||
(ordinarily, one or both of
|
||||
.Dv RTF_CLONING
|
||||
or
|
||||
.Dv RTF_PRCLONING ) .
|
||||
.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
|
||||
.Ar sa
|
||||
argument. The second argument,
|
||||
.Ar 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,
|
||||
.Ar flags ,
|
||||
is a set of flags to ignore, as in
|
||||
.Fn rtalloc_ign .
|
||||
.Sh RETURN VALUES
|
||||
The
|
||||
.Fn rtalloc
|
||||
and
|
||||
.Fn rtalloc_ign
|
||||
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
|
||||
.Sh HISTORY
|
||||
The
|
||||
.Nm rtalloc
|
||||
facility first appeared in
|
||||
.Bx 4.2 ,
|
||||
although with much different internals. The
|
||||
.Fn rtalloc_ign
|
||||
function and the
|
||||
.Ar flags
|
||||
argument to
|
||||
.Fn rtalloc1
|
||||
first appeared in
|
||||
.Fx 2.0 .
|
||||
.Sh AUTHOR
|
||||
This manual page was written by Garrett Wollman, as were the changes
|
||||
to implement
|
||||
.Dv RTF_PRCLONING
|
||||
and the
|
||||
.Fn rtalloc_ign
|
||||
function and the
|
||||
.Ar flags
|
||||
argument to
|
||||
.Fn rtalloc1 .
|
||||
Loading…
Reference in New Issue
Block a user