mirror of https://github.com/mkerrisk/man-pages
sendmmsg.2: New page for sendmmsg(2)
Some pieces inspired by an initial attempt by Stephan Mueller. Reported-by: Stephan Mueller <stephan.mueller@atsec.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
d5563c9427
commit
82c182484a
|
@ -0,0 +1,170 @@
|
|||
.\" Copyright (c) 2011 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.
|
||||
.\"
|
||||
.\" Permission is granted to make and distribute verbatim copies of this
|
||||
.\" manual provided the copyright notice and this permission notice are
|
||||
.\" preserved on all copies.
|
||||
.\"
|
||||
.\" Permission is granted to copy and distribute modified versions of this
|
||||
.\" manual under the conditions for verbatim copying, provided that the
|
||||
.\" entire resulting derived work is distributed under the terms of a
|
||||
.\" permission notice identical to this one.
|
||||
.\"
|
||||
.\" Since the Linux kernel and libraries are constantly changing, this
|
||||
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
||||
.\" responsibility for errors or omissions, or for damages resulting from
|
||||
.\" the use of the information contained herein. The author(s) may not
|
||||
.\" have taken the same level of care in the production of this manual,
|
||||
.\" which is licensed free of charge, as they might when working
|
||||
.\" professionally.
|
||||
.\"
|
||||
.\" Formatted or processed versions of this manual, if unaccompanied by
|
||||
.\" the source, must acknowledge the copyright and authors of this work.
|
||||
.\"
|
||||
.TH SENDMMSG 2 2011-09-09 "Linux" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
sendmmsg \- send multiple messages on a socket
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
.B "#define _GNU_SOURCE"
|
||||
.BI "#include <sys/socket.h>"
|
||||
|
||||
.BI "int sendmmsg(int " sockfd ", struct mmsghdr *" msgvec \
|
||||
", unsigned int " vlen ","
|
||||
.BI " unsigned 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
|
||||
|
||||
The
|
||||
.I sockfd
|
||||
argument is the file descriptor of the socket
|
||||
on which data is to be transmitted.
|
||||
|
||||
The
|
||||
.I msgvec
|
||||
argument is a pointer to an array of
|
||||
.I mmsghdr
|
||||
structures.
|
||||
The size of this array is specified in
|
||||
.IR vlen .
|
||||
|
||||
The
|
||||
.I mmsghdr
|
||||
structure is defined in
|
||||
.I <sys/socket.h>
|
||||
as:
|
||||
|
||||
.in +4n
|
||||
.nf
|
||||
struct mmsghdr {
|
||||
struct msghdr msg_hdr; /* Message header */
|
||||
unsigned int msg_len; /* Number of bytes transmitted */
|
||||
};
|
||||
.fi
|
||||
.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
|
||||
.IR msg_hdr
|
||||
(i.e., the same as the return value from a single
|
||||
.BR sendmsg (2)
|
||||
call).
|
||||
|
||||
The
|
||||
.I flags
|
||||
argument contains flags ORed together.
|
||||
The flags are the same as for
|
||||
.BR sendmsg (2).
|
||||
|
||||
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.
|
||||
|
||||
On return from
|
||||
.BR sendmmsg (),
|
||||
the
|
||||
.I msg_len
|
||||
fields of successive elements of
|
||||
.IR 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.
|
||||
|
||||
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.
|
||||
.\" 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 behaviour of other syscalls like read/write - it
|
||||
.\" is not an error if less than the requested number of elements are sent.
|
||||
.SH VERSIONS
|
||||
The
|
||||
.BR sendmmsg ()
|
||||
system call was added in Linux 3.0.
|
||||
Support in glibc was added in version 2.14.
|
||||
.SH CONFORMING TO
|
||||
.BR sendmmsg ()
|
||||
is Linux-specific.
|
||||
.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 SEE ALSO
|
||||
.BR recvmmsg (2),
|
||||
.BR sendmsg (2),
|
||||
.BR socket (2),
|
||||
.BR socket (7)
|
Loading…
Reference in New Issue