share/man/man9/rtalloc.9

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