From owner-svn-src-stable-9@FreeBSD.ORG Tue Jan 31 19:00:02 2012 Return-Path: Delivered-To: svn-src-stable-9@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 6B598106564A; Tue, 31 Jan 2012 19:00:02 +0000 (UTC) (envelope-from glebius@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 4E99B8FC0A; Tue, 31 Jan 2012 19:00:02 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id q0VJ02Ea050410; Tue, 31 Jan 2012 19:00:02 GMT (envelope-from glebius@svn.freebsd.org) Received: (from glebius@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id q0VJ02rm050407; Tue, 31 Jan 2012 19:00:02 GMT (envelope-from glebius@svn.freebsd.org) Message-Id: <201201311900.q0VJ02rm050407@svn.freebsd.org> From: Gleb Smirnoff Date: Tue, 31 Jan 2012 19:00:02 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-9@freebsd.org X-SVN-Group: stable-9 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r230840 - stable/9/share/man/man9 X-BeenThere: svn-src-stable-9@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for only the 9-stable src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 31 Jan 2012 19:00:02 -0000 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" .