recvmmsg.2: Various improvements and formatting fixes

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/recvmmsg.2

@@ -1,34 +1,47 @@
-.TH RECVMMSG 2 2010-11-23 "Linux" "Linux Programmer's Manual"
+.\" and Copyright (c) 2011 by Michael Kerrisk <mtk.manpages@gmail.com>
+.TH RECVMMSG 2 2011-09-09 "Linux" "Linux Programmer's Manual"
 .SH NAME
 recvmmsg \- receive multiple messages on a socket
 .SH SYNOPSIS
+.nf
+.B "#define _GNU_SOURCE"
 .BI "#include <sys/socket.h>"
-.br
-.BI "int recvmmsg(int " fd ", struct mmsghdr *" mmsghdr \
+
+.BI "int recvmmsg(int " sockfd ", struct mmsghdr *" msgvec \
 ", unsigned int " vlen ","
 .br
 .BI "             unsigned int " flags ", struct timespec *" timeout ");" 
+.fi
 .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. 
+.BR recvmmsg ()
+system call is an extension of
+.BR recvmsg (2)
+that allows the caller to receive multiple messages from a socket
+using a single system call.
+(This has performance benefits for some applications.)
+A further extension over
+.BR recvmsg (2)
+is support for a timeout on the receive operation.
 
-.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  
+The
+.I sockfd 
+argument is the file descriptor of the socket to receive data from.
+
+The
+.I msgvec
+argument is a pointer to an array of
 .I mmsghdr
-structures. 
-.I struct mmsg 
-is defined in
-.I sys/socket.h
+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 {
@@ -38,63 +51,96 @@ struct mmsghdr {
 .fi
 .in
 .PP
-.B msg_hdr 
-is a struct
+The
+.I msg_hdr 
+field is a
 .I msghdr
-as described in
-.I recvmsg(2).
-.B msg_len
-is the number of bytes returned for the message in the entry.
+structure, as described in
+.BR recvmsg (2).
+The
+.I msg_len
+field 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)
+.BR recvmsg (2)
 on the header.
 
-.B flags
-contains flags ored together. The flags are the same
-as documented for
-.I recvmsg(2).
-The additional
+The
+.I flags
+argument contains flags ORed together.
+The flags are the same as documented for
+.BR recvmsg (2),
+with the following addition:
+.TP
 .B MSG_WAITFORONE
-turns one 
-.I MSG_DONTWAIT
+Turns on
+.B MSG_DONTWAIT
 after the first message has been received.
-
-.B timeout
-points to a 
+.PP
+The
+.I timeout
+argument points to a 
 .I struct timespec
 (see 
-.I clock_gettime(2)
-)
-defining a timeout for receiving, or 
+.BR clock_gettime (2))
+defining a timeout (seconds plus nanoseconds) for the receive operation.
+If
+.I timeout
+is
 .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 
+then the operation blocks indefinitely.
+
+A blocking
+.BR recvmmsg ()
+call blocks until
+.I vlen
+messages have been received
+or until the timeout expires.
+A nonblocking call reads as many messages as are available
+(up to the limit specified by
+.IR vlen )
+and returns immediately.
+
+On return from
+.BR recvmmsg (),
+successive elements of
+.IR msgvec
+are updated to contain information about each received message:
 .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)
+contains the size of the received message;
+the subfields of
+.I msg_hdr
+are updated as described in 
+.BR recvmsg (2).
+The return value of the call indicates the number of elements of
+.I msgvec
+that have been updated.
+.SH RETURN VALUE
+On success,
+.BR recvmmsg ()
+returns the number of messages received in
+.IR msgvec ;
+on error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+Errors are as for
+.BR recvmsg (2).
+In addition, the following error can occur:
+.TP
+.B EINVAL
+.I timeout
+is invalid.
 .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).
+.BR recvmmsg ()
+system call was added in Linux 2.6.32.
+Support in glibc was added in version 2.12.
+.SH CONFORMING TO
+.BR recvmmsg ()
+is Linux-specific.
+.SH SEE ALSO
+.BR clock_gettime (2),
+.BR recvmsg (2),
+.BR sendmsg (2),
+.BR socket (2),
+.BR socket (7)