share/man/man9/rtentry.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 October 7, 2004
  32 .Os
  33 .Dt RTENTRY 9
  34 .Sh NAME
  35 .Nm rtentry
  36 .Nd structure of an entry in the kernel routing table
  37 .Sh SYNOPSIS
  38 .In sys/types.h
  39 .In sys/socket.h
  40 .In net/route.h
  41 .Sh DESCRIPTION
  42 The kernel provides a common mechanism by which all protocols can store
  43 and retrieve entries from a central table of routes.
  44 Parts of this
  45 mechanism are also used to interact with user-level processes by means
  46 of a socket in the
  47 .Xr route 4
  48 pseudo-protocol family.
  49 The
  50 .In net/route.h
  51 header file defines the structures and manifest constants used in this
  52 facility.
  53 .Pp
  54 The basic structure of a route is defined by
  55 .Vt "struct rtentry" ,
  56 which includes the following fields:
  57 .Bl -tag -offset indent -width 6n
  58 .It Vt "struct radix_node rt_nodes[2]" ;
  59 Glue used by the radix-tree routines.
  60 These members also include in
  61 their substructure the key (i.e., destination address) and mask used
  62 when the route was created.
  63 The
  64 .Fn rt_key rt
  65 and
  66 .Fn rt_mask rt
  67 macros can be used to extract this information (in the form of a
  68 .Vt "struct sockaddr *" )
  69 given a
  70 .Vt "struct rtentry *" .
  71 .It Vt "struct sockaddr *rt_gateway" ;
  72 The
  73 .Dq target
  74 of the route, which can either represent a destination in its own
  75 right (some protocols will put a link-layer address here), or some
  76 intermediate stop on the way to that destination (if the
  77 .Dv RTF_GATEWAY
  78 flag is set).
  79 .It Vt "u_long rt_flags" ;
  80 See below.
  81 .It Vt "struct ifnet *rt_ifp" ;
  82 .It Vt "struct ifaddr *rt_ifa" ;
  83 These two fields represent the
  84 .Dq answer ,
  85 as it were, to the question posed by a route lookup; that is, they
  86 name the interface and interface address to be used in sending a
  87 packet to the destination or set of destinations which this route
  88 represents.
  89 .It Vt "struct rt_metrics_lite rt_rmx" ;
  90 See below.
  91 .It Vt "long rt_refcnt" ;
  92 Route entries are reference-counted; this field indicates the number
  93 of external (to the radix tree) references.
  94 If the
  95 .Dv RTF_UP
  96 flag is not present, the
  97 .Fn rtfree
  98 function will delete the route from the radix tree when the last
  99 reference drops.
 100 .It Vt "struct sockaddr *rt_genmask" ;
 101 When the
 102 .Fn rtalloc
 103 family of functions performs a cloning operation as requested by the
 104 .Dv RTF_CLONING
 105 flag, this field is used as the mask for the new route which is
 106 inserted into the table.
 107 If this field is a null pointer, then a host
 108 route is generated.
 109 .It Vt "caddr_t rt_llinfo" ;
 110 When the
 111 .Dv RTF_LLINFO
 112 flag is set, this field contains information specific to the link
 113 layer represented by the named interface address.
 114 (It is normally managed by the
 115 .Va rt_ifa->ifa_rtrequest
 116 routine.)
 117 Protocols such as
 118 .Xr arp 4
 119 use this field to reference per-destination state internal to that
 120 protocol.
 121 .It Vt "struct rtentry *rt_gwroute" ;
 122 This member is a reference to a route whose destination is
 123 .Va rt_gateway .
 124 It is only used for
 125 .Dv RTF_GATEWAY
 126 routes.
 127 .It Vt "struct rtentry *rt_parent" ;
 128 A reference to the route from which this route was cloned, or a null
 129 pointer if this route was not generated by cloning.
 130 See also the
 131 .Dv RTF_WASCLONED
 132 flag.
 133 .It Vt "struct mtx rt_mtx" ;
 134 Mutex to lock this routing entry.
 135 .El
 136 .Pp
 137 The following flag bits are defined:
 138 .Bl -tag -offset indent -width ".Dv RTF_BLACKHOLE" -compact
 139 .It Dv RTF_UP
 140 The route is not deleted.
 141 .It Dv RTF_GATEWAY
 142 The route points to an intermediate destination and not the ultimate
 143 recipient; the
 144 .Va rt_gateway
 145 and
 146 .Va rt_gwroute
 147 fields name that destination.
 148 .It Dv RTF_HOST
 149 This is a host route.
 150 .It Dv RTF_REJECT
 151 The destination is presently unreachable.
 152 This should result in an
 153 .Er EHOSTUNREACH
 154 error from output routines.
 155 .It Dv RTF_DYNAMIC
 156 This route was created dynamically by
 157 .Fn rtredirect .
 158 .It Dv RTF_MODIFIED
 159 This route was modified by
 160 .Fn rtredirect .
 161 .It Dv RTF_DONE
 162 Used only in the
 163 .Xr route 4
 164 protocol, indicating that the request was executed.
 165 .It Dv RTF_CLONING
 166 When this route is returned as a result of a lookup, automatically
 167 create a new route using this one as a template and
 168 .Va rt_genmask
 169 (if present) as a mask.
 170 .It Dv RTF_XRESOLVE
 171 When this route is returned as a result of a lookup, send a report on
 172 the
 173 .Xr route 4
 174 interface requesting that an external process perform resolution for
 175 this route.
 176 (Used in conjunction with
 177 .Dv RTF_CLONING . )
 178 .It Dv RTF_LLINFO
 179 Indicates that this route represents information being managed by a
 180 link layer's adaptation layer (e.g.,
 181 .Tn ARP ) .
 182 .It Dv RTF_STATIC
 183 Indicates that this route was manually added by means of the
 184 .Xr route 8
 185 command.
 186 .It Dv RTF_BLACKHOLE
 187 Requests that output sent via this route be discarded.
 188 .It Dv RTF_PROTO1
 189 .It Dv RTF_PROTO2
 190 .It Dv RTF_PROTO3
 191 Protocol-specific.
 192 .It Dv RTF_PRCLONING
 193 This flag is obsolete and simply ignored by facility.
 194 .It Dv RTF_WASCLONED
 195 Indicates that this route was generated as a result of cloning
 196 requested by the
 197 .Dv RTF_CLONING
 198 flag.
 199 When set, the
 200 .Va rt_parent
 201 field indicates the route from which this one was generated.
 202 .It Dv RTF_PINNED
 203 (Reserved for future use to indicate routes which are not to be
 204 modified by a routing protocol.)
 205 .It Dv RTF_LOCAL
 206 Indicates that the destination of this route is an address configured
 207 as belonging to this system.
 208 .It Dv RTF_BROADCAST
 209 Indicates that the destination is a broadcast address.
 210 .It Dv RTF_MULTICAST
 211 Indicates that the destination is a multicast address.
 212 .El
 213 .Pp
 214 Every route has associated with it a set of metrics, stored in
 215 .Vt "struct rt_metrics_lite" .
 216 Metrics are supplied in
 217 .Vt "struct rt_metrics"
 218 passed with routing control messages via
 219 .Xr route 4
 220 API.
 221 Currently only
 222 .Vt rmx_mtu , rmx_expire ,
 223 and
 224 .Vt rmx_pksent
 225 metrics are used in
 226 .Vt "struct rt_metrics_lite" .
 227 All others are ignored.
 228 .Pp
 229 The following metrics are defined by
 230 .Vt "struct rt_metrics" :
 231 .Bl -tag -offset indent -width 6n
 232 .It Vt "u_long rmx_locks" ;
 233 Flag bits indicating which metrics the kernel is not permitted to
 234 dynamically modify.
 235 .It Vt "u_long rmx_mtu" ;
 236 MTU for this path.
 237 .It Vt "u_long rmx_hopcount" ;
 238 Number of intermediate systems on the path to this destination.
 239 .It Vt "u_long rmx_expire" ;
 240 The time
 241 (a la
 242 .Xr time 3 )
 243 at which this route should expire, or zero if it should never expire.
 244 It is the responsibility of individual protocol suites to ensure that routes
 245 are actually deleted once they expire.
 246 .It Vt "u_long rmx_recvpipe" ;
 247 Nominally, the bandwidth-delay product for the path
 248 .Em from
 249 the destination
 250 .Em to
 251 this system.
 252 In practice, this value is used to set the size of the
 253 receive buffer (and thus the window in sliding-window protocols like
 254 .Tn TCP ) .
 255 .It Vt "u_long rmx_sendpipe" ;
 256 As before, but in the opposite direction.
 257 .It Vt "u_long rmx_ssthresh" ;
 258 The slow-start threshold used in
 259 .Tn TCP
 260 congestion-avoidance.
 261 .It Vt "u_long rmx_rtt" ;
 262 The round-trip time to this destination, in units of
 263 .Dv RMX_RTTUNIT
 264 per second.
 265 .It Vt "u_long rmx_rttvar" ;
 266 The average deviation of the round-trip time to this destination, in
 267 units of
 268 .Dv RMX_RTTUNIT
 269 per second.
 270 .It Vt "u_long rmx_pksent" ;
 271 A count of packets successfully sent via this route.
 272 .It Vt "u_long rmx_filler[4]" ;
 273 .\" XXX badly named
 274 Empty space available for protocol-specific information.
 275 .El
 276 .Sh SEE ALSO
 277 .Xr route 4 ,
 278 .Xr route 8 ,
 279 .Xr rtalloc 9
 280 .Sh HISTORY
 281 The
 282 .Vt rtentry
 283 structure first appeared in
 284 .Bx 4.2 .
 285 The radix-tree representation of the routing table and the
 286 .Vt rt_metrics
 287 structure first appeared in
 288 .Bx 4.3 reno .
 289 .Sh AUTHORS
 290 This manual page was written by
 291 .An Garrett Wollman .
 292 .Sh BUGS
 293 There are a number of historical relics remaining in this interface.
 294 The
 295 .Va rt_gateway
 296 and
 297 .Va rmx_filler
 298 fields could be named better.
 299 .Pp
 300 There is some disagreement over whether it is legitimate for
 301 .Dv RTF_LLINFO
 302 to be set by any process other than
 303 .Va rt_ifa->ifa_rtrequest .