Sortix nightly manual
This manual documents Sortix nightly, a development build that has not been officially released. You can instead view this document in the latest official manual.
NAME
if — network interfaceDESCRIPTION
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.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];
};
- IF_FEATURE_ETHERNET_CRC_OFFLOAD
- The Ethernet CRC32 checksum is computed in hardware.
struct if_status {
int flags;
size_t mtu;
};
- IF_STATUS_FLAGS_UP
- The network interface link is up and packets can be received and transmitted.
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;
};
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.