335 lines
9.2 KiB
Groff
335 lines
9.2 KiB
Groff
.\"
|
|
.\" Copyright 1996 Massachusetts Institute of Technology
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software and
|
|
.\" its documentation for any purpose and without fee is hereby
|
|
.\" granted, provided that both the above copyright notice and this
|
|
.\" permission notice appear in all copies, that both the above
|
|
.\" copyright notice and this permission notice appear in all
|
|
.\" supporting documentation, and that the name of M.I.T. not be used
|
|
.\" in advertising or publicity pertaining to distribution of the
|
|
.\" software without specific, written prior permission. M.I.T. makes
|
|
.\" no representations about the suitability of this software for any
|
|
.\" purpose. It is provided "as is" without express or implied
|
|
.\" warranty.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS
|
|
.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
|
|
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
|
|
.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
|
|
.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
|
|
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.Dd October 8, 1996
|
|
.Os
|
|
.Dt RTENTRY 9
|
|
.Sh NAME
|
|
.Nm rtentry
|
|
.Nd structure of an entry in the kernel routing table
|
|
.Sh SYNOPSIS
|
|
.Fd #include <sys/types.h>
|
|
.Fd #include <sys/socket.h>
|
|
.Fd #include <net/route.h>
|
|
.Sh DESCRIPTION
|
|
The kernel provides a common mechanism by which all protocols can store
|
|
and retrieve entries from a central table of routes. Parts of this
|
|
mechanism are also used to interact with user-level processes by means
|
|
of a socket in the
|
|
.Xr route 4
|
|
pseudo-protocol family.
|
|
The
|
|
.Aq Pa net/route.h
|
|
header file defines the structures and manifest constants used in this
|
|
facility.
|
|
.Pp
|
|
The basic structure a route is defined by
|
|
.Dq Li struct rtentry ,
|
|
which includes the following fields:
|
|
.Bl -tag -offset indent -width 6n
|
|
.It Xo
|
|
.Vt "struct radix_node rt_nodes[2]" ;
|
|
.Xc
|
|
Glue used by the radix-tree routines. These members also include in
|
|
their substructure the key (i.e., destination address) and mask used
|
|
when the route was created. The
|
|
.Fn rt_key \&rt
|
|
and
|
|
.Fn rt_mask \&rt
|
|
macros can be used to extract this information (in the form of a
|
|
.Dq Li "struct sockaddr *" )
|
|
given a
|
|
.Li "struct rtentry *" .
|
|
.It Xo
|
|
.Vt "struct sockaddr *rt_gateway" ;
|
|
.Xc
|
|
The
|
|
.Dq target
|
|
of the route, which can either represent a destination in its own
|
|
right (some protocols will put a link-layer address here), or some
|
|
intermediate stop on the way to that destination (if the
|
|
.Dv RTF_GATEWAY
|
|
flag is set).
|
|
.It Xo
|
|
.Vt "long rt_refcnt" ;
|
|
.Xc
|
|
Route entries are reference-counted; this field indicates the number
|
|
of external (to the radix tree) references. If the
|
|
.Dv RTF_UP
|
|
flag is not present, the
|
|
.Fn rtfree
|
|
function will delete the route from the radix tree when the last
|
|
reference drops.
|
|
.It Xo
|
|
.Vt "u_long rt_flags" ;
|
|
.Xc
|
|
See below.
|
|
.It Xo
|
|
.Vt "struct ifnet *rt_ifp" ;
|
|
.Xc
|
|
.It Xo
|
|
.Vt "struct ifaddr *rt_ifa" ;
|
|
.Xc
|
|
These two fields represent the
|
|
.Dq answer ,
|
|
as it were, to the question posed by a route lookup; that is, they
|
|
name the interface and interface address to be used in sending a
|
|
packet to the destination or set of destinations which this route
|
|
represents.
|
|
.It Xo
|
|
.Vt "struct sockaddr *rt_genmask" ;
|
|
.Xc
|
|
When the
|
|
.Fn rtalloc
|
|
family of functions performs a cloning operation as requested by the
|
|
.Dv RTF_CLONING
|
|
or
|
|
.Dv RTF_PRCLONING
|
|
flag, this field is used as the mask for the new route which is
|
|
inserted into the table. If this field is a null pointer, then a host
|
|
route is generated.
|
|
.It Xo
|
|
.Vt "caddr_t rt_llinfo" ;
|
|
.Xc
|
|
When the
|
|
.Dv RTF_LLINFO
|
|
flag is set, this field contains information specific to the link
|
|
layer represented by the named interface address. (It is normally
|
|
managed by the
|
|
.Fn rt_ifa->ifa_rtrequest
|
|
routine.) Protocols such as
|
|
.Xr arp 4
|
|
use this field to reference per-destination state internal to that
|
|
protocol.
|
|
.It Xo
|
|
.Vt "struct rt_metrics rt_rmx" ;
|
|
.Xc
|
|
See below.
|
|
.It Xo
|
|
.Vt "struct rtentry *rt_gwroute" ;
|
|
.Xc
|
|
This member is a reference to a route whose destination is
|
|
.Li rt_gateway .
|
|
It is only used for
|
|
.Dv RTF_GATEWAY
|
|
routes.
|
|
.\" .It Dv "int (*rt_output)();"
|
|
.\" See below.
|
|
.It Xo
|
|
.Vt "struct rtentry *rt_parent" ;
|
|
.Xc
|
|
A reference to the route from which this route was cloned, or a null
|
|
pointer if this route was not generated by cloning. See also the
|
|
.Dv RTF_WASCLONED
|
|
flag.
|
|
.El
|
|
.Pp
|
|
The following flag bits are defined:
|
|
.Bl -tag -offset indent -width RTF_CHAINDELETE -compact
|
|
.It Dv RTF_UP
|
|
The route is not deleted.
|
|
.It Dv RTF_GATEWAY
|
|
The route points to an intermediate destination and not the ultimate
|
|
recipient; the
|
|
.Li rt_gateway
|
|
and
|
|
.Li rt_gwroute
|
|
fields name that destination.
|
|
.It Dv RTF_HOST
|
|
This is a host route.
|
|
.It Dv RTF_REJECT
|
|
The destination is presently unreachable. This should result in an
|
|
.Er EHOSTUNREACH
|
|
error from output routines.
|
|
.It Dv RTF_DYNAMIC
|
|
This route was created dynamically by
|
|
.Fn rtredirect .
|
|
.It Dv RTF_MODIFIED
|
|
This route was modified by
|
|
.Fn rtredirect .
|
|
.It Dv RTF_DONE
|
|
Used only in the
|
|
.Xr route 4
|
|
protocol, indicating that the request was executed.
|
|
.It Dv RTF_CLONING
|
|
When this route is returned as a result of a lookup, automatically
|
|
create a new route using this one as a template and
|
|
.Li rt_genmask
|
|
(if present) as a mask.
|
|
.It Dv RTF_XRESOLVE
|
|
When this route is returned as a result of a lookup, send a report on
|
|
the
|
|
.Xr route 4
|
|
interface requesting that an external process perform resolution for
|
|
this route. (Used in conjunction with
|
|
.Dv RTF_CLONING . )
|
|
.It Dv RTF_LLINFO
|
|
Indicates that this route represents information being managed by a
|
|
link layer's adaptation layer (e.g.,
|
|
.Tn ARP ) .
|
|
.It Dv RTF_STATIC
|
|
Indicates that this route was manually added by means of the
|
|
.Xr route 8
|
|
command.
|
|
.It Dv RTF_BLACKHOLE
|
|
Requests that output sent via this route be discarded.
|
|
.It Dv RTF_PROTO1
|
|
.It Dv RTF_PROTO2
|
|
.It Dv RTF_PROTO3
|
|
Protocol-specific.
|
|
.It Dv RTF_PRCLONING
|
|
Like
|
|
.Dv RTF_CLONING ,
|
|
only managed by an entire protocol. (E.g.,
|
|
.Tn IP
|
|
uses this flag to manage a per-host cache integrated with the routing
|
|
table, for those destinations which do not have a link layer
|
|
performing this function.)
|
|
.It Dv RTF_WASCLONED
|
|
Indicates that this route was generated as a result of cloning
|
|
requested by the
|
|
.Dv RTF_CLONING
|
|
or
|
|
.Dv RTF_PRCLONING
|
|
flag. When set, the
|
|
.Li rt_parent
|
|
field indicates the route from which this one was generated.
|
|
.It Dv RTF_PINNED
|
|
(Reserved for future use to indicate routes which are not to be
|
|
modified by a routing protocol.)
|
|
.It Dv RTF_LOCAL
|
|
Indicates that the destination of this route is an address configured
|
|
as belonging to this system.
|
|
.It Dv RTF_BROADCAST
|
|
Indicates that the destination is a broadcast address.
|
|
.It Dv RTF_MULTICAST
|
|
Indicates that the destination is a multicast address.
|
|
.El
|
|
.Pp
|
|
Every route has associated with it a set of metrics, defined by
|
|
.Li struct rt_metrics :
|
|
.Bl -tag -offset indent -width 6n
|
|
.It Xo
|
|
.Vt "u_long rmx_locks" ;
|
|
.Xc
|
|
Flag bits indicating which metrics the kernel is not permitted to
|
|
dynamically modify.
|
|
.It Xo
|
|
.Vt "u_long rmx_mtu" ;
|
|
.Xc
|
|
MTU for this path.
|
|
.It Xo
|
|
.Vt "u_long rmx_hopcount" ;
|
|
.Xc
|
|
Number of intermediate systems on the path to this destination.
|
|
.It Xo
|
|
.Vt "u_long rmx_expire" ;
|
|
.Xc
|
|
The time
|
|
(a la
|
|
.Xr time 3 )
|
|
at which this route should expire, or zero if it should never expire.
|
|
It is the responsibility of individual protocol suites to ensure that routes
|
|
are actually deleted once they expire.
|
|
.It Xo
|
|
.Vt "u_long rmx_recvpipe" ;
|
|
.Xc
|
|
Nominally, the bandwidth-delay product for the path
|
|
.Em from
|
|
the destination
|
|
.Em to
|
|
this system. In practice, this value is used to set the size of the
|
|
receive buffer (and thus the window in sliding-window protocols like
|
|
.Tn TCP ) .
|
|
.It Xo
|
|
.Vt "u_long rmx_sendpipe" ;
|
|
.Xc
|
|
As before, but in the opposite direction.
|
|
.It Xo
|
|
.Vt "u_long rmx_ssthresh" ;
|
|
.Xc
|
|
The slow-start threshold used in
|
|
.Tn TCP
|
|
congestion-avoidance.
|
|
.It Xo
|
|
.Vt "u_long rmx_rtt" ;
|
|
.Xc
|
|
The round-trip time to this destination, in units of
|
|
.Dv RMX_RTTUNIT
|
|
per second.
|
|
.It Xo
|
|
.Vt "u_long rmx_rttvar" ;
|
|
.Xc
|
|
The average deviation of the round-type time to this destination, in
|
|
units of
|
|
.Dv RMX_RTTUNIT
|
|
per second.
|
|
.It Xo
|
|
.Vt "u_long rmx_pksent" ;
|
|
.Xc
|
|
A count of packets successfully sent via this route.
|
|
.It Xo
|
|
.Vt "u_long rmx_filler[4]" ;
|
|
.Xc
|
|
.\" XXX badly named
|
|
Empty space available for protocol-specific information.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr route 4 ,
|
|
.Xr route 8 ,
|
|
.Xr rtalloc 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
structure first appeared in
|
|
.Bx 4.2 .
|
|
The radix-tree representation of the routing table and the
|
|
.Nm rt_metrics
|
|
structure first appeared in
|
|
.Bx 4.3 reno .
|
|
The
|
|
.Nm RTF_PRCLONING
|
|
mechanism first appeared in
|
|
.Fx 2.0 .
|
|
.Sh BUGS
|
|
There are a number of historical relics remaining in this interface.
|
|
The
|
|
.Li rt_gateway
|
|
and
|
|
.Li rmx_filler
|
|
fields could be named better.
|
|
.Pp
|
|
There is some disagreement over whether it is legitimate for
|
|
.Dv RTF_LLINFO
|
|
to be set by any process other than
|
|
.Fn rt_ifa->ifa_rtrequest .
|
|
.Sh AUTHORS
|
|
This manual page was written by
|
|
.An Garrett Wollman .
|