summaryrefslogtreecommitdiffstats
path: root/man/man2/sendmmsg.2
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-24 04:52:22 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-24 04:52:22 +0000
commit3d08cd331c1adcf0d917392f7e527b3f00511748 (patch)
tree312f0d1e1632f48862f044b8bb87e602dcffb5f9 /man/man2/sendmmsg.2
parentAdding debian version 6.7-2. (diff)
downloadmanpages-3d08cd331c1adcf0d917392f7e527b3f00511748.tar.xz
manpages-3d08cd331c1adcf0d917392f7e527b3f00511748.zip
Merging upstream version 6.8.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man/man2/sendmmsg.2')
-rw-r--r--man/man2/sendmmsg.2232
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)