Man pages for send & recv function brought up to date

Signed-off-by: Martin Sustrik <sustrik@250bpm.com>

5 files changed, 304 insertions, 90 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index eec7209..dae71be 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -2,7 +2,8 @@ MAN3 = zmq_bind.3 zmq_close.3 zmq_connect.3 zmq_init.3 \
     zmq_msg_close.3 zmq_msg_copy.3 zmq_msg_data.3 zmq_msg_init.3 \
     zmq_msg_init_data.3 zmq_msg_init_size.3 zmq_msg_move.3 zmq_msg_size.3 \
     zmq_poll.3 zmq_recv.3 zmq_send.3 zmq_setsockopt.3 zmq_socket.3 \
-    zmq_strerror.3 zmq_term.3 zmq_version.3 zmq_getsockopt.3 zmq_errno.3
+    zmq_strerror.3 zmq_term.3 zmq_version.3 zmq_getsockopt.3 zmq_errno.3 \
+    zmq_sendmsg.3 zmq_recvmsg.3
 MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_epgm.7 zmq_inproc.7 zmq_ipc.7
 
 MAN_DOC = $(MAN1) $(MAN3) $(MAN7)
diff --git a/doc/zmq_recv.txt b/doc/zmq_recv.txt
index 0b6e0e4..f09d298 100644
--- a/doc/zmq_recv.txt
+++ b/doc/zmq_recv.txt
@@ -9,30 +9,29 @@ zmq_recv - receive a message from a socket
 
 SYNOPSIS
 --------
-*int zmq_recv (void '*socket', zmq_msg_t '*msg', int 'flags');*
+*int zmq_recv (void '*socket', void '*buf', size_t 'len', int 'flags');*
 
 
 DESCRIPTION
 -----------
-The _zmq_recv()_ function shall receive a message from the socket referenced by
-the 'socket' argument and store it in the message referenced by the 'msg'
-argument. Any content previously stored in 'msg' shall be properly deallocated.
-If there are no messages available on the specified 'socket' the _zmq_recv()_
-function shall block until the request can be satisfied. The 'flags' argument
-is a combination of the flags defined below:
+The _zmq_recv()_ function shall receive a message from the socket referenced
+by the 'socket' argument and store it in the buffer referenced by the 'buf'
+argument. Any bytes exceeding the length specified by the 'len' argument shall
+be truncated. If there are no messages available on the specified 'socket'
+the _zmq_recv()_ function shall block until the request can be satisfied.
+The 'flags' argument is a combination of the flags defined below:
 
 *ZMQ_DONTWAIT*::
 Specifies that the operation should be performed in non-blocking mode. If there
-are no messages available on the specified 'socket', the _zmq_recv()_ function
-shall fail with 'errno' set to EAGAIN.
+are no messages available on the specified 'socket', the _zmq_recv()_
+function shall fail with 'errno' set to EAGAIN.
 
 
 Multi-part messages
 ~~~~~~~~~~~~~~~~~~~
-A 0MQ message is composed of 1 or more message parts; each message part is an
-independent 'zmq_msg_t' in its own right. 0MQ ensures atomic delivery of
-messages; peers shall receive either all _message parts_ of a message or none
-at all.
+A 0MQ message is composed of 1 or more message parts. 0MQ ensures atomic
+delivery of messages; peers shall receive either all _message parts_ of a
+message or none at all.
 
 The total number of message parts is unlimited.
 
@@ -46,8 +45,10 @@ shall report a value of zero. Otherwise, _ZMQ_RCVMORE_ shall report a value of
 
 RETURN VALUE
 ------------
-The _zmq_recv()_ function shall return zero if successful. Otherwise it shall
-return `-1` and set 'errno' to one of the values defined below.
+The _zmq_recv()_ function shall return number of bytes in the message
+if successful. Note that the value can exceed the value of the 'len' parameter
+in case the message was truncated. If not successful the function shall return
+`-1` and set 'errno' to one of the values defined below.
 
 
 ERRORS
@@ -57,8 +58,8 @@ Non-blocking mode was requested and no messages are available at the moment.
 *ENOTSUP*::
 The _zmq_recv()_ operation is not supported by this socket type.
 *EFSM*::
