if(7P) (man pages section 7: Device and Network Interfaces)

man pages section 7: Device and Network Interfaces

if(7P)

NAME

if_tcp, if- general properties of Internet Protocol network interfaces

DESCRIPTION

A network interface is a device for sending and receiving packets on a network. It is usually a hardware device, although it can be implemented in software. Network interfaces used by the Internet Protocol (IPv4 or IPv6) must be STREAMS devices conforming to the Datalink Provider Interface (DLPI ). See dlpi(7P) .

APPLICATION PROGRAMMING INTERFACE

An interface becomes available to IP when it is opened and the IP module is pushed onto the stream with the I_PUSH ioctl(2) command (see streamio(7I) ), and the SIOCSLIFNAME ioctl(2) is issued to specify the name of the interface and whether it is IPv4 or IPv6 . This may be initiated by the kernel at boot time or by a user program some time after the system is running. Each interface must be assigned an IP address with the SIOCSLIFADDR ioctl() before it can be used. On interfaces where the network-to-link layer address mapping is static, only the network number is taken from the ioctl() request; the remainder is found in a hardware specific manner. On interfaces which provide dynamic network-to-link layer address mapping facilities, for example, 10Mb/s Ethernets using arp(7P) , the entire address specified in the ioctl() is used. A routing table entry for destinations on the network of the interface is installed automatically when an interface's address is set.

IOCTLS

The following ioctl() calls may be used to manipulate IP network interfaces. Unless specified otherwise, the request takes an lifreq structure as its parameter. This structure has the form:

/* Interface request structure used for socket ioctls.  All       */
/* interface ioctls must have parameter definitions which         */
/* begin with ifr_name.  The remainder may be interface specific. */
struct lifreq {
#define LIFNAMSIZ	32
   char    lfr_name[LIFNAMSIZ];               /* if name, for example "le1" */
   union {
      int    lifru_addrlen;                   /* for subnet/token etc */
      uint_t lifru_ppa;                       /* SIOCSLIFNAME */
   } lifr_lifru1;
   union {
      struct sockaddr_storage lifru_addr;
      struct sockaddr_storage lifru_dstaddr;
      struct sockaddr_storage lifru_broadaddr;
      struct sockaddr_storage lifru_token;    /* With lifr_addrlen */
      struct sockaddr_storage lifru_subnet;   /* With lifr_addrlen */
      int                     lifru_index;    /* interface index */
      uint64_t                lifru_flags;    /* SIOC?LIFFLAGS */
      int                     lifru_metric;
      uint_t                  lifru_mtu;
      char                    lifru_data[1];  /* interface dependent data */
      char                    lifru_enaddr[6];
      int                     lif_muxid[2];   /* mux id's for arp and ip */
      struct lif_nd_req       lifru_nd_req;
      struct lif_ifinfo_req   lifru_ifinfo_req;
   } lifr_lifru;

#define lifr_addrlen   lifr_lifru1.lifru_addrlen
#define lifr_ppa       lifr_lifru1.lifru_ppa       /* Driver's ppa */
#define lifr_addr      lifr_lifru.lifru_addr       /* address */
#define lifr_dstaddr   lifr_lifru.lifru_dstaddr    
#define lifr_broadaddr lifr_lifru.lifru_broadaddr  /* broadcast address */
#define lifr_token     lifr_lifru.lifru_token      /* address token */
#define lifr_subnet    lifr_lifru.lifru_subnet     /* subnet prefix */
#define lifr_index     lifr_lifru.lifru_index      /* interface index */
#define lifr_flags     lifr_lifru.lifru_flags      /* flags */
#define lifr_metric    lifr_lifru.lifru_metric     /* metric */
#define lifr_mtu       lifr_lifru.lifru_mtu        /* mtu */
#define lifr_data      lifr_lifru.lifru_data       
#define lifr_enaddr    lifr_lifru.lifru_enaddr     /* ethernet address */
#define lifr_index     lifr_lifru.lifru_index      /* interface index  */
#define lifr_ip_muxid  lifr_lifru.lif_muxid[0]
#define lifr_arp_muxid lifr_lifru.lif_muxid[1]
#define lifr_nd        lifr_lifru.lifru_nd_req     /* SIOCLIF*ND */
#define lifr_ifinfo    lifr_lifru.lifru_ifinfo_req /* SIOC[GS]LIFLNKINFO */
};

