diff options
Diffstat (limited to 'doc/xs_getmsgopt.txt')
-rw-r--r-- | doc/xs_getmsgopt.txt | 85 |
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>. |