Adding upstream version 6.8.upstream/6.8upstream

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

1 files changed, 232 insertions, 0 deletions

diff --git a/man/man2/sendmmsg.2 b/man/man2/sendmmsg.2
new file mode 100644
index 0000000..5e06151
--- /dev/null
+++ b/man/man2/sendmmsg.2
@@ -0,0 +1,232 @@
+.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\" with some material from a draft by
+.\" Stephan Mueller <stephan.mueller@atsec.com>
+.\" in turn based on Andi Kleen's recvmmsg.2 page.
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH sendmmsg 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+sendmmsg \- send multiple messages on a socket
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
+.B #include <sys/socket.h>
+.P
+.BI "int sendmmsg(int " sockfd ", struct mmsghdr *" msgvec \
+", unsigned int " vlen ","
+.BI "             int " flags ");"
+.fi
+.SH DESCRIPTION
+The
+.BR sendmmsg ()
+system call is an extension of
+.BR sendmsg (2)
+that allows the caller to transmit multiple messages on a socket
+using a single system call.
+(This has performance benefits for some applications.)
+.\" See commit 228e548e602061b08ee8e8966f567c12aa079682
+.P
+The
+.I sockfd
+argument is the file descriptor of the socket
+on which data is to be transmitted.
+.P
+The
+.I msgvec
+argument is a pointer to an array of
+.I mmsghdr
+structures.
+The size of this array is specified in
+.IR vlen .
+.P
+The
+.I mmsghdr
+structure is defined in
+.I <sys/socket.h>
+as:
+.P
+.in +4n
+.EX
+struct mmsghdr {
+    struct msghdr msg_hdr;  /* Message header */
+    unsigned int  msg_len;  /* Number of bytes transmitted */
+};
+.EE
+.in
+.P
+The
+.I msg_hdr
+field is a
+.I msghdr
+structure, as described in
+.BR sendmsg (2).
+The
+.I msg_len
+field is used to return the number of bytes sent from the message in
+.I msg_hdr
+(i.e., the same as the return value from a single
+.BR sendmsg (2)
+call).
+.P
+The
+.I flags
+argument contains flags ORed together.
+The flags are the same as for
+.BR sendmsg (2).
+.P
+A blocking
+.BR sendmmsg ()
+call blocks until
+.I vlen
+messages have been sent.
+A nonblocking call sends as many messages as possible
+(up to the limit specified by
+.IR vlen )
+and returns immediately.
+.P
+On return from
+.BR sendmmsg (),
+the
+.I msg_len
+fields of successive elements of
+.I msgvec
+are updated to contain the number of bytes transmitted from the corresponding
+.IR msg_hdr .
+The return value of the call indicates the number of elements of
+.I msgvec
+that have been updated.
+.SH RETURN VALUE
+On success,
+.BR sendmmsg ()
+returns the number of messages sent from
+.IR msgvec ;
+if this is less than
+.IR vlen ,
+the caller can retry with a further
+.BR sendmmsg ()
+call to send the remaining messages.
+.P
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+Errors are as for
+.BR sendmsg (2).
+An error is returned only if no datagrams could be sent.
+See also BUGS.
+.\" commit 728ffb86f10873aaf4abd26dde691ee40ae731fe
+.\"     ... only return an error if no datagrams could be sent.
+.\"     If less than the requested number of messages were sent, the application
+.\"     must retry starting at the first failed one and if the problem is
+.\"     persistent the error will be returned.
+.\"
+.\"     This matches the behavior of other syscalls like read/write - it
+.\"     is not an error if less than the requested number of elements are sent.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 3.0,
+glibc 2.14.
+.SH NOTES
+The value specified in
+.I vlen
+is capped to
+.B UIO_MAXIOV
+(1024).
+.\" commit 98382f419f32d2c12d021943b87dea555677144b
+.\"     net: Cap number of elements for sendmmsg
+.\"
+.\"     To limit the amount of time we can spend in sendmmsg, cap the
+.\"     number of elements to UIO_MAXIOV (currently 1024).
+.\"
+.\"     For error handling an application using sendmmsg needs to retry at
+.\"     the first unsent message, so capping is simpler and requires less
+.\"     application logic than returning EINVAL.
+.SH BUGS
+If an error occurs after at least one message has been sent,
+the call succeeds, and returns the number of messages sent.
+The error code is lost.
+The caller can retry the transmission,
+starting at the first failed message, but there is no guarantee that,
+if an error is returned, it will be the same as the one that was lost
+on the previous call.
+.SH EXAMPLES
+The example below uses
+.BR sendmmsg ()
+to send
+.I onetwo
+and
+.I three
+in two distinct UDP datagrams using one system call.
+The contents of the first datagram originates from a pair of buffers.
+.P
+.\" SRC BEGIN (sendmmsg.c)
+.EX
+#define _GNU_SOURCE
+#include <arpa/inet.h>
+#include <netinet/in.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/socket.h>
+#include <sys/types.h>
+\&
+int
+main(void)
+{
+    int                 retval;
+    int                 sockfd;
+    struct iovec        msg1[2], msg2;
+    struct mmsghdr      msg[2];
+    struct sockaddr_in  addr;
+\&
+    sockfd = socket(AF_INET, SOCK_DGRAM, 0);
+    if (sockfd == \-1) {
+        perror("socket()");
+        exit(EXIT_FAILURE);
+    }
+\&
+    addr.sin_family = AF_INET;
+    addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+    addr.sin_port = htons(1234);
+    if (connect(sockfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) {
+        perror("connect()");
+        exit(EXIT_FAILURE);
+    }
+\&
+    memset(msg1, 0, sizeof(msg1));
+    msg1[0].iov_base = "one";
+    msg1[0].iov_len = 3;
+    msg1[1].iov_base = "two";
+    msg1[1].iov_len = 3;
+\&
+    memset(&msg2, 0, sizeof(msg2));
+    msg2.iov_base = "three";
+    msg2.iov_len = 5;
+\&
+    memset(msg, 0, sizeof(msg));
+    msg[0].msg_hdr.msg_iov = msg1;
+    msg[0].msg_hdr.msg_iovlen = 2;
+\&
+    msg[1].msg_hdr.msg_iov = &msg2;
+    msg[1].msg_hdr.msg_iovlen = 1;
+\&
+    retval = sendmmsg(sockfd, msg, 2, 0);
+    if (retval == \-1)
+        perror("sendmmsg()");
+    else
+        printf("%d messages sent\en", retval);
+\&
+    exit(0);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR recvmmsg (2),
+.BR sendmsg (2),
+.BR socket (2),
+.BR socket (7)