1 files changed, 85 insertions, 0 deletions
diff --git a/doc/xs_getmsgopt.txt b/doc/xs_getmsgopt.txt
new file mode 100644
index 0000000..4b06322
--- /dev/null
+++ b/doc/xs_getmsgopt.txt
@@ -0,0 +1,85 @@
+xs_getmsgopt(3)
+===============
+
+
+NAME
+----
+xs_getmsgopt - retrieve message option
+
+
+SYNOPSIS
+--------
+*int xs_getmsgopt (xs_msg_t '*message', int 'option_name', void '*option_value', size_t '*option_len');*
+
+
+DESCRIPTION
+-----------
+The _xs_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 _xs_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 _xs_getmsgopt()_ function:
+
+*XS_MORE*::
+Indicates that there are more message parts to follow after the 'message'.
+
+RETURN VALUE
+------------
+The _xs_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
+----
+xs_msg_t part;
+int more;
+size_t more_size = sizeof (more);
+while (true) {
+    /* Create an empty message to hold the message part */
+    int rc = xs_msg_init (&part);
+    assert (rc == 0);
+    /* Block until a message is available to be received from socket */
+    rc = xs_recvmsg (socket, &part, 0);
+    assert (rc != -1);
+    rc = getmsgopt (&part, XS_MORE, &more, &more_size);
+    assert (rc == 0);
+    if (more) {
+      fprintf (stderr, "more\n");
+    }
+    else {
+      fprintf (stderr, "end\n");
+      break;
+    }
+    xs_msg_close (part);
+}
+----
+
+
+SEE ALSO
+--------
+linkxs:xs_msg_data[3]
+linkxs:xs_msg_init[3]
+linkxs:xs_msg_init_size[3]
+linkxs:xs_msg_init_data[3]
+linkxs:xs_msg_close[3]
+linkxs:xs[7]
+
+
+AUTHORS
+-------
+This manual page was written by Chuck Remes <cremes@mac.com>.