Author: glebius
Date: Tue Jan 31 19:00:01 2012
New Revision: 230840
URL: http://svn.freebsd.org/changeset/base/230840
Log:
Merge r228499:
Update this page to describe modern interfaces.
Modified:
stable/9/share/man/man9/rtalloc.9
Directory Properties:
stable/9/share/man/man9/ (props changed)
Modified: stable/9/share/man/man9/rtalloc.9
==============================================================================
--- stable/9/share/man/man9/rtalloc.9 Tue Jan 31 18:48:54 2012
(r230839)
+++ stable/9/share/man/man9/rtalloc.9 Tue Jan 31 19:00:01 2012
(r230840)
@@ -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.
-.Pp
-The default interface is
-.Fn rtalloc .
-Its only argument is
+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
+.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" .
-.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" .
+argument, which is same as in
+.Fn rtalloc1_fib .
.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
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" .
_______________________________________________
svn-src-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"
