From 50853e53cc8b0243c65a501adeea64c58765a231 Mon Sep 17 00:00:00 2001 From: Garrett Wollman Date: Tue, 8 Oct 1996 20:25:39 +0000 Subject: [PATCH] Add an rtentry(9) page to describe the structure of a routing-table entry and the metrics and flags which pertain thereto. --- share/man/man9/Makefile | 4 +- share/man/man9/rtalloc.9 | 5 +- share/man/man9/rtentry.9 | 287 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 292 insertions(+), 4 deletions(-) create mode 100644 share/man/man9/rtentry.9 diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index dc598d3cd7b2..fec91d6aa62a 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1,7 +1,7 @@ -# $Id$ +# $Id: Makefile,v 1.10 1996/10/08 18:45:03 wollman Exp $ MAN9= at_shutdown.9 at_fork.9 at_exit.9 copy.9 devfs_add_devswf.9 \ - devfs_link.9 fetch.9 intro.9 rtalloc.9 sleep.9 spl.9 \ + devfs_link.9 fetch.9 intro.9 rtalloc.9 rtentry.9 sleep.9 spl.9 \ store.9 style.9 timeout.9 MLINKS+= copy.9 copyin.9 copy.9 copyout.9 copy.9 copystr.9 copy.9 copyinstr.9 diff --git a/share/man/man9/rtalloc.9 b/share/man/man9/rtalloc.9 index bc91eca847ce..6fc827e8101b 100644 --- a/share/man/man9/rtalloc.9 +++ b/share/man/man9/rtalloc.9 @@ -26,7 +26,7 @@ .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id$ +.\" $Id: rtalloc.9,v 1.1 1996/10/08 18:45:06 wollman Exp $ .Dd October 8, 1996 .Os .Dt RTALLOC 9 @@ -174,7 +174,8 @@ translated to the value .Er EHOSTUNREACH . .Sh SEE ALSO -.Xr route 4 +.Xr route 4 , +.Xr rtentry 9 .Sh HISTORY The .Nm rtalloc diff --git a/share/man/man9/rtentry.9 b/share/man/man9/rtentry.9 new file mode 100644 index 000000000000..1b5c7a128587 --- /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 +.Fd #include +.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.