Merging upstream version 6.8.

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

1 files changed, 0 insertions, 563 deletions

diff --git a/man2/recv.2 b/man2/recv.2
deleted file mode 100644
index 916cca3..0000000
--- a/man2/recv.2
+++ /dev/null
@@ -1,563 +0,0 @@
-.\" 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-02-18 "Linux man-pages 6.7"
-.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)