1 files changed, 240 insertions, 0 deletions
diff --git a/share/man/man9/rtalloc.9 b/share/man/man9/rtalloc.9
new file mode 100644
index 000000000000..cbd2c5eaab5f
--- /dev/null
+++ b/share/man/man9/rtalloc.9
@@ -0,0 +1,240 @@
+.\"
+.\" 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 December 11, 2008
+.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
+.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 caller does not want to receive
+the returned
+.Fa rtentry
+locked.
+The
+.Fa ro
+argument is the same as
+.Fn rtalloc ,
+but there is additionally a
+.Fa flags
+argument, which is now only used to pass
+.Dv RTF_RNH_LOCKED
+indicating that the radix tree lock is already held.
+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 the lower layers are notified when a lookup fails.
+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 .