-The _zmq_recv()_ operation cannot be performed on this socket at the moment due
-to the socket not being in the appropriate state.  This error may occur with
+The _zmq_recv()_ operation cannot be performed on this socket at the moment
+due to the socket not being in the appropriate state.  This error may occur with
 socket types that switch between several states, such as ZMQ_REP.  See the
 _messaging patterns_ section of linkzmq:zmq_socket[3] for more information.
 *ETERM*::
@@ -68,48 +69,23 @@ The provided 'socket' was invalid.
 *EINTR*::
 The operation was interrupted by delivery of a signal before a message was
 available.
-*EFAULT*::
-The message passed to the function was invalid.
 
 
 EXAMPLE
 -------
 .Receiving a message from a socket
 ----
-/* Create an empty 0MQ message */
-zmq_msg_t msg;
-int rc = zmq_msg_init (&msg);
-assert (rc == 0);
-/* Block until a message is available to be received from socket */
-rc = zmq_recv (socket, &msg, 0);
-assert (rc == 0);
-/* Release message */
-zmq_msg_close (&msg);
-----
-
-.Receiving a multi-part message
-----
-int64_t more;
-size_t more_size = sizeof more;
-do {
-    /* Create an empty 0MQ message to hold the message part */
-    zmq_msg_t part;
-    int rc = zmq_msg_init (&part);
-    assert (rc == 0);
-    /* Block until a message is available to be received from socket */
-    rc = zmq_recv (socket, &part, 0);
-    assert (rc == 0);
-    /* Determine if more message parts are to follow */
-    rc = zmq_getsockopt (socket, ZMQ_RCVMORE, &more, &more_size);
-    assert (rc == 0);
-    zmq_msg_close (&part);
-} while (more);
+char buf [256];
+nbytes = zmq_recv (socket, buf, 256, 0);
+assert (nbytes != -1);
 ----
 
 
 SEE ALSO
 --------
+linkzmq:zmq_recvmsg[3]
 linkzmq:zmq_send[3]
+linkzmq:zmq_sendmsg[3]
 linkzmq:zmq_getsockopt[3]
 linkzmq:zmq_socket[7]
 linkzmq:zmq[7]