SIOCSLIFADDR: Set interface address. Following the address assignment, the "initialization" routine for the interface is called.
SIOCGLIFADDR: Get interface address.
SIOCSLIFDSTADDR: Set point to point address for interface.
SIOCGLIFDSTADDR: Get point to point address for interface.
SIOCSLIFFLAGS: Set interface flags field. If the interface is marked down, any processes currently routing packets through the interface are notified.
SIOCGLIFFLAGS: Get interface flags.
SIOCGLIFCONF: Get interface configuration list. This request takes an lifconf structure (see below) as a value-result parameter. The lifc_len field should be initially set to the size of the buffer pointed to by lifc_buf . On return it will contain the length, in bytes, of the configuration list. The lifc_family field should be set to AF_UNSPEC to retrieve both AF_INET and AF_INET6 interfaces. The lifc_flags field should be initially set to zero.
SIOCGLIFNUM: Get number of interfaces. This request returns an integer which is the number of interface descriptions (struct lifreq ) that will be returned by the SIOCGLIFCONF ioctl; that is, it gives an indication of how large lifc_len has to be. This request takes an lifnum structure (see below) as a value-result parameter. The lifn_family field should be set to AF_UNSPEC to count both AF_INET and AF_INET6 interfaces. The lifn_flags field should be initially set to zero.
SIOCSLIFMTU: Set the maximum transmission unit (MTU) size for interface. Place the result of this request in lifru_mtu field. The MTU can not exceed the physical MTU limitation (which is reported in the DLPI DL_INFO_ACK message).
SIOCGLIFMTU: Get the maximum transmission unit size for interface. Place the result of this request in ifru_mtu field.
SIOCSLIFMETRIC: Set the metric associated with the interface. The metric is used by routine daemons such as in.routed(1M) .
SIOCGLIFMETRIC: Get the metric associated with the interface.
SIOCGLIFMUXID: Get the ip and arp muxid associated with the interface.
SIOCSLIFMUXID: Set the ip and arp muxid associated with the interface.
SIOCGLIFINDEX: Get the interface index associated with the interface.
SIOCSLIFINDEX: Set the interface index associated with the interface.
SIOCLIFADDIF: Add a new logical interface on a physical interface using an unused logical unit number.
SIOCLIFREMOVEIF: Remove a logical interface by specifying its IP address or logical interface name.
SIOCSLIFTOKEN: Set the address token used to form IPv6 link-local addresses and for stateless address autoconfiguration.
SIOCGLIFTOKEN: Get the address token used to form IPv6 link-local addresses and for stateless address autoconfiguration.
SIOCSLIFSUBNET: Set the subnet prefix associated with the interface.
SIOCGLIFSUBNET: Get the subnet prefix associated with the interface.
SIOCSLIFLNKINFO: Set link specific parameters for the interface.
SIOCGLIFLNKINFO: Get link specific parameters for the interface.
SIOCLIFDELND: Delete a neighbor cache entry for IPv6 .
SIOCLIFGETND: Get a neighbor cache entry for IPv6 .
SIOCLIFSETND: Set a neighbor cache entry for IPv6 .
SIOCTMYADDR: Test if the address is assigned to this node. This request takes an sioc_addrreq structure (see below) as a value-result parameter. The sa_addr field should be set to the address to test. The sa_res field will contain a non-zero value if the address is assigned to this node.
SIOCTONLINK: Test if the address is directly reachable, for example, that it can be reached without going through a router. This request takes an sioc_addrreq structure (see below) as a value-result parameter. The sa_addr field should be set to the address to test. The sa_res field will contain a non-zero value if the address is onlink.
SIOCTMYSITE: Test if the address is part of the same site as this node. This request takes an sioc_addrreq structure (see below) as a value-result parameter. The sa_addr field should be set to the address to test. The sa_res field will contain a non-zero value if the address is in the same site.

The lifconf structure has the form:

/*
 * Structure used in SIOCGLIFCONF request.
 * Used to retrieve interface configuration
 * for machine (useful for programs which
 * must know all networks accessible).
 */
struct lifconf {
   sa_family_t     lifc_family;
   int             lifc_flags;          /* request specific interfaces */
   int             lifc_len;            /* size of associated buffer */
   union {
      caddr_t      lifcu_buf;
      struct ifreq *lifcu_req;
   } lifc_lifcu;

#define lifc_buf lifc_lifcu.lifcu_buf   /* buffer address */
#define lifc_req lifc_lifcu.lifcu_req   /* array of structures returned */
};

The sioc_addrreq structure has the form:

/* Structure used in SIOCGLIFNUM request. */
struct lifnum {
   sa_family_t     lifn_family;
   int             lifn_flags;   /* request specific interfaces */
   int             lifn_count;   /* Result */
};

/*
 * Argument structure for SIOCT* address testing ioctls.
 */
struct sioc_addrreq {
   struct sockaddr_storage sa_addr; /* Address to test */
   int                     sa_res;  /* Result - 0/1 */
};

The following ioctl() calls are maintained for compatibility but only apply to IPv4 network interfaces, since the data structures are to small to hold an IPv6 address. Unless specified otherwise, the request takes an ifreq structure as its parameter. This structure has the form:

