summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorChuck Remes <cremes@mac.com>2011-11-06 14:03:51 +0100
committerMartin Sustrik <sustrik@250bpm.com>2011-11-06 14:03:51 +0100
commit93529d8c5db599a45171942c4510f1b84ed09e6a (patch)
tree07ae1a6ff6f840eaa6ea1b2ffe8c76ce126f4237 /doc
parentbb66f3cc3bc2a76d10f16e1206f35480eb250a07 (diff)
Add zmq_getmsgopt to the API
The new function allows to retrieve options (flags) from zmq_msg_t. Signed-off-by: Chuck Remes <cremes@mac.com> Renamed from zmq_msg_flags to zmq_getmsgopt Signed-off-by: Martin Sustrik <sustrik@250bpm.com>
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am2
-rw-r--r--doc/zmq_getmsgopt.txt85
2 files changed, 86 insertions, 1 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index dae71be..ff00c18 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -3,7 +3,7 @@ MAN3 = zmq_bind.3 zmq_close.3 zmq_connect.3 zmq_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_sendmsg.3 zmq_recvmsg.3
+ zmq_sendmsg.3 zmq_recvmsg.3 zmq_getmsgopt.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_getmsgopt.txt b/doc/zmq_getmsgopt.txt
new file mode 100644
index 0000000..a82c30c
--- /dev/null
+++ b/doc/zmq_getmsgopt.txt
@@ -0,0 +1,85 @@
+zmq_getmsgopt(3)
+================
+
+
+NAME
+----
+zmq_getmsgopt - retrieve message option
+
+
+SYNOPSIS
+--------
+*int zmq_getmsgopt (zmq_msg_t '*message', int 'option_name', void '*option_value', size_t '*option_len');*
+
+
+DESCRIPTION
+-----------
+The _zmq_getmsgopt()_ function shall retrieve the value for the option
+specified by the 'option_name' argument for the message pointed to by the
+'message' argument, and store it in the buffer pointed to by the 'option_value'
+argument. The 'option_len' argument is the size in bytes of the buffer pointed
+to by 'option_value'; upon successful completion _zmq_getsockopt()_ shall
+modify the 'option_len' argument to indicate the actual size of the option
+value stored in the buffer.
+
+The following options can be retrieved with the _zmq_getmsgopt()_ function:
+
+*ZMQ_MORE*::
+Indicates that there are more message parts to follow after the 'message'.
+
+RETURN VALUE
+------------
+The _zmq_getmsgopt()_ function shall return zero if successful. Otherwise it
+shall return `-1` and set 'errno' to one of the values defined below.
+
+
+ERRORS
+------
+*EINVAL*::
+The requested option _option_name_ is unknown, or the requested _option_size_ or
+_option_value_ is invalid, or the size of the buffer pointed to by
+_option_value_, as specified by _option_len_, is insufficient for storing the
+option value.
+
+
+EXAMPLE
+-------
+.Receiving a multi-part message
+----
+zmq_msg_t part;
+int more;
+size_t more_size = sizeof (more);
+while (true) {
+ /* Create an empty 0MQ message to hold the message 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);
+ rc = getmsgopt (&part, ZMQ_MORE, &more, &more_size);
+ assert (rc == 0);
+ if (more) {
+ fprintf (stderr, "more\n");
+ }
+ else {
+ fprintf (stderr, "end\n");
+ break;
+ }
+ zmq_msg_close (part);
+}
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_msg_data[3]
+linkzmq:zmq_msg_init[3]
+linkzmq:zmq_msg_init_size[3]
+linkzmq:zmq_msg_init_data[3]
+linkzmq:zmq_msg_close[3]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+The 0MQ documentation was written by Chuck Remes <cremes@mac.com>.