diff --git a/doc/zmq_recvmsg.txt b/doc/zmq_recvmsg.txt
new file mode 100644
index 0000000..640768a
--- /dev/null
+++ b/doc/zmq_recvmsg.txt
@@ -0,0 +1,124 @@
+zmq_recvmsg(3)
+==============
+
+
+NAME
+----
+zmq_recvmsg - receive a message from a socket
+
+
+SYNOPSIS
+--------
+*int zmq_recvmsg (void '*socket', zmq_msg_t '*msg', int 'flags');*
+
+
+DESCRIPTION
+-----------
+The _zmq_recvmsg()_ function shall receive a message from the socket referenced
+by the 'socket' argument and store it in the message referenced by the 'msg'
+argument. Any content previously stored in 'msg' shall be properly deallocated.
+If there are no messages available on the specified 'socket' the _zmq_recvmsg()_
+function shall block until the request can be satisfied. The 'flags' argument
+is a combination of the flags defined below:
+
+*ZMQ_DONTWAIT*::
+Specifies that the operation should be performed in non-blocking mode. If there
+are no messages available on the specified 'socket', the _zmq_recvmsg()_
+function shall fail with 'errno' set to EAGAIN.
+
+
+Multi-part messages
+~~~~~~~~~~~~~~~~~~~
+A 0MQ message is composed of 1 or more message parts; each message part is an
+independent 'zmq_msg_t' in its own right. 0MQ ensures atomic delivery of
+messages; peers shall receive either all _message parts_ of a message or none
+at all.
+
+The total number of message parts is unlimited.
+
+An application wishing to determine if a message is composed of multiple parts
+does so by retrieving the value of the _ZMQ_RCVMORE_ socket option on the
+'socket' it is receiving the message from. If there are no message parts to
+follow, or if the message is not composed of multiple parts, _ZMQ_RCVMORE_
+shall report a value of zero. Otherwise, _ZMQ_RCVMORE_ shall report a value of
+1, indicating that more message parts are to follow.
+
+
+RETURN VALUE
+------------
+The _zmq_recvmsg()_ function shall return number of bytes in the message
+if successful. Otherwise it shall return `-1` and set 'errno' to one of the
+values defined below.
+
+
+ERRORS
+------
+*EAGAIN*::
+Non-blocking mode was requested and no messages are available at the moment.
+*ENOTSUP*::
+The _zmq_recvmsg()_ operation is not supported by this socket type.
+*EFSM*::
+The _zmq_recvmsg()_ operation cannot be performed on this socket at the moment
+due to the socket not being in the appropriate state.  This error may occur with
+socket types that switch between several states, such as ZMQ_REP.  See the
+_messaging patterns_ section of linkzmq:zmq_socket[3] for more information.
+*ETERM*::
+The 0MQ 'context' associated with the specified 'socket' was terminated.
+*ENOTSOCK*::
+The provided 'socket' was invalid.
+*EINTR*::
+The operation was interrupted by delivery of a signal before a message was
+available.
+*EFAULT*::
+The message passed to the function was invalid.
+
+
+EXAMPLE
+-------
+.Receiving a message from a socket
+----
+/* Create an empty 0MQ message */
+zmq_msg_t msg;
+int rc = zmq_msg_init (&msg);
+assert (rc == 0);
+/* Block until a message is available to be received from socket */
+rc = zmq_recvmsg (socket, &msg, 0);
+assert (rc != -1);
+/* Release message */
+zmq_msg_close (&msg);
+----
+
+.Receiving a multi-part message
+----
+int64_t more;
+size_t more_size = sizeof more;
+do {
+    /* Create an empty 0MQ message to hold the message part */
+    zmq_msg_t part;
+    int rc = zmq_msg_init (&part);
+    assert (rc == 0);
+    /* Block until a message is available to be received from socket */
+    rc = zmq_recvmsg (socket, &part, 0);
+    assert (rc != -1);
+    /* Determine if more message parts are to follow */
+    rc = zmq_getsockopt (socket, ZMQ_RCVMORE, &more, &more_size);
+    assert (rc == 0);
+    zmq_msg_close (&part);
+} while (more);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_recv[3]
+linkzmq:zmq_send[3]
+linkzmq:zmq_sendmsg[3]
+linkzmq:zmq_getsockopt[3]
+linkzmq:zmq_socket[7]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_send.txt b/doc/zmq_send.txt
index 52a50ae..2b51953 100644
--- a/doc/zmq_send.txt
+++ b/doc/zmq_send.txt
@@ -9,19 +9,19 @@ zmq_send - send a message on a socket
 
 SYNOPSIS
 --------
-*int zmq_send (void '*socket', zmq_msg_t '*msg', int 'flags');*
+*int zmq_send (void '*socket', void '*buf', size_t 'len', int 'flags');*
 
 
 DESCRIPTION
 -----------
-The _zmq_send()_ function shall queue the message referenced by the 'msg'
-argument to be sent to the socket referenced by the 'socket' argument.  The
-'flags' argument is a combination of the flags defined below:
+The _zmq_send()_ function shall queue a message created from the buffer
+referenced by the 'buf' and 'len' arguments. The 'flags' argument is
+a combination of the flags defined below:
 
 *ZMQ_DONTWAIT*::
 Specifies that the operation should be performed in non-blocking mode. If the
-message cannot be queued on the 'socket', the _zmq_send()_ function shall fail
-with 'errno' set to EAGAIN.
+message cannot be queued on the 'socket', the _zmq_send()_ function shall
+fail with 'errno' set to EAGAIN.
 
 *ZMQ_SNDMORE*::
 Specifies that the message being sent is a multi-part message, and that further
@@ -32,10 +32,6 @@ below for a detailed description.
 Specifies that the message being sent is a label. Labels are used internally
 by 0MQ.
 
-The _zmq_msg_t_ structure passed to _zmq_send()_ is nullified during the call.
-If you want to send the same message to multiple sockets you have to copy it
-using (e.g. using _zmq_msg_copy()_).
-
 NOTE: A successful invocation of _zmq_send()_ does not indicate that the
 message has been transmitted to the network, only that it has been queued on
 the 'socket' and 0MQ has assumed responsibility for the message.
@@ -43,25 +39,26 @@ the 'socket' and 0MQ has assumed responsibility for the message.
 
 Multi-part messages
 ~~~~~~~~~~~~~~~~~~~
