1ZMQ_POLL(3)                       0MQ Manual                       ZMQ_POLL(3)
2
3
4

NAME

6       zmq_poll - input/output multiplexing
7

SYNOPSIS

9       int zmq_poll (zmq_pollitem_t *items, int nitems, long timeout);
10

DESCRIPTION

12       The zmq_poll() function provides a mechanism for applications to
13       multiplex input/output events in a level-triggered fashion over a set
14       of sockets. Each member of the array pointed to by the items argument
15       is a zmq_pollitem_t structure. The nitems argument specifies the number
16       of items in the items array. The zmq_pollitem_t structure is defined as
17       follows:
18
19           typedef struct
20           {
21               void *socket;
22               int fd;
23               short events;
24               short revents;
25           } zmq_pollitem_t;
26
27       For each zmq_pollitem_t item, zmq_poll() shall examine either the 0MQ
28       socket referenced by socket or the standard socket specified by the
29       file descriptor fd, for the event(s) specified in events. If both
30       socket and fd are set in a single zmq_pollitem_t, the 0MQ socket
31       referenced by socket shall take precedence and the value of fd shall be
32       ignored.
33
34       For each zmq_pollitem_t item, zmq_poll() shall first clear the revents
35       member, and then indicate any requested events that have occurred by
36       setting the bit corresponding to the event condition in the revents
37       member.
38
39       If none of the requested events have occurred on any zmq_pollitem_t
40       item, zmq_poll() shall wait timeout milliseconds for an event to occur
41       on any of the requested items. If the value of timeout is 0, zmq_poll()
42       shall return immediately. If the value of timeout is -1, zmq_poll()
43       shall block indefinitely until a requested event has occurred on at
44       least one zmq_pollitem_t.
45
46       The events and revents members of zmq_pollitem_t are bit masks
47       constructed by OR’ing a combination of the following event flags:
48
49       ZMQ_POLLIN
50           For 0MQ sockets, at least one message may be received from the
51           socket without blocking. For standard sockets this is equivalent to
52           the POLLIN flag of the poll() system call and generally means that
53           at least one byte of data may be read from fd without blocking.
54
55       ZMQ_POLLOUT
56           For 0MQ sockets, at least one message may be sent to the socket
57           without blocking. For standard sockets this is equivalent to the
58           POLLOUT flag of the poll() system call and generally means that at
59           least one byte of data may be written to fd without blocking.
60
61       ZMQ_POLLERR
62           For standard sockets, this flag is passed through zmq_poll() to the
63           underlying poll() system call and generally means that some sort of
64           error condition is present on the socket specified by fd. For 0MQ
65           sockets this flag has no effect if set in events, and shall never
66           be returned in revents by zmq_poll().
67
68       ZMQ_POLLPRI
69           For 0MQ sockets this flags is of no use. For standard sockets this
70           means there is urgent data to read. Refer to the POLLPRI flag for
71           more informations. For file descriptor, refer to your use case: as
72           an example, GPIO interrupts are signaled through a POLLPRI event.
73           This flag has no effect on Windows.
74
75           Note
76           The zmq_poll() function may be implemented or emulated using
77           operating system interfaces other than poll(), and as such may be
78           subject to the limits of those interfaces in ways not defined in
79           this documentation.
80

THREAD SAFETY

82       The zmq_pollitem_t array must only be used by the thread which will/is
83       calling zmq_poll.
84
85       If a socket is contained in multiple zmq_pollitem_t arrays, each owned
86       by a different thread, the socket itself needs to be thead-safe
87       (Server, Client, ...). Otherwise, behaviour is undefined.
88

RETURN VALUE

90       Upon successful completion, the zmq_poll() function shall return the
91       number of zmq_pollitem_t structures with events signaled in revents or
92       0 if no events have been signaled. Upon failure, zmq_poll() shall
93       return -1 and set errno to one of the values defined below.
94

ERRORS

96       ETERM
97           At least one of the members of the items array refers to a socket
98           whose associated 0MQ context was terminated.
99
100       EFAULT
101           The provided items was not valid (NULL).
102
103       EINTR
104           The operation was interrupted by delivery of a signal before any
105           events were available.
106

EXAMPLE

108       Polling indefinitely for input events on both a 0MQ socket and a
109       standard socket..
110
111           zmq_pollitem_t items [2];
112           /* First item refers to 0MQ socket 'socket' */
113           items[0].socket = socket;
114           items[0].events = ZMQ_POLLIN;
115           /* Second item refers to standard socket 'fd' */
116           items[1].socket = NULL;
117           items[1].fd = fd;
118           items[1].events = ZMQ_POLLIN;
119           /* Poll for events indefinitely */
120           int rc = zmq_poll (items, 2, -1);
121           assert (rc >= 0);
122           /* Returned events will be stored in items[].revents */
123
124

SEE ALSO

126       zmq_socket(3) zmq_send(3) zmq_recv(3) zmq(7)
127
128       Your operating system documentation for the poll() system call.
129

AUTHORS

131       This page was written by the 0MQ community. To make a change please
132       read the 0MQ Contribution Policy at
133       http://www.zeromq.org/docs:contributing.
134
135
136
1370MQ 4.3.4                         01/21/2023                       ZMQ_POLL(3)
Impressum