Renamed zmq_getmsgopt to zmq_msg_peek

* Added zmq_msg_poke for orthogonality
* Added zmq_msg_more for simplicity
* Fixed up man pages and test program

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_getmsgopt.3
+    zmq_sendmsg.3 zmq_recvmsg.3 zmq_msg_peek.3 zmq_msg_poke.3 zmq_msg_more.3
 MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_epgm.7 zmq_inproc.7 zmq_ipc.7
 
 MAN_DOC = $(MAN1) $(MAN3) $(MAN7)

doc/zmq.txt

@@ -83,9 +83,11 @@ Release a message::
 Access message content::
     linkzmq:zmq_msg_data[3]
     linkzmq:zmq_msg_size[3]
+    linkzmq:zmq_msg_more[3]
 
-Get message properties::
-    linkzmq:zmq_getmsgopt[3]
+Work with message properties::
+    linkzmq:zmq_msg_peek[3]
+    linkzmq:zmq_msg_poke[3]
 
 Message manipulation::
     linkzmq:zmq_msg_copy[3]
@@ -180,14 +182,14 @@ by C programmers. The intent is that programmers using 0MQ from other languages
 shall refer to this documentation alongside any documentation provided by the
 vendor of their language binding.
 
-Language bindings (Python, Ruby, Java and more) are provided by members
+Language bindings (Python, PHP, Ruby, Java and more) are provided by members
 of the 0MQ community and pointers can be found on the 0MQ website.
 
 
 AUTHORS
 -------
-The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
-Martin Lucina <martin@lucina.net>.
+This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com>,
+Martin Lucina <martin@lucina.net>, and Pieter Hintjens <ph@imatix.com>.
 
 
 RESOURCES

doc/zmq_msg_more.txt

+zmq_msg_more(3)
+===============
+
+
+NAME
+----
+zmq_msg_more - indicate if there are more message parts to receive
+
+
+SYNOPSIS
+--------
+*int zmq_msg_more (zmq_msg_t '*message');*
+
+
+DESCRIPTION
+-----------
+The _zmq_msg_more()_ function indicates whether this is part of a multi-part
+message, and there are further parts to receive.
+
+
+RETURN VALUE
+------------
+The _zmq_msg_more()_ function shall return zero if this is the final part of
+a multi-part message, or the only part of a single-part message. It shall
+return 1 if there are further parts to receive.
+
+
+EXAMPLE
+-------
+.Receiving a multi-part message
+----
+zmq_msg_t part;
+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);
+    if (zmq_msg_more (&part))
+        fprintf (stderr, "more\n");
+    else {
+        fprintf (stderr, "end\n");
+        break;
+    }
+    zmq_msg_close (part);
+}
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_msg_peek[3]
+linkzmq:zmq_msg_poke[3]
+linkzmq:zmq_msg_init[3]
+linkzmq:zmq_msg_close[3]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Chuck Remes <cremes@mac.com> and Pieter
+Hintjens <ph@imatix.com>.

doc/zmq_getmsgopt.txt → doc/zmq_msg_peek.txt

-zmq_getmsgopt(3)
-================
+zmq_msg_peek(3)
+===============
 
 
 NAME
 ----
-zmq_getmsgopt - retrieve message option
+zmq_msg_peek - get message options
 
 
 SYNOPSIS
 --------
-*int zmq_getmsgopt (zmq_msg_t '*message', int 'option_name', void '*option_value', size_t '*option_len');*
+*int zmq_msg_peek (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
+The _zmq_msg_peek()_ 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
@@ -22,14 +22,14 @@ 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:
+The following options can be retrieved with the _zmq_msg_peek()_ 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
+The _zmq_msg_peek()_ function shall return zero if successful. Otherwise it
 shall return `-1` and set 'errno' to one of the values defined below.
 
 
@@ -50,20 +50,19 @@ zmq_msg_t part;
 int more;
 size_t more_size = sizeof (more);
 while (true) {
-    /* Create an empty 0MQ message to hold the message part */
+    //  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 */
+    //  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");
-    }
+    if (more)
+        fprintf (stderr, "more\n");
     else {
-      fprintf (stderr, "end\n");
-      break;
+        fprintf (stderr, "end\n");
+        break;
     }
     zmq_msg_close (part);
 }