-A 0MQ message is composed of 1 or more message parts; each message part is an
-independent 'zmq_msg_t' in its own right. 0MQ ensures atomic delivery of
-messages; peers shall receive either all _message parts_ of a message or none
-at all.
+A 0MQ message is composed of 1 or more message parts; each invocation of
+_zmq_send()_ creates an independent message part in its own right. 0MQ ensures
+atomic delivery of messages; peers shall receive either all _message parts_ of
+a message or none at all.
 
 The total number of message parts is unlimited.
 
 An application wishing to send a multi-part message does so by specifying the
-'ZMQ_SNDMORE' flag to _zmq_send()_. The presence of this flag indicates to 0MQ
-that the message being sent is a multi-part message and that more message parts
-are to follow. When the application wishes to send the final message part it
-does so by calling _zmq_send()_ without the 'ZMQ_SNDMORE' flag; this indicates
-that no more message parts are to follow.
+'ZMQ_SNDMORE' flag to _zmq_send()_. The presence of this flag indicates to
+0MQ that the message being sent is a multi-part message and that more message
+parts are to follow. When the application wishes to send the final message part
+it does so by calling _zmq_send()_ without the 'ZMQ_SNDMORE' flag; this
+indicates that no more message parts are to follow.
 
 
 RETURN VALUE
 ------------
-The _zmq_send()_ function shall return zero if successful. Otherwise it shall
-return `-1` and set 'errno' to one of the values defined below.
+The _zmq_send()_ function shall return number of bytes in the message
+if successful. Otherwise it shall return `-1` and set 'errno' to one of the
+values defined below.
 
 
 ERRORS
@@ -71,8 +68,8 @@ Non-blocking mode was requested and the message cannot be sent at the moment.
 *ENOTSUP*::
 The _zmq_send()_ operation is not supported by this socket type.
 *EFSM*::
-The _zmq_send()_ operation cannot be performed on this socket at the moment due
-to the socket not being in the appropriate state.  This error may occur with
+The _zmq_send()_ operation cannot be performed on this socket at the moment
+due to the socket not being in the appropriate state.  This error may occur with
 socket types that switch between several states, such as ZMQ_REP.  See the
 _messaging patterns_ section of linkzmq:zmq_socket[3] for more information.
 *ETERM*::
@@ -82,38 +79,27 @@ The provided 'socket' was invalid.
 *EINTR*::
 The operation was interrupted by delivery of a signal before the message was
 sent.
-*EFAULT*::
-Invalid message.
 
 
 EXAMPLE
 -------
-.Filling in a message and sending it to a socket
-----
-/* Create a new message, allocating 6 bytes for message content */
-zmq_msg_t msg;
-int rc = zmq_msg_init_size (&msg, 6);
-assert (rc == 0);
-/* Fill in message content with 'AAAAAA' */
-memset (zmq_msg_data (&msg), 'A', 6);
-/* Send the message to the socket */
-rc = zmq_send (socket, &msg, 0);
-assert (rc == 0);
-----
-
 .Sending a multi-part message
 ----
 /* Send a multi-part message consisting of three parts to socket */
-rc = zmq_send (socket, &part1, ZMQ_SNDMORE);
-rc = zmq_send (socket, &part2, ZMQ_SNDMORE);
+rc = zmq_send (socket, "ABC", 3, ZMQ_SNDMORE);
+assert (rc == 3);
+rc = zmq_send (socket, "DEFGH", 5, ZMQ_SNDMORE);
+assert (rc == 5);
 /* Final part; no more parts to follow */
-rc = zmq_send (socket, &part3, 0);
+rc = zmq_send (socket, "JK", 2, 0);
+assert (rc == 2);
 ----
 
-
 SEE ALSO
 --------
+linkzmq:zmq_sendmsg[3]
 linkzmq:zmq_recv[3]
+linkzmq:zmq_recvmsg[3]
 linkzmq:zmq_socket[7]
 linkzmq:zmq[7]
 
