1ZSOCK(3)                          CZMQ Manual                         ZSOCK(3)
2
3
4

NAME

6       zsock - Class for high-level socket API that hides libzmq contexts and
7       sockets
8

SYNOPSIS

10       //  This is a stable class, and may not change except for emergencies. It
11       //  is provided in stable builds.
12       //  This class has draft methods, which may change over time. They are not
13       //  in stable releases, by default. Use --enable-drafts to enable.
14       //  Create a new socket. Returns the new socket, or NULL if the new socket
15       //  could not be created. Note that the symbol zsock_new (and other
16       //  constructors/destructors for zsock) are redirected to the *_checked
17       //  variant, enabling intelligent socket leak detection. This can have
18       //  performance implications if you use a LOT of sockets. To turn off this
19       //  redirection behaviour, define ZSOCK_NOCHECK.
20       CZMQ_EXPORT zsock_t *
21           zsock_new (int type);
22
23       //  Create a PUB socket. Default action is bind.
24       CZMQ_EXPORT zsock_t *
25           zsock_new_pub (const char *endpoint);
26
27       //  Create a SUB socket, and optionally subscribe to some prefix string. Default
28       //  action is connect.
29       CZMQ_EXPORT zsock_t *
30           zsock_new_sub (const char *endpoint, const char *subscribe);
31
32       //  Create a REQ socket. Default action is connect.
33       CZMQ_EXPORT zsock_t *
34           zsock_new_req (const char *endpoint);
35
36       //  Create a REP socket. Default action is bind.
37       CZMQ_EXPORT zsock_t *
38           zsock_new_rep (const char *endpoint);
39
40       //  Create a DEALER socket. Default action is connect.
41       CZMQ_EXPORT zsock_t *
42           zsock_new_dealer (const char *endpoint);
43
44       //  Create a ROUTER socket. Default action is bind.
45       CZMQ_EXPORT zsock_t *
46           zsock_new_router (const char *endpoint);
47
48       //  Create a PUSH socket. Default action is connect.
49       CZMQ_EXPORT zsock_t *
50           zsock_new_push (const char *endpoint);
51
52       //  Create a PULL socket. Default action is bind.
53       CZMQ_EXPORT zsock_t *
54           zsock_new_pull (const char *endpoint);
55
56       //  Create an XPUB socket. Default action is bind.
57       CZMQ_EXPORT zsock_t *
58           zsock_new_xpub (const char *endpoint);
59
60       //  Create an XSUB socket. Default action is connect.
61       CZMQ_EXPORT zsock_t *
62           zsock_new_xsub (const char *endpoint);
63
64       //  Create a PAIR socket. Default action is connect.
65       CZMQ_EXPORT zsock_t *
66           zsock_new_pair (const char *endpoint);
67
68       //  Create a STREAM socket. Default action is connect.
69       CZMQ_EXPORT zsock_t *
70           zsock_new_stream (const char *endpoint);
71
72       //  Destroy the socket. You must use this for any socket created via the
73       //  zsock_new method.
74       CZMQ_EXPORT void
75           zsock_destroy (zsock_t **self_p);
76
77       //  Bind a socket to a formatted endpoint. For tcp:// endpoints, supports
78       //  ephemeral ports, if you specify the port number as "*". By default
79       //  zsock uses the IANA designated range from C000 (49152) to FFFF (65535).
80       //  To override this range, follow the "*" with "[first-last]". Either or
81       //  both first and last may be empty. To bind to a random port within the
82       //  range, use "!" in place of "*".
83       //
84       //  Examples:
85       //      tcp://127.0.0.1:*           bind to first free port from C000 up
86       //      tcp://127.0.0.1:!           bind to random port from C000 to FFFF
87       //      tcp://127.0.0.1:*[60000-]   bind to first free port from 60000 up
88       //      tcp://127.0.0.1:![-60000]   bind to random port from C000 to 60000
89       //      tcp://127.0.0.1:![55000-55999]
90       //                                  bind to random port from 55000 to 55999
91       //
92       //  On success, returns the actual port number used, for tcp:// endpoints,
93       //  and 0 for other transports. On failure, returns -1. Note that when using
94       //  ephemeral ports, a port may be reused by different services without
95       //  clients being aware. Protocols that run on ephemeral ports should take
96       //  this into account.
97       CZMQ_EXPORT int
98           zsock_bind (zsock_t *self, const char *format, ...) CHECK_PRINTF (2);
99
100       //  Returns last bound endpoint, if any.
101       CZMQ_EXPORT const char *
102           zsock_endpoint (zsock_t *self);
103
104       //  Unbind a socket from a formatted endpoint.
105       //  Returns 0 if OK, -1 if the endpoint was invalid or the function
106       //  isn't supported.
107       CZMQ_EXPORT int
108           zsock_unbind (zsock_t *self, const char *format, ...) CHECK_PRINTF (2);
109
110       //  Connect a socket to a formatted endpoint
111       //  Returns 0 if OK, -1 if the endpoint was invalid.
112       CZMQ_EXPORT int
113           zsock_connect (zsock_t *self, const char *format, ...) CHECK_PRINTF (2);
114
115       //  Disconnect a socket from a formatted endpoint
116       //  Returns 0 if OK, -1 if the endpoint was invalid or the function
117       //  isn't supported.
118       CZMQ_EXPORT int
119           zsock_disconnect (zsock_t *self, const char *format, ...) CHECK_PRINTF (2);
120
121       //  Attach a socket to zero or more endpoints. If endpoints is not null,
122       //  parses as list of ZeroMQ endpoints, separated by commas, and prefixed by
123       //  '@' (to bind the socket) or '>' (to connect the socket). Returns 0 if all
124       //  endpoints were valid, or -1 if there was a syntax error. If the endpoint
125       //  does not start with '@' or '>', the serverish argument defines whether
126       //  it is used to bind (serverish = true) or connect (serverish = false).
127       CZMQ_EXPORT int
128           zsock_attach (zsock_t *self, const char *endpoints, bool serverish);
129
130       //  Returns socket type as printable constant string.
131       CZMQ_EXPORT const char *
132           zsock_type_str (zsock_t *self);
133
134       //  Send a 'picture' message to the socket (or actor). The picture is a
135       //  string that defines the type of each frame. This makes it easy to send
136       //  a complex multiframe message in one call. The picture can contain any
137       //  of these characters, each corresponding to one or two arguments:
138       //
139       //      i = int (signed)
140       //      1 = uint8_t
141       //      2 = uint16_t
142       //      4 = uint32_t
143       //      8 = uint64_t
144       //      s = char *
145       //      b = byte *, size_t (2 arguments)
146       //      c = zchunk_t *
147       //      f = zframe_t *
148       //      h = zhashx_t *
149       //      U = zuuid_t *
150       //      p = void * (sends the pointer value, only meaningful over inproc)
151       //      m = zmsg_t * (sends all frames in the zmsg)
152       //      z = sends zero-sized frame (0 arguments)
153       //      u = uint (deprecated)
154       //
155       //  Note that s, b, c, and f are encoded the same way and the choice is
156       //  offered as a convenience to the sender, which may or may not already
157       //  have data in a zchunk or zframe. Does not change or take ownership of
158       //  any arguments. Returns 0 if successful, -1 if sending failed for any
159       //  reason.
160       CZMQ_EXPORT int
161           zsock_send (void *self, const char *picture, ...);
162
163       //  Send a 'picture' message to the socket (or actor). This is a va_list
164       //  version of zsock_send (), so please consult its documentation for the
165       //  details.
166       CZMQ_EXPORT int
167           zsock_vsend (void *self, const char *picture, va_list argptr);
168
169       //  Receive a 'picture' message to the socket (or actor). See zsock_send for
170       //  the format and meaning of the picture. Returns the picture elements into
171       //  a series of pointers as provided by the caller:
172       //
173       //      i = int * (stores signed integer)
174       //      4 = uint32_t * (stores 32-bit unsigned integer)
175       //      8 = uint64_t * (stores 64-bit unsigned integer)
176       //      s = char ** (allocates new string)
177       //      b = byte **, size_t * (2 arguments) (allocates memory)
178       //      c = zchunk_t ** (creates zchunk)
179       //      f = zframe_t ** (creates zframe)
180       //      U = zuuid_t * (creates a zuuid with the data)
181       //      h = zhashx_t ** (creates zhashx)
182       //      p = void ** (stores pointer)
183       //      m = zmsg_t ** (creates a zmsg with the remaing frames)
184       //      z = null, asserts empty frame (0 arguments)
185       //      u = uint * (stores unsigned integer, deprecated)
186       //
187       //  Note that zsock_recv creates the returned objects, and the caller must
188       //  destroy them when finished with them. The supplied pointers do not need
189       //  to be initialized. Returns 0 if successful, or -1 if it failed to recv
190       //  a message, in which case the pointers are not modified. When message
191       //  frames are truncated (a short message), sets return values to zero/null.
192       //  If an argument pointer is NULL, does not store any value (skips it).
193       //  An 'n' picture matches an empty frame; if the message does not match,
194       //  the method will return -1.
195       CZMQ_EXPORT int
196           zsock_recv (void *self, const char *picture, ...);
197
198       //  Receive a 'picture' message from the socket (or actor). This is a
199       //  va_list version of zsock_recv (), so please consult its documentation
200       //  for the details.
201       CZMQ_EXPORT int
202           zsock_vrecv (void *self, const char *picture, va_list argptr);
203
204       //  Send a binary encoded 'picture' message to the socket (or actor). This
205       //  method is similar to zsock_send, except the arguments are encoded in a
206       //  binary format that is compatible with zproto, and is designed to reduce
207       //  memory allocations. The pattern argument is a string that defines the
208       //  type of each argument. Supports these argument types:
209       //
210       //   pattern    C type                  zproto type:
211       //      1       uint8_t                 type = "number" size = "1"
212       //      2       uint16_t                type = "number" size = "2"
213       //      4       uint32_t                type = "number" size = "3"
214       //      8       uint64_t                type = "number" size = "4"
215       //      s       char *, 0-255 chars     type = "string"
216       //      S       char *, 0-2^32-1 chars  type = "longstr"
217       //      c       zchunk_t *              type = "chunk"
218       //      f       zframe_t *              type = "frame"
219       //      u       zuuid_t *               type = "uuid"
220       //      m       zmsg_t *                type = "msg"
221       //      p       void *, sends pointer value, only over inproc
222       //
223       //  Does not change or take ownership of any arguments. Returns 0 if
224       //  successful, -1 if sending failed for any reason.
225       CZMQ_EXPORT int
226           zsock_bsend (void *self, const char *picture, ...);
227
228       //  Receive a binary encoded 'picture' message from the socket (or actor).
229       //  This method is similar to zsock_recv, except the arguments are encoded
230       //  in a binary format that is compatible with zproto, and is designed to
231       //  reduce memory allocations. The pattern argument is a string that defines
232       //  the type of each argument. See zsock_bsend for the supported argument
233       //  types. All arguments must be pointers; this call sets them to point to
234       //  values held on a per-socket basis.
235       //  For types 1, 2, 4 and 8 the caller must allocate the memory itself before
236       //  calling zsock_brecv.
237       //  For types S, the caller must free the value once finished with it, as
238       //  zsock_brecv will allocate the buffer.
239       //  For type s, the caller must not free the value as it is stored in a
240       //  local cache for performance purposes.
241       //  For types c, f, u and m the caller must call the appropriate destructor
242       //  depending on the object as zsock_brecv will create new objects.
243       //  For type p the caller must coordinate with the sender, as it is just a
244       //  pointer value being passed.
245       CZMQ_EXPORT int
246           zsock_brecv (void *self, const char *picture, ...);
247
248       //  Set socket to use unbounded pipes (HWM=0); use this in cases when you are
249       //  totally certain the message volume can fit in memory. This method works
250       //  across all versions of ZeroMQ. Takes a polymorphic socket reference.
251       CZMQ_EXPORT void
252           zsock_set_unbounded (void *self);
253
254       //  Send a signal over a socket. A signal is a short message carrying a
255       //  success/failure code (by convention, 0 means OK). Signals are encoded
256       //  to be distinguishable from "normal" messages. Accepts a zsock_t or a
257       //  zactor_t argument, and returns 0 if successful, -1 if the signal could
258       //  not be sent. Takes a polymorphic socket reference.
259       CZMQ_EXPORT int
260           zsock_signal (void *self, byte status);
261
262       //  Wait on a signal. Use this to coordinate between threads, over pipe
263       //  pairs. Blocks until the signal is received. Returns -1 on error, 0 or
264       //  greater on success. Accepts a zsock_t or a zactor_t as argument.
265       //  Takes a polymorphic socket reference.
266       CZMQ_EXPORT int
267           zsock_wait (void *self);
268
269       //  If there is a partial message still waiting on the socket, remove and
270       //  discard it. This is useful when reading partial messages, to get specific
271       //  message types.
272       CZMQ_EXPORT void
273           zsock_flush (void *self);
274
275       //  Probe the supplied object, and report if it looks like a zsock_t.
276       //  Takes a polymorphic socket reference.
277       CZMQ_EXPORT bool
278           zsock_is (void *self);
279
280       //  Probe the supplied reference. If it looks like a zsock_t instance, return
281       //  the underlying libzmq socket handle; else if it looks like a file
282       //  descriptor, return NULL; else if it looks like a libzmq socket handle,
283       //  return the supplied value. Takes a polymorphic socket reference.
284       CZMQ_EXPORT void *
285           zsock_resolve (void *self);
286
287       //  Get socket option `heartbeat_ivl`.
288       //  Available from libzmq 4.2.0.
289       //  Caller owns return value and must destroy it when done.
290       CZMQ_EXPORT int
291           zsock_heartbeat_ivl (void *self);
292
293       //  Set socket option `heartbeat_ivl`.
294       //  Available from libzmq 4.2.0.
295       CZMQ_EXPORT void
296           zsock_set_heartbeat_ivl (void *self, int heartbeat_ivl);
297
298       //  Get socket option `heartbeat_ttl`.
299       //  Available from libzmq 4.2.0.
300       //  Caller owns return value and must destroy it when done.
301       CZMQ_EXPORT int
302           zsock_heartbeat_ttl (void *self);
303
304       //  Set socket option `heartbeat_ttl`.
305       //  Available from libzmq 4.2.0.
306       CZMQ_EXPORT void
307           zsock_set_heartbeat_ttl (void *self, int heartbeat_ttl);
308
309       //  Get socket option `heartbeat_timeout`.
310       //  Available from libzmq 4.2.0.
311       //  Caller owns return value and must destroy it when done.
312       CZMQ_EXPORT int
313           zsock_heartbeat_timeout (void *self);
314
315       //  Set socket option `heartbeat_timeout`.
316       //  Available from libzmq 4.2.0.
317       CZMQ_EXPORT void
318           zsock_set_heartbeat_timeout (void *self, int heartbeat_timeout);
319
320       //  Get socket option `use_fd`.
321       //  Available from libzmq 4.2.0.
322       //  Caller owns return value and must destroy it when done.
323       CZMQ_EXPORT int
324           zsock_use_fd (void *self);
325
326       //  Set socket option `use_fd`.
327       //  Available from libzmq 4.2.0.
328       CZMQ_EXPORT void
329           zsock_set_use_fd (void *self, int use_fd);
330
331       //  Set socket option `xpub_manual`.
332       //  Available from libzmq 4.2.0.
333       CZMQ_EXPORT void
334           zsock_set_xpub_manual (void *self, int xpub_manual);
335
336       //  Set socket option `xpub_welcome_msg`.
337       //  Available from libzmq 4.2.0.
338       CZMQ_EXPORT void
339           zsock_set_xpub_welcome_msg (void *self, const char *xpub_welcome_msg);
340
341       //  Set socket option `stream_notify`.
342       //  Available from libzmq 4.2.0.
343       CZMQ_EXPORT void
344           zsock_set_stream_notify (void *self, int stream_notify);
345
346       //  Get socket option `invert_matching`.
347       //  Available from libzmq 4.2.0.
348       //  Caller owns return value and must destroy it when done.
349       CZMQ_EXPORT int
350           zsock_invert_matching (void *self);
351
352       //  Set socket option `invert_matching`.
353       //  Available from libzmq 4.2.0.
354       CZMQ_EXPORT void
355           zsock_set_invert_matching (void *self, int invert_matching);
356
357       //  Set socket option `xpub_verboser`.
358       //  Available from libzmq 4.2.0.
359       CZMQ_EXPORT void
360           zsock_set_xpub_verboser (void *self, int xpub_verboser);
361
362       //  Get socket option `connect_timeout`.
363       //  Available from libzmq 4.2.0.
364       //  Caller owns return value and must destroy it when done.
365       CZMQ_EXPORT int
366           zsock_connect_timeout (void *self);
367
368       //  Set socket option `connect_timeout`.
369       //  Available from libzmq 4.2.0.
370       CZMQ_EXPORT void
371           zsock_set_connect_timeout (void *self, int connect_timeout);
372
373       //  Get socket option `tcp_maxrt`.
374       //  Available from libzmq 4.2.0.
375       //  Caller owns return value and must destroy it when done.
376       CZMQ_EXPORT int
377           zsock_tcp_maxrt (void *self);
378
379       //  Set socket option `tcp_maxrt`.
380       //  Available from libzmq 4.2.0.
381       CZMQ_EXPORT void
382           zsock_set_tcp_maxrt (void *self, int tcp_maxrt);
383
384       //  Get socket option `thread_safe`.
385       //  Available from libzmq 4.2.0.
386       //  Caller owns return value and must destroy it when done.
387       CZMQ_EXPORT int
388           zsock_thread_safe (void *self);
389
390       //  Get socket option `multicast_maxtpdu`.
391       //  Available from libzmq 4.2.0.
392       //  Caller owns return value and must destroy it when done.
393       CZMQ_EXPORT int
394           zsock_multicast_maxtpdu (void *self);
395
396       //  Set socket option `multicast_maxtpdu`.
397       //  Available from libzmq 4.2.0.
398       CZMQ_EXPORT void
399           zsock_set_multicast_maxtpdu (void *self, int multicast_maxtpdu);
400
401       //  Get socket option `vmci_buffer_size`.
402       //  Available from libzmq 4.2.0.
403       //  Caller owns return value and must destroy it when done.
404       CZMQ_EXPORT int
405           zsock_vmci_buffer_size (void *self);
406
407       //  Set socket option `vmci_buffer_size`.
408       //  Available from libzmq 4.2.0.
409       CZMQ_EXPORT void
410           zsock_set_vmci_buffer_size (void *self, int vmci_buffer_size);
411
412       //  Get socket option `vmci_buffer_min_size`.
413       //  Available from libzmq 4.2.0.
414       //  Caller owns return value and must destroy it when done.
415       CZMQ_EXPORT int
416           zsock_vmci_buffer_min_size (void *self);
417
418       //  Set socket option `vmci_buffer_min_size`.
419       //  Available from libzmq 4.2.0.
420       CZMQ_EXPORT void
421           zsock_set_vmci_buffer_min_size (void *self, int vmci_buffer_min_size);
422
423       //  Get socket option `vmci_buffer_max_size`.
424       //  Available from libzmq 4.2.0.
425       //  Caller owns return value and must destroy it when done.
426       CZMQ_EXPORT int
427           zsock_vmci_buffer_max_size (void *self);
428
429       //  Set socket option `vmci_buffer_max_size`.
430       //  Available from libzmq 4.2.0.
431       CZMQ_EXPORT void
432           zsock_set_vmci_buffer_max_size (void *self, int vmci_buffer_max_size);
433
434       //  Get socket option `vmci_connect_timeout`.
435       //  Available from libzmq 4.2.0.
436       //  Caller owns return value and must destroy it when done.
437       CZMQ_EXPORT int
438           zsock_vmci_connect_timeout (void *self);
439
440       //  Set socket option `vmci_connect_timeout`.
441       //  Available from libzmq 4.2.0.
442       CZMQ_EXPORT void
443           zsock_set_vmci_connect_timeout (void *self, int vmci_connect_timeout);
444
445       //  Get socket option `tos`.
446       //  Available from libzmq 4.1.0.
447       //  Caller owns return value and must destroy it when done.
448       CZMQ_EXPORT int
449           zsock_tos (void *self);
450
451       //  Set socket option `tos`.
452       //  Available from libzmq 4.1.0.
453       CZMQ_EXPORT void
454           zsock_set_tos (void *self, int tos);
455
456       //  Set socket option `router_handover`.
457       //  Available from libzmq 4.1.0.
458       CZMQ_EXPORT void
459           zsock_set_router_handover (void *self, int router_handover);
460
461       //  Set socket option `connect_rid`.
462       //  Available from libzmq 4.1.0.
463       CZMQ_EXPORT void
464           zsock_set_connect_rid (void *self, const char *connect_rid);
465
466       //  Set socket option `connect_rid` from 32-octet binary
467       //  Available from libzmq 4.1.0.
468       CZMQ_EXPORT void
469           zsock_set_connect_rid_bin (void *self, const byte *connect_rid);
470
471       //  Get socket option `handshake_ivl`.
472       //  Available from libzmq 4.1.0.
473       //  Caller owns return value and must destroy it when done.
474       CZMQ_EXPORT int
475           zsock_handshake_ivl (void *self);
476
477       //  Set socket option `handshake_ivl`.
478       //  Available from libzmq 4.1.0.
479       CZMQ_EXPORT void
480           zsock_set_handshake_ivl (void *self, int handshake_ivl);
481
482       //  Get socket option `socks_proxy`.
483       //  Available from libzmq 4.1.0.
484       //  Caller owns return value and must destroy it when done.
485       CZMQ_EXPORT char *
486           zsock_socks_proxy (void *self);
487
488       //  Set socket option `socks_proxy`.
489       //  Available from libzmq 4.1.0.
490       CZMQ_EXPORT void
491           zsock_set_socks_proxy (void *self, const char *socks_proxy);
492
493       //  Set socket option `xpub_nodrop`.
494       //  Available from libzmq 4.1.0.
495       CZMQ_EXPORT void
496           zsock_set_xpub_nodrop (void *self, int xpub_nodrop);
497
498       //  Set socket option `router_mandatory`.
499       //  Available from libzmq 4.0.0.
500       CZMQ_EXPORT void
501           zsock_set_router_mandatory (void *self, int router_mandatory);
502
503       //  Set socket option `probe_router`.
504       //  Available from libzmq 4.0.0.
505       CZMQ_EXPORT void
506           zsock_set_probe_router (void *self, int probe_router);
507
508       //  Set socket option `req_relaxed`.
509       //  Available from libzmq 4.0.0.
510       CZMQ_EXPORT void
511           zsock_set_req_relaxed (void *self, int req_relaxed);
512
513       //  Set socket option `req_correlate`.
514       //  Available from libzmq 4.0.0.
515       CZMQ_EXPORT void
516           zsock_set_req_correlate (void *self, int req_correlate);
517
518       //  Set socket option `conflate`.
519       //  Available from libzmq 4.0.0.
520       CZMQ_EXPORT void
521           zsock_set_conflate (void *self, int conflate);
522
523       //  Get socket option `zap_domain`.
524       //  Available from libzmq 4.0.0.
525       //  Caller owns return value and must destroy it when done.
526       CZMQ_EXPORT char *
527           zsock_zap_domain (void *self);
528
529       //  Set socket option `zap_domain`.
530       //  Available from libzmq 4.0.0.
531       CZMQ_EXPORT void
532           zsock_set_zap_domain (void *self, const char *zap_domain);
533
534       //  Get socket option `mechanism`.
535       //  Available from libzmq 4.0.0.
536       //  Caller owns return value and must destroy it when done.
537       CZMQ_EXPORT int
538           zsock_mechanism (void *self);
539
540       //  Get socket option `plain_server`.
541       //  Available from libzmq 4.0.0.
542       //  Caller owns return value and must destroy it when done.
543       CZMQ_EXPORT int
544           zsock_plain_server (void *self);
545
546       //  Set socket option `plain_server`.
547       //  Available from libzmq 4.0.0.
548       CZMQ_EXPORT void
549           zsock_set_plain_server (void *self, int plain_server);
550
551       //  Get socket option `plain_username`.
552       //  Available from libzmq 4.0.0.
553       //  Caller owns return value and must destroy it when done.
554       CZMQ_EXPORT char *
555           zsock_plain_username (void *self);
556
557       //  Set socket option `plain_username`.
558       //  Available from libzmq 4.0.0.
559       CZMQ_EXPORT void
560           zsock_set_plain_username (void *self, const char *plain_username);
561
562       //  Get socket option `plain_password`.
563       //  Available from libzmq 4.0.0.
564       //  Caller owns return value and must destroy it when done.
565       CZMQ_EXPORT char *
566           zsock_plain_password (void *self);
567
568       //  Set socket option `plain_password`.
569       //  Available from libzmq 4.0.0.
570       CZMQ_EXPORT void
571           zsock_set_plain_password (void *self, const char *plain_password);
572
573       //  Get socket option `curve_server`.
574       //  Available from libzmq 4.0.0.
575       //  Caller owns return value and must destroy it when done.
576       CZMQ_EXPORT int
577           zsock_curve_server (void *self);
578
579       //  Set socket option `curve_server`.
580       //  Available from libzmq 4.0.0.
581       CZMQ_EXPORT void
582           zsock_set_curve_server (void *self, int curve_server);
583
584       //  Get socket option `curve_publickey`.
585       //  Available from libzmq 4.0.0.
586       //  Caller owns return value and must destroy it when done.
587       CZMQ_EXPORT char *
588           zsock_curve_publickey (void *self);
589
590       //  Set socket option `curve_publickey`.
591       //  Available from libzmq 4.0.0.
592       CZMQ_EXPORT void
593           zsock_set_curve_publickey (void *self, const char *curve_publickey);
594
595       //  Set socket option `curve_publickey` from 32-octet binary
596       //  Available from libzmq 4.0.0.
597       CZMQ_EXPORT void
598           zsock_set_curve_publickey_bin (void *self, const byte *curve_publickey);
599
600       //  Get socket option `curve_secretkey`.
601       //  Available from libzmq 4.0.0.
602       //  Caller owns return value and must destroy it when done.
603       CZMQ_EXPORT char *
604           zsock_curve_secretkey (void *self);
605
606       //  Set socket option `curve_secretkey`.
607       //  Available from libzmq 4.0.0.
608       CZMQ_EXPORT void
609           zsock_set_curve_secretkey (void *self, const char *curve_secretkey);
610
611       //  Set socket option `curve_secretkey` from 32-octet binary
612       //  Available from libzmq 4.0.0.
613       CZMQ_EXPORT void
614           zsock_set_curve_secretkey_bin (void *self, const byte *curve_secretkey);
615
616       //  Get socket option `curve_serverkey`.
617       //  Available from libzmq 4.0.0.
618       //  Caller owns return value and must destroy it when done.
619       CZMQ_EXPORT char *
620           zsock_curve_serverkey (void *self);
621
622       //  Set socket option `curve_serverkey`.
623       //  Available from libzmq 4.0.0.
624       CZMQ_EXPORT void
625           zsock_set_curve_serverkey (void *self, const char *curve_serverkey);
626
627       //  Set socket option `curve_serverkey` from 32-octet binary
628       //  Available from libzmq 4.0.0.
629       CZMQ_EXPORT void
630           zsock_set_curve_serverkey_bin (void *self, const byte *curve_serverkey);
631
632       //  Get socket option `gssapi_server`.
633       //  Available from libzmq 4.0.0.
634       //  Caller owns return value and must destroy it when done.
635       CZMQ_EXPORT int
636           zsock_gssapi_server (void *self);
637
638       //  Set socket option `gssapi_server`.
639       //  Available from libzmq 4.0.0.
640       CZMQ_EXPORT void
641           zsock_set_gssapi_server (void *self, int gssapi_server);
642
643       //  Get socket option `gssapi_plaintext`.
644       //  Available from libzmq 4.0.0.
645       //  Caller owns return value and must destroy it when done.
646       CZMQ_EXPORT int
647           zsock_gssapi_plaintext (void *self);
648
649       //  Set socket option `gssapi_plaintext`.
650       //  Available from libzmq 4.0.0.
651       CZMQ_EXPORT void
652           zsock_set_gssapi_plaintext (void *self, int gssapi_plaintext);
653
654       //  Get socket option `gssapi_principal`.
655       //  Available from libzmq 4.0.0.
656       //  Caller owns return value and must destroy it when done.
657       CZMQ_EXPORT char *
658           zsock_gssapi_principal (void *self);
659
660       //  Set socket option `gssapi_principal`.
661       //  Available from libzmq 4.0.0.
662       CZMQ_EXPORT void
663           zsock_set_gssapi_principal (void *self, const char *gssapi_principal);
664
665       //  Get socket option `gssapi_service_principal`.
666       //  Available from libzmq 4.0.0.
667       //  Caller owns return value and must destroy it when done.
668       CZMQ_EXPORT char *
669           zsock_gssapi_service_principal (void *self);
670
671       //  Set socket option `gssapi_service_principal`.
672       //  Available from libzmq 4.0.0.
673       CZMQ_EXPORT void
674           zsock_set_gssapi_service_principal (void *self, const char *gssapi_service_principal);
675
676       //  Get socket option `ipv6`.
677       //  Available from libzmq 4.0.0.
678       //  Caller owns return value and must destroy it when done.
679       CZMQ_EXPORT int
680           zsock_ipv6 (void *self);
681
682       //  Set socket option `ipv6`.
683       //  Available from libzmq 4.0.0.
684       CZMQ_EXPORT void
685           zsock_set_ipv6 (void *self, int ipv6);
686
687       //  Get socket option `immediate`.
688       //  Available from libzmq 4.0.0.
689       //  Caller owns return value and must destroy it when done.
690       CZMQ_EXPORT int
691           zsock_immediate (void *self);
692
693       //  Set socket option `immediate`.
694       //  Available from libzmq 4.0.0.
695       CZMQ_EXPORT void
696           zsock_set_immediate (void *self, int immediate);
697
698       //  Get socket option `sndhwm`.
699       //  Available from libzmq 3.0.0.
700       //  Caller owns return value and must destroy it when done.
701       CZMQ_EXPORT int
702           zsock_sndhwm (void *self);
703
704       //  Set socket option `sndhwm`.
705       //  Available from libzmq 3.0.0.
706       CZMQ_EXPORT void
707           zsock_set_sndhwm (void *self, int sndhwm);
708
709       //  Get socket option `rcvhwm`.
710       //  Available from libzmq 3.0.0.
711       //  Caller owns return value and must destroy it when done.
712       CZMQ_EXPORT int
713           zsock_rcvhwm (void *self);
714
715       //  Set socket option `rcvhwm`.
716       //  Available from libzmq 3.0.0.
717       CZMQ_EXPORT void
718           zsock_set_rcvhwm (void *self, int rcvhwm);
719
720       //  Get socket option `maxmsgsize`.
721       //  Available from libzmq 3.0.0.
722       //  Caller owns return value and must destroy it when done.
723       CZMQ_EXPORT int
724           zsock_maxmsgsize (void *self);
725
726       //  Set socket option `maxmsgsize`.
727       //  Available from libzmq 3.0.0.
728       CZMQ_EXPORT void
729           zsock_set_maxmsgsize (void *self, int maxmsgsize);
730
731       //  Get socket option `multicast_hops`.
732       //  Available from libzmq 3.0.0.
733       //  Caller owns return value and must destroy it when done.
734       CZMQ_EXPORT int
735           zsock_multicast_hops (void *self);
736
737       //  Set socket option `multicast_hops`.
738       //  Available from libzmq 3.0.0.
739       CZMQ_EXPORT void
740           zsock_set_multicast_hops (void *self, int multicast_hops);
741
742       //  Set socket option `xpub_verbose`.
743       //  Available from libzmq 3.0.0.
744       CZMQ_EXPORT void
745           zsock_set_xpub_verbose (void *self, int xpub_verbose);
746
747       //  Get socket option `tcp_keepalive`.
748       //  Available from libzmq 3.0.0.
749       //  Caller owns return value and must destroy it when done.
750       CZMQ_EXPORT int
751           zsock_tcp_keepalive (void *self);
752
753       //  Set socket option `tcp_keepalive`.
754       //  Available from libzmq 3.0.0.
755       CZMQ_EXPORT void
756           zsock_set_tcp_keepalive (void *self, int tcp_keepalive);
757
758       //  Get socket option `tcp_keepalive_idle`.
759       //  Available from libzmq 3.0.0.
760       //  Caller owns return value and must destroy it when done.
761       CZMQ_EXPORT int
762           zsock_tcp_keepalive_idle (void *self);
763
764       //  Set socket option `tcp_keepalive_idle`.
765       //  Available from libzmq 3.0.0.
766       CZMQ_EXPORT void
767           zsock_set_tcp_keepalive_idle (void *self, int tcp_keepalive_idle);
768
769       //  Get socket option `tcp_keepalive_cnt`.
770       //  Available from libzmq 3.0.0.
771       //  Caller owns return value and must destroy it when done.
772       CZMQ_EXPORT int
773           zsock_tcp_keepalive_cnt (void *self);
774
775       //  Set socket option `tcp_keepalive_cnt`.
776       //  Available from libzmq 3.0.0.
777       CZMQ_EXPORT void
778           zsock_set_tcp_keepalive_cnt (void *self, int tcp_keepalive_cnt);
779
780       //  Get socket option `tcp_keepalive_intvl`.
781       //  Available from libzmq 3.0.0.
782       //  Caller owns return value and must destroy it when done.
783       CZMQ_EXPORT int
784           zsock_tcp_keepalive_intvl (void *self);
785
786       //  Set socket option `tcp_keepalive_intvl`.
787       //  Available from libzmq 3.0.0.
788       CZMQ_EXPORT void
789           zsock_set_tcp_keepalive_intvl (void *self, int tcp_keepalive_intvl);
790
791       //  Get socket option `tcp_accept_filter`.
792       //  Available from libzmq 3.0.0.
793       //  Caller owns return value and must destroy it when done.
794       CZMQ_EXPORT char *
795           zsock_tcp_accept_filter (void *self);
796
797       //  Set socket option `tcp_accept_filter`.
798       //  Available from libzmq 3.0.0.
799       CZMQ_EXPORT void
800           zsock_set_tcp_accept_filter (void *self, const char *tcp_accept_filter);
801
802       //  Get socket option `last_endpoint`.
803       //  Available from libzmq 3.0.0.
804       //  Caller owns return value and must destroy it when done.
805       CZMQ_EXPORT char *
806           zsock_last_endpoint (void *self);
807
808       //  Set socket option `router_raw`.
809       //  Available from libzmq 3.0.0.
810       CZMQ_EXPORT void
811           zsock_set_router_raw (void *self, int router_raw);
812
813       //  Get socket option `ipv4only`.
814       //  Available from libzmq 3.0.0.
815       //  Caller owns return value and must destroy it when done.
816       CZMQ_EXPORT int
817           zsock_ipv4only (void *self);
818
819       //  Set socket option `ipv4only`.
820       //  Available from libzmq 3.0.0.
821       CZMQ_EXPORT void
822           zsock_set_ipv4only (void *self, int ipv4only);
823
824       //  Set socket option `delay_attach_on_connect`.
825       //  Available from libzmq 3.0.0.
826       CZMQ_EXPORT void
827           zsock_set_delay_attach_on_connect (void *self, int delay_attach_on_connect);
828
829       //  Get socket option `hwm`.
830       //  Available from libzmq 2.0.0 to 3.0.0.
831       //  Caller owns return value and must destroy it when done.
832       CZMQ_EXPORT int
833           zsock_hwm (void *self);
834
835       //  Set socket option `hwm`.
836       //  Available from libzmq 2.0.0 to 3.0.0.
837       CZMQ_EXPORT void
838           zsock_set_hwm (void *self, int hwm);
839
840       //  Get socket option `swap`.
841       //  Available from libzmq 2.0.0 to 3.0.0.
842       //  Caller owns return value and must destroy it when done.
843       CZMQ_EXPORT int
844           zsock_swap (void *self);
845
846       //  Set socket option `swap`.
847       //  Available from libzmq 2.0.0 to 3.0.0.
848       CZMQ_EXPORT void
849           zsock_set_swap (void *self, int swap);
850
851       //  Get socket option `affinity`.
852       //  Available from libzmq 2.0.0.
853       //  Caller owns return value and must destroy it when done.
854       CZMQ_EXPORT int
855           zsock_affinity (void *self);
856
857       //  Set socket option `affinity`.
858       //  Available from libzmq 2.0.0.
859       CZMQ_EXPORT void
860           zsock_set_affinity (void *self, int affinity);
861
862       //  Get socket option `identity`.
863       //  Available from libzmq 2.0.0.
864       //  Caller owns return value and must destroy it when done.
865       CZMQ_EXPORT char *
866           zsock_identity (void *self);
867
868       //  Set socket option `identity`.
869       //  Available from libzmq 2.0.0.
870       CZMQ_EXPORT void
871           zsock_set_identity (void *self, const char *identity);
872
873       //  Get socket option `rate`.
874       //  Available from libzmq 2.0.0.
875       //  Caller owns return value and must destroy it when done.
876       CZMQ_EXPORT int
877           zsock_rate (void *self);
878
879       //  Set socket option `rate`.
880       //  Available from libzmq 2.0.0.
881       CZMQ_EXPORT void
882           zsock_set_rate (void *self, int rate);
883
884       //  Get socket option `recovery_ivl`.
885       //  Available from libzmq 2.0.0.
886       //  Caller owns return value and must destroy it when done.
887       CZMQ_EXPORT int
888           zsock_recovery_ivl (void *self);
889
890       //  Set socket option `recovery_ivl`.
891       //  Available from libzmq 2.0.0.
892       CZMQ_EXPORT void
893           zsock_set_recovery_ivl (void *self, int recovery_ivl);
894
895       //  Get socket option `recovery_ivl_msec`.
896       //  Available from libzmq 2.0.0 to 3.0.0.
897       //  Caller owns return value and must destroy it when done.
898       CZMQ_EXPORT int
899           zsock_recovery_ivl_msec (void *self);
900
901       //  Set socket option `recovery_ivl_msec`.
902       //  Available from libzmq 2.0.0 to 3.0.0.
903       CZMQ_EXPORT void
904           zsock_set_recovery_ivl_msec (void *self, int recovery_ivl_msec);
905
906       //  Get socket option `mcast_loop`.
907       //  Available from libzmq 2.0.0 to 3.0.0.
908       //  Caller owns return value and must destroy it when done.
909       CZMQ_EXPORT int
910           zsock_mcast_loop (void *self);
911
912       //  Set socket option `mcast_loop`.
913       //  Available from libzmq 2.0.0 to 3.0.0.
914       CZMQ_EXPORT void
915           zsock_set_mcast_loop (void *self, int mcast_loop);
916
917       //  Get socket option `rcvtimeo`.
918       //  Available from libzmq 2.2.0.
919       //  Caller owns return value and must destroy it when done.
920       CZMQ_EXPORT int
921           zsock_rcvtimeo (void *self);
922
923       //  Set socket option `rcvtimeo`.
924       //  Available from libzmq 2.2.0.
925       CZMQ_EXPORT void
926           zsock_set_rcvtimeo (void *self, int rcvtimeo);
927
928       //  Get socket option `sndtimeo`.
929       //  Available from libzmq 2.2.0.
930       //  Caller owns return value and must destroy it when done.
931       CZMQ_EXPORT int
932           zsock_sndtimeo (void *self);
933
934       //  Set socket option `sndtimeo`.
935       //  Available from libzmq 2.2.0.
936       CZMQ_EXPORT void
937           zsock_set_sndtimeo (void *self, int sndtimeo);
938
939       //  Get socket option `sndbuf`.
940       //  Available from libzmq 2.0.0.
941       //  Caller owns return value and must destroy it when done.
942       CZMQ_EXPORT int
943           zsock_sndbuf (void *self);
944
945       //  Set socket option `sndbuf`.
946       //  Available from libzmq 2.0.0.
947       CZMQ_EXPORT void
948           zsock_set_sndbuf (void *self, int sndbuf);
949
950       //  Get socket option `rcvbuf`.
951       //  Available from libzmq 2.0.0.
952       //  Caller owns return value and must destroy it when done.
953       CZMQ_EXPORT int
954           zsock_rcvbuf (void *self);
955
956       //  Set socket option `rcvbuf`.
957       //  Available from libzmq 2.0.0.
958       CZMQ_EXPORT void
959           zsock_set_rcvbuf (void *self, int rcvbuf);
960
961       //  Get socket option `linger`.
962       //  Available from libzmq 2.0.0.
963       //  Caller owns return value and must destroy it when done.
964       CZMQ_EXPORT int
965           zsock_linger (void *self);
966
967       //  Set socket option `linger`.
968       //  Available from libzmq 2.0.0.
969       CZMQ_EXPORT void
970           zsock_set_linger (void *self, int linger);
971
972       //  Get socket option `reconnect_ivl`.
973       //  Available from libzmq 2.0.0.
974       //  Caller owns return value and must destroy it when done.
975       CZMQ_EXPORT int
976           zsock_reconnect_ivl (void *self);
977
978       //  Set socket option `reconnect_ivl`.
979       //  Available from libzmq 2.0.0.
980       CZMQ_EXPORT void
981           zsock_set_reconnect_ivl (void *self, int reconnect_ivl);
982
983       //  Get socket option `reconnect_ivl_max`.
984       //  Available from libzmq 2.0.0.
985       //  Caller owns return value and must destroy it when done.
986       CZMQ_EXPORT int
987           zsock_reconnect_ivl_max (void *self);
988
989       //  Set socket option `reconnect_ivl_max`.
990       //  Available from libzmq 2.0.0.
991       CZMQ_EXPORT void
992           zsock_set_reconnect_ivl_max (void *self, int reconnect_ivl_max);
993
994       //  Get socket option `backlog`.
995       //  Available from libzmq 2.0.0.
996       //  Caller owns return value and must destroy it when done.
997       CZMQ_EXPORT int
998           zsock_backlog (void *self);
999
1000       //  Set socket option `backlog`.
1001       //  Available from libzmq 2.0.0.
1002       CZMQ_EXPORT void
1003           zsock_set_backlog (void *self, int backlog);
1004
1005       //  Set socket option `subscribe`.
1006       //  Available from libzmq 2.0.0.
1007       CZMQ_EXPORT void
1008           zsock_set_subscribe (void *self, const char *subscribe);
1009
1010       //  Set socket option `unsubscribe`.
1011       //  Available from libzmq 2.0.0.
1012       CZMQ_EXPORT void
1013           zsock_set_unsubscribe (void *self, const char *unsubscribe);
1014
1015       //  Get socket option `type`.
1016       //  Available from libzmq 2.0.0.
1017       //  Caller owns return value and must destroy it when done.
1018       CZMQ_EXPORT int
1019           zsock_type (void *self);
1020
1021       //  Get socket option `rcvmore`.
1022       //  Available from libzmq 2.0.0.
1023       //  Caller owns return value and must destroy it when done.
1024       CZMQ_EXPORT int
1025           zsock_rcvmore (void *self);
1026
1027       //  Get socket option `fd`.
1028       //  Available from libzmq 2.0.0.
1029       //  Caller owns return value and must destroy it when done.
1030       CZMQ_EXPORT SOCKET
1031           zsock_fd (void *self);
1032
1033       //  Get socket option `events`.
1034       //  Available from libzmq 2.0.0.
1035       //  Caller owns return value and must destroy it when done.
1036       CZMQ_EXPORT int
1037           zsock_events (void *self);
1038
1039       //  Self test of this class.
1040       CZMQ_EXPORT void
1041           zsock_test (bool verbose);
1042
1043       #ifdef CZMQ_BUILD_DRAFT_API
1044       //  *** Draft method, for development use, may change without warning ***
1045       //  Create a SERVER socket. Default action is bind.
1046       CZMQ_EXPORT zsock_t *
1047           zsock_new_server (const char *endpoint);
1048
1049       //  *** Draft method, for development use, may change without warning ***
1050       //  Create a CLIENT socket. Default action is connect.
1051       CZMQ_EXPORT zsock_t *
1052           zsock_new_client (const char *endpoint);
1053
1054       //  *** Draft method, for development use, may change without warning ***
1055       //  Create a RADIO socket. Default action is bind.
1056       CZMQ_EXPORT zsock_t *
1057           zsock_new_radio (const char *endpoint);
1058
1059       //  *** Draft method, for development use, may change without warning ***
1060       //  Create a DISH socket. Default action is connect.
1061       CZMQ_EXPORT zsock_t *
1062           zsock_new_dish (const char *endpoint);
1063
1064       //  *** Draft method, for development use, may change without warning ***
1065       //  Create a GATHER socket. Default action is bind.
1066       CZMQ_EXPORT zsock_t *
1067           zsock_new_gather (const char *endpoint);
1068
1069       //  *** Draft method, for development use, may change without warning ***
1070       //  Create a SCATTER socket. Default action is connect.
1071       CZMQ_EXPORT zsock_t *
1072           zsock_new_scatter (const char *endpoint);
1073
1074       //  *** Draft method, for development use, may change without warning ***
1075       //  Return socket routing ID if any. This returns 0 if the socket is not
1076       //  of type ZMQ_SERVER or if no request was already received on it.
1077       CZMQ_EXPORT uint32_t
1078           zsock_routing_id (zsock_t *self);
1079
1080       //  *** Draft method, for development use, may change without warning ***
1081       //  Set routing ID on socket. The socket MUST be of type ZMQ_SERVER.
1082       //  This will be used when sending messages on the socket via the zsock API.
1083       CZMQ_EXPORT void
1084           zsock_set_routing_id (zsock_t *self, uint32_t routing_id);
1085
1086       //  *** Draft method, for development use, may change without warning ***
1087       //  Join a group for the RADIO-DISH pattern. Call only on ZMQ_DISH.
1088       //  Returns 0 if OK, -1 if failed.
1089       CZMQ_EXPORT int
1090           zsock_join (void *self, const char *group);
1091
1092       //  *** Draft method, for development use, may change without warning ***
1093       //  Leave a group for the RADIO-DISH pattern. Call only on ZMQ_DISH.
1094       //  Returns 0 if OK, -1 if failed.
1095       CZMQ_EXPORT int
1096           zsock_leave (void *self, const char *group);
1097
1098       #endif // CZMQ_BUILD_DRAFT_API
1099       Please add '@interface' section in './../src/zsock.c'.
1100

