Add an rtentry(9) page to describe the structure of a routing-table

entry and the metrics and flags which pertain thereto.

1 files changed, 287 insertions, 0 deletions

diff --git a/share/man/man9/rtentry.9 b/share/man/man9/rtentry.9
new file mode 100644
index 0000000..1b5c7a1
--- /dev/null
+++ b/share/man/man9/rtentry.9
@@ -0,0 +1,287 @@
+.\"
+.\" 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.
+.\"
+.\"	$Id$
+.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/socket.h>
+.Fd #include <net/route.h>
+.Sh DESCRIPTION
+The kernel provides a common mechanism by which all protcols 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 Li "struct radix_node rt_nodes[2];"
+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 Li "struct sockaddr *rt_gateway;"
+The
+.Dq target
+of the route, which can either represent a destination in its own
+right (some protcols 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 Li "short rt_refcnt;"
+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 Li "u_long rt_flags;"
+See below.
+.It Li "struct ifnet *rt_ifp;"
+.It Li "struct ifaddr *rt_ifa;"
+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 Li "struct sockaddr *rt_genmask;"
+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 Li "caddr_t rt_llinfo;"
+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 Li "struct rt_metrics rt_rmx;"
+See below.
+.It Li "struct rtentry *rt_gwroute;"
+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 Dv "struct rtentry *rt_parent;"
+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 Li "u_long rmx_locks;"
+Flag bits indicating which metrics the kernel is not permitted to
+dynamically modify.
+.It Li "u_long rmx_mtu;"
+MTU for this path.
+.It Li "u_long rmx_hopcount;"
+Number of intermediate systems on the path to this destination.
+.It Li "u_long rmx_expire;"
+The time 
+(\*(aga la
+.Xr time 2 )
+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 Li "u_long rmx_recvpipe;"
+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 Li "u_long rmx_sendpipe;"
+As before, but in the opposite direction.
+.It Li "u_long rmx_ssthresh;"
+The slow-start threshold used in
+.Tn TCP
+congestion-avoidance.
+.It Li "u_long rmx_rtt;"
+The round-trip time to this destination, in units of
+.Dv RMX_RTTUNIT
+per second.
+.It Li "u_long rmx_rttvar;"
+The average deviation of the round-type time to this destination, in
+units of
+.Dv RMX_RTTUNIT
+per second.
+.It Li "u_long rmx_pksent;"
+A count of packets successfully sent via this route.
+.It Li "u_long rmx_filler[4];"
+.\" 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 rtentry
+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 AUTHOR
+This manual page was written by Garrett Wollman.