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