recvmmsg.2: New man page for recvmmsg(2)

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

man2/recvmmsg.2

@@ -0,0 +1,100 @@
+.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).