diff options
Diffstat (limited to 'man/man2/sendmmsg.2')
| -rw-r--r-- | man/man2/sendmmsg.2 | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/man/man2/sendmmsg.2 b/man/man2/sendmmsg.2 new file mode 100644 index 000000000..bc541aae5 --- /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 (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> +.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) |