route man page on BSDOS

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDOS logo
[printable version]

ROUTE(4)		    BSD Programmer's Manual		      ROUTE(4)

NAME
     route - forwarding information database and routing socket

SYNOPSIS
     #include <sys/socket.h>
     #include <net/if.h>
     #include <net/route.h>

     int
     socket(PF_ROUTE, SOCK_RAW, int family);

DESCRIPTION
     The operating system provides packet forwarding facilities by maintaining
     a ``forwarding information database'', or ``forwarding table''. This
     database is used in selecting the appropriate network interface when
     transmitting packets.

     One or more co-operating user processes (see gated(8)and routed(8))
     maintain this database by sending messages over a special type of socket,
     the ``routing socket''. This supplants the fixed size ioctl(2) calls
     (SIOCADDRT and SIOCDELRT) used in earlier releases.

     The term ``routing'' technically refers to the use of routing protocols
     to discover ``routes'' to remote networks and hosts.  The term
     ``forwarding'' refers to the process of sending a packet on towards its
     eventual destination.  An entry in the operating system's forwarding
     table can be referred to as a ``forwarding table entry'' or a ``route''.

     The ability to change the forwarding table is restricted to the super us-
     er.

     The operating system may spontaneously emit routing socket messages in
     response to external events, such as receipt of a re-direct, failure to
     locate a suitable route when attempting to send or forward a packet, or
     interface status or address changes.  The message types are described in
     greater detail below.

     Forwarding database entries come in two flavors: for a specific host, or
     for all hosts on a generic subnetwork (as specified by a bit mask and
     value under the mask). The effect of a ``wildcard'' or ``default'' route
     may be achieved by using a mask of all zeros, and there may be hierarchi-
     cal routes.

     When the system is booted and addresses are assigned to the network in-
     terfaces, each protocol family installs a forwarding table entry for each
     interface when it is ready for traffic.  Normally the protocol specifies
     the route through each interface as a ``direct'' connection to the desti-
     nation host or network.  If the route is direct, the transport layer of a
     protocol family usually requests the packet be sent to the same host
     specified in the packet.  Otherwise, the interface is requested to ad-
     dress the packet to the gateway listed in the forwarding entry (i.e. the
     packet is forwarded).

     When forwarding a packet, the operating system will attempt to find the
     most specific route matching the destination.  If no entry is found, the
     destination is declared to be unreachable, and a routing-miss (RTM_MISS)
     message is generated if there are any listeners on the routing socket as
     described below.  If there are two different mask and value-under-the-
     mask pairs that match, the more specific is the one with more bits in the
     mask.  A route to a host is regarded as being supplied with a mask of as
     many ones as there are bits in the destination.

     A wildcard (or ``default'') routing entry is specified with a zero desti-
     nation address value, and a mask of all zeroes.  Wild card routes will be
     used when the system fails to find other routes matching the destination.
     The combination of wildcard routes and routing redirects can provide an
     economical mechanism for routing traffic.

     A process opens the routing socket for passing control messages by using
     the socket(2) system call shown in the synopsis.  Multiple routing sock-
     ets can be open simultaneously.  Messages will be restricted to the ad-
     dress family provided via the family parameter unless AF_UNSPEC is used
     to request messages from all address families.

     Messages are formed by a header followed by a small number of struct
     sockaddr entries.	(now variable length particularly in the ISO case),
     interpreted by position, and delimited by the new length entry in the
     struct sockaddr (rounded up to the size of a long). Network masks should
     have a family of AF_UNSPEC. The interpretation of which address are pre-
     sent is given by a bit mask within the header, and the sequence is least
     significant to most significant bit within the vector.

     Any messages sent to the operating system are returned, and copies are
     sent to all interested listeners.	The operating system will provide the
     process ID for the sender, and the sender may use an additional sequence
     field to distinguish between outstanding messages.	 However, message
     replies may be lost when operating system buffers are exhausted.

     The operating system may reject certain messages, and will indicate this
     by filling in the rtm_errno field as described below.  In the current im-
     plementation, all routing process run locally, and the values for
     rtm_errno are available through the normal errno mechanism, even if the
     routing reply message is lost.

     A process may avoid the expense of reading replies to its own messages by
     issuing a setsockopt(2) call indicating that the SO_USELOOPBACK option at
     the SOL_SOCKET level is to be turned off.	A process may ignore all mes-
     sages from the routing socket by doing a shutdown(2) system call to dis-
     allow further input.

     If a route is in use when it is deleted, the forwarding table entry will
     be marked down and removed from the table, but the resources associated
     with it will not be reclaimed until all references to it are released.
     User processes can obtain information about the forwarding table entry
     used to forward to a specific destination by using a RTM_GET message, or
     by issuing a sysctl(3) system call.

   Forwarding table maintenance messages

     The following message types are defined for forwarding table maintenance:

     RTM_ADD	   Add a route to the forwarding table.

     RTM_CHANGE	   Change an existing route in the forwarding table.

     RTM_DELETE	   Remove a route from the forwarding table.

     RTM_GET	   Look up and returns the characteristics of a route in the
		   forwarding table.  The route returned is the (longest
		   match) route for the specified destination.

     RTM_LOCK	   Used by user processes to set the ``lock'' bits for certain
		   metrics.  When the metrics are locked, the operating system
		   will not update them.

     RTM_LOSING	   The operating system detects packet loss.

     RTM_MISS	   No entry in the forwarding table was found for the speci-

		   fied address.

     RTM_REDIRECT  The operating system has received and processed a redirect.

     RTM_RESOLVE   A request from the operating system for a user process to
		   resolve the specified destination to a link level address.

     A routing related message header consists of:

     struct rt_msghdr {
	 u_short rtm_msglen;  /* to skip over non-understood messages */
	 u_char	 rtm_version; /* Set to RTM_VERSION */
	 u_char	 rtm_type;    /* message type */
	 u_short rtm_index;   /* index for associated ifp */
	 int	 rtm_flags;   /* flags, incl kern & message, e.g. DONE */
	 int	 rtm_addrs;   /* bitmask identifying sockaddrs in msg */
	 pid_t	 rtm_pid;     /* identify sender */
	 int	 rtm_seq;     /* for sender to identify action */
	 int	 rtm_errno;   /* why failed */
	 int	 rtm_use;     /* from rtentry */
	 u_long	 rtm_inits;   /* which values we are initializing */
	 struct	 rt_metrics rtm_rmx; /* metrics themselves */
     };

     rtm_addrs	  Description of addresses included as defined below.

     rtm_errno	  Indication of success (when 0) or reason for failure to pro-
		  cess message.

     rtm_flags	  Route flags as defined below.

     rtm_index	  Index of associated interface.  Only used in messages gener-
		  ated by the operating system.

     rtm_inits	  Indication of which fields of rtm_rmx are being set.

     rtm_msglen	  Total length of message, including struct sockaddr entries.

     rtm_pid	  Process ID of the sender, set by the operating system.

     rtm_rmx	  Route metrics from struct rtentry as described below.

     rtm_seq	  Sequence number assigned by the sender.

     rtm_type	  Message type as defined above.

     rtm_use	  Value of rt_use from struct rtentry.

     rtm_version  Version of the message format in use, should be set to
		  RTM_VERSION.

     Route metrics are defined as:

     struct rt_metrics {
	 u_long rmx_locks;     /* Kernel must leave these values alone */
	 u_long rmx_mtu;       /* MTU for this path */
	 u_long rmx_hopcount;  /* max hops expected */
	 u_long rmx_expire;    /* lifetime for route, e.g. redirect */
	 u_long rmx_recvpipe;  /* inbound delay-bandwith product */
	 u_long rmx_sendpipe;  /* outbound delay-bandwith product */
	 u_long rmx_ssthresh;  /* outbound gateway buffer limit */
	 u_long rmx_rtt;       /* estimated round trip time */
	 u_long rmx_rttvar;    /* estimated rtt variance */
     };

     Values for rtm_flags include the values:

     RTF_BLACKHOLE  Packets using this route will be silently dropped.

     RTF_CLONED	    This route was cloned dynamically from a more general
		    route.

     RTF_CLONING    References to this route should generate a more specific
		    route with the specified cloning mask.

     RTF_DONE	    Indicates that processing of this message has been com-
		    pleted.  The preferred method of detecting if a

     RTF_DYNAMIC    Created dynamically, usually by a redirect.

     RTF_GATEWAY    The route points to a ``gateway'' which will forward the
		    packet on to it's final destination.

     RTF_HOST	    The destination references a host, no netmask is present.

     RTF_LLINFO	    Indicates that this route contains link level information,
		    used by routes installed by arp(4) and esis(4).

     RTF_MODIFIED   Modified dynamically, usually by a redirect.  RTM_REDIRECT
		    message was processed by the operating system is to exam-
		    ine rtm_errno.

     RTF_PROTO1

     RTF_PROTO2	    Protocol specific routing flags.

     RTF_REJECT	    Packets using this route will be dropped and EHOSTUNREACH
		    or ENETUNREACH errors to be returned.

     RTF_STATIC	    Indicates that this route was manually added by the system
		    administrator with the route(8) command.  This provides a
		    indication to user-level routing daemons (e.g.
		    gated(8)routed(8))	 that this route should be retained.

     RTF_UP	    The route is usable.

     RTF_XRESOLVE   References to this route should generate RTM_RESOLVE rout-
		    ing socket messages to request a more specific route be
		    installed by a user process.

     Specifiers for metric values in rmx_locks and rtm_inits are:

     #define RTV_MTU	   0x1	  /* init or lock _mtu */
     #define RTV_HOPCOUNT  0x2	  /* init or lock _hopcount */
     #define RTV_EXPIRE	   0x4	  /* init or lock _hopcount */
     #define RTV_RPIPE	   0x8	  /* init or lock _recvpipe */
     #define RTV_SPIPE	   0x10	  /* init or lock _sendpipe */
     #define RTV_SSTHRESH  0x20	  /* init or lock _ssthresh */
     #define RTV_RTT	   0x40	  /* init or lock _rtt */
     #define RTV_RTTVAR	   0x80	  /* init or lock _rttvar */

     Specifiers for which addresses are present in the messages are:

     #define RTA_DST	   0x1	  /* destination sockaddr present */
     #define RTA_GATEWAY   0x2	  /* gateway sockaddr present */
     #define RTA_NETMASK   0x4	  /* netmask sockaddr present */
     #define RTA_GENMASK   0x8	  /* cloning mask sockaddr present */
     #define RTA_IFP	   0x10	  /* interface name sockaddr present */
     #define RTA_IFA	   0x20	  /* interface addr sockaddr present */
     #define RTA_AUTHOR	   0x40	  /* sockaddr for author of redirect */
     #define RTA_BRD	   0x80	  /* for NEWADDR, broadcast or p-p dest addr */

   Interface status messages

     Messages describing interfaces and interface status changes are:

     RTM_DELADDR  Generated whenever an existing address is deleted from an
		  interface.

     RTM_IFINFO	  Generated whenever the status of an interface changes.

     RTM_NEWADDR  Generated whenever a new address is added to an interface,
		  or the characteristics of an existing address are changed.

     The RTM_IFINFO message uses the following message header:

     struct if_msghdr {
	 u_short ifm_msglen;	  /* to skip over non-understood messages */
	 u_char	 ifm_version;	  /* future binary compatability */
	 u_char	 ifm_type;	  /* message type */
	 int	 ifm_addrs;	  /* like rtm_addrs */
	 int	 ifm_flags;	  /* value of if_flags */
	 u_short ifm_index;	  /* index for associated ifp */
	 struct if_data ifm_data; /* statistics and other data about if */
     };

     ifm_msglen	  Total length of message, including struct sockaddr entries.

     ifm_addrs	  Description of addresses included as defined above.

     ifm_data	  Interface statistics as defined in struct if_data found in
		  <net/if.h>.

     ifm_flags	  Interface flags as defined in	 <net/if.h>.

     ifm_index	  Index of associated interface.

     ifm_type	  Message type as defined above.

     ifm_version  Version of the message format in use, should be set to
		  RTM_VERSION.

     Messages describing the addition or deletion of addresses on an interface
     use the following message header:

     struct ifa_msghdr {
	 u_short ifam_msglen;	  /* to skip over non-understood messages */
	 u_char	 ifam_version;	  /* future binary compatability */
	 u_char	 ifam_type;	  /* message type */
	 int	 ifam_addrs;	  /* like rtm_addrs */
	 int	 ifam_flags;	  /* value of ifa_flags */
	 u_short ifam_index;	  /* index for associated ifp */
	 int	 ifam_metric;	  /* value of ifa_metric */
     };

     ifam_msglen   Total length of message, including struct sockaddr entries.

     ifam_addrs	   Description of addresses included as defined above.

     ifam_flags	   Interface address flags from struct ifaddr.

     ifam_index	   Interface index of associated interface.

     ifam_metric   Interface address metric from struct ifaddr.

     ifam_type	   Message type as defined above.

     ifam_version  Version of the message format in use, should be set to
		   RTM_VERSION.

ERRORS
     The routing code returns the following errors in the global variable
     errno and as rtm_errno.

     [EEXIST]
	      The entry being added would duplicate an existing entry.

     [ESRCH]  The entry being deleted does not exist.

     [ENOBUFS]
	      Insufficient resources were available to install a new route.

SEE ALSO
     ioctl(2),	shutdown(2),  socket(2),  sysctl(3),  arp(4),  esis(4),
     inet(4),  intro(4),  iso(4),  localdomain(4),  netintro(4),  ns(4),
     config(8),	 gated(8),  ifconfig(8),  routed(8)

BSDI BSD/OS			April 19, 1994				     6
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server BSDOS

List of man pages available for BSDOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net