+++ /dev/null
-.\" 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 (date) "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>
-.PP
-.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
-.PP
-The
-.I sockfd
-argument is the file descriptor of the socket
-on which data is to be transmitted.
-.PP
-The
-.I msgvec
-argument is a pointer to an array of
-.I mmsghdr
-structures.
-The size of this array is specified in
-.IR vlen .
-.PP
-The
-.I mmsghdr
-structure is defined in
-.I <sys/socket.h>
-as:
-.PP
-.in +4n
-.EX
-struct mmsghdr {
- struct msghdr msg_hdr; /* Message header */
- unsigned int msg_len; /* Number of bytes transmitted */
-};
-.EE
-.in
-.PP
-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).
-.PP
-The
-.I flags
-argument contains flags ORed together.
-The flags are the same as for
-.BR sendmsg (2).
-.PP
-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.
-.PP
-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.
-.PP
-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.
-.PP
-.\" 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)
projects / thirdparty / man-pages.git / blobdiff