ip(ADMP)

ip -- Internet protocol

Syntax

Programmer's interface:

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

s = socket(AF_INET, SOCK_RAW, proto);

#include <paths.h>
#include <fcntl.h>
#include <netinet/if.h>
#include <netinet/ip_var.h>

fd = open(_PATH_IP, flags);

Description

IP is the network layer protocol used by the Internet protocol family. Options may be set at the IP level when using higher-level protocols that are based on IP (such as TCP and UDP). It may also be accessed through a ``raw socket'' or device when developing new protocols or special purpose applications.

Options are set with setsockopt and examined with getsockopt (see getsockopt(SSC)). Several generic options are supported at the IP level. The first, IP_OPTIONS, may be used to provide IP options to be transmitted in the IP header of each outgoing packet. The format of IP options to be sent is that specified by the IP protocol specification, with one exception: the list of addresses for Source Route options must include the first-hop gateway at the beginning of the list of gateways. The first-hop gateway address will be extracted from the option list and the size adjusted accordingly before use. IP options may be used with any socket type in the Internet family.

The time-to-live in outgoing IP datagrams can be set using the IP_TTL option, whose argument is an unsigned character between 1 and 255.

The type-of-service in outgoing IP datagrams can be set using the IP_TOS option, whose argument is an unsigned character. Legal precedence values are defined in RFC 791.

IP supports multicasting of datagrams (see RFC 1112). Several options are available to control the behavior of multicasting.

IP_MULTICAST_IF takes a struct in_addr as an argument. This argument is a local interface address. When this option is set, multicast datagrams will be sent out of the interface whose address is specified by the argument. Otherwise, multicast datagrams are sent out of whichever interface is associated with a route to the specified multicast address.

Normally, multicast datagrams are looped back to the local system. The IP_MULTICAST_LOOP option can be used to prevent this. This option takes a character argument. Legal values are zero to disable multicast loopback and 1 to enable multicast loopback.

Multicast groups may be joined and left using IP_ADD_MEMBERSHIP and IP_DROP_MEMBERSHIP. A group is specified using the following structure:

   struct ip_mreq {
      struct in_addr imr_multiaddr;  /* IP multicast address of group */
      struct in_addr imr_interface;  /* local IP address of interface */
   };

IP supports the ability to retrieve protocol information for use with UDP. The information that can currently be retrieved is: the destination address of the datagram, the IP options in the datagram, and reflected options for use in replies. These can be enabled or disabled via the following boolean options: IP_RECVDESTADDR, IP_RECVOPTS, and IP_RECVRETOPTS.

On Ethernet and FDDI networks, multicast addresses are mapped to a range of assigned multicast addresses as specified in RFC 1042. On 802.5 networks, multicast addresses are normally mapped to the functional address specified in RFC 1469. Enabling the IFF_LINK0 (see ifconfig(ADMN)) flag prior to setting the interface address will cause multicast addresses to be mapped to the all-rings broadcast address.

Raw IP sockets are connectionless, and are normally used with the sendto and recvfrom calls; the connect(SSC) call may also be used to fix the destination for future packets (in which case the read(S) or recv(SSC) and write(S) or send(SSC) system calls may be used).

If proto is 0, the default protocol IPPROTO_RAW is used for outgoing packets, and only incoming packets destined for that protocol are received. If proto is non-zero, that protocol number will be used on outgoing packets and to filter incoming packets.

Outgoing packets automatically have an IP header prepended (based on the destination address given and the protocol number with which the socket is created). This behavior can be modified by setting the following booleans to a non-zero value (the first must be defined to use the other two):

IP_HDRINCL: allows all fields in the header to be user-supplied except ip_len, ip_off, and the header checksum. (If these fields are present in the user-supplied header, the kernel will simply overwrite them.)
IP_LENINCL: permits ip_len and ip_off to be user-supplied.
IP_SUMINCL: permits the header checksum to be user-supplied.

When all these options are used, the application is responsible for providing the full IP header, including any protocol options desired (IP_OPTIONS is ignored when IP_HDRINCL is set). Fields in the user-supplied header should be specified in network byte order, except for ip_len and ip_off. These fields are converted to network byte order by IP prior to transmitting the packet. The kernel normally refuses to receive packets with incorrect checksum. With IP_SUMINCL turned on, the kernel pays no attention to received checksums on the affected raw IP protocol; the reader receives the checksum that was present on the wire, and may interpret it as desired.

