NAME

if — network interface

SYNOPSIS

#include <sys/ioctl.h>
#include <net/if.h>

DESCRIPTION

Network interfaces are devices that provide transmission and receipt of network packets. The name of a network interface is the name of the device driver followed by the driver instance number, and each network interface have an unique index number distinct from the driver instance number. The name length is restricted to IF_NAMESIZE bytes including the trailing nul byte. Network interfaces are exposed in the filesystem as /dev/nameX devices, where name is the driver name, and the X number denotes which device using that driver. Each driver is documented with a manual page with the driver's name in section 4 of the manual.

The state of the network interface can be awaited with poll(2) where the POLLIN and POLLOUT events are signaled when the network is up (IF_STATUS_FLAGS_UP).

LINK LAYER

Network interfaces abstracts a hardware device or a software device as a link layer protocol:

Ethernet Controller (IF_TYPE_ETHERNET)

Packets are received and transmitted with the Ethernet ether(4) link layer protocol. The type field of struct if_info is set to IF_TYPE_ETHERNET and the addr field contains the 6-byte Ethernet address assigned to the Ethernet controller.

Loopback Device (IF_TYPE_LOOPBACK)

The software loopback device lo(4) on the local host receives any packets transmitted on it. The type field of struct if_info is set to IF_TYPE_LOOPBACK and the addr field is unused.

NETWORK LAYER

Network layer protocols are layered on top of the link layer:

Internet Protocol version 4 (AF_INET)

The Internet Protocol version 4 ip(4) provides the network layer of the Internet Protocol version 4 protocol family inet(4), containing transport protocols such as the Transmission Control Protocol tcp(4), and the User Datagram Protocol udp(4). When combined with the Ethernet link layer, the Address Resolution Protocol arp(4) is used to resolve network layer addresses into link layer addresses.

CONFIGURATION

The static information about a network interface is stored in struct if_info:

struct if_info {
        unsigned int linkid;
        int type;
        int features;
        size_t addrlen;
        char name[IF_NAMESIZE];
        unsigned char addr[IF_HWADDR_MAXSIZE];
};

linkid is the network interface's index number. type is the link layer protocol. features is a bit mask of the features provided by the network interface:

IF_FEATURE_ETHERNET_CRC_OFFLOAD

The Ethernet CRC32 checksum is computed in hardware.

addrlen is the size of the interface's assigned hardware address stored in the addr field. name is the nul-terminated string name of the network interface.

The status information about a network interface is stored in struct if_status:

struct if_status {
        int flags;
        size_t mtu;
};

flags is a bit mask of network interface status conditions:

IF_STATUS_FLAGS_UP

The network interface link is up and packets can be received and transmitted.

mtu is the maximum transmission unit of the network layer datagram that can be sent or transmitted on the link layer.

The configuration of the network interface is stored in if_config:

struct if_config_ether {
       struct ether_addr address;
};

struct if_config_inet {
       struct in_addr address;
       struct in_addr router;
       struct in_addr subnet;
};

struct if_config {
       struct if_config_ether ether;
       struct if_config_inet inet;
};

ether is the configuration of the ether(4) link layer protocol where address is the Ethernet address that received packets must have as the destination address and the address used as the source address in transmitted packets. address defaults on network interface creation to the value of the addr field of the network interface's struct if_info.

inet is the configuration of the ip(4) network layer protocol where address is the local address, router is the default route, and subnet is the subnet mask. The protocol is disabled if address is set to the any address (0.0.0.0).

Configuration changes to the local addresses or routing information will cause the remote side of existing sockets to become unreachable where paths are no longer configured. Currently outgoing packets are unaffected by configuration changes when they have left the appropriate network layers. Outgoing packets may be queued for a short period in queues such as the data link layer address resolution queue or in the transmission queue.

IOCTLS

Network interfaces provide the following ioctl(2) requests defined in <sys/ioctl.h>:

IOCGETTYPE void

Return the device type that as a parameter to the IOC_TYPE(int type) macro returns IOC_TYPE_NETWORK_INTERFACE if the device is a network interface.

NIOC_GETCONFIG struct if_config *

Retrieve the network interface configuration for all protocols atomically.

NIOC_GETCONFIG_ETHER struct if_config_ether *

Retrieve the Ethernet configuration.

NIOC_GETCONFIG_INET struct if_config_inet *

Retrieve Internet Protocol version 4 configuration.

NIOC_GETINFO struct if_info *

Retrieve the network interface static information.

NIOC_GETSTATUS struct if_status *

Retrieve the network interface status.

NIOC_SETCONFIG const struct if_config *

Set the network interface configuration for all protocols atomically.