DESCRIPTION

1102       The zsock class wraps the libzmq socket handle (a void *) with a proper
1103       structure that follows the CLASS rules for construction and
1104       destruction. Some zsock methods take a void * "polymorphic" reference,
1105       which can be either a zsock_t or a zactor_t reference, or a libzmq void
1106       *.
1107
1108       Please add @discuss section in ./../src/zsock.c.
1109

EXAMPLE

1111       From zsock_test method.
1112
1113           zsock_t *writer = zsock_new (ZMQ_PUSH);
1114           assert (writer);
1115           int port = zsock_bind (writer, "tcp://127.0.0.1:*");
1116           assert (port != -1);
1117           assert (zsock_resolve (writer) != writer);
1118           assert (streq (zsock_type_str (writer), "PUSH"));
1119
1120           int rc;
1121           #if (ZMQ_VERSION >= ZMQ_MAKE_VERSION (3, 2, 0))
1122           //  Check unbind
1123           rc = zsock_unbind (writer, "tcp://127.0.0.1:%d", port);
1124           assert (rc == 0);
1125
1126           //  In some cases and especially when running under Valgrind, doing
1127           //  a bind immediately after an unbind causes an EADDRINUSE error.
1128           //  Even a short sleep allows the OS to release the port for reuse.
1129           zclock_sleep (100);
1130
1131           //  Bind again
1132           rc = zsock_bind (writer, "tcp://127.0.0.1:%d", port);
1133           assert (rc == port);
1134           char endpoint [40];
1135           sprintf (endpoint, "tcp://127.0.0.1:%d", port);
1136           assert (streq (zsock_endpoint (writer), endpoint));
1137           #endif
1138
1139           zsock_t *reader = zsock_new (ZMQ_PULL);
1140           assert (reader);
1141           rc = zsock_connect (reader, "tcp://127.0.0.1:%d", port);
1142           assert (rc != -1);
1143           assert (zsock_resolve (reader) != reader);
1144           assert (streq (zsock_type_str (reader), "PULL"));
1145
1146           //  Basic Hello, World
1147           zstr_send (writer, "Hello, World");
1148           zmsg_t *msg = zmsg_recv (reader);
1149           assert (msg);
1150           char *string = zmsg_popstr (msg);
1151           assert (streq (string, "Hello, World"));
1152           freen (string);
1153           zmsg_destroy (&msg);
1154
1155           //  Test resolve libzmq socket
1156           #if (ZMQ_VERSION >= ZMQ_MAKE_VERSION (3, 2, 0))
1157           void *zmq_ctx = zmq_ctx_new ();
1158           #else
1159           void *zmq_ctx = zmq_ctx_new (1);
1160           #endif
1161           assert (zmq_ctx);
1162           void *zmq_sock = zmq_socket (zmq_ctx, ZMQ_PUB);
1163           assert (zmq_sock);
1164           assert (zsock_resolve (zmq_sock) == zmq_sock);
1165           zmq_close (zmq_sock);
1166           zmq_ctx_term (zmq_ctx);
1167
1168           //  Test resolve zsock
1169           zsock_t *resolve = zsock_new_pub("@tcp://127.0.0.1:*");
1170           assert (resolve);
1171           assert (zsock_resolve (resolve) == resolve->handle);
1172           zsock_destroy (&resolve);
1173
1174           //  Test resolve FD
1175           SOCKET fd = zsock_fd (reader);
1176           assert (zsock_resolve ((void *) &fd) == NULL);
1177
1178           //  Test binding to ephemeral ports, sequential and random
1179           port = zsock_bind (writer, "tcp://127.0.0.1:*");
1180           assert (port >= DYNAMIC_FIRST && port <= DYNAMIC_LAST);
1181           port = zsock_bind (writer, "tcp://127.0.0.1:*[50000-]");
1182           assert (port >= 50000 && port <= DYNAMIC_LAST);
1183           port = zsock_bind (writer, "tcp://127.0.0.1:*[-50001]");
1184           assert (port >= DYNAMIC_FIRST && port <= 50001);
1185           port = zsock_bind (writer, "tcp://127.0.0.1:*[60000-60500]");
1186           assert (port >= 60000 && port <= 60500);
1187
1188           port = zsock_bind (writer, "tcp://127.0.0.1:!");
1189           assert (port >= DYNAMIC_FIRST && port <= DYNAMIC_LAST);
1190           port = zsock_bind (writer, "tcp://127.0.0.1:![50000-]");
1191           assert (port >= 50000 && port <= DYNAMIC_LAST);
1192           port = zsock_bind (writer, "tcp://127.0.0.1:![-50001]");
1193           assert (port >= DYNAMIC_FIRST && port <= 50001);
1194           port = zsock_bind (writer, "tcp://127.0.0.1:![60000-60500]");
1195           assert (port >= 60000 && port <= 60500);
1196
1197           //  Test zsock_attach method
1198           zsock_t *dealer = zsock_new (ZMQ_DEALER);
1199           assert (dealer);
1200           rc = zsock_attach (dealer, "@inproc://myendpoint,tcp://127.0.0.1:*,inproc://others", true);
1201           assert (rc == 0);
1202           rc = zsock_attach (dealer, "", false);
1203           assert (rc == 0);
1204           rc = zsock_attach (dealer, NULL, true);
1205           assert (rc == 0);
1206           rc = zsock_attach (dealer, ">a,@b, c,, ", false);
1207           assert (rc == -1);
1208           zsock_destroy (&dealer);
1209
1210           //  Test zsock_endpoint method
1211           rc = zsock_bind (writer, "inproc://test.%s", "writer");
1212           assert (rc == 0);
1213           assert (streq (zsock_endpoint (writer), "inproc://test.writer"));
1214
1215           //  Test error state when connecting to an invalid socket type
1216           //  ('txp://' instead of 'tcp://', typo intentional)
1217           rc = zsock_connect (reader, "txp://127.0.0.1:5560");
1218           assert (rc == -1);
1219
1220           //  Test signal/wait methods
1221           rc = zsock_signal (writer, 123);
1222           assert (rc == 0);
1223           rc = zsock_wait (reader);
1224           assert (rc == 123);
1225
1226           //  Test zsock_send/recv pictures
1227           uint8_t  number1 = 123;
1228           uint16_t number2 = 123 * 123;
1229           uint32_t number4 = 123 * 123;
1230           number4 *= 123;
1231           uint32_t number4_MAX = UINT32_MAX;
1232           uint64_t number8 = 123 * 123;
1233           number8 *= 123;
1234           number8 *= 123;
1235           uint64_t number8_MAX = UINT64_MAX;
1236
1237           zchunk_t *chunk = zchunk_new ("HELLO", 5);
1238           assert (chunk);
1239           zframe_t *frame = zframe_new ("WORLD", 5);
1240           assert (frame);
1241           zhashx_t *hash = zhashx_new ();
1242           assert (hash);
1243           zuuid_t *uuid = zuuid_new ();
1244           assert (uuid);
1245           zhashx_set_destructor (hash, (zhashx_destructor_fn *) zstr_free);
1246           zhashx_set_duplicator (hash, (zhashx_duplicator_fn *) strdup);
1247           zhashx_insert (hash, "1", "value A");
1248           zhashx_insert (hash, "2", "value B");
1249           char *original = "pointer";
1250
1251           //  Test zsock_recv into each supported type
1252           zsock_send (writer, "i124488zsbcfUhp",
1253                       -12345, number1, number2, number4, number4_MAX,
1254                       number8, number8_MAX,
1255                       "This is a string", "ABCDE", 5,
1256                       chunk, frame, uuid, hash, original);
1257           char *uuid_str = strdup (zuuid_str (uuid));
1258           zchunk_destroy (&chunk);
1259           zframe_destroy (&frame);
1260           zuuid_destroy (&uuid);
1261           zhashx_destroy (&hash);
1262
1263           int integer;
1264           byte *data;
1265           size_t size;
1266           char *pointer;
1267           number8_MAX = number8 = number4_MAX = number4 = number2 = number1 = 0ULL;
1268           rc = zsock_recv (reader, "i124488zsbcfUhp",
1269                            &integer, &number1, &number2, &number4, &number4_MAX,
1270                            &number8, &number8_MAX, &string, &data, &size, &chunk,
1271                            &frame, &uuid, &hash, &pointer);
1272           assert (rc == 0);
1273           assert (integer == -12345);
1274           assert (number1 == 123);
1275           assert (number2 == 123 * 123);
1276           assert (number4 == 123 * 123 * 123);
1277           assert (number4_MAX == UINT32_MAX);
1278           assert (number8 == 123 * 123 * 123 * 123);
1279           assert (number8_MAX == UINT64_MAX);
1280           assert (streq (string, "This is a string"));
1281           assert (memcmp (data, "ABCDE", 5) == 0);
1282           assert (size == 5);
1283           assert (memcmp (zchunk_data (chunk), "HELLO", 5) == 0);
1284           assert (zchunk_size (chunk) == 5);
1285           assert (streq (uuid_str, zuuid_str (uuid)));
1286           assert (memcmp (zframe_data (frame), "WORLD", 5) == 0);
1287           assert (zframe_size (frame) == 5);
1288           char *value = (char *) zhashx_lookup (hash, "1");
1289           assert (streq (value, "value A"));
1290           value = (char *) zhashx_lookup (hash, "2");
1291           assert (streq (value, "value B"));
1292           assert (original == pointer);
1293           freen (string);
1294           freen (data);
1295           freen (uuid_str);
1296           zframe_destroy (&frame);
1297           zchunk_destroy (&chunk);
1298           zhashx_destroy (&hash);
1299           zuuid_destroy (&uuid);
1300
1301           //  Test zsock_recv of short message; this lets us return a failure
1302           //  with a status code and then nothing else; the receiver will get
1303           //  the status code and NULL/zero for all other values
1304           zsock_send (writer, "i", -1);
1305           zsock_recv (reader, "izsbcfp",
1306               &integer, &string, &data, &size, &chunk, &frame, &pointer);
1307           assert (integer == -1);
1308           assert (string == NULL);
1309           assert (data == NULL);
1310           assert (size == 0);
1311           assert (chunk == NULL);
1312           assert (frame == NULL);
1313           assert (pointer == NULL);
1314
1315           msg = zmsg_new ();
1316           zmsg_addstr (msg, "frame 1");
1317           zmsg_addstr (msg, "frame 2");
1318           zsock_send (writer, "szm", "header", msg);
1319           zmsg_destroy (&msg);
1320
1321           zsock_recv (reader, "szm", &string, &msg);
1322
1323           assert (streq ("header", string));
1324           assert (zmsg_size (msg) == 2);
1325           assert (zframe_streq (zmsg_first (msg), "frame 1"));
1326           assert (zframe_streq (zmsg_next (msg), "frame 2"));
1327           zstr_free (&string);
1328           zmsg_destroy (&msg);
1329
1330           //  Test zsock_recv with null arguments
1331           chunk = zchunk_new ("HELLO", 5);
1332           assert (chunk);
1333           frame = zframe_new ("WORLD", 5);
1334           assert (frame);
1335           zsock_send (writer, "izsbcfp",
1336                       -12345, "This is a string", "ABCDE", 5, chunk, frame, original);
1337           zframe_destroy (&frame);
1338           zchunk_destroy (&chunk);
1339           zsock_recv (reader, "izsbcfp", &integer, NULL, NULL, NULL, &chunk, NULL, NULL);
1340           assert (integer == -12345);
1341           assert (memcmp (zchunk_data (chunk), "HELLO", 5) == 0);
1342           assert (zchunk_size (chunk) == 5);
1343           zchunk_destroy (&chunk);
1344
1345           //  Test zsock_bsend/brecv pictures with binary encoding
1346           frame = zframe_new ("Hello", 5);
1347           chunk = zchunk_new ("World", 5);
1348
1349           msg = zmsg_new ();
1350           zmsg_addstr (msg, "Hello");
1351           zmsg_addstr (msg, "World");
1352
1353           zsock_bsend (writer, "1248sSpcfm",
1354                        number1, number2, number4, number8,
1355                        "Hello, World",
1356                        "Goodbye cruel World!",
1357                        original,
1358                        chunk, frame, msg);
1359           zchunk_destroy (&chunk);
1360           zframe_destroy (&frame);
1361           zmsg_destroy (&msg);
1362
1363           number8 = number4 = number2 = number1 = 0;
1364           char *longstr;
1365           zsock_brecv (reader, "1248sSpcfm",
1366                        &number1, &number2, &number4, &number8,
1367                        &string, &longstr,
1368                        &pointer,
1369                        &chunk, &frame, &msg);
1370           assert (number1 == 123);
1371           assert (number2 == 123 * 123);
1372           assert (number4 == 123 * 123 * 123);
1373           assert (number8 == 123 * 123 * 123 * 123);
1374           assert (streq (string, "Hello, World"));
1375           assert (streq (longstr, "Goodbye cruel World!"));
1376           assert (pointer == original);
1377           zstr_free (&longstr);
1378           zchunk_destroy (&chunk);
1379           zframe_destroy (&frame);
1380           zmsg_destroy (&msg);
1381
1382           #ifdef ZMQ_SERVER
1383
1384           //  Test zsock_bsend/brecv pictures with binary encoding on SERVER and CLIENT sockets
1385           zsock_t *server = zsock_new (ZMQ_SERVER);
1386           assert (server);
1387           port = zsock_bind (server, "tcp://127.0.0.1:*");
1388           assert (port != -1);
1389           zsock_t* client = zsock_new (ZMQ_CLIENT);
1390           assert (client);
1391           rc = zsock_connect (client, "tcp://127.0.0.1:%d", port);
1392           assert (rc != -1);
1393
1394           //  From client to server
1395           chunk = zchunk_new ("World", 5);
1396           zsock_bsend (client, "1248sSpc",
1397                        number1, number2, number4, number8,
1398                        "Hello, World",
1399                        "Goodbye cruel World!",
1400                        original,
1401                        chunk);
1402           zchunk_destroy (&chunk);
1403
1404           number8 = number4 = number2 = number1 = 0;
1405           zsock_brecv (server, "1248sSpc",
1406                        &number1, &number2, &number4, &number8,
1407                        &string, &longstr,
1408                        &pointer,
1409                        &chunk);
1410           assert (number1 == 123);
1411           assert (number2 == 123 * 123);
1412           assert (number4 == 123 * 123 * 123);
1413           assert (number8 == 123 * 123 * 123 * 123);
1414           assert (streq (string, "Hello, World"));
1415           assert (streq (longstr, "Goodbye cruel World!"));
1416           assert (pointer == original);
1417           assert (zsock_routing_id (server));
1418           zstr_free (&longstr);
1419           zchunk_destroy (&chunk);
1420
1421           //  From server to client
1422           chunk = zchunk_new ("World", 5);
1423           zsock_bsend (server, "1248sSpc",
1424                        number1, number2, number4, number8,
1425                        "Hello, World",
1426                        "Goodbye cruel World!",
1427                        original,
1428                        chunk);
1429           zchunk_destroy (&chunk);
1430
1431           number8 = number4 = number2 = number1 = 0;
1432           zsock_brecv (client, "1248sSpc",
1433                        &number1, &number2, &number4, &number8,
1434                        &string, &longstr,
1435                        &pointer,
1436                        &chunk);
1437           assert (number1 == 123);
1438           assert (number2 == 123 * 123);
1439           assert (number4 == 123 * 123 * 123);
1440           assert (number8 == 123 * 123 * 123 * 123);
1441           assert (streq (string, "Hello, World"));
1442           assert (streq (longstr, "Goodbye cruel World!"));
1443           assert (pointer == original);
1444           assert (zsock_routing_id (client) == 0);
1445           zstr_free (&longstr);
1446           zchunk_destroy (&chunk);
1447
1448           zsock_destroy (&client);
1449           zsock_destroy (&server);
1450
1451           #else
1452           errno = 0;
1453           zsock_t* server = zsock_new_server (NULL);
1454           assert(server == NULL);
1455           assert(errno == ENOTSUP);
1456
1457           errno = 0;
1458           zsock_t* client = zsock_new_client (NULL);
1459           assert(client == NULL);
1460           assert(errno == ENOTSUP);
1461           #endif
1462
1463           #ifdef ZMQ_SCATTER
1464
1465           zsock_t* gather = zsock_new_gather ("inproc://test-gather-scatter");
1466           assert (gather);
1467           zsock_t* scatter = zsock_new_scatter ("inproc://test-gather-scatter");
1468           assert (scatter);
1469
1470           rc = zstr_send (scatter, "HELLO");
1471           assert (rc == 0);
1472
1473           char* message;
1474           message = zstr_recv (gather);
1475           assert (streq(message, "HELLO"));
1476           zstr_free (&message);
1477
1478           zsock_destroy (&gather);
1479           zsock_destroy (&scatter);
1480           #else
1481           errno = 0;
1482           zsock_t* scatter = zsock_new_scatter (NULL);
1483           assert(scatter == NULL);
1484           assert(errno == ENOTSUP);
1485
1486           errno = 0;
1487           zsock_t* gather = zsock_new_gather (NULL);
1488           assert(gather == NULL);
1489           assert(errno == ENOTSUP);
1490           #endif
1491
1492           #ifndef ZMQ_RADIO
1493           errno = 0;
1494           zsock_t* radio = zsock_new_radio (NULL);
1495           assert(radio == NULL);
1496           assert(errno == ENOTSUP);
1497
1498           errno = 0;
1499           zsock_t* dish = zsock_new_dish (NULL);
1500           assert(dish == NULL);
1501           assert(errno == ENOTSUP);
1502
1503           errno = 0;
1504           zsock_t* sock = zsock_new_req (NULL); // any supported socket type
1505           rc = zsock_join (sock, "group1");
1506           assert(rc == -1);
1507           assert(errno == ENOTSUP);
1508           errno = 0;
1509           rc = zsock_leave (sock, "group1");
1510           assert(rc == -1);
1511           assert(errno == ENOTSUP);
1512           zsock_destroy (&sock);
1513           #endif
1514
1515           //  Check that we can send a zproto format message
1516           zsock_bsend (writer, "1111sS4", 0xAA, 0xA0, 0x02, 0x01, "key", "value", 1234);
1517           zgossip_msg_t *gossip = zgossip_msg_new ();
1518           zgossip_msg_recv (gossip, reader);
1519           assert (zgossip_msg_id (gossip) == ZGOSSIP_MSG_PUBLISH);
1520           zgossip_msg_destroy (&gossip);
1521
1522           zsock_destroy (&reader);
1523           zsock_destroy (&writer);
1524
1525

AUTHORS

1527       The czmq manual was written by the authors in the AUTHORS file.
1528

RESOURCES

1530       Main web site:
1531
1532       Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
1533
1535       Copyright (c) the Contributors as noted in the AUTHORS file. This file
1536       is part of CZMQ, the high-level C binding for 0MQ:
1537       http://czmq.zeromq.org. This Source Code Form is subject to the terms
1538       of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
1539       distributed with this file, You can obtain one at
1540       http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
1541       distribution.
1542

NOTES

1544        1. zeromq-dev@lists.zeromq.org
1545           mailto:zeromq-dev@lists.zeromq.org
1546
1547
1548
1549CZMQ 4.1.1                        01/31/2019                          ZSOCK(3)
Impressum