Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 312 insertions, 0 deletions

diff --git a/man/man7/udp.7 b/man/man7/udp.7
new file mode 100644
index 0000000..5c6a490
--- /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 2024-05-02 "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.