Merging upstream version 6.8.

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

1 files changed, 563 insertions, 0 deletions

diff --git a/man/man2/recv.2 b/man/man2/recv.2
new file mode 100644
index 0000000..dac38eb
--- /dev/null
+++ b/man/man2/recv.2
@@ -0,0 +1,563 @@
+.\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California.
+.\" All rights reserved.
+.\"
+.\" SPDX-License-Identifier: BSD-4-Clause-UC
+.\"
+.\"     $Id: recv.2,v 1.3 1999/05/13 11:33:38 freitag Exp $
+.\"
+.\" Modified Sat Jul 24 00:22:20 1993 by Rik Faith <faith@cs.unc.edu>
+.\" Modified Tue Oct 22 17:45:19 1996 by Eric S. Raymond <esr@thyrsus.com>
+.\" Modified 1998,1999 by Andi Kleen
+.\" 2001-06-19 corrected SO_EE_OFFENDER, bug report by James Hawtin
+.\"
+.TH recv 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+recv, recvfrom, recvmsg \- receive a message from a socket
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/socket.h>
+.P
+.BI "ssize_t recv(int " sockfd ", void " buf [. len "], size_t " len ,
+.BI "                 int " flags );
+.BI "ssize_t recvfrom(int " sockfd ", void " buf "[restrict ." len "], size_t " len ,
+.BI "                 int " flags ,
+.BI "                 struct sockaddr *_Nullable restrict " src_addr ,
+.BI "                 socklen_t *_Nullable restrict " addrlen );
+.BI "ssize_t recvmsg(int " sockfd ", struct msghdr *" msg ", int " flags );
+.fi
+.SH DESCRIPTION
+The
+.BR recv (),
+.BR recvfrom (),
+and
+.BR recvmsg ()
+calls are used to receive messages from a socket.
+They may be used
+to receive data on both connectionless and connection-oriented sockets.
+This page first describes common features of all three system calls,
+and then describes the differences between the calls.
+.P
+The only difference between
+.BR recv ()
+and
+.BR read (2)
+is the presence of
+.IR flags .
+With a zero
+.I flags
+argument,
+.BR recv ()
+is generally equivalent to
+.BR read (2)
+(but see NOTES).
+Also, the following call
+.P
+.in +4n
+.EX
+recv(sockfd, buf, len, flags);
+.EE
+.in
+.P
+is equivalent to
+.P
+.in +4n
+.EX
+recvfrom(sockfd, buf, len, flags, NULL, NULL);
+.EE
+.in
+.P
+All three calls return the length of the message on successful
+completion.
+If a message is too long to fit in the supplied buffer, excess
+bytes may be discarded depending on the type of socket the message is
+received from.
+.P
+If no messages are available at the socket, the receive calls wait for a
+message to arrive, unless the socket is nonblocking (see
+.BR fcntl (2)),
+in which case the value \-1 is returned and
+.I errno
+is set to
+.BR EAGAIN " or " EWOULDBLOCK .
+The receive calls normally return any data available, up to the requested
+amount, rather than waiting for receipt of the full amount requested.
+.P
+An application can use
+.BR select (2),
+.BR poll (2),
+or
+.BR epoll (7)
+to determine when more data arrives on a socket.
+.SS The flags argument
+The
+.I flags
+argument is formed by ORing one or more of the following values:
+.TP
+.BR MSG_CMSG_CLOEXEC " (" recvmsg "() only; since Linux 2.6.23)"
+Set the close-on-exec flag for the file descriptor received
+via a UNIX domain file descriptor using the
+.B SCM_RIGHTS
+operation (described in
+.BR unix (7)).
+This flag is useful for the same reasons as the
+.B O_CLOEXEC
+flag of
+.BR open (2).
+.TP
+.BR MSG_DONTWAIT " (since Linux 2.2)"
+Enables nonblocking operation; if the operation would block,
+the call fails with the error
+.BR EAGAIN " or " EWOULDBLOCK .
+This provides similar behavior to setting the
+.B O_NONBLOCK
+flag (via the
+.BR fcntl (2)
+.B F_SETFL
+operation), but differs in that
+.B MSG_DONTWAIT
+is a per-call option, whereas
+.B O_NONBLOCK
+is a setting on the open file description (see
+.BR open (2)),
+which will affect all threads in the calling process
+as well as other processes that hold file descriptors
+referring to the same open file description.
+.TP
+.BR MSG_ERRQUEUE " (since Linux 2.2)"
+This flag
+specifies that queued errors should be received from the socket error queue.
+The error is passed in
+an ancillary message with a type dependent on the protocol (for IPv4
+.BR IP_RECVERR ).
+The user should supply a buffer of sufficient size.
+See
+.BR cmsg (3)
+and
+.BR ip (7)
+for more information.
+The payload of the original packet that caused the error
+is passed as normal data via
+.IR msg_iovec .
+The original destination address of the datagram that caused the error
+is supplied via
+.IR msg_name .
+.IP
+The error is supplied in a
+.I sock_extended_err
+structure:
+.IP
+.in +4n
+.EX
+#define SO_EE_ORIGIN_NONE    0
+#define SO_EE_ORIGIN_LOCAL   1
+#define SO_EE_ORIGIN_ICMP    2
+#define SO_EE_ORIGIN_ICMP6   3
+\&
+struct sock_extended_err
+{
+    uint32_t ee_errno;   /* Error number */
+    uint8_t  ee_origin;  /* Where the error originated */
+    uint8_t  ee_type;    /* Type */
+    uint8_t  ee_code;    /* Code */
+    uint8_t  ee_pad;     /* Padding */
+    uint32_t ee_info;    /* Additional information */
+    uint32_t ee_data;    /* Other data */
+    /* More data may follow */
+};
+\&
+struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);
+.EE
+.in
+.IP
+.I ee_errno
+contains the
+.I errno
+number of the queued error.
+.I ee_origin
+is the origin code of where the error originated.
+The other fields are protocol-specific.
+The macro
+.B SO_EE_OFFENDER
+returns a pointer to the address of the network object
+where the error originated from given a pointer to the ancillary message.
+If this address is not known, the
+.I sa_family
+member of the
+.I sockaddr
+contains
+.B AF_UNSPEC
+and the other fields of the
+.I sockaddr
+are undefined.
+The payload of the packet that caused the error is passed as normal data.
+.IP
+For local errors, no address is passed (this
+can be checked with the
+.I cmsg_len
+member of the
+.IR cmsghdr ).
+For error receives,
+the
+.B MSG_ERRQUEUE
+flag is set in the
+.IR msghdr .
+After an error has been passed, the pending socket error
+is regenerated based on the next queued error and will be passed
+on the next socket operation.
+.TP
+.B MSG_OOB
+This flag requests receipt of out-of-band data that would not be received
+in the normal data stream.
+Some protocols place expedited data
+at the head of the normal data queue, and thus this flag cannot
+be used with such protocols.
+.TP
+.B MSG_PEEK
+This flag causes the receive operation to
+return data from the beginning of the
+receive queue without removing that data from the queue.
+Thus, a
+subsequent receive call will return the same data.
+.TP
+.BR MSG_TRUNC " (since Linux 2.2)"
+For raw
+.RB ( AF_PACKET ),
+Internet datagram (since Linux 2.4.27/2.6.8),
+netlink (since Linux 2.6.22),
+and UNIX datagram as well as sequenced-packet
+.\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f
+(since Linux 3.4) sockets:
+return the real length of the packet or datagram,
+even when it was longer than the passed buffer.
+.IP
+For use with Internet stream sockets, see
+.BR tcp (7).
+.TP
+.BR MSG_WAITALL " (since Linux 2.2)"
+This flag requests that the operation block until the full request is
+satisfied.
+However, the call may still return less data than requested if
+a signal is caught, an error or disconnect occurs, or the next data to be
+received is of a different type than that returned.
+This flag has no effect for datagram sockets.
+.\"
+.SS recvfrom()
+.BR recvfrom ()
+places the received message into the buffer
+.IR buf .
+The caller must specify the size of the buffer in
+.IR len .
+.P
+If
+.I src_addr
+is not NULL,
+and the underlying protocol provides the source address of the message,
+that source address is placed in the buffer pointed to by
+.IR src_addr .
+.\" (Note: for datagram sockets in both the UNIX and Internet domains,
+.\" .I src_addr
+.\" is filled in.
+.\" .I src_addr
+.\" is also filled in for stream sockets in the UNIX domain, but is not
+.\" filled in for stream sockets in the Internet domain.)
+.\" [The above notes on AF_UNIX and AF_INET sockets apply as at
+.\" Kernel 2.4.18. (MTK, 22 Jul 02)]
+In this case,
+.I addrlen
+is a value-result argument.
+Before the call,
+it should be initialized to the size of the buffer associated with
+.IR src_addr .
+Upon return,
+.I addrlen
+is updated to contain the actual size of the source address.
+The returned address is truncated if the buffer provided is too small;
+in this case,
+.I addrlen
+will return a value greater than was supplied to the call.
+.P
+If the caller is not interested in the source address,
+.I src_addr
+and
+.I addrlen
+should be specified as NULL.
+.\"
+.SS recv()
+The
+.BR recv ()
+call is normally used only on a
+.I connected
+socket (see
+.BR connect (2)).
+It is equivalent to the call:
+.P
+.in +4n
+.EX
+recvfrom(fd, buf, len, flags, NULL, 0);
+.EE
+.in
+.\"
+.SS recvmsg()
+The
+.BR recvmsg ()
+call uses a
+.I msghdr
+structure to minimize the number of directly supplied arguments.
+This structure is defined as follows in
+.IR <sys/socket.h> :
+.P
+.in +4n
+.EX
+struct msghdr {
+    void         *msg_name;       /* Optional address */
+    socklen_t     msg_namelen;    /* Size of address */
+    struct iovec *msg_iov;        /* Scatter/gather array */
+    size_t        msg_iovlen;     /* # elements in msg_iov */
+    void         *msg_control;    /* Ancillary data, see below */
+    size_t        msg_controllen; /* Ancillary data buffer len */
+    int           msg_flags;      /* Flags on received message */
+};
+.EE
+.in
+.P
+The
+.I msg_name
+field points to a caller-allocated buffer that is used to
+return the source address if the socket is unconnected.
+The caller should set
+.I msg_namelen
+to the size of this buffer before this call;
+upon return from a successful call,
+.I msg_namelen
+will contain the length of the returned address.
+If the application does not need to know the source address,
+.I msg_name
+can be specified as NULL.
+.P
+The fields
+.I msg_iov
+and
+.I msg_iovlen
+describe scatter-gather locations, as discussed in
+.BR readv (2).
+.P
+The field
+.IR msg_control ,
+which has length
+.IR msg_controllen ,
+points to a buffer for other protocol control-related messages or
+miscellaneous ancillary data.
+When
+.BR recvmsg ()
+is called,
+.I msg_controllen
+should contain the length of the available buffer in
+.IR msg_control ;
+upon return from a successful call it will contain the length
+of the control message sequence.
+.P
+The messages are of the form:
+.P
+.in +4n
+.EX
+struct cmsghdr {
+    size_t cmsg_len;    /* Data byte count, including header
+                           (type is socklen_t in POSIX) */
+    int    cmsg_level;  /* Originating protocol */
+    int    cmsg_type;   /* Protocol\-specific type */
+/* followed by
+    unsigned char cmsg_data[]; */
+};
+.EE
+.in
+.P
+Ancillary data should be accessed only by the macros defined in
+.BR cmsg (3).
+.P
+As an example, Linux uses this ancillary data mechanism to pass extended
+errors, IP options, or file descriptors over UNIX domain sockets.
+For further information on the use of ancillary data in various
+socket domains, see
+.BR unix (7)
+and
+.BR ip (7).
+.P
+The
+.I msg_flags
+field in the
+.I msghdr
+is set on return of
+.BR recvmsg ().
+It can contain several flags:
+.TP
+.B MSG_EOR
+indicates end-of-record; the data returned completed a record (generally
+used with sockets of type
+.BR SOCK_SEQPACKET ).
+.TP
+.B MSG_TRUNC
+indicates that the trailing portion of a datagram was discarded because the
+datagram was larger than the buffer supplied.
+.TP
+.B MSG_CTRUNC
+indicates that some control data was discarded due to lack of space in the
+buffer for ancillary data.
+.TP
+.B MSG_OOB
+is returned to indicate that expedited or out-of-band data was received.
+.TP
+.B MSG_ERRQUEUE
+indicates that no data was received but an extended error from the socket
+error queue.
+.TP
+.BR MSG_CMSG_CLOEXEC " (since Linux 2.6.23)"
+.\" commit 4a19542e5f694cd408a32c3d9dc593ba9366e2d7
+indicates that
+.B MSG_CMSG_CLOEXEC
+was specified in the
+.I flags
+argument of
+.BR recvmsg ().
+.SH RETURN VALUE
+These calls return the number of bytes received, or \-1
+if an error occurred.
+In the event of an error,
+.I errno
+is set to indicate the error.
+.P
+When a stream socket peer has performed an orderly shutdown,
+the return value will be 0 (the traditional "end-of-file" return).
+.P
+Datagram sockets in various domains (e.g., the UNIX and Internet domains)
+permit zero-length datagrams.
+When such a datagram is received, the return value is 0.
+.P
+The value 0 may also be returned if the requested number of bytes
+to receive from a stream socket was 0.
+.SH ERRORS
+These are some standard errors generated by the socket layer.
+Additional errors
+may be generated and returned from the underlying protocol modules;
+see their manual pages.
+.TP
+.BR EAGAIN " or " EWOULDBLOCK
+.\" Actually EAGAIN on Linux
+The socket is marked nonblocking and the receive operation
+would block, or a receive timeout had been set and the timeout expired
+before data was received.
+POSIX.1 allows either error to be returned for this case,
+and does not require these constants to have the same value,
+so a portable application should check for both possibilities.
+.TP
+.B EBADF
+The argument
+.I sockfd
+is an invalid file descriptor.
+.TP
+.B ECONNREFUSED
+A remote host refused to allow the network connection (typically
+because it is not running the requested service).
+.TP
+.B EFAULT
+The receive buffer pointer(s) point outside the process's
+address space.
+.TP
+.B EINTR
+The receive was interrupted by delivery of a signal before
+any data was available; see
+.BR signal (7).
+.TP
+.B EINVAL
+Invalid argument passed.
+.\" e.g., msg_namelen < 0 for recvmsg() or addrlen < 0 for recvfrom()
+.TP
+.B ENOMEM
+Could not allocate memory for
+.BR recvmsg ().
+.TP
+.B ENOTCONN
+The socket is associated with a connection-oriented protocol
+and has not been connected (see
+.BR connect (2)
+and
+.BR accept (2)).
+.TP
+.B ENOTSOCK
+The file descriptor
+.I sockfd
+does not refer to a socket.
+.SH VERSIONS
+According to POSIX.1,
+.\" POSIX.1-2001, POSIX.1-2008
+the
+.I msg_controllen
+field of the
+.I msghdr
+structure should be typed as
+.IR socklen_t ,
+and the
+.I msg_iovlen
+field should be typed as
+.IR int ,
+but glibc currently types both as
+.IR size_t .
+.\" glibc bug for msg_controllen raised 12 Mar 2006
+.\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448
+.\" The problem is an underlying kernel issue: the size of the
+.\" __kernel_size_t type used to type these fields varies
+.\" across architectures, but socklen_t is always 32 bits,
+.\" as (at least with GCC) is int.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001,
+4.4BSD (first appeared in 4.2BSD).
+.P
+POSIX.1 describes only the
+.BR MSG_OOB ,
+.BR MSG_PEEK ,
+and
+.B MSG_WAITALL
+flags.
+.SH NOTES
+If a zero-length datagram is pending,
+.BR read (2)
+and
+.BR recv ()
+with a
+.I flags
+argument of zero provide different behavior.
+In this circumstance,
+.BR read (2)
+has no effect (the datagram remains pending), while
+.BR recv ()
+consumes the pending datagram.
+.P
+See
+.BR recvmmsg (2)
+for information about a Linux-specific system call
+that can be used to receive multiple datagrams in a single call.
+.SH EXAMPLES
+An example of the use of
+.BR recvfrom ()
+is shown in
+.BR getaddrinfo (3).
+.SH SEE ALSO
+.BR fcntl (2),
+.BR getsockopt (2),
+.BR read (2),
+.BR recvmmsg (2),
+.BR select (2),
+.BR shutdown (2),
+.BR socket (2),
+.BR cmsg (3),
+.BR sockatmark (3),
+.BR ip (7),
+.BR ipv6 (7),
+.BR socket (7),
+.BR tcp (7),
+.BR udp (7),
+.BR unix (7)