diff options
Diffstat (limited to 'man/man7/udp.7')
| -rw-r--r-- | man/man7/udp.7 | 312 |
1 files changed, 312 insertions, 0 deletions
diff --git a/man/man7/udp.7 b/man/man7/udp.7 new file mode 100644 index 000000000..5827102b4 --- /dev/null +++ b/man/man7/udp.7 @@ -0,0 +1,312 @@ +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>. +.\" +.\" $Id: udp.7,v 1.7 2000/01/22 01:55:05 freitag Exp $ +.\" +.TH udp 7 (date) "Linux man-pages (unreleased)" +.SH NAME +udp \- User Datagram Protocol for IPv4 +.SH SYNOPSIS +.nf +.B #include <sys/socket.h> +.B #include <netinet/in.h> +.B #include <netinet/udp.h> +.P +.IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);" +.fi +.SH DESCRIPTION +This is an implementation of the User Datagram Protocol +described in RFC\ 768. +It implements a connectionless, unreliable datagram packet service. +Packets may be reordered or duplicated before they arrive. +UDP generates and checks checksums to catch transmission errors. +.P +When a UDP socket is created, +its local and remote addresses are unspecified. +Datagrams can be sent immediately using +.BR sendto (2) +or +.BR sendmsg (2) +with a valid destination address as an argument. +When +.BR connect (2) +is called on the socket, the default destination address is set and +datagrams can now be sent using +.BR send (2) +or +.BR write (2) +without specifying a destination address. +It is still possible to send to other destinations by passing an +address to +.BR sendto (2) +or +.BR sendmsg (2). +In order to receive packets, the socket can be bound to a local +address first by using +.BR bind (2). +Otherwise, the socket layer will automatically assign +a free local port out of the range defined by +.I /proc/sys/net/ipv4/ip_local_port_range +and bind the socket to +.BR INADDR_ANY . +.P +All receive operations return only one packet. +When the packet is smaller than the passed buffer, only that much +data is returned; when it is bigger, the packet is truncated and the +.B MSG_TRUNC +flag is set. +.B MSG_WAITALL +is not supported. +.P +IP options may be sent or received using the socket options described in +.BR ip (7). +They are processed by the kernel only when the appropriate +.I /proc +parameter +is enabled (but still passed to the user even when it is turned off). +See +.BR ip (7). +.P +When the +.B MSG_DONTROUTE +flag is set on sending, the destination address must refer to a local +interface address and the packet is sent only to that interface. +.P +By default, Linux UDP does path MTU (Maximum Transmission Unit) discovery. +This means the kernel +will keep track of the MTU to a specific target IP address and return +.B EMSGSIZE +when a UDP packet write exceeds it. +When this happens, the application should decrease the packet size. +Path MTU discovery can be also turned off using the +.B IP_MTU_DISCOVER +socket option or the +.I /proc/sys/net/ipv4/ip_no_pmtu_disc +file; see +.BR ip (7) +for details. +When turned off, UDP will fragment outgoing UDP packets +that exceed the interface MTU. +However, disabling it is not recommended +for performance and reliability reasons. +.SS Address format +UDP uses the IPv4 +.I sockaddr_in +address format described in +.BR ip (7). +.SS Error handling +All fatal errors will be passed to the user as an error return even +when the socket is not connected. +This includes asynchronous errors +received from the network. +You may get an error for an earlier packet +that was sent on the same socket. +This behavior differs from many other BSD socket implementations +which don't pass any errors unless the socket is connected. +Linux's behavior is mandated by +.BR RFC\ 1122 . +.P +For compatibility with legacy code, in Linux 2.0 and 2.2 +it was possible to set the +.B SO_BSDCOMPAT +.B SOL_SOCKET +option to receive remote errors only when the socket has been +connected (except for +.B EPROTO +and +.BR EMSGSIZE ). +Locally generated errors are always passed. +Support for this socket option was removed in later kernels; see +.BR socket (7) +for further information. +.P +When the +.B IP_RECVERR +option is enabled, all errors are stored in the socket error queue, +and can be received by +.BR recvmsg (2) +with the +.B MSG_ERRQUEUE +flag set. +.SS /proc interfaces +System-wide UDP parameter settings can be accessed by files in the directory +.IR /proc/sys/net/ipv4/ . +.TP +.IR udp_mem " (since Linux 2.6.25)" +This is a vector of three integers governing the number +of pages allowed for queueing by all UDP sockets. +.RS +.TP +.I min +Below this number of pages, UDP is not bothered about its +memory appetite. +When the amount of memory allocated by UDP exceeds +this number, UDP starts to moderate memory usage. +.TP +.I pressure +This value was introduced to follow the format of +.I tcp_mem +(see +.BR tcp (7)). +.TP +.I max +Number of pages allowed for queueing by all UDP sockets. +.RE +.IP +Defaults values for these three items are +calculated at boot time from the amount of available memory. +.TP +.IR udp_rmem_min " (integer; default value: PAGE_SIZE; since Linux 2.6.25)" +Minimal size, in bytes, of receive buffers used by UDP sockets in moderation. +Each UDP socket is able to use the size for receiving data, +even if total pages of UDP sockets exceed +.I udp_mem +pressure. +.TP +.IR udp_wmem_min " (integer; default value: PAGE_SIZE; since Linux 2.6.25)" +Minimal size, in bytes, of send buffer used by UDP sockets in moderation. +Each UDP socket is able to use the size for sending data, +even if total pages of UDP sockets exceed +.I udp_mem +pressure. +.SS Socket options +To set or get a UDP socket option, call +.BR getsockopt (2) +to read or +.BR setsockopt (2) +to write the option with the option level argument set to +.BR IPPROTO_UDP . +Unless otherwise noted, +.I optval +is a pointer to an +.IR int . +.P +Following is a list of UDP-specific socket options. +For details of some other socket options that are also applicable +for UDP sockets, see +.BR socket (7). +.TP +.BR UDP_CORK " (since Linux 2.5.44)" +If this option is enabled, then all data output on this socket +is accumulated into a single datagram that is transmitted when +the option is disabled. +This option should not be used in code intended to be +portable. +.\" FIXME document UDP_ENCAP (new in Linux 2.5.67) +.\" From include/linux/udp.h: +.\" UDP_ENCAP_ESPINUDP_NON_IKE draft-ietf-ipsec-nat-t-ike-00/01 +.\" UDP_ENCAP_ESPINUDP draft-ietf-ipsec-udp-encaps-06 +.\" UDP_ENCAP_L2TPINUDP rfc2661 +.\" FIXME Document UDP_NO_CHECK6_TX and UDP_NO_CHECK6_RX, added in Linux 3.16 +.TP +.BR UDP_SEGMENT " (since Linux 4.18)" +Enables UDP segmentation offload. +Segmentation offload reduces +.BR send (2) +cost by transferring multiple datagrams worth of data +as a single large packet through the kernel transmit path, +even when that exceeds MTU. +As late as possible, +the large packet is split by segment size into a series of datagrams. +This segmentation offload step is deferred to hardware if supported, +else performed in software. +This option takes a value in the range +.RB [ 0 ,\~ USHRT_MAX ] +that sets the segment size: +the size of datagram payload, +excluding the UDP header. +The segment size must be chosen such that +at most 64 datagrams are sent in a single call +and that the datagrams after segmentation meet +the same MTU rules that apply to datagrams sent without this option. +Segmentation offload depends on checksum offload, +as datagram checksums are computed after segmentation. +The option may also be set for individual +.BR sendmsg (2) +calls by passing it as a +.BR cmsg (3). +A value of zero disables the feature. +This option should not be used in code intended to be portable. +.TP +.BR UDP_GRO " (since Linux 5.0)" +Enables UDP receive offload. +If enabled, +the socket may receive multiple datagrams worth of data +as a single large buffer, +together with a +.BR cmsg (3) +that holds the segment size. +This option is the inverse of segmentation offload. +It reduces receive cost by handling multiple datagrams worth of data +as a single large packet in the kernel receive path, +even when that exceeds MTU. +This option should not be used in code intended to be portable. +.SS Ioctls +These ioctls can be accessed using +.BR ioctl (2). +The correct syntax is: +.P +.RS +.nf +.BI int " value"; +.IB error " = ioctl(" udp_socket ", " ioctl_type ", &" value ");" +.fi +.RE +.TP +.BR FIONREAD " (" SIOCINQ ) +Gets a pointer to an integer as argument. +Returns the size of the next pending datagram in the integer in bytes, +or 0 when no datagram is pending. +.B Warning: +Using +.BR FIONREAD , +it is impossible to distinguish the case where no datagram is pending +from the case where the next pending datagram contains zero bytes of data. +It is safer to use +.BR select (2), +.BR poll (2), +or +.BR epoll (7) +to distinguish these cases. +.\" See http://www.securiteam.com/unixfocus/5KP0I15IKO.html +.\" "GNUnet DoS (UDP Socket Unreachable)", 14 May 2006 +.TP +.BR TIOCOUTQ " (" SIOCOUTQ ) +Returns the number of data bytes in the local send queue. +Supported only with Linux 2.4 and above. +.P +In addition, all ioctls documented in +.BR ip (7) +and +.BR socket (7) +are supported. +.SH ERRORS +All errors documented for +.BR socket (7) +or +.BR ip (7) +may be returned by a send or receive on a UDP socket. +.TP +.B ECONNREFUSED +No receiver was associated with the destination address. +This might be caused by a previous packet sent over the socket. +.SH VERSIONS +.B IP_RECVERR +is a new feature in Linux 2.2. +.\" .SH CREDITS +.\" This man page was written by Andi Kleen. +.SH SEE ALSO +.BR ip (7), +.BR raw (7), +.BR socket (7), +.BR udplite (7) +.P +The kernel source file +.IR Documentation/networking/ip\-sysctl.txt . +.P +RFC\ 768 for the User Datagram Protocol. +.br +RFC\ 1122 for the host requirements. +.br +RFC\ 1191 for a description of path MTU discovery. |