route man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

route(7P)							     route(7P)

       route - kernel packet forwarding database

       This  manpage describes routing socket interface to read and write ker‐
       nel routing messages.

       The information on how to transmit network packets is maintained by the
       HP-UX  kernel  in  the  routing information database, also known as the
       routing table.  A user process can read or update  information  in  the
       routing table by sending routing messages to the kernel via an AF_ROUTE
       socket.	The message types are described in more detail in the  section

       The  family  parameter  in  the system call shown in the may be used to
       filter the routing messages the caller receives.	 The valid values  for
       family are:

	      AF_INET	     get  routing messages affecting the Internet Pro‐
	      AF_INET6	     get routing messages affecting the Internet  Pro‐
			     tocol version 6.
	      AF_UNSPEC	     get  routing  messages affecting both AF_INET and
			     AF_INET6 protocols.

       Entries in the routing table specify the	 appropriate  remote  host  or
       gateway	to  use	 when  transmitting packets.  These entries are either
       host-specific, or are applicable to all hosts located on a generic sub‐
       network, as specified by a netmask value.

       After  the system boots, each protocol family adds entries to the rout‐
       ing table for each network interface configured and ready  to  transmit
       network	traffic.   Normally,  the route entry is specified as a to the
       destination host or network.  For direct routes, the transport layer of
       the  network  stack sends packets directly to the host specified in the
       packet header.  For  non-direct	routes,	 the  interface	 forwards  the
       packet to the gateway listed in the routing entry for that interface.

       When  routing packets, the kernel attempts to find an optimal route for
       each destination.  If more than one entry matches the  netmask  of  the
       destination,  the  kernel  selects the route with the greater number of
       1's in the netmask.

       A default (wildcard) route is used if no other route  to	 a  particular
       remote  host  or	 network can be located.  A default route is specified
       with an all 0 destination address value	and  a	netmask	 of  all  0's.
       Default	routes, in combination with routing redirects, provide an eco‐
       nomical mechanism for routing network traffic.

       If no routing entry is found, the destination is declared  as  unreach‐
       able,  and  a  routing-miss message (RTM_MISS) is generated to any user
       processes using the routing socket facilities, as described below.

   Message Types
       After creating a routing socket, the process can send commands  to  the
       kernel by writing to the socket.	 The process can read information from
       the kernel by reading from the socket.  The following message types can
       be used to communicate routing information between the user process and
       the kernel:

	      RTM_ADD		add route
	      RTM_CHANGE	change gateway, metrics or flags
	      RTM_DELADDR	address being removed from interface
	      RTM_DELETE	delete route
	      RTM_GET		report metrics and other information
	      RTM_IFINFO	interface going up, down, etc.
	      RTM_LOSING	kernel suspects route is failing
	      RTM_LOCK		lock specified metrics
	      RTM_MISS		lookup on this address failed
	      RTM_NEWADDR	address being added to interface
	      RTM_REDIRECT	kernel instructs to use different route
	      RTM_RESOLVE	request to resolve destination	to  link-layer

       All  12	message types can be used to read information from the kernel.
       To write to the kernel, the process can issue RTM_ADD,  RTM_DELETE,  or
       RTM_GET message types to update information in the routing table.

       Message types RTM_CHANGE and RTM_LOCK are not supported on HP-UX.  If a
       user process issues these messages, error will be returned.

   Message Structure
       Messages are formed by a message header followed by a small  number  of
       socket address structures.

       What message header to use depends on the message type.	The RTM_IFINFO
       messages use the header.	 The RTM_NEWADDR and RTM_DELADDR messages  use
       the header.  All other message types use the header.

       The structure contains the following members:

	 uint16_t rtm_msglen;	    /* to skip over unrecognized messages */
	 uint8_t  rtm_version;	    /* future binary compatibility */
	 uint8_t  rtm_type;	    /* message type */
	 uint16_t rtm_index;	    /* index for associated ifp */
	 int32_t  rtm_flags;	    /* flags, incl. kern & message,
				     * e.g. DONE */
	 int32_t  rtm_addrs;	    /* bitmask identifying sockaddrs in
				     * the message */
	 pid_t	  rtm_pid;	    /* identify sender */
	 int32_t  rtm_seq;	    /* for sender to identify action */
	 int32_t  rtm_errno;	    /* error indicator */
	 int32_t  rtm_use;	    /* from rtentry */
	 uint32_t rtm_inits;	    /* which metrics we are initializing */
	 struct rt_metrics rtm_rmx; /* metrics themselves */

       The structure contains the following members:

	 uint16_t ifm_msglen;	    /* to skip over unrecognized messages */
	 uint8_t  ifm_version;	    /* future binary compatibility */
	 uint8_t  ifm_type;	    /* message type */
	 int32_t  ifm_addrs;	    /* bitmask identifying sockaddrs in
				     * the message */
	 int32_t  ifm_flags;	    /* value of if_flags */
	 uint16_t ifm_index;	    /* index for associated ifp */
	 struct if_data ifm_data;   /* statistics and other data about
				     * interface */

       The structure contains the following members:

	 uint16_t ifam_msglen;	    /* to skip over unrecognized messages */
	 uint8_t  ifam_version;	    /* future binary compatibility */
	 uint8_t  ifam_type;	    /* message type */
	 int32_t  ifam_addrs;	    /* bitmask identifying sockaddrs in
				     * the message */
	 int32_t  ifam_flags;	    /* value of ifa_flags */
	 uint16_t ifam_index;	    /* index for associated ifp */
	 int32_t  ifam_metric;	    /* value of ifa_metric */

       To determine retransmission behavior, reliable protocols use the struc‐
       ture included in the message header.  The structure contains  the  fol‐
       lowing members:

	 uint32_t rmx_locks;	    /* Kernel must leave these values alone */
	 uint32_t rmx_mtu;	    /* MTU for this path */
	 uint32_t rmx_hopcount;	    /* max hops expected */
	 uint32_t rmx_expire;	    /* lifetime for route, e.g. redirect */
	 uint32_t rmx_recvpipe;	    /* inbound delay-bandwidth product */
	 uint32_t rmx_sendpipe;	    /* outbound delay-bandwidth product */
	 uint32_t rmx_ssthresh;	    /* outbound gateway buffer limit */
	 uint32_t rmx_rtt;	    /* estimated round trip time */
	 uint32_t rmx_rttvar;	    /* estimated rtt variance */
	 uint32_t rmx_pksent;	    /* packets sent using this route */

       The structure included in the message header defines a queue for a net‐
       work interface and contains the following members:

	 /* generic interface information */
	 uint8_t ifi_type;	    /* ethernet, tokenring, etc */
	 uint8_t ifi_physical;	    /* AUI, Thinnet, 10base-T, etc */
	 uint8_t ifi_addrlen;	    /* media address length */
	 uint8_t ifi_hdrlen;	    /* media header length */
	 uint8_t ifi_recvquota;	    /* polling quota for receive intrs */
	 uint8_t ifi_xmitquota;	    /* polling quota for xmit intrs */
	 uint32_t ifi_mtu;	    /* maximum transmission unit */
	 uint32_t ifi_metric;	    /* routing metric (external only) */
	 uint32_t ifi_baudrate;	    /* linespeed */

	 /* volatile statistics */
	 uint32_t ifi_ipackets;	    /* packets received on interface */
	 uint32_t ifi_ierrors;	    /* input errors on interface */
	 uint32_t ifi_opackets;	    /* packets sent on interface */
	 uint32_t ifi_oerrors;	    /* output errors on interface */
	 uint32_t ifi_collisions;   /* collisions on csma interfaces */
	 uint32_t ifi_ibytes;	    /* total number of octets received */
	 uint32_t ifi_obytes;	    /* total number of octets sent */
	 uint32_t ifi_imcasts;	    /* packets received via multicast */
	 uint32_t ifi_omcasts;	    /* packets sent via multicast */
	 uint32_t ifi_iqdrops;	    /* dropped on input, this interface */
	 uint32_t ifi_noproto;	    /* destined for unsupported protocol */
	 uint32_t ifi_hwassist;	    /* HW offload capabilities */
	 uint32_t ifi_unused;	    /* XXX was ifi_xmittiming */
	 struct timeval ifi_lastchange; /* time of last administrative change */

       (Note that the position of  items  in  all  previously  mentioned  data
       structures does not necessarily reflect the order of the members in the

       The members and of the message headers are bitmasks that	 specify  what
       socket  address structure(s) follow the message.	 When multiple sockad‐
       drs follow the message, they are interpreted based on  their  order  in
       the message and the value stored in the bitmask.	 The sequence is least
       significant to the most significant bit within the vector.

       The following constants are defined to indicate which socket  addresses
       are present in the routing message:

	 #define RTA_DST     0x01   /* destination sockaddr present */
	 #define RTA_GATEWAY 0x02   /* gateway sockaddr present */
	 #define RTA_NETMASK 0x04   /* netmask sockaddr present */
	 #define RTA_GENMASK 0x08   /* cloning mask sockaddr present */
	 #define RTA_IFP     0x10   /* interface name sockaddr present */
	 #define RTA_IFA     0x20   /* interface address sockaddr present */
	 #define RTA_AUTHOR  0x40   /* author of redirect sockaddr present */
	 #define RTA_BRD     0x80   /* for NEWADDR, broadcast or
				     * point-to-point destination
				     * address */

       Any  messages sent to the kernel are returned back to the process issu‐
       ing the command, and message copies are sent to all interested  listen‐
       ers.  The sender may provide its process ID to be stored in the message
       header.	An additional  sequence	 field	can  be	 used  to  distinguish
       between	outstanding  messages.	 However,  message replies may be lost
       when kernel buffers are exhausted.

       Any messages generated by the kernel would have process ID and sequence
       field set to zero.

       The  kernel  may	 spontaneously	emit  routing  messages in response to
       external events, such as receipt of a redirect command, or  failure  to
       locate  an  appropriate	route for a request.  A process may ignore all
       messages from the routing socket by doing a  system  call  for  further

   Security Restrictions
       Only  users with appropriate privileges can make changes to the routing

       Some fields in the message header structures are	 not  used  on	HP-UX.
       This  means  when  the  kernel generates routing messages it sets these
       fields to 0.  Also, when	 the  kernel  receives	routing	 messages,  it
       ignores any values contained in these fields.  This applies to the fol‐
       lowing fields:

	      rtm_use, rtm_inits,
			     rtm_rmx, except for rtm_rmx.rmx_mtu
			     and rtm_rmx.rmx_rtt

	      ifm_data, except for ifm_data.ifi_mtu,
			     ifm_data.ifi_ipackets,	     and


       If the kernel rejects a routing message, the field in the
       structure may be set to one of the following values:

	      The specified entry already exist.
				  Requested  to	  duplicate   an
				  existing entry.

	      Network is unreachable.

	      The specified entry does not exist.
				  Requested  to delete non-exis‐
				  tent entry.

	      No buffer space is available.
				  Insufficient	resources   were
				  available  to	 install  a  new

	      Operation not supported.
				  Message types	 RTM_CHANGE  and
				  RTM_LOCK  are not supported on

	      Permission to issue a command is denied.
				  The  user  needs   appropriate
				  privileges  to make changes to
				  the routing table.

       The following  sample  program  illustrates  how	 a  user
       process can add a route to the kernel's routing table.

	      #include <sys/types.h>
	      #include <sys/socket.h>
	      #include <net/route.h>
	      #include <net/if.h>
	      #include <netinet/in.h>

	      int main(int argc, char **argv)
		      int    s;
		      char   buf[1024];
		      struct rt_msghdr *rtm;
		      struct sockaddr_in *sin1, *sin2;

		      if (argc != 3) {
			      printf("usage: %s <destinationIP> <gatewayIP>\n",
			      return -1;

		      if ((s = socket(AF_ROUTE, SOCK_RAW, AF_UNSPEC)) < 0) {
			       perror("failed to create socket");
			       return -1;

		      rtm = (struct rt_msghdr *)buf;

		      rtm->rtm_msglen = sizeof(struct rt_msghdr) +
					(2 * sizeof(struct sockaddr_in));
		      rtm->rtm_version = RTM_VERSION;
		      rtm->rtm_type = RTM_ADD;
		      rtm->rtm_flags = (RTF_UP | RTF_GATEWAY | RTF_HOST);
		      rtm->rtm_addrs = (RTA_DST | RTA_GATEWAY);
		      rtm->rtm_pid = getpid();
		      rtm->rtm_errno = 0;
		      rtm->rtm_seq = 0001;

		       * the destination address being added follows
		       * the routing header
		      sin1 = (struct sockaddr_in *)(rtm + 1);
		      sin1->sin_family = AF_INET;
		      sin1->sin_addr.s_addr = inet_addr(argv[1]);

		       * the gateway address being added follows the
		       * destination address
		      sin2 = (struct sockaddr_in *)(sin1 + 1);
		      sin2->sin_family = AF_INET;
		      sin2->sin_addr.s_addr = inet_addr(argv[2]);

		      if (write(s, (caddr_t)rtm, rtm->rtm_msglen) < 0) {
			      perror("Failed to send routing message");
			      return -1;

		      return 0;

       Routing socket interface was developed by HP and the Uni‐
       versity of California, Berkeley.

       route(1M), ioctl(2), shutdown(2), socket(2), routing(7).


List of man pages available for HP-UX

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]
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