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