Sortix volatile manual
This manual documents Sortix volatile, a development build that has not been officially released. You can instead view this document in the latest official manual.
NAME
udp — user datagram protocolSYNOPSIS
#include <sys/socket.h>#include <netinet/in.h>
#include <netinet/udp.h>
socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);
DESCRIPTION
The User Datagram Protocol (UDP) is a connectionless transport layer for the Internet Protocol ip(4) that provides best-effort delivery of datagrams. It is designed for packet-switched networks and provides multiplexing with a 16-bit port number, basic data integrity checks (16-bit ones' complement sum), and broadcasting. It does not provide a guarantee of delivery, avoidance of delivering multiple times, ordering, out of band data, nor flow control. UDP provides the SOCK_DGRAM abstraction for the inet(4) protocol family.- The address family it belongs to.
- The network interface it is bound to (if any) (SO_BINDTODEVICE and SO_BINDTOINDEX) (initially none).
- The local address and port (when bound) (initially none).
- The remote address and port (when connected) (initially none).
- A receive queue (initially empty).
- Whether the socket has been shutdown(2) for read and/or write (initially neither).
- A single pending asynchronous error (if any) (SO_ERROR) (initially none).
- Whether broadcast datagrams can be sent (SO_BROADCAST) (initially no).
- Whether binding to the any address and a port doesn't conflict with binding to another address on the same port (SO_REUSEADDR) (initially no).
- Limits on the size of the receive and send queues (SO_RCVBUF and SO_SNDBUF).
- The datagram belongs to the socket's address family and the protocol is UDP.
- The datagram's checksum matches the datagram or it has no checksum.
- The datagram is not sent from port 0 and is not sent to port 0.
- The datagram is sent to the address or broadcast address of the network interface it is received on, or the datagram was sent to the broadcast address;
- The socket is either bound to the receiving network interface, or the socket is not bound to a network interface;
- The datagram is sent to the socket's local port;
- The datagram is sent to the socket's local address, or the socket's local address is the any address (and no other socket is bound to the datagram's address and that port);
- The socket is connected and the datagram was sent from the remote address and the remote port, or the socket is not connected; and
- The socket is not shut down for reading.
SOCKET OPTIONS
UDP sockets support these setsockopt(2) / getsockopt(2) options at level SOL_SOCKET:- SO_BINDTODEVICE char[]
- Bind to a network interface by its name. (Described in if(4))
- SO_BINDTOINDEX unsigned int
- Bind to a network interface by its index number. (Described in if(4))
- SO_BROADCAST int
- Whether sending to a broadcast address is allowed. (Described in if(4))
- SO_DEBUG int
- Whether the socket is in debug mode. This option is not implemented and is initially 0. Attempting to set it to non-zero will fail with EPERM. (Described in if(4))
- SO_DOMAIN sa_family_t
- The socket domain (the address family). This option can only be read. (Described in if(4))
- SO_DONTROUTE int
- Whether to bypass the routing table and only send on the local network. This option is not implemented and is initially 0. Attempting to set it to non-zero will fail with EPERM. (Described in if(4))
- SO_ERROR int
- The asynchronous pending error (an errno(3) value). Cleared to 0 when read. This option can only be read. (Described in if(4))
- SO_PROTOCOL int
- The socket protocol (IPPROTO_UDP). This option can only be read. (Described in if(4))
- SO_RCVBUF int
- How many bytes the receive queue can use (default is 64 pages, max 4096 pages). (Described in if(4))
- SO_REUSEADDR int
- Whether binding to the any address on a port doesn't conflict with binding to another address and the same port, if both sockets have this option set and the user binding the second socket is the same that bound the first socket or the user binding the second socket has superuser privileges. (Described in if(4))
- SO_SNDBUF int
- How many bytes the send queue can use (default is 64 pages, max 4096 pages). (Described in if(4))
- SO_TYPE int
- The socket type (SOCK_DGRAM). This option can only be read. (Described in if(4))
IMPLEMENTATION NOTES
There is no way to disable the checksum on sent packets, however received packets without a checksum will not be checksummed.EXAMPLES
This example creates and binds a UDP socket to a local address and port and sends a broadcast datagram to a remote address and port and receives a response and remembers who sent the response. local is the local socket address that is bound to and local_len is the size of the local socket address and likewise with remote and remote_len. responder is an uninitialized socket address of the appropriate size responder_len for the protocol family af where the source address of the response is stored. The response is stored in the incoming array of size amount. The af, local, local_len, remote, remote_len, responder, and responder_len values should all be chosen according to the address family and network layer.sa_family_t af = /* ... */; const struct sockaddr *local = /* ... */; socklen_t local_len = /* ... */; const struct sockaddr *remote = /* ... */; socklen_t remote_len = /* ... */; const struct sockaddr *responder = /* ... */; socklen_t responder_len = /* ... */; int fd = socket(af, SOCK_DGRAM, IPPROTO_UDP); if (fd < 0) err(1, "socket"); if (bind(fd, local, local_len) < 0) err(1, "bind"); int value = 1; if (setsockopt(fd, SOL_SOCKET, SO_BROADCAST, &value, sizeof(value)) < 0) err(1, "setsockopt"); char outgoing[] = "Hello"; if (sendto(fd, outgoing, strlen(outgoing), 0, remote, remote_len) < 0) err(1, "sendto"); char incoming[1024]; ssize_t amount = recvfrom(fd, incoming, sizeof(incoming), 0, responder, &responder_len); if (amount < 0 ) err(1, "recvfrom");
COMPATIBILITY
Sortix is the only known system where connect(2) will remove datagrams from the wrong source from the receive queue. All other systems will deliver datagrams already present in the receive queue, even if from the wrong source, despite the POSIX requirement that connect(2) "limits the remote sender for subsequent recv() functions". Software for affected systems must either first empty the receive queue after connect(2), or use recvmsg(2) and validate the source address rather than rely on the kernel validation.ERRORS
Socket operations can fail due to these error conditions, in addition to the error conditions of the network and link layer, and the error conditions of the invoked function.- [EACCES]
- A datagram was sent to a broadcast address, but SO_BROADCAST is turned off.
- [EADDRINUSE]
- The socket cannot be bound to the requested address and port because another socket was already bound to 1) the same address and port 2) the any address and the same port (and SO_REUSEADDR was not set on both sockets), or 3) some address and the same port but the requested address was the any address (and SO_REUSEADDR was not set on both sockets).
- [EADDRNOTAVAIL]
- The socket cannot be bound to the requested address because no network interface had that address or broadcast address.
- [EADDRNOTAVAIL]
- The socket was connected to port 0, or a datagram was sent to port 0.
- [EAGAIN]
- A port could not be assigned because each port in the dynamic port range had already been bound to a socket in a conflicting manner.
- [ECONNREFUSED]
- The destination host of a datagram was not listening on the port. This error can happen asynchronously.
- [EHOSTDOWN]
- The destination host of a datagram is not up. This error can happen asynchronously.
- [EHOSTUNREACH]
- The destination host of a datagram was unreachable. This error can happen asynchronously.
- [EISCONN]
- A destination address and port was specified when sending a datagram, but the socket has already been connected to a remote address and port.
- [EMSGSIZE]
- The datagram was too large to be sent because it exceeded the maximum transmission unit (MTU) on the path between the local and remote address, or it exceeded the UDP datagram size limit of 65527 bytes. This error can happen asynchronously.
- [ENETDOWN]
- The network interface used to deliver a datagram isn't up. This error can happen asynchronously.
- [ENETUNREACH]
- The destination network of a datagram was unreachable. This error can happen asynchronously.
- [ENETUNREACH]
- The remote address could not be connected because there was no route from the local address to the remote address.
- [ENOBUFS]
- There was not enough memory available for network packets.
- [EPERM]
- One of the unimplemented SO_DEBUG and SO_DONTROUTE socket options was attempted to be set to a non-zero value.