@@ -72,14 +71,13 @@ while (true) {
 
 SEE ALSO
 --------
-linkzmq:zmq_msg_data[3]
+linkzmq:zmq_msg_poke[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
 -------
-This 0MQ manual page was written by Chuck Remes <cremes@mac.com>.
+This 0MQ manual page was written by Chuck Remes <cremes@mac.com> and Pieter
+Hintjens <ph@imatix.com>.

doc/zmq_msg_poke.txt

+zmq_msg_poke(3)
+===============
+
+
+NAME
+----
+
+zmq_msg_poke - set message options
+
+
+SYNOPSIS
+--------
+*int zmq_msg_peek (zmq_msg_t '*message', int 'option_name', const void '*option_value', size_t '*option_len');*
+
+
+DESCRIPTION
+-----------
+The _zmq_msg_poke()_ function shall set the option specified by the
+'option_name' argument to the value pointed to by the 'option_value' argument
+for the 0MQ socket pointed to by the 'socket' argument. The 'option_len'
+argument is the size of the option value in bytes.
+
+Currently the _zmq_msg_poke()_ function does not support any option names.
+
+
+RETURN VALUE
+------------
+The _zmq_msg_poke()_ 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_len_ or
+_option_value_ is invalid.
+
+
+SEE ALSO
+--------
+linkzmq:zmq_msg_peek[3]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>.

include/zmq.h

 /*
-    Copyright (c) 2007-2010 iMatix Corporation
+    Copyright (c) 2007-2012 iMatix Corporation
     Copyright (c) 2009-2011 250bpm s.r.o.
     Copyright (c) 2011 VMware, Inc.
     Copyright (c) 2007-2011 Other contributors as noted in the AUTHORS file
@@ -166,8 +166,12 @@ ZMQ_EXPORT int zmq_msg_move (zmq_msg_t *dest, zmq_msg_t *src);
 ZMQ_EXPORT int zmq_msg_copy (zmq_msg_t *dest, zmq_msg_t *src);
 ZMQ_EXPORT void *zmq_msg_data (zmq_msg_t *msg);
 ZMQ_EXPORT size_t zmq_msg_size (zmq_msg_t *msg);
-ZMQ_EXPORT int zmq_getmsgopt (zmq_msg_t *msg, int option, void *optval,
-    size_t *optvallen);
+ZMQ_EXPORT int zmq_msg_more (zmq_msg_t *msg);
+ZMQ_EXPORT int zmq_msg_peek (zmq_msg_t *msg, int option, void *optval,
+                             size_t *optvallen);
+ZMQ_EXPORT int zmq_msg_poke (zmq_msg_t *msg, int option, const void *optval,
+                             size_t *optvallen);
+
 
 /******************************************************************************/
 /*  0MQ infrastructure (a.k.a. context) initialisation & termination.         */

src/zmq.cpp

 /*
+    Copyright (c) 2007-2012 iMatix Corporation
     Copyright (c) 2009-2011 250bpm s.r.o.
-    Copyright (c) 2007-2011 iMatix Corporation
     Copyright (c) 2007-2011 Other contributors as noted in the AUTHORS file
 
     This file is part of 0MQ.
@@ -541,23 +541,48 @@ size_t zmq_msg_size (zmq_msg_t *msg_)
     return ((zmq::msg_t*) msg_)->size ();
 }
 
-int zmq_getmsgopt (zmq_msg_t *msg_, int option_, void *optval_,
+int zmq_msg_more (zmq_msg_t *msg_)
+{
+    int more;
+    size_t more_size = sizeof (more);
+    int rc = zmq_msg_peek (msg_, ZMQ_MORE, &more, &more_size);
+    assert (rc == 0);
+    return more;
+}
+
+int zmq_msg_peek (zmq_msg_t *msg_, int option_, void *optval_,
     size_t *optvallen_)
 {
+    if (!msg_) {
+        errno = EFAULT;
+        return -1;
+    }
     switch (option_) {
-    case ZMQ_MORE:
-        if (*optvallen_ < sizeof (int)) {
+        case ZMQ_MORE:
+            if (*optvallen_ < sizeof (int)) {
+                errno = EINVAL;
+                return -1;
+            }
+            *((int*) optval_) =
+                (((zmq::msg_t*) msg_)->flags () & zmq::msg_t::more)? 1 : 0;
+            *optvallen_ = sizeof (int);
+            return 0;
+        default:
             errno = EINVAL;
             return -1;
-        }
-        *((int*) optval_) =
-            (((zmq::msg_t*) msg_)->flags () & zmq::msg_t::more) ? 1 : 0;
-        *optvallen_ = sizeof (int);
-        return 0;
-    default:
-        errno = EINVAL;
+    }
+}
+
+int zmq_msg_poke (zmq_msg_t *msg_, int option_, const void *optval_,
+    size_t *optvallen_)
+{
+    if (!msg_) {
+        errno = EFAULT;
         return -1;
     }
+    //  No options supported at present
+    errno = EINVAL;
+    return -1;
 }
 
 // Polling.

tests/test_msg_flags.cpp

 /*
+    Copyright (c) 2007-2012 iMatix Corporation
     Copyright (c) 2011 250bpm s.r.o.
+    Copyright (c) 2007-2011 Other contributors as noted in the AUTHORS file
 
     This file is part of 0MQ.
 
@@ -50,7 +52,7 @@ int main (int argc, char *argv [])
     assert (rc >= 0);
     int more;
     size_t more_size = sizeof (more);
-    rc = zmq_getmsgopt (&msg, ZMQ_MORE, &more, &more_size);
+    rc = zmq_msg_peek (&msg, ZMQ_MORE, &more, &more_size);
     assert (rc == 0);
     assert (more == 1);
 
@@ -58,7 +60,7 @@ int main (int argc, char *argv [])
     rc = zmq_recvmsg (sb, &msg, 0);
     assert (rc == 1);
     more_size = sizeof (more);
-    rc = zmq_getmsgopt (&msg, ZMQ_MORE, &more, &more_size);
+    rc = zmq_msg_peek (&msg, ZMQ_MORE, &more, &more_size);
     assert (rc == 0);
     assert (more == 1);
 
@@ -66,7 +68,7 @@ int main (int argc, char *argv [])
     rc = zmq_recvmsg (sb, &msg, 0);
     assert (rc == 1);
     more_size = sizeof (more);
-    rc = zmq_getmsgopt (&msg, ZMQ_MORE, &more, &more_size);
+    rc = zmq_msg_peek (&msg, ZMQ_MORE, &more, &more_size);
     assert (rc == 0);
     assert (more == 0);