From ad31211dc61389d54af7dde530601cd9d1451ea9 Mon Sep 17 00:00:00 2001 From: Garrett Wollman Date: Tue, 8 Oct 1996 18:45:06 +0000 Subject: [PATCH] Document what I believe to be the interface of rtalloc*. --- share/man/man9/Makefile | 5 +- share/man/man9/rtalloc.9 | 200 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 203 insertions(+), 2 deletions(-) create mode 100644 share/man/man9/rtalloc.9 diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 400908fcfefa..dc598d3cd7b2 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -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 diff --git a/share/man/man9/rtalloc.9 b/share/man/man9/rtalloc.9 new file mode 100644 index 000000000000..bc91eca847ce --- /dev/null +++ b/share/man/man9/rtalloc.9 @@ -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 +.Fd #include +.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 .