summaryrefslogtreecommitdiff
path: root/doc/xs_getmsgopt.txt
blob: 4b06322442a32022635add5ccbd72c33cab0b0ec (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
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>.