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
38 .Nd look up a route in the kernel routing table
43 .Ft "struct rtentry *"
44 .Fn rtalloc1_fib "struct sockaddr *dst" "int report" "u_long flags" "u_int fibnum"
46 .Fn rtalloc_fib "struct route *ro" "u_int fibnum"
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"
57 .Fn rtfree "struct rt_entry *rt"
58 .Ft "struct rtentry *"
59 .Fn rtalloc1 "struct sockaddr *dst" "int report" "u_long flags"
61 .Fn rtalloc "struct route *ro"
63 .Fn rtalloc_ign "struct route *ro" "u_long flags"
65 .Cd options RADIX_MPATH
67 The kernel uses a radix tree structure to manage routes for the
70 .Cd options RADIX_MPATH
71 kernel may maintain several independent forwarding information databases (FIBs).
74 family of routines is used by protocols to query these structures for a
75 route corresponding to a particular end-node address, and to cause
76 certain protocol\- and interface-specific actions to take place.
80 function is the most general form of
82 and all of the other forms are implemented as calls to it.
84 .Fa "struct sockaddr *"
90 controls whether the routing sockets are notified when a lookup fails.
95 .Bl -item -offset indent
98 indicates that the radix tree lock is already held
103 specifies number of forwarding information database (FIB) on which
104 the lookup should be performed.
105 In case of success the
107 function returns a pointer to a locked
109 with an additional reference.
113 is the most simple variant.
118 which is defined as follows:
119 .Bd -literal -offset indent
121 struct rtentry *ro_rt;
122 struct llentry *ro_lle;
123 struct sockaddr ro_dst;
127 Thus, this function can only be used for address families which are
128 smaller than the default
129 .Ft "struct sockaddr" .
132 for the first time, callers should ensure that unused bits of the
133 structure are set to zero.
137 In case of success of the
141 points to a valid and unlocked
143 which has an additional reference put on it, freeing which is
144 responsibility of the caller.
147 returns without performing a lookup if
151 flag is set in the rtentry's
157 function is the same as the
159 but there is additional
161 argument, which is same as in
166 macro is used to unref and possibly free a locked routing entry
167 with one our reference, for example previously allocated by
172 macro is used to unref and possibly free an unlocked route entries with
173 one our reference, for example previously allocated by
176 .Fn rtalloc_ign_fib .
182 macros decrement the reference count on the routing table entry,
183 and proceed with actual freeing if the reference count has reached zero.
187 macro is used to lock a routing table entry.
191 macro is used to unlock a routing table entry.
195 macro increments the reference count on a previously locked route entry.
196 It should be used whenever a reference to an
198 is going to be stored outside the routing table.
202 macro decrements the reference count on a previously locked route entry.
203 Its usage is contrary to
208 macro is used to free route entry that is referenced by struct route.
209 At certain circumstances the latter may not hold a reference on rtentry,
212 treats such routes correctly.
216 function does the actual free of the routing table entry, and shouldn't
217 be called directly by facilities, that just perform routing table lookups.
219 Prior to introduction of multiple routing tables functions did not
228 functions are kept for compatibility, and are equivalent to
229 calling new interface with
233 which implies default forwarding table.
237 function returns a pointer to a locked routing-table entry if it succeeds,
238 otherwise a null pointer.
243 functions do not return a value, but they fill in the
247 argument with a pointer to an unlocked routing-table entry if they
248 succeed, otherwise a null pointer.
249 In a case of success all functions put a reference on the
250 routing-table entry, freeing of which is responsibility of the caller.
251 Lack of a route should in most cases be
262 facility first appeared in
264 although with much different internals.
273 Routing table locking was introduced in
275 Multiple routing tables were introduced in
278 The original version of this manual page was written by
280 .An "Garrett Wollman" .
281 It was significantly updated by
282 .An "Gleb Smirnoff" .