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 December 11, 2008
  32 .Os
  33 .Dt RTALLOC 9
  34 .Sh NAME
  35 .Nm rtalloc ,
  36 .Nm rtalloc_ign ,
  37 .Nm rtalloc1 ,
  38 .Nm rtfree
  39 .Nd look up a route in the kernel routing table
  40 .Sh SYNOPSIS
  41 .In sys/types.h
  42 .In sys/socket.h
  43 .In net/route.h
  44 .Ft void
  45 .Fn rtalloc "struct route *ro"
  46 .Ft void
  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"
  50 .Ft void
  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"
  57 .Sh DESCRIPTION
  58 The kernel uses a radix tree structure to manage routes for the
  59 networking subsystem.
  60 The
  61 .Fn rtalloc
  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
  66 .\" en dashes.
  67 .Pp
  68 .Dv RTF_PRCLONING
  69 flag is obsolete and thus ignored by facility.
  70 If the
  71 .Dv RTF_XRESOLVE
  72 flag is set, then the
  73 .Dv RTM_RESOLVE
  74 message is sent instead on the
  75 .Xr route 4
  76 socket interface, requesting that an external program resolve the
  77 address in question and modify the route appropriately.
  78 .Pp
  79 The default interface is
  80 .Fn rtalloc .
  81 Its only argument is
  82 .Fa ro ,
  83 a pointer to a
  84 .Dq Li "struct route" ,
  85 which is defined as follows:
  86 .Bd -literal -offset indent
  87 struct route {
  88         struct sockaddr ro_dst;
  89         struct rtentry *ro_rt;
  90 };
  91 .Ed
  92 .Pp
  93 Thus, this function can only be used for address families which are
  94 smaller than the default
  95 .Dq Li "struct sockaddr" .
  96 Before calling
  97 .Fn rtalloc
  98 for the first time, callers should ensure that unused bits of the
  99 structure are set to zero.
 100 On subsequent calls,
 101 .Fn rtalloc
 102 returns without performing a lookup if
 103 .Fa ro->ro_rt
 104 is non-null and the
 105 .Dv RTF_UP
 106 flag is set in the route's
 107 .Li rt_flags
 108 field.
 109 .Pp
 110 The
 111 .Fn rtalloc_ign
 112 interface can be used when the caller does not want to receive
 113 the returned
 114 .Fa rtentry
 115 locked.
 116 The
 117 .Fa ro
 118 argument is the same as
 119 .Fn rtalloc ,
 120 but there is additionally a
 121 .Fa flags
 122 argument, which is now only used to pass
 123 .Dv RTF_RNH_LOCKED
 124 indicating that the radix tree lock is already held.
 125 Both
 126 .Fn rtalloc
 127 and
 128 .Fn rtalloc_ign
 129 functions return a pointer to an unlocked
 130 .Vt "struct rtentry" .
 131 .Pp
 132 The
 133 .Fn rtalloc1
 134 function is the most general form of
 135 .Fn rtalloc
 136 (and both of the other forms are implemented as calls to rtalloc1).
 137 It does not use the
 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" .
 142 Instead, it takes a
 143 .Dq Li "struct sockaddr *"
 144 directly as the
 145 .Fa sa
 146 argument.
 147 The second argument,
 148 .Fa report ,
 149 controls whether the lower layers are notified when a lookup fails.
 150 The third argument,
 151 .Fa flags ,
 152 is a set of flags to ignore, as in
 153 .Fn rtalloc_ign .
 154 The
 155 .Fn rtalloc1
 156 function returns a pointer to a locked
 157 .Vt "struct rtentry" .
 158 .Pp
 159 The
 160 .Fn rtfree
 161 function frees a locked route entry, e.g., a previously allocated by
 162 .Fn rtalloc1 .
 163 .Pp
 164 The
 165 .Fn RTFREE
 166 macro is used to free unlocked route entries, previously allocated by
 167 .Fn rtalloc
 168 or
 169 .Fn rtalloc_ign .
 170 The
 171 .Fn RTFREE
 172 macro decrements the reference count on the routing table entry (see below),
 173 and frees it if the reference count has reached zero.
 174 .Pp
 175 The preferred usage is allocating a route using
 176 .Fn rtalloc
 177 or
 178 .Fn rtalloc_ign
 179 and freeing using
 180 .Fn RTFREE .
 181 .Pp
 182 The
 183 .Fn RT_LOCK
 184 macro is used to lock a routing table entry.
 185 The
 186 .Fn RT_UNLOCK
 187 macro is used to unlock a routing table entry.
 188 .Pp
 189 The
 190 .Fn RT_ADDREF
 191 macro increments the reference count on a previously locked route entry.
 192 The
 193 .Fn RT_REMREF
 194 macro decrements the reference count on a previously locked route entry.
 195 .Sh RETURN VALUES
 196 The
 197 .Fn rtalloc ,
 198 .Fn rtalloc_ign
 199 and
 200 .Fn rtfree
 201 functions do not return a value.
 202 The
 203 .Fn rtalloc1
 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
 207 translated to the
 208 .Xr errno 2
 209 value
 210 .Er EHOSTUNREACH .
 211 .Sh SEE ALSO
 212 .Xr route 4 ,
 213 .Xr rtentry 9
 214 .Sh HISTORY
 215 The
 216 .Nm
 217 facility first appeared in
 218 .Bx 4.2 ,
 219 although with much different internals.
 220 The
 221 .Fn rtalloc_ign
 222 function and the
 223 .Fa flags
 224 argument to
 225 .Fn rtalloc1
 226 first appeared in
 227 .Fx 2.0 .
 228 Routing table locking was introduced in
 229 .Fx 5.2 .
 230 .Sh AUTHORS
 231 This manual page was written by
 232 .An Garrett Wollman ,
 233 as were the changes to implement
 234 .Dv RTF_PRCLONING
 235 and the
 236 .Fn rtalloc_ign
 237 function and the
 238 .Fa flags
 239 argument to
 240 .Fn rtalloc1 .