diff options
Diffstat (limited to 'man2/sendmmsg.2')
| -rw-r--r-- | man2/sendmmsg.2 | 232 |
1 files changed, 0 insertions, 232 deletions
diff --git a/man2/sendmmsg.2 b/man2/sendmmsg.2 deleted file mode 100644 index 64a4da0..0000000 --- a/man2/sendmmsg.2 +++ /dev/null @@ -1,232 +0,0 @@ -.\" 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 2023-10-31 "Linux man-pages 6.7" -.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) |