Draft manpage for recvmmsg

[Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org>]

Here's a draft manpage for recvmmsg(2), which is one 
of the last undocumented syscalls currently.
Please review and comment.

-Andi


.TH RECVMMSG 2 2010-11-23 "Linux" "Linux Programmer's Manual"
.SH NAME
recvmmsg \- receive multiple messages on a socket
.SH SYNOPSIS
.BI "#include <sys/socket.h>"
.br
.BI "int recvmmsg(int " fd ", struct mmsghdr *" mmsghdr \
", unsigned int " vlen ","
.br
.BI "             unsigned int " flags ", struct timespec *" timeout ");" 
.SH DESCRIPTION
The 
.B recvmmsg 
system call receives multiple messages in a socket.
It acts similar to 
.B recvmsg(2),
but allows to batch multiple receive operations into a single syscall.
In addition it support an explicit timeout. 

.B fd 
is the file descriptor of the socket to receive data from. 
.B mmsghdr
is a pointer to an array with length
.B vlen
of  
.I mmsghdr
structures. 
.I struct mmsg 
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 received bytes for header */
};
.fi
.in
.PP
.B msg_hdr 
is a struct
.I msghdr
as described in
.I recvmsg(2).
.B msg_len
is the number of bytes returned for the message in the entry.
This field has the same value as the return value of a single
.I recvmsg(2)
on the header.

.B flags
contains flags ored together. The flags are the same
as documented for
.I recvmsg(2).
The additional
.B MSG_WAITFORONE
turns one 
.I MSG_DONTWAIT
after the first message has been received.

.B timeout
points to a 
.I struct timespec
(see 
.I clock_gettime(2)
)
defining a timeout for receiving, or 
.I NULL 
for no timeout. When the timeout expires
.I recvmmsg
returns.
.SH RETURN VALUE
.I recvmmsg
returns the number of messages received in
.I mmsghdr
or 
-1
when an error occurs. The 
.I msg_len
members of 
.I mmsghdr
are updated for each received message,
in addition to other fields in the msg_hdr for each message,
as described in 
.I recvmsg(2).
.SH SEE ALSO
.B recvmsg(2),
.B sendmsg(2),
.B socket(7),
.B socket(2),
.B clock_gettime(2)
.SH VERSIONS
The
.I recvmmsg
syscall was added with kernel 2.6.32.
Support in glibc was added with 2.6.12.
On earlier glibcs the function can be called
manually using 
.I syscall(2).


-- 
ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org -- Speaking for myself only.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html