The kernel normally checks the ip_len field of incoming packets. If the packet's ip_len is longer than the actual packet data received from the lower layer (ethernet, loopback or other media), the packet is discarded. If ip_len is shorter than the actual packet, the packet is truncated to ip_len before being passed up to higher protocol layers. When IP_LENINCL is turned on, packets received on the affected raw IP protocol are handled differently. The buffer length passed up to higher protocol layers is derived directly from the ethernet (or other media) packet length, without regard to the packet's ip_len field. The ip_len field is left intact and may be handled by the reader as desired.

Both IP_SUMINCL and IP_LENINCL apply to a particular raw IP protocol, corresponding to a particular value of the protocol field ip_p in the IP header. The settings of these two options persist as long as any process has a raw IP socket open to that particular protocol; they revert to the default (disabled) state when the last socket to that protocol number is closed. For output, the flags apply only when output is actually being written through a raw IP socket which has had the IP_HDRINCL option turned on (that is, a socket opened with socket(AF_INET, SOCK_RAW, proto) followed by setsockopt(IP_HDRINCL)). For input, the flags apply to all processes reading from any raw socket that receives the affected protocol number.

The IP driver can also be accessed by opening it directly. Various kinds of networking statistics can be gathered by issuing ioctl directives to the driver. The following STREAMS ioctl directives defined in <netinet/ip_var.h> are supported by the IP driver:

SIOCGIFALL

to extract all the available information pertaining to an interface, namely, the ifnet entry, the interface statistics (if available) and the list of addresses associated with the interface. The desired interface is specified by the interface number (sequence number in the list of the interfaces). The following structures are used to extract information pertaining to an interface:

#define IF_MAXADDRS 10
struct ifreq_all {
	struct ifnet if_entry;
#define if_number	if_entry.if_index
	int    if_statsavail;
	struct ifstats if_stats;
	int    if_outqlen;
	int    if_naddr;
	struct all_addrs if_addrs[IF_MAXADDRS];
	/* fetches a max. of IF_MAXADDRS addrs. */
};

struct all_addrs {
	struct sockaddr  addr;
	struct sockaddr  dstaddr;
	struct sockaddr  netmask;
	u_short  flags;
};

SIOCGIPSTUFF

to fetch the IP statistics and other related information. The following structure is passed as an argument to the I_STR ioctl to extract the desired information:

struct ip_stuff {
	struct	ipstat ip_stat;	   /* IP statistics */
	struct	rtstat rt_stat;    /* routing statistics */
	int	ip_forwarding;	   /* are we forwarding? */
	int	ip_default_ttl;	   /* IP TTL */
	int	ipq_ttl;	   /* fragment TTL */
	int	ipq_reasm_reqds;   /* dgrams waiting for reassembly */
	int	icmp_answermask;   /* auth. for mask replies */
	int	ip_sendredirects;  /* sending redirects */
};

SIOCSIPMISC

to manipulate the IP variables ipforwarding and ip_ttl. The following structure is passed as an argument to the I_STR ioctl call:

struct ip_misc {
	int    arg;
	int    ip_forwarding;
	int    ip_default_ttl;
};

The value of the arg field (1 or 2) specifies which of the two variables is to be set.

SIOCSIPTRAP

To designate the ip_pcb associated with this end-point to receive the link-up/down messages from the driver (used by the SNMP agent to send traps to management stations).

Diagnostics

A socket operation may fail with one of the following errors returned:

[EISCONN]: when trying to establish a connection on a socket which already has one, or when trying to send a datagram with the destination address specified and the socket is already connected
[ENOTCONN]: when trying to send a datagram, but no destination address is specified, and the socket has not been connected
[ENOSR]: when the system runs out of memory for an internal data structure
[EADDRNOTAVAIL]: when an attempt is made to create a socket with a network address for which no network interface exists

The following errors specific to IP may occur when setting or getting IP options:

[EINVAL]: an unknown socket option name was given
[EINVAL]: the IP option field was improperly formed; an option field was shorter than the minimum value or longer than the option buffer provided

The ioctl operation may fail and the errno may be set to:

[EINVAL]: when no argument/NULL argument is passed to the driver, or when the arg in the structure ip_misc is set to a value other than 1 or 2

Files

/dev/inet/ip
/dev/inet/rip

Standards conformance

ip is conformant with: