Document what I believe to be the interface of rtalloc*.

2 files changed, 203 insertions, 2 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 400908f..dc598d3 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 0000000..bc91eca
--- /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 <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 .