Update this page to describe modern interfaces.

1 files changed, 147 insertions, 114 deletions

diff --git a/share/man/man9/rtalloc.9 b/share/man/man9/rtalloc.9
index 31d5ebb..ab5379a 100644
--- a/share/man/man9/rtalloc.9
+++ b/share/man/man9/rtalloc.9
@@ -28,160 +28,163 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd December 11, 2008
+.Dd December 14, 2011
 .Dt RTALLOC 9
 .Os
 .Sh NAME
-.Nm rtalloc ,
-.Nm rtalloc_ign ,
-.Nm rtalloc1 ,
-.Nm rtfree
+.Nm rtalloc1_fib ,
+.Nm rtalloc_ign_fib ,
+.Nm rtalloc_fib
 .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"
+.Fn rtalloc1_fib "struct sockaddr *dst" "int report" "u_long flags" "u_int fibnum"
 .Ft void
-.Fn rtfree "struct rt_entry *rt"
+.Fn rtalloc_fib "struct route *ro" "u_int fibnum"
+.Ft void
+.Fn rtalloc_ign_fib "struct route *ro" "u_long flags" "u_int fibnum"
+.Fn RTFREE_LOCKED "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"
+.Ft void
+.Fn rtfree "struct rt_entry *rt"
+.Ft "struct rtentry *"
+.Fn rtalloc1 "struct sockaddr *dst" "int report" "u_long flags"
+.Ft void
+.Fn rtalloc "struct route *ro"
+.Ft void
+.Fn rtalloc_ign "struct route *ro" "u_long flags"
+.Pp
+.Cd options RADIX_MPATH
 .Sh DESCRIPTION
 The kernel uses a radix tree structure to manage routes for the
 networking subsystem.
+If compiled with
+.Cd options RADIX_MPATH
+kernel may maintain several independent forwarding information databases (FIBs).
 The
 .Fn rtalloc
-family of routines is used by protocols to query this structure for a
+family of routines is used by protocols to query these structures 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.
+The
+.Fn rtalloc1_fib
+function is the most general form of
+.Fn rtalloc ,
+and all of the other forms are implemented as calls to it.
+It takes a
+.Fa "struct sockaddr *"
+directly as the
+.Fa dst
+argument.
+The second argument,
+.Fa report ,
+controls whether the routing sockets are notified when a lookup fails.
+The third argument,
+.Fa flags ,
+is a combination of
+the following values:
+.Bl -item -offset indent
+.It
+.Dv RTF_RNH_LOCKED
+indicates that the radix tree lock is already held
+.El
+.Pp
+The last argument
+.Fa fibnum
+specifies number of forwarding information database (FIB) on which
+the lookup should be performed.
+In case of success the
+.Fn rtalloc1_fib
+function returns a pointer to a locked
+.Vt "struct rtentry"
+with an additional reference.
 .Pp
-The default interface is
-.Fn rtalloc .
-Its only argument is
+The
+.Fn rtalloc_fib
+is the most simple variant.
+Its main argument is
 .Fa ro ,
 a pointer to a
-.Dq Li "struct route" ,
+.Fa "struct route" ,
 which is defined as follows:
 .Bd -literal -offset indent
 struct route {
-	struct sockaddr ro_dst;
 	struct rtentry *ro_rt;
+	struct llentry *ro_lle;
+	struct sockaddr ro_dst;
 };
 .Ed
 .Pp
 Thus, this function can only be used for address families which are
 smaller than the default
-.Dq Li "struct sockaddr" .
+.Ft "struct sockaddr" .
 Before calling
-.Fn rtalloc
+.Fn rtalloc_fib
 for the first time, callers should ensure that unused bits of the
 structure are set to zero.
+The second argument
+.Fa fibnum
+is FIB number.
+In case of success of the
+.Fn rtalloc_fib
+the
+.Fa ro_rt
+points to a valid and unlocked
+.Xr rtentry 9 ,
+which has an additional reference put on it, freeing which is
+responsibility of the caller.
 On subsequent calls,
