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