/* Interface request structure used for socket ioctls.  All */
/* interface ioctls must have parameter definitions which */
/* begin with ifr_name.  The remainder may be interface specific. */
struct ifreq {
#define IFNAMSIZ	16
	char	ifr_name[IFNAMSIZ];	                /* if name, for example */
				                                  /* "le1" */
	union {
		struct sockaddr	ifru_addr;
		struct sockaddr	ifru_dstaddr;
		char	ifru_oname[IFNAMSIZ];	           /* other if name */
		struct sockaddr	ifru_broadaddr;
		short	ifru_flags;
		int	ifru_metric;
		char	ifru_data[1];	                    /* interface dependent data */
		char	ifru_enaddr[6];
		int	if_muxid[2];                     /* mux id's for arp and ip */
		int	ifru_index;	                      /* interface index */
	} ifr_ifru;

#define ifr_addr	ifr_ifru.ifru_addr      /* address */
#define ifr_dstaddr	ifr_ifru.ifru_dstaddr /* other end of p-to-p link */
#define ifr_oname	ifr_ifru.ifru_oname	    /* other if name */
#define ifr_broadaddr	ifr_ifru.ifru_broadaddr	/* broadcast address */
#define ifr_flags	ifr_ifru.ifru_flags     /* flags */
#define ifr_index 	ifr_ifru.ifru_index	  /* interface index  */
#define ifr_metric	ifr_ifru.ifru_metric  /* metric */
#define ifr_data	ifr_ifru.ifru_data      /* for use by interface */
#define ifr_enaddr	ifr_ifru.ifru_enaddr	a/* ethernet address */
};

SIOCSIFADDR: Set interface address. Following the address assignment, the "initialization" routine for the interface is called.
SIOCGIFADDR: Get interface address.
SIOCSIFDSTADDR: Set point to point address for interface.
SIOCGIFDSTADDR: Get point to point address for interface.
SIOCSIFFLAGS: Set interface flags field. If the interface is marked down, any processes currently routing packets through the interface are notified.
SIOCGIFFLAGS: Get interface flags.
SIOCGIFCONF: Get interface configuration list. This request takes an ifconf structure (see below) as a value-result parameter. The ifc_len field should be initially set to the size of the buffer pointed to by ifc_buf . On return it will contain the length, in bytes, of the configuration list.
SIOCGIFNUM: Get number of interfaces. This request returns an integer which is the number of interface descriptions (struct ifreq ) that will be returned by the SIOCGIFCONF ioctl; that is, it gives an indication of how large ifc_len has to be.
SIOCSIFMTU: Set the maximum transmission unit (MTU ) size for interface. Place the result of this request in ifru_metric field. The MTU has to be smaller than physical MTU limitation (which is reported in the DLPI DL_INFO_ACK message).
SIOCGIFMTU: Get the maximum transmission unit size for interface. Place the result of this request in ifru_metric field.
SIOCSIFMETRIC: Set the metric associated with the interface. The metric is used by routine daemons such as in.routed(1M) .
SIOCGIFMETRIC: Get the metric associated with the interface.
SIOCGIFMUXID: Get the ip and arp muxid associated with the interface.
SIOCSIFMUXID: Set the ip and arp muxid associated with the interface.
SIOCGIFINDEX: Get the interface index associated with the interface.
SIOCSIFINDEX: Set the interface index associated with the interface.

The ifconf structure has the form:

/*
 * Structure used in SIOCGIFCONF request.
 * Used to retrieve interface configuration
 * for machine (useful for programs which
 * must know all networks accessible).
 */
struct ifconf {
	int	ifc_len;		               /* size of associated buffer */
	union {
		caddr_t	ifcu_buf;
		struct ifreq	*ifcu_req;
	} ifc_ifcu;

#define ifc_buf	ifc_ifcu.ifcu_buf	/* buffer address */
#define ifc_req	ifc_ifcu.ifcu_req	/* array of structures returned */
};

ERRORS

EPERM

The effective user id of the calling process in not superuser.

ENXIO

The lifr_name member of the lifreq structure contains an invalid value.

EBADADDR

Wrong address family or malformed address.

EBUSY

For SIOCSLIFFLAGS , this error is returned when the order of bringing the primary/physical interface (for example, le0 ) and a secondary/logical interface associated with the same physical interface (for example, le0:1 ) up or down is violated. The physical interface must be configured up first and cannot be configured down until all the corresponding logical interfaces have been configured down.

EINVAL

For SIOCGLIFCONF , this error is returned when the size of the buffer pointed to by the lifc_buf member of the lifconf structure is too small.

For SIOCSLIFMTU , this error is returned when the requested MTU size is invalid. This error indicates the MTU size is greater than the MTU size supported by the DLPI provider or less than 68 (for IPv4 ) or less than 1200 (for IPv6 ).