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: src/share/man/man9/rtalloc.9,v 1.8.2.4 2001/12/17 11:30:18 ru Exp $ 30.\" 31.Dd October 8, 1996 32.Dt RTALLOC 9 33.Os 34.Sh NAME 35.Nm rtalloc , 36.Nm rtalloc_ign , 37.Nm rtalloc1 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.Sh DESCRIPTION 50The kernel uses a radix tree structure to manage routes for the 51networking subsystem. The 52.Fn rtalloc 53family of routines is used by protocols to query this structure for a 54route corresponding to a particular end-node address, and to cause 55certain protocol\- and interface-specific actions to take place. 56.\" XXX - -mdoc should contain a standard request for getting em and 57.\" en dashes. 58.Pp 59When a route with the flag 60.Dv RTF_CLONING 61or 62.Dv RTF_PRCLONING 63is retrieved, and the action of those flags is not masked, the 64.Nm 65facility automatically generates a new route using information in the 66old route as a template, and in the case of 67.Dv RTF_CLONING , 68sends an 69.Dv RTM_RESOLVE 70message to the appropriate interface-address route-management routine 71.Pq Fn ifa->ifa_rtrequest . 72.Dv RTF_PRCLONING 73routes are assumed to be managed by the protocol family and no 74resolution requests are made, but all routes generated by the cloning 75process retain a reference to the route from which they were 76generated. 77If the 78.Dv RTF_XRESOLVE 79flag is set, then the 80.Dv RTM_RESOLVE 81message is sent instead on the 82.Xr route 4 83socket interface, requesting that an external program resolve the 84address in question and modify the route appropriately. 85.Pp 86The default interface is 87.Fn rtalloc . 88Its only argument is 89.Fa ro , 90a pointer to a 91.Dq Li "struct route" , 92which is defined as follows: 93.Bd -literal -offset indent 94struct route { 95 struct sockaddr ro_dst; 96 struct rtentry *ro_rt; 97}; 98.Ed 99Thus, this function can only be used for address families which are 100smaller than the default 101.Dq Li "struct sockaddr" . 102Before calling 103.Fn rtalloc 104for the first time, callers should ensure that unused bits of the 105structure are set to zero. On subsequent calls, 106.Fn rtalloc 107returns without performing a lookup if 108.Va ro->ro_rt 109is non-null and the 110.Dv RTF_UP 111flag is set in the route's 112.Li rt_flags 113field. 114.Pp 115The 116.Fn rtalloc_ign 117interface can be used when the default actions of 118.Fn rtalloc 119in the presence of the 120.Dv RTF_CLONING 121and 122.Dv RTF_PRCLONING 123flags are undesired. The 124.Fa ro 125argument is the same as 126.Fn rtalloc , 127but there is additionally a 128.Fa flags 129argument, which lists the flags in the route which are to be 130.Em ignored 131(ordinarily, one or both of 132.Dv RTF_CLONING 133or 134.Dv RTF_PRCLONING ) . 135.Pp 136The 137.Fn rtalloc1 138function is the most general form of 139.Fn rtalloc 140(and both of the other forms are implemented as calls to rtalloc1). 141It does not use the 142.Dq Li "struct route" , 143and is therefore suitable for address families which require more 144space than is in a traditional 145.Dq Li "struct sockaddr" . 146Instead, it takes a 147.Dq Li "struct sockaddr *" 148directly as the 149.Fa sa 150argument. The second argument, 151.Fa report , 152controls whether 153.Dv RTM_RESOLVE 154requests are sent to the lower layers when an 155.Dv RTF_CLONING 156or 157.Dv RTF_PRCLONING 158route is cloned. Ordinarily a value of one should be passed, except 159in the processing of those lower layers which use the cloning 160facility. 161The third argument, 162.Fa flags , 163is a set of flags to ignore, as in 164.Fn rtalloc_ign . 165.Sh RETURN VALUES 166The 167.Fn rtalloc 168and 169.Fn rtalloc_ign 170functions do not return a value. The 171.Fn rtalloc1 172function returns a pointer to a routing-table entry if it succeeds, 173otherwise a null pointer. Lack of a route should in most cases be 174translated to the 175.Xr errno 2 176value 177.Er EHOSTUNREACH . 178.Sh SEE ALSO 179.Xr route 4 , 180.Xr rtentry 9 181.Sh HISTORY 182The 183.Nm 184facility first appeared in 185.Bx 4.2 , 186although with much different internals. The 187.Fn rtalloc_ign 188function and the 189.Fa flags 190argument to 191.Fn rtalloc1 192first appeared in 193.Fx 2.0 . 194.Sh AUTHORS 195This manual page was written by 196.An Garrett Wollman , 197as were the changes to implement 198.Dv RTF_PRCLONING 199and the 200.Fn rtalloc_ign 201function and the 202.Fa flags 203argument to 204.Fn rtalloc1 . 205