diff options
Diffstat (limited to 'man7/udp.7')
| -rw-r--r-- | man7/udp.7 | 312 |
1 files changed, 0 insertions, 312 deletions
diff --git a/man7/udp.7 b/man7/udp.7 deleted file mode 100644 index 6b643a2..0000000 --- a/man7/udp.7 +++ /dev/null @@ -1,312 +0,0 @@ -.\" 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 2023-10-31 "Linux man-pages 6.7" -.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. |