NIOC_SETCONFIG_ETHER const struct if_config_ether *

Set the Ethernet configuration.

NIOC_SETCONFIG_INET const struct if_config_inet *

Set the Internet Protocol version 4 configuration.

SOCKET OPTIONS

Sockets are made with socket(2) by requesting the desired network layer protocol and the desired transport layer protocol. These setsockopt(2) / getsockopt(2) options of level SOL_SOCKET control aspects related to the network interface and are defined in <sys/socket.h>:

SO_BINDTODEVICE char[]

Set the network interface the socket is bound to by looking up the string value (which need not be nul-terminated) as an network interface name, and then binding the socket to that network interface index number; or failing with ENODEV if no such device exists. Gets the name of the network interface the socket is bound to, by looking up the network interface index number the socket is bound to, and copying out the name of that network interface; or copying out the empty string if so no such device exists. If bound to a network interface, a socket will only receive from and transmit on that network interface. (Initially the empty string)

SO_BINDTOINDEX unsigned int

Sets the network interface the socket is bound to by the network interface index number, not verifying such an network interface exists, returning with the error EINVAL if the requested index number exceeds UINT_MAX. Gets the index number of the network interface the socket is bound to. Index 0 means no network interface. If bound to a network interface, a socket will only receive from and transmit on that network interface. (Initially 0)

SO_BROADCAST int

Sending to a broadcast address is allowed when set to 1, sending to a broadcast address will fail with EACCESS when set to 0. This option is boolean, setting it to non-zero is the same as setting it to 1. This option only pertains to datagram sockets. (Initially 0)

SO_DEBUG int

Whether the socket is in debug mode. This option is not implemented. This option is boolean, setting it to non-zero is the same as setting it to 1. Attempting to set it to non-zero will fail with EPERM. (Initially 0)

SO_DOMAIN sa_family_t

The socket domain (the address family). This option can only be read. The initial value is set when making the socket.

SO_DONTROUTE int

Whether to bypass the routing table and only send on the local network. This option is not implemented. This option is boolean, setting it to non-zero is the same as setting it to 1. Attempting to set it to non-zero will fail with EPERM. (Initially 0)

SO_ERROR int

The asynchronous pending error (an errno(3) value). Cleared to 0 when read unless the error is permanent. This option can only be read. (Initially 0)

SO_PROTOCOL int

The socket protocol. This option can only be read. The initial value is set when making the socket.

SO_RCVBUF int

How many bytes the receive queue can use. Setting this option to a value beyond the socket's hard limit will instead set this option to the hard limit. The initial value depends on the socket protocol.

SO_REUSEADDR int

Don't fail to bind(2) the second socket with EADDRINUSE when one socket is bound to the any address and a port and the other socket is bound to another address and that port, whenever this option is set to 1. This option is boolean, setting it to non-zero is the same as setting it to 1. (Initially 0)

SO_SNDBUF int

How many bytes the send queue can use. Setting this option to a value beyond the socket's hard limit will instead set this option to the hard limit. The initial value depends on the socket protocol.

SO_TYPE int

The socket type. This option can only be read. The initial value is set when making the socket.

IMPLEMENTATION NOTES

Network packets waiting to be transmitted or received have 384 dedicated pages of backing memory (allocated on first use). If more packets are needed, available system memory is used up to a limit of 1/16 of the total system memory. If no memory is available for another network packet or the limit is hit, received packets may be dropped and transmitted packets may be dropped or temporarily fail with ENOBUFS.

SEE ALSO

getsockopt(2), ioctl(2), setsockopt(2), getifaddrs(3), if_nameindex(3), arp(4), ether(4), inet(4), ip(4), lo(4), kernel(7), dhclient(8), ifconfig(8)

STANDARDS

IEEE Std 1003.1-2008 (“POSIX.1”) only specifies a minimal <net/if.h> with IF_NAMESIZE, struct if_nameindex and the if_nameindex(3) family of functions.

IEEE Std 1003.1-2008 (“POSIX.1”) specifies the socket options SO_ACCEPTCONN, SO_BROADCAST, SO_DEBUG, SO_DONTROUTE, SO_ERROR, SO_KEEPALIVE, SO_LINGER, SO_OOBINLINE, SO_RCVBUF, SO_RCVLOWAT, SO_RCVTIMEO, SO_REUSEADDR, SO_SNDBUF, SO_SNDLOWAT, SO_SNDTIMEO, and SO_TYPE in <sys/socket.h>

HISTORY

Network interfaces as described here originally appeared in Sortix 1.1, except when noted otherwise.

The SO_BINDTODEVICE socket option is also found on Linux.