2 .\" Copyright 1996 Massachusetts Institute of Technology
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
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
39 .Nd look up a route in the kernel routing table
45 .Fn rtalloc "struct route *ro"
47 .Fn rtalloc_ign "struct route *ro" "u_long flags"
48 .Ft "struct rtentry *"
49 .Fn rtalloc1 "struct sockaddr *sa" "int report" "u_long flags"
51 .Fn rtfree "struct rt_entry *rt"
52 .Fn RTFREE "struct rt_entry *rt"
53 .Fn RT_LOCK "struct rt_entry *rt"
54 .Fn RT_UNLOCK "struct rt_entry *rt"
55 .Fn RT_ADDREF "struct rt_entry *rt"
56 .Fn RT_REMREF "struct rt_entry *rt"
58 The kernel uses a radix tree structure to manage routes for the
62 family of routines is used by protocols to query this structure for a
63 route corresponding to a particular end-node address, and to cause
64 certain protocol\- and interface-specific actions to take place.
65 .\" XXX - -mdoc should contain a standard request for getting em and
69 flag is obsolete and thus ignored by facility.
74 message is sent instead on the
76 socket interface, requesting that an external program resolve the
77 address in question and modify the route appropriately.
79 The default interface is
84 .Dq Li "struct route" ,
85 which is defined as follows:
86 .Bd -literal -offset indent
88 struct sockaddr ro_dst;
89 struct rtentry *ro_rt;
93 Thus, this function can only be used for address families which are
94 smaller than the default
95 .Dq Li "struct sockaddr" .
98 for the first time, callers should ensure that unused bits of the
99 structure are set to zero.
102 returns without performing a lookup if
106 flag is set in the route's
112 interface can be used when the caller does not want to receive
118 argument is the same as
120 but there is additionally a
122 argument, which is now only used to pass
124 indicating that the radix tree lock is already held.
129 functions return a pointer to an unlocked
130 .Vt "struct rtentry" .
134 function is the most general form of
136 (and both of the other forms are implemented as calls to rtalloc1).
138 .Dq Li "struct route" ,
139 and is therefore suitable for address families which require more
140 space than is in a traditional
141 .Dq Li "struct sockaddr" .
143 .Dq Li "struct sockaddr *"
149 controls whether the lower layers are notified when a lookup fails.
152 is a set of flags to ignore, as in
156 function returns a pointer to a locked
157 .Vt "struct rtentry" .
161 function frees a locked route entry, e.g., a previously allocated by
166 macro is used to free unlocked route entries, previously allocated by
172 macro decrements the reference count on the routing table entry (see below),
173 and frees it if the reference count has reached zero.
175 The preferred usage is allocating a route using
184 macro is used to lock a routing table entry.
187 macro is used to unlock a routing table entry.
191 macro increments the reference count on a previously locked route entry.
194 macro decrements the reference count on a previously locked route entry.
201 functions do not return a value.
204 function returns a pointer to a routing-table entry if it succeeds,
205 otherwise a null pointer.
206 Lack of a route should in most cases be
217 facility first appeared in
219 although with much different internals.
228 Routing table locking was introduced in
231 This manual page was written by
232 .An Garrett Wollman ,
233 as were the changes to implement