-.Fn rtalloc
+.Fn rtalloc_fib
 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
+flag is set in the rtentry's
+.Fa 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
+.Fn rtalloc_ign_fib
+function is the same as the
+.Fn rtalloc_fib ,
+but there is additional
 .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" .
+argument, which is same as in
+.Fn rtalloc1_fib .
 .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 .
+.Fn RTFREE_LOCKED
+macro is used to unref and possibly free a locked routing entry
+with one our reference, for example previously allocated by
+.Fn rtalloc1_fib .
 .Pp
 The
 .Fn RTFREE
-macro is used to free unlocked route entries, previously allocated by
-.Fn rtalloc
+macro is used to unref and possibly free an unlocked route entries with
+one our reference, for example previously allocated by
+.Fn rtalloc_fib
 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.
+.Fn rtalloc_ign_fib .
 .Pp
-The preferred usage is allocating a route using
-.Fn rtalloc
-or
-.Fn rtalloc_ign
-and freeing using
-.Fn RTFREE .
+Both
+.Fn RTFREE_LOCKED
+and
+.Fn RTFREE
+macros decrement the reference count on the routing table entry,
+and proceed with actual freeing if the reference count has reached zero.
 .Pp
 The
 .Fn RT_LOCK
 macro is used to lock a routing table entry.
+.Pp
 The
 .Fn RT_UNLOCK
 macro is used to unlock a routing table entry.
@@ -189,20 +192,53 @@ macro is used to unlock a routing table entry.
 The
 .Fn RT_ADDREF
 macro increments the reference count on a previously locked route entry.
+It should be used whenever a reference to an
+.Xr rtentry 9
+is going to be stored outside the routing table.
+.Pp
 The
 .Fn RT_REMREF
 macro decrements the reference count on a previously locked route entry.
-.Sh RETURN VALUES
+Its usage is contrary to
+.Fn RT_ADDREF .
+.Pp
 The
-.Fn rtalloc ,
-.Fn rtalloc_ign
-and
 .Fn rtfree
-functions do not return a value.
+function does the actual free of the routing table entry, and shouldn't
+be called directly by facilities, that just perform routing table lookups.
+.Sh LEGACY INTERFACE
+Prior to introduction of multiple routing tables functions did not
+require the
+.Fa "u_int fibnum"
+argument.
+Legacy
+.Fn rtalloc1 ,
+.Fn rtalloc
+and
+.Fn rtalloc_ign
+functions are kept for compatibility, and are equivalent to
+calling new interface with
+.Fa fibnum
+argument equal to
+.Va 0 ,
+which implies default forwarding table.
+.Sh RETURN VALUES
 The
-.Fn rtalloc1
-function returns a pointer to a routing-table entry if it succeeds,
+.Fn rtalloc1_fib
+function returns a pointer to a locked routing-table entry if it succeeds,
 otherwise a null pointer.
+The
+.Fn rtalloc_fib
+and
+.Fn rtalloc_ign_fib
+functions do not return a value, but they fill in the
+.Fa *ro_rt
+member of the
+.Fa *ro
+argument with a pointer to an unlocked routing-table entry if they
+succeed, otherwise a null pointer.
+In a case of success all functions put a reference on the
+routing-table entry, freeing of which is responsibility of the caller.
 Lack of a route should in most cases be
 translated to the
 .Xr errno 2
@@ -213,7 +249,7 @@ value
 .Xr rtentry 9
 .Sh HISTORY
 The
-.Nm
+.Nm rtalloc
 facility first appeared in
 .Bx 4.2 ,
 although with much different internals.
@@ -227,14 +263,11 @@ first appeared in
 .Fx 2.0 .
 Routing table locking was introduced in
 .Fx 5.2 .
+Multiple routing tables were introduced in
+.Fx 8.0 .
 .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 .
+The original version of this manual page was written by
+.An -nosplit
+.An "Garrett Wollman" .
+It was significantly updated by
+.An "Gleb Smirnoff" .