From 93529d8c5db599a45171942c4510f1b84ed09e6a Mon Sep 17 00:00:00 2001 From: Chuck Remes Date: Sun, 6 Nov 2011 14:03:51 +0100 Subject: Add zmq_getmsgopt to the API The new function allows to retrieve options (flags) from zmq_msg_t. Signed-off-by: Chuck Remes Renamed from zmq_msg_flags to zmq_getmsgopt Signed-off-by: Martin Sustrik --- doc/Makefile.am | 2 +- doc/zmq_getmsgopt.txt | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 86 insertions(+), 1 deletion(-) create mode 100644 doc/zmq_getmsgopt.txt (limited to 'doc') 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 . -- cgit v1.2.3