Merging upstream version 6.8.

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

1 files changed, 506 insertions, 0 deletions

diff --git a/man/man2/send.2 b/man/man2/send.2
new file mode 100644
index 0000000..99c4a2d
--- /dev/null
+++ b/man/man2/send.2
@@ -0,0 +1,506 @@
+.\" Copyright (c) 1983, 1991 The Regents of the University of California.
+.\" All rights reserved.
+.\"
+.\" SPDX-License-Identifier: BSD-4-Clause-UC
+.\"
+.\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
+.\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
+.\" Modified Oct 1998 by Andi Kleen
+.\" Modified Oct 2003 by aeb
+.\" Modified 2004-07-01 by mtk
+.\"
+.TH send 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+send, sendto, sendmsg \- send a message on a socket
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/socket.h>
+.P
+.BI "ssize_t send(int " sockfd ", const void " buf [. len "], size_t " len \
+", int " flags );
+.BI "ssize_t sendto(int " sockfd ", const void " buf [. len "], size_t " len \
+", int " flags ,
+.BI "               const struct sockaddr *" dest_addr ", socklen_t " addrlen );
+.BI "ssize_t sendmsg(int " sockfd ", const struct msghdr *" msg \
+", int " flags );
+.fi
+.SH DESCRIPTION
+The system calls
+.BR send (),
+.BR sendto (),
+and
+.BR sendmsg ()
+are used to transmit a message to another socket.
+.P
+The
+.BR send ()
+call may be used only when the socket is in a
+.I connected
+state (so that the intended recipient is known).
+The only difference between
+.BR send ()
+and
+.BR write (2)
+is the presence of
+.IR flags .
+With a zero
+.I flags
+argument,
+.BR send ()
+is equivalent to
+.BR write (2).
+Also, the following call
+.P
+.in +4n
+.EX
+send(sockfd, buf, len, flags);
+.EE
+.in
+.P
+is equivalent to
+.P
+.in +4n
+.EX
+sendto(sockfd, buf, len, flags, NULL, 0);
+.EE
+.in
+.P
+The argument
+.I sockfd
+is the file descriptor of the sending socket.
+.P
+If
+.BR sendto ()
+is used on a connection-mode
+.RB ( SOCK_STREAM ,
+.BR SOCK_SEQPACKET )
+socket, the arguments
+.I dest_addr
+and
+.I addrlen
+are ignored (and the error
+.B EISCONN
+may be returned when they are
+not NULL and 0), and the error
+.B ENOTCONN
+is returned when the socket was not actually connected.
+Otherwise, the address of the target is given by
+.I dest_addr
+with
+.I addrlen
+specifying its size.
+For
+.BR sendmsg (),
+the address of the target is given by
+.IR msg.msg_name ,
+with
+.I msg.msg_namelen
+specifying its size.
+.P
+For
+.BR send ()
+and
+.BR sendto (),
+the message is found in
+.I buf
+and has length
+.IR len .
+For
+.BR sendmsg (),
+the message is pointed to by the elements of the array
+.IR msg.msg_iov .
+The
+.BR sendmsg ()
+call also allows sending ancillary data (also known as control information).
+.P
+If the message is too long to pass atomically through the
+underlying protocol, the error
+.B EMSGSIZE
+is returned, and the message is not transmitted.
+.P
+No indication of failure to deliver is implicit in a
+.BR send ().
+Locally detected errors are indicated by a return value of \-1.
+.P
+When the message does not fit into the send buffer of the socket,
+.BR send ()
+normally blocks, unless the socket has been placed in nonblocking I/O
+mode.
+In nonblocking mode it would fail with the error
+.B EAGAIN
+or
+.B EWOULDBLOCK
+in this case.
+The
+.BR select (2)
+call may be used to determine when it is possible to send more data.
+.SS The flags argument
+The
+.I flags
+argument is the bitwise OR
+of zero or more of the following flags.
+.\" FIXME . ? document MSG_PROXY (which went away in Linux 2.3.15)
+.TP
+.BR MSG_CONFIRM " (since Linux 2.3.15)"
+Tell the link layer that forward progress happened: you got a successful
+reply from the other side.
+If the link layer doesn't get this
+it will regularly reprobe the neighbor (e.g., via a unicast ARP).
+Valid only on
+.B SOCK_DGRAM
+and
+.B SOCK_RAW
+sockets and currently implemented only for IPv4 and IPv6.
+See
+.BR arp (7)
+for details.
+.TP
+.B MSG_DONTROUTE
+Don't use a gateway to send out the packet, send to hosts only on
+directly connected networks.
+This is usually used only
+by diagnostic or routing programs.
+This is defined only for protocol
+families that route; packet sockets don't.
+.TP
+.BR MSG_DONTWAIT " (since Linux 2.2)"
+Enables nonblocking operation; if the operation would block,
+.B EAGAIN
+or
+.B EWOULDBLOCK
+is returned.
+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_EOR " (since Linux 2.2)"
+Terminates a record (when this notion is supported, as for sockets of type
+.BR SOCK_SEQPACKET ).
+.TP
+.BR MSG_MORE " (since Linux 2.4.4)"
+The caller has more data to send.
+This flag is used with TCP sockets to obtain the same effect
+as the
+.B TCP_CORK
+socket option (see
+.BR tcp (7)),
+with the difference that this flag can be set on a per-call basis.
+.IP
+Since Linux 2.6, this flag is also supported for UDP sockets, and informs
+the kernel to package all of the data sent in calls with this flag set
+into a single datagram which is transmitted only when a call is performed
+that does not specify this flag.
+(See also the
+.B UDP_CORK
+socket option described in
+.BR udp (7).)
+.TP
+.BR MSG_NOSIGNAL " (since Linux 2.2)"
+Don't generate a
+.B SIGPIPE
+signal if the peer on a stream-oriented socket has closed the connection.
+The
+.B EPIPE
+error is still returned.
+This provides similar behavior to using
+.BR sigaction (2)
+to ignore
+.BR SIGPIPE ,
+but, whereas
+.B MSG_NOSIGNAL
+is a per-call feature,
+ignoring
+.B SIGPIPE
+sets a process attribute that affects all threads in the process.
+.TP
+.B MSG_OOB
+Sends
+.I out-of-band
+data on sockets that support this notion (e.g., of type
+.BR SOCK_STREAM );
+the underlying protocol must also support
+.I out-of-band
+data.
+.TP
+.BR MSG_FASTOPEN " (since Linux 3.7)"
+Attempts TCP Fast Open (RFC7413) and sends data in the SYN like a
+combination of
+.BR connect (2)
+and
+.BR write (2),
+by performing an implicit
+.BR connect (2)
+operation.
+It blocks until the data is buffered and the handshake has completed.
+For a non-blocking socket,
+it returns the number of bytes buffered and sent in the SYN packet.
+If the cookie is not available locally,
+it returns
+.BR EINPROGRESS ,
+and sends a SYN with a Fast Open cookie request automatically.
+The caller needs to write the data again when the socket is connected.
+On errors,
+it sets the same
+.I errno
+as
+.BR connect (2)
+if the handshake fails.
+This flag requires enabling TCP Fast Open client support on sysctl
+.IR net.ipv4.tcp_fastopen .
+.IP
+Refer to
+.B TCP_FASTOPEN_CONNECT
+socket option in
+.BR tcp (7)
+for an alternative approach.
+.SS sendmsg()
+The definition of the
+.I msghdr
+structure employed by
+.BR sendmsg ()
+is as follows:
+.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 (unused) */
+};
+.EE
+.in
+.P
+The
+.I msg_name
+field is used on an unconnected socket to specify the target
+address for a datagram.
+It points to a buffer containing the address; the
+.I msg_namelen
+field should be set to the size of the address.
+For a connected socket, these fields should be specified as NULL and 0,
+respectively.
+.P
+The
+.I msg_iov
+and
+.I msg_iovlen
+fields specify scatter-gather locations, as for
+.BR writev (2).
+.P
+You may send control information (ancillary data) using the
+.I msg_control
+and
+.I msg_controllen
+members.
+The maximum control buffer length the kernel can process is limited
+per socket by the value in
+.IR /proc/sys/net/core/optmem_max ;
+see
+.BR socket (7).
+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 is ignored.
+.\" Still to be documented:
+.\"  Send file descriptors and user credentials using the
+.\"  msg_control* fields.
+.SH RETURN VALUE
+On success, these calls return the number of bytes sent.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.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 respective manual pages.
+.TP
+.B EACCES
+(For UNIX domain sockets, which are identified by pathname)
+Write permission is denied on the destination socket file,
+or search permission is denied for one of the directories
+the path prefix.
+(See
+.BR path_resolution (7).)
+.IP
+(For UDP sockets) An attempt was made to send to a
+network/broadcast address as though it was a unicast address.
+.TP
+.BR EAGAIN " or " EWOULDBLOCK
+.\" Actually EAGAIN on Linux
+The socket is marked nonblocking and the requested operation
+would block.
+POSIX.1-2001 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 EAGAIN
+(Internet domain datagram sockets)
+The socket referred to by
+.I sockfd
+had not previously been bound to an address and,
+upon attempting to bind it to an ephemeral port,
+it was determined that all port numbers in the ephemeral port range
+are currently in use.
+See the discussion of
+.I /proc/sys/net/ipv4/ip_local_port_range
+in
+.BR ip (7).
+.TP
+.B EALREADY
+Another Fast Open is in progress.
+.TP
+.B EBADF
+.I sockfd
+is not a valid open file descriptor.
+.TP
+.B ECONNRESET
+Connection reset by peer.
+.TP
+.B EDESTADDRREQ
+The socket is not connection-mode, and no peer address is set.
+.TP
+.B EFAULT
+An invalid user space address was specified for an argument.
+.TP
+.B EINTR
+A signal occurred before any data was transmitted; see
+.BR signal (7).
+.TP
+.B EINVAL
+Invalid argument passed.
+.TP
+.B EISCONN
+The connection-mode socket was connected already but a
+recipient was specified.
+(Now either this error is returned, or the recipient specification
+is ignored.)
+.TP
+.B EMSGSIZE
+The socket type
+.\" (e.g., SOCK_DGRAM )
+requires that message be sent atomically, and the size
+of the message to be sent made this impossible.
+.TP
+.B ENOBUFS
+The output queue for a network interface was full.
+This generally indicates that the interface has stopped sending,
+but may be caused by transient congestion.
+(Normally, this does not occur in Linux.
+Packets are just silently dropped
+when a device queue overflows.)
+.TP
+.B ENOMEM
+No memory available.
+.TP
+.B ENOTCONN
+The socket is not connected, and no target has been given.
+.TP
+.B ENOTSOCK
+The file descriptor
+.I sockfd
+does not refer to a socket.
+.TP
+.B EOPNOTSUPP
+Some bit in the
+.I flags
+argument is inappropriate for the socket type.
+.TP
+.B EPIPE
+The local end has been shut down on a connection oriented socket.
+In this case, the process
+will also receive a
+.B SIGPIPE
+unless
+.B MSG_NOSIGNAL
+is set.
+.SH VERSIONS
+According to POSIX.1-2001, 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.
+.P
+.B MSG_CONFIRM
+is a Linux extension.
+.SH HISTORY
+4.4BSD, SVr4, POSIX.1-2001.
+(first appeared in 4.2BSD).
+.P
+POSIX.1-2001 describes only the
+.B MSG_OOB
+and
+.B MSG_EOR
+flags.
+POSIX.1-2008 adds a specification of
+.BR MSG_NOSIGNAL .
+.SH NOTES
+See
+.BR sendmmsg (2)
+for information about a Linux-specific system call
+that can be used to transmit multiple datagrams in a single call.
+.SH BUGS
+Linux may return
+.B EPIPE
+instead of
+.BR ENOTCONN .
+.SH EXAMPLES
+An example of the use of
+.BR sendto ()
+is shown in
+.BR getaddrinfo (3).
+.SH SEE ALSO
+.BR fcntl (2),
+.BR getsockopt (2),
+.BR recv (2),
+.BR select (2),
+.BR sendfile (2),
+.BR sendmmsg (2),
+.BR shutdown (2),
+.BR socket (2),
+.BR write (2),
+.BR cmsg (3),
+.BR ip (7),
+.BR ipv6 (7),
+.BR socket (7),
+.BR tcp (7),
+.BR udp (7),
+.BR unix (7)