1.\" 2.\" Copyright 1996 Massachusetts Institute of Technology 3.\" 4.\" Permission to use, copy, modify, and distribute this software and 5.\" its documentation for any purpose and without fee is hereby 6.\" granted, provided that both the above copyright notice and this 7.\" permission notice appear in all copies, that both the above 8.\" copyright notice and this permission notice appear in all 9.\" supporting documentation, and that the name of M.I.T. not be used 10.\" in advertising or publicity pertaining to distribution of the 11.\" software without specific, written prior permission. M.I.T. makes 12.\" no representations about the suitability of this software for any 13.\" purpose. It is provided "as is" without express or implied 14.\" warranty. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS 17.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, 18.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 19.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT 20.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 21.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 22.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF 23.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 24.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 25.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 26.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" $FreeBSD$ 30.\" 31.Dd July 4, 2012 32.Dt RTALLOC 9 33.Os 34.Sh NAME 35.Nm rtalloc1_fib , 36.Nm rtalloc_ign_fib , 37.Nm rtalloc_fib 38.Nd look up a route in the kernel routing table 39.Sh SYNOPSIS 40.In sys/types.h 41.In sys/socket.h 42.In net/route.h 43.Ft "struct rtentry *" 44.Fn rtalloc1_fib "struct sockaddr *dst" "int report" "u_long flags" "u_int fibnum" 45.Ft void 46.Fn rtalloc_fib "struct route *ro" "u_int fibnum" 47.Ft void 48.Fn rtalloc_ign_fib "struct route *ro" "u_long flags" "u_int fibnum" 49.Fn RTFREE_LOCKED "struct rt_entry *rt" 50.Fn RTFREE "struct rt_entry *rt" 51.Fn RT_LOCK "struct rt_entry *rt" 52.Fn RT_UNLOCK "struct rt_entry *rt" 53.Fn RT_ADDREF "struct rt_entry *rt" 54.Fn RT_REMREF "struct rt_entry *rt" 55.Fn RO_RTFREE "struct route *ro" 56.Ft void 57.Fn rtfree "struct rt_entry *rt" 58.Ft "struct rtentry *" 59.Fn rtalloc1 "struct sockaddr *dst" "int report" "u_long flags" 60.Ft void 61.Fn rtalloc "struct route *ro" 62.Ft void 63.Fn rtalloc_ign "struct route *ro" "u_long flags" 64.Pp 65.Cd options RADIX_MPATH 66.Sh DESCRIPTION 67The kernel uses a radix tree structure to manage routes for the 68networking subsystem. 69If compiled with 70.Cd options RADIX_MPATH 71kernel may maintain several independent forwarding information databases (FIBs). 72The 73.Fn rtalloc 74family of routines is used by protocols to query these structures for a 75route corresponding to a particular end-node address, and to cause 76certain protocol\- and interface-specific actions to take place. 77.Pp 78The 79.Fn rtalloc1_fib 80function is the most general form of 81.Fn rtalloc , 82and all of the other forms are implemented as calls to it. 83It takes a 84.Fa "struct sockaddr *" 85directly as the 86.Fa dst 87argument. 88The second argument, 89.Fa report , 90controls whether the routing sockets are notified when a lookup fails. 91The third argument, 92.Fa flags , 93is a combination of 94the following values: 95.Bl -item -offset indent 96.It 97.Dv RTF_RNH_LOCKED 98indicates that the radix tree lock is already held 99.El 100.Pp 101The last argument 102.Fa fibnum 103specifies number of forwarding information database (FIB) on which 104the lookup should be performed. 105In case of success the 106.Fn rtalloc1_fib 107function returns a pointer to a locked 108.Vt "struct rtentry" 109with an additional reference. 110.Pp 111The 112.Fn rtalloc_fib 113is the most simple variant. 114Its main argument is 115.Fa ro , 116a pointer to a 117.Fa "struct route" , 118which is defined as follows: 119.Bd -literal -offset indent 120struct route { 121 struct rtentry *ro_rt; 122 struct llentry *ro_lle; 123 struct sockaddr ro_dst; 124}; 125.Ed 126.Pp 127Thus, this function can only be used for address families which are 128smaller than the default 129.Ft "struct sockaddr" . 130Before calling 131.Fn rtalloc_fib 132for the first time, callers should ensure that unused bits of the 133structure are set to zero. 134The second argument 135.Fa fibnum 136is FIB number. 137In case of success of the 138.Fn rtalloc_fib 139the 140.Fa ro_rt 141points to a valid and unlocked 142.Xr rtentry 9 , 143which has an additional reference put on it, freeing which is 144responsibility of the caller. 145On subsequent calls, 146.Fn rtalloc_fib 147returns without performing a lookup if 148.Fa ro->ro_rt 149is non-null and the 150.Dv RTF_UP 151flag is set in the rtentry's 152.Fa rt_flags 153field. 154.Pp 155The 156.Fn rtalloc_ign_fib 157function is the same as the 158.Fn rtalloc_fib , 159but there is additional 160.Fa flags 161argument, which is same as in 162.Fn rtalloc1_fib . 163.Pp 164The 165.Fn RTFREE_LOCKED 166macro is used to unref and possibly free a locked routing entry 167with one our reference, for example previously allocated by 168.Fn rtalloc1_fib . 169.Pp 170The 171.Fn RTFREE 172macro is used to unref and possibly free an unlocked route entries with 173one our reference, for example previously allocated by 174.Fn rtalloc_fib 175or 176.Fn rtalloc_ign_fib . 177.Pp 178Both 179.Fn RTFREE_LOCKED 180and 181.Fn RTFREE 182macros decrement the reference count on the routing table entry, 183and proceed with actual freeing if the reference count has reached zero. 184.Pp 185The 186.Fn RT_LOCK 187macro is used to lock a routing table entry. 188.Pp 189The 190.Fn RT_UNLOCK 191macro is used to unlock a routing table entry. 192.Pp 193The 194.Fn RT_ADDREF 195macro increments the reference count on a previously locked route entry. 196It should be used whenever a reference to an 197.Xr rtentry 9 198is going to be stored outside the routing table. 199.Pp 200The 201.Fn RT_REMREF 202macro decrements the reference count on a previously locked route entry. 203Its usage is contrary to 204.Fn RT_ADDREF . 205.Pp 206The 207.Fn RO_RTFREE 208macro is used to free route entry that is referenced by struct route. 209At certain circumstances the latter may not hold a reference on rtentry, 210and 211.Fn RO_RTFREE 212treats such routes correctly. 213.Pp 214The 215.Fn rtfree 216function does the actual free of the routing table entry, and shouldn't 217be called directly by facilities, that just perform routing table lookups. 218.Sh LEGACY INTERFACE 219Prior to introduction of multiple routing tables functions did not 220require the 221.Fa "u_int fibnum" 222argument. 223Legacy 224.Fn rtalloc1 , 225.Fn rtalloc 226and 227.Fn rtalloc_ign 228functions are kept for compatibility, and are equivalent to 229calling new interface with 230.Fa fibnum 231argument equal to 232.Va 0 , 233which implies default forwarding table. 234.Sh RETURN VALUES 235The 236.Fn rtalloc1_fib 237function returns a pointer to a locked routing-table entry if it succeeds, 238otherwise a null pointer. 239The 240.Fn rtalloc_fib 241and 242.Fn rtalloc_ign_fib 243functions do not return a value, but they fill in the 244.Fa *ro_rt 245member of the 246.Fa *ro 247argument with a pointer to an unlocked routing-table entry if they 248succeed, otherwise a null pointer. 249In a case of success all functions put a reference on the 250routing-table entry, freeing of which is responsibility of the caller. 251Lack of a route should in most cases be 252translated to the 253.Xr errno 2 254value 255.Er EHOSTUNREACH . 256.Sh SEE ALSO 257.Xr route 4 , 258.Xr rtentry 9 259.Sh HISTORY 260The 261.Nm rtalloc 262facility first appeared in 263.Bx 4.2 , 264although with much different internals. 265The 266.Fn rtalloc_ign 267function and the 268.Fa flags 269argument to 270.Fn rtalloc1 271first appeared in 272.Fx 2.0 . 273Routing table locking was introduced in 274.Fx 5.2 . 275Multiple routing tables were introduced in 276.Fx 8.0 . 277.Sh AUTHORS 278The original version of this manual page was written by 279.An -nosplit 280.An "Garrett Wollman" . 281It was significantly updated by 282.An "Gleb Smirnoff" . 283