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.Dd October 11, 2004 31.Os 32.Dt RTALLOC 9 33.Sh NAME 34.Nm rtalloc , 35.Nm rtalloc_ign , 36.Nm rtalloc1 , 37.Nm rtfree 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 void 44.Fn rtalloc "struct route *ro" 45.Ft void 46.Fn rtalloc_ign "struct route *ro" "u_long flags" 47.Ft "struct rtentry *" 48.Fn rtalloc1 "struct sockaddr *sa" "int report" "u_long flags" 49.Ft void 50.Fn rtfree "struct rt_entry *rt" 51.Fn RTFREE "struct rt_entry *rt" 52.Fn RT_LOCK "struct rt_entry *rt" 53.Fn RT_UNLOCK "struct rt_entry *rt" 54.Fn RT_ADDREF "struct rt_entry *rt" 55.Fn RT_REMREF "struct rt_entry *rt" 56.Sh DESCRIPTION 57The kernel uses a radix tree structure to manage routes for the 58networking subsystem. 59The 60.Fn rtalloc 61family of routines is used by protocols to query this structure for a 62route corresponding to a particular end-node address, and to cause 63certain protocol\- and interface-specific actions to take place. 64.\" XXX - -mdoc should contain a standard request for getting em and 65.\" en dashes. 66.Pp 67When a route with the flag 68.Dv RTF_CLONING 69is retrieved, and the action of this flag is not masked, the 70.Nm 71facility automatically generates a new route using information in the 72old route as a template, and 73sends an 74.Dv RTM_RESOLVE 75message to the appropriate interface-address route-management routine 76.Pq Fn ifa->ifa_rtrequest . 77This generated route is called 78.Em cloned , 79and has 80.Dv RTF_WASCLONED 81flag set. 82.Dv RTF_PRCLONING 83flag is obsolete and thus ignored by facility. 84If the 85.Dv RTF_XRESOLVE 86flag is set, then the 87.Dv RTM_RESOLVE 88message is sent instead on the 89.Xr route 4 90socket interface, requesting that an external program resolve the 91address in question and modify the route appropriately. 92.Pp 93The default interface is 94.Fn rtalloc . 95Its only argument is 96.Fa ro , 97a pointer to a 98.Dq Li "struct route" , 99which is defined as follows: 100.Bd -literal -offset indent 101struct route { 102 struct sockaddr ro_dst; 103 struct rtentry *ro_rt; 104}; 105.Ed 106.Pp 107Thus, this function can only be used for address families which are 108smaller than the default 109.Dq Li "struct sockaddr" . 110Before calling 111.Fn rtalloc 112for the first time, callers should ensure that unused bits of the 113structure are set to zero. 114On subsequent calls, 115.Fn rtalloc 116returns without performing a lookup if 117.Fa ro->ro_rt 118is non-null and the 119.Dv RTF_UP 120flag is set in the route's 121.Li rt_flags 122field. 123.Pp 124The 125.Fn rtalloc_ign 126interface can be used when the default actions of 127.Fn rtalloc 128in the presence of the 129.Dv RTF_CLONING 130flag is undesired. 131The 132.Fa ro 133argument is the same as 134.Fn rtalloc , 135but there is additionally a 136.Fa flags 137argument, which lists the flags in the route which are to be 138.Em ignored 139(in most cases this is 140.Dv RTF_CLONING 141flag). 142Both 143.Fn rtalloc 144and 145.Fn rtalloc_ign 146functions return a pointer to an unlocked 147.Vt "struct rtentry" . 148.Pp 149The 150.Fn rtalloc1 151function is the most general form of 152.Fn rtalloc 153(and both of the other forms are implemented as calls to rtalloc1). 154It does not use the 155.Dq Li "struct route" , 156and is therefore suitable for address families which require more 157space than is in a traditional 158.Dq Li "struct sockaddr" . 159Instead, it takes a 160.Dq Li "struct sockaddr *" 161directly as the 162.Fa sa 163argument. 164The second argument, 165.Fa report , 166controls whether 167.Dv RTM_RESOLVE 168requests are sent to the lower layers when an 169.Dv RTF_CLONING 170or 171.Dv RTF_PRCLONING 172route is cloned. 173Ordinarily a value of one should be passed, except 174in the processing of those lower layers which use the cloning 175facility. 176The third argument, 177.Fa flags , 178is a set of flags to ignore, as in 179.Fn rtalloc_ign . 180The 181.Fn rtalloc1 182function returns a pointer to a locked 183.Vt "struct rtentry" . 184.Pp 185The 186.Fn rtfree 187function frees a locked route entry, e.g., a previously allocated by 188.Fn rtalloc1 . 189.Pp 190The 191.Fn RTFREE 192macro is used to free unlocked route entries, previously allocated by 193.Fn rtalloc 194or 195.Fn rtalloc_ign . 196The 197.Fn RTFREE 198macro decrements the reference count on the routing table entry (see below), 199and frees it if the reference count has reached zero. 200.Pp 201The preferred usage is allocating a route using 202.Fn rtalloc 203or 204.Fn rtalloc_ign 205and freeing using 206.Fn RTFREE . 207.Pp 208The 209.Fn RT_LOCK 210macro is used to lock a routing table entry. 211The 212.Fn RT_UNLOCK 213macro is used to unlock a routing table entry. 214.Pp 215The 216.Fn RT_ADDREF 217macro increments the reference count on a previously locked route entry. 218The 219.Fn RT_REMREF 220macro decrements the reference count on a previously locked route entry. 221.Sh RETURN VALUES 222The 223.Fn rtalloc , 224.Fn rtalloc_ign 225and 226.Fn rtfree 227functions do not return a value. 228The 229.Fn rtalloc1 230function returns a pointer to a routing-table entry if it succeeds, 231otherwise a null pointer. 232Lack of a route should in most cases be 233translated to the 234.Xr errno 2 235value 236.Er EHOSTUNREACH . 237.Sh SEE ALSO 238.Xr route 4 , 239.Xr rtentry 9 240.Sh HISTORY 241The 242.Nm 243facility first appeared in 244.Bx 4.2 , 245although with much different internals. 246The 247.Fn rtalloc_ign 248function and the 249.Fa flags 250argument to 251.Fn rtalloc1 252first appeared in 253.Fx 2.0 . 254Routing table locking was introduced in 255.Fx 5.2 . 256.Sh AUTHORS 257This manual page was written by 258.An Garrett Wollman , 259as were the changes to implement 260.Dv RTF_PRCLONING 261and the 262.Fn rtalloc_ign 263function and the 264.Fa flags 265argument to 266.Fn rtalloc1 . 267