diff --git a/doc/zmq_sendmsg.txt b/doc/zmq_sendmsg.txt
new file mode 100644
index 0000000..ddf585c
--- /dev/null
+++ b/doc/zmq_sendmsg.txt
@@ -0,0 +1,127 @@
+zmq_sendmsg(3)
+==============
+
+
+NAME
+----
+zmq_sendmsg - send a message on a socket
+
+
+SYNOPSIS
+--------
+*int zmq_sendmsg (void '*socket', zmq_msg_t '*msg', int 'flags');*
+
+
+DESCRIPTION
+-----------
+The _zmq_send()_ function shall queue the message referenced by the 'msg'
+argument to be sent to the socket referenced by the 'socket' argument.  The
+'flags' argument is a combination of the flags defined below:
+
+*ZMQ_DONTWAIT*::
+Specifies that the operation should be performed in non-blocking mode. If the
+message cannot be queued on the 'socket', the _zmq_sendmsg()_ function shall
+fail with 'errno' set to EAGAIN.
+
+*ZMQ_SNDMORE*::
+Specifies that the message being sent is a multi-part message, and that further
+message parts are to follow. Refer to the section regarding multi-part messages
+below for a detailed description.
+
+*ZMQ_SNDLABEL*::
+Specifies that the message being sent is a label. Labels are used internally
+by 0MQ.
+
+The _zmq_msg_t_ structure passed to _zmq_sendmsg()_ is nullified during the
+call. If you want to send the same message to multiple sockets you have to copy
+it using (e.g. using _zmq_msg_copy()_).
+
+NOTE: A successful invocation of _zmq_sendmsg()_ does not indicate that the
+message has been transmitted to the network, only that it has been queued on
+the 'socket' and 0MQ has assumed responsibility for the message.
+
+
+Multi-part messages
+~~~~~~~~~~~~~~~~~~~
+A 0MQ message is composed of 1 or more message parts; each message part is an
+independent 'zmq_msg_t' in its own right. 0MQ ensures atomic delivery of
+messages; peers shall receive either all _message parts_ of a message or none
+at all.
+
+The total number of message parts is unlimited.
+
+An application wishing to send a multi-part message does so by specifying the
+'ZMQ_SNDMORE' flag to _zmq_sendmsg()_. The presence of this flag indicates to
+0MQ that the message being sent is a multi-part message and that more message
+parts are to follow. When the application wishes to send the final message part
+it does so by calling _zmq_sendmsg()_ without the 'ZMQ_SNDMORE' flag; this
+indicates that no more message parts are to follow.
+
+
+RETURN VALUE
+------------
+The _zmq_sendmsg()_ function shall return number of bytes in the message
+if successful. Otherwise it shall return `-1` and set 'errno' to one of the
+values defined below.
+
+
+ERRORS
+------
+*EAGAIN*::
+Non-blocking mode was requested and the message cannot be sent at the moment.
+*ENOTSUP*::
+The _zmq_sendmsg()_ operation is not supported by this socket type.
+*EFSM*::
+The _zmq_sendmsg()_ operation cannot be performed on this socket at the moment
+due to the socket not being in the appropriate state.  This error may occur with
+socket types that switch between several states, such as ZMQ_REP.  See the
+_messaging patterns_ section of linkzmq:zmq_socket[3] for more information.
+*ETERM*::
+The 0MQ 'context' associated with the specified 'socket' was terminated.
+*ENOTSOCK*::
+The provided 'socket' was invalid.
+*EINTR*::
+The operation was interrupted by delivery of a signal before the message was
+sent.
+*EFAULT*::
+Invalid message.
+
+
+EXAMPLE
+-------
+.Filling in a message and sending it to a socket
+----
+/* Create a new message, allocating 6 bytes for message content */
+zmq_msg_t msg;
+int rc = zmq_msg_init_size (&msg, 6);
+assert (rc == 0);
+/* Fill in message content with 'AAAAAA' */
+memset (zmq_msg_data (&msg), 'A', 6);
+/* Send the message to the socket */
+rc = zmq_sendmsg (socket, &msg, 0);
+assert (rc == 6);
+----
+
+.Sending a multi-part message
+----
+/* Send a multi-part message consisting of three parts to socket */
+rc = zmq_sendmsg (socket, &part1, ZMQ_SNDMORE);
+rc = zmq_sendmsg (socket, &part2, ZMQ_SNDMORE);
+/* Final part; no more parts to follow */
+rc = zmq_sendmsg (socket, &part3, 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_recv[3]
+linkzmq:zmq_recv[3]
+linkzmq:zmq_recvmsg[3]
+linkzmq:zmq_socket[7]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.