/doc/zmq_setsockopt.txt

  1zmq_setsockopt(3)
  2=================
  3
  4
  5NAME
  6----
  7
  8zmq_setsockopt - set 0MQ socket options
  9
 10
 11SYNOPSIS
 12--------
 13*int zmq_setsockopt (void '*socket', int 'option_name', const void '*option_value', size_t 'option_len');*
 14
 15Caution: All options, with the exception of ZMQ_SUBSCRIBE, ZMQ_UNSUBSCRIBE,
 16ZMQ_LINGER, ZMQ_ROUTER_MANDATORY and ZMQ_XPUB_VERBOSE only take effect for 
 17subsequent socket bind/connects.
 18
 19DESCRIPTION
 20-----------
 21The _zmq_setsockopt()_ function shall set the option specified by the
 22'option_name' argument to the value pointed to by the 'option_value' argument
 23for the 0MQ socket pointed to by the 'socket' argument. The 'option_len'
 24argument is the size of the option value in bytes.
 25
 26The following socket options can be set with the _zmq_setsockopt()_ function:
 27
 28
 29ZMQ_SNDHWM: Set high water mark for outbound messages
 30~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 31The 'ZMQ_SNDHWM' option shall set the high water mark for outbound messages on
 32the specified 'socket'. The high water mark is a hard limit on the maximum
 33number of outstanding messages 0MQ shall queue in memory for any single peer
 34that the specified 'socket' is communicating with. A value of zero means no
 35limit.
 36
 37If this limit has been reached the socket shall enter an exceptional state and
 38depending on the socket type, 0MQ shall take appropriate action such as
 39blocking or dropping sent messages. Refer to the individual socket descriptions
 40in linkzmq:zmq_socket[3] for details on the exact action taken for each socket
 41type.
 42
 43NOTE: 0MQ does not guarantee that the socket will accept as many as ZMQ_SNDHWM
 44messages, and the actual limit may be as much as 60-70% lower depending on the
 45flow of messages on the socket.
 46
 47[horizontal]
 48Option value type:: int
 49Option value unit:: messages
 50Default value:: 1000
 51Applicable socket types:: all
 52
 53
 54ZMQ_RCVHWM: Set high water mark for inbound messages
 55~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 56The 'ZMQ_RCVHWM' option shall set the high water mark for inbound messages on
 57the specified 'socket'. The high water mark is a hard limit on the maximum
 58number of outstanding messages 0MQ shall queue in memory for any single peer
 59that the specified 'socket' is communicating with. A value of zero means no
 60limit.
 61
 62If this limit has been reached the socket shall enter an exceptional state and
 63depending on the socket type, 0MQ shall take appropriate action such as
 64blocking or dropping sent messages. Refer to the individual socket descriptions
 65in linkzmq:zmq_socket[3] for details on the exact action taken for each socket
 66type.
 67
 68[horizontal]
 69Option value type:: int
 70Option value unit:: messages
 71Default value:: 1000
 72Applicable socket types:: all
 73
 74
 75ZMQ_AFFINITY: Set I/O thread affinity
 76~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 77The 'ZMQ_AFFINITY' option shall set the I/O thread affinity for newly created
 78connections on the specified 'socket'.
 79
 80Affinity determines which threads from the 0MQ I/O thread pool associated with
 81the socket's _context_ shall handle newly created connections.  A value of zero
 82specifies no affinity, meaning that work shall be distributed fairly among all
 830MQ I/O threads in the thread pool. For non-zero values, the lowest bit
 84corresponds to thread 1, second lowest bit to thread 2 and so on.  For example,
 85a value of 3 specifies that subsequent connections on 'socket' shall be handled
 86exclusively by I/O threads 1 and 2.
 87
 88See also linkzmq:zmq_init[3] for details on allocating the number of I/O
 89threads for a specific _context_.
 90
 91[horizontal]
 92Option value type:: uint64_t
 93Option value unit:: N/A (bitmap)
 94Default value:: 0
 95Applicable socket types:: N/A
 96
 97
 98ZMQ_SUBSCRIBE: Establish message filter
 99~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
100The 'ZMQ_SUBSCRIBE' option shall establish a new message filter on a 'ZMQ_SUB'
101socket. Newly created 'ZMQ_SUB' sockets shall filter out all incoming messages,
102therefore you should call this option to establish an initial message filter.
103
104An empty 'option_value' of length zero shall subscribe to all incoming
105messages. A non-empty 'option_value' shall subscribe to all messages beginning
106with the specified prefix. Multiple filters may be attached to a single
107'ZMQ_SUB' socket, in which case a message shall be accepted if it matches at
108least one filter.
109
110[horizontal]
111Option value type:: binary data
112Option value unit:: N/A
113Default value:: N/A
114Applicable socket types:: ZMQ_SUB
115
116
117ZMQ_UNSUBSCRIBE: Remove message filter
118~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
119The 'ZMQ_UNSUBSCRIBE' option shall remove an existing message filter on a
120'ZMQ_SUB' socket. The filter specified must match an existing filter previously
121established with the 'ZMQ_SUBSCRIBE' option. If the socket has several
122instances of the same filter attached the 'ZMQ_UNSUBSCRIBE' option shall remove
123only one instance, leaving the rest in place and functional.
124
125[horizontal]
126Option value type:: binary data
127Option value unit:: N/A
128Default value:: N/A
129Applicable socket types:: ZMQ_SUB
130
131
132ZMQ_IDENTITY: Set socket identity
133~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
134The 'ZMQ_IDENTITY' option shall set the identity of the specified 'socket'.
135Socket identity is used only by request/reply pattern. Namely, it can be used
136in tandem with ROUTER socket to route messages to the peer with specific
137identity.
138
139Identity should be at least one byte and at most 255 bytes long. Identities
140starting with binary zero are reserved for use by 0MQ infrastructure.
141
142If two peers use the same identity when connecting to a third peer, the
143results shall be undefined.
144
145[horizontal]
146Option value type:: binary data
147Option value unit:: N/A
148Default value:: NULL
149Applicable socket types:: all
150
151
152ZMQ_RATE: Set multicast data rate
153~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
154The 'ZMQ_RATE' option shall set the maximum send or receive data rate for
155multicast transports such as linkzmq:zmq_pgm[7] using the specified 'socket'.
156
157[horizontal]
158Option value type:: int
159Option value unit:: kilobits per second
160Default value:: 100
161Applicable socket types:: all, when using multicast transports
162
163
164ZMQ_RECOVERY_IVL: Set multicast recovery interval
165~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
166The 'ZMQ_RECOVERY_IVL' option shall set the recovery interval for multicast
167transports using the specified 'socket'. The recovery interval determines the
168maximum time in milliseconds that a receiver can be absent from a multicast
169group before unrecoverable data loss will occur.
170
171CAUTION: Exercise care when setting large recovery intervals as the data
172needed for recovery will be held in memory. For example, a 1 minute recovery
173interval at a data rate of 1Gbps requires a 7GB in-memory buffer.
174
175[horizontal]
176Option value type:: int
177Option value unit:: milliseconds
178Default value:: 10000
179Applicable socket types:: all, when using multicast transports
180
181ZMQ_SNDBUF: Set kernel transmit buffer size
182~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
183The 'ZMQ_SNDBUF' option shall set the underlying kernel transmit buffer size
184for the 'socket' to the specified size in bytes.  A value of zero means leave
185the OS default unchanged. For details please refer to your operating system
186documentation for the 'SO_SNDBUF' socket option.
187
188[horizontal]
189Option value type:: int
190Option value unit:: bytes
191Default value:: 0
192Applicable socket types:: all
193
194
195ZMQ_RCVBUF: Set kernel receive buffer size
196~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
197The 'ZMQ_RCVBUF' option shall set the underlying kernel receive buffer size for
198the 'socket' to the specified size in bytes.  A value of zero means leave the
199OS default unchanged. For details refer to your operating system documentation
200for the 'SO_RCVBUF' socket option.
201
202[horizontal]
203Option value type:: int
204Option value unit:: bytes
205Default value:: 0
206Applicable socket types:: all
207
208
209ZMQ_LINGER: Set linger period for socket shutdown
210~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
211The 'ZMQ_LINGER' option shall set the linger period for the specified 'socket'.
212The linger period determines how long pending messages which have yet to be
213sent to a peer shall linger in memory after a socket is closed with
214linkzmq:zmq_close[3], and further affects the termination of the socket's
215context with linkzmq:zmq_term[3]. The following outlines the different
216behaviours:
217
218* The default value of '-1' specifies an infinite linger period. Pending
219  messages shall not be discarded after a call to _zmq_close()_; attempting to
220  terminate the socket's context with _zmq_term()_ shall block until all
221  pending messages have been sent to a peer.
222
223* The value of '0' specifies no linger period. Pending messages shall be
224  discarded immediately when the socket is closed with _zmq_close()_.
225
226* Positive values specify an upper bound for the linger period in milliseconds.
227  Pending messages shall not be discarded after a call to _zmq_close()_;
228  attempting to terminate the socket's context with _zmq_term()_ shall block
229  until either all pending messages have been sent to a peer, or the linger
230  period expires, after which any pending messages shall be discarded.
231
232[horizontal]
233Option value type:: int
234Option value unit:: milliseconds
235Default value:: -1 (infinite)
236Applicable socket types:: all
237
238
239ZMQ_RECONNECT_IVL: Set reconnection interval
240~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
241The 'ZMQ_RECONNECT_IVL' option shall set the initial reconnection interval for
242the specified 'socket'.  The reconnection interval is the period 0MQ
243shall wait between attempts to reconnect disconnected peers when using
244connection-oriented transports. The value -1 means no reconnection.
245
246NOTE: The reconnection interval may be randomized by 0MQ to prevent
247reconnection storms in topologies with a large number of peers per socket.
248
249[horizontal]
250Option value type:: int
251Option value unit:: milliseconds
252Default value:: 100
253Applicable socket types:: all, only for connection-oriented transports
254
255
256ZMQ_RECONNECT_IVL_MAX: Set maximum reconnection interval
257~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
258The 'ZMQ_RECONNECT_IVL_MAX' option shall set the maximum reconnection interval 
259for the specified 'socket'.  This is the maximum period 0MQ shall wait between
260attempts to reconnect. On each reconnect attempt, the previous interval shall be
261doubled untill ZMQ_RECONNECT_IVL_MAX is reached. This allows for exponential
262backoff strategy. Default value means no exponential backoff is performed and
263reconnect interval calculations are only based on ZMQ_RECONNECT_IVL.
264
265NOTE:  Values less than ZMQ_RECONNECT_IVL will be ignored.
266
267[horizontal]
268Option value type:: int
269Option value unit:: milliseconds
270Default value:: 0 (only use ZMQ_RECONNECT_IVL)
271Applicable socket types:: all, only for connection-oriented transports
272
273
274ZMQ_BACKLOG: Set maximum length of the queue of outstanding connections
275~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
276The 'ZMQ_BACKLOG' option shall set the maximum length of the queue of
277outstanding peer connections for the specified 'socket'; this only applies to
278connection-oriented transports. For details refer to your operating system
279documentation for the 'listen' function.
280
281[horizontal]
282Option value type:: int
283Option value unit:: connections
284Default value:: 100
285Applicable socket types:: all, only for connection-oriented transports.
286
287
288ZMQ_MAXMSGSIZE: Maximum acceptable inbound message size
289~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
290
291Limits the size of the inbound message. If a peer sends a message larger than
292ZMQ_MAXMSGSIZE it is disconnected. Value of -1 means 'no limit'.
293
294[horizontal]
295Option value type:: int64_t
296Option value unit:: bytes
297Default value:: -1
298Applicable socket types:: all
299
300
301ZMQ_MULTICAST_HOPS: Maximum network hops for multicast packets
302~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
303
304Sets the time-to-live field in every multicast packet sent from this socket.
305The default is 1 which means that the multicast packets don't leave the local
306network.
307
308[horizontal]
309Option value type:: int
310Option value unit:: network hops
311Default value:: 1
312Applicable socket types:: all, when using multicast transports
313
314
315ZMQ_RCVTIMEO: Maximum time before a recv operation returns with EAGAIN
316~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
317
318Sets the timeout for receive operation on the socket. If the value is `0`,
319_zmq_recv(3)_ will return immediately, with a EAGAIN error if there is no
320message to receive. If the value is `-1`, it will block until a message is
321available. For all other values, it will wait for a message for that amount
322of time before returning with an EAGAIN error.
323
324[horizontal]
325Option value type:: int
326Option value unit:: milliseconds
327Default value:: -1 (infinite)
328Applicable socket types:: all
329
330
331ZMQ_SNDTIMEO: Maximum time before a send operation returns with EAGAIN
332~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
333
334Sets the timeout for send operation on the socket. If the value is `0`,
335_zmq_send(3)_ will return immediately, with a EAGAIN error if the message
336cannot be sent. If the value is `-1`, it will block until the message is sent.
337For all other values, it will try to send the message for that amount of time
338before returning with an EAGAIN error.
339
340[horizontal]
341Option value type:: int
342Option value unit:: milliseconds
343Default value:: -1 (infinite)
344Applicable socket types:: all
345
346
347ZMQ_IPV6: Enable IPv6 on socket
348~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
349
350Set the IPv6 option for the socket. A value of `1` means IPv6 is
351enabled on the socket, while `0` means the socket will use only IPv4.
352When IPv6 is enabled the socket will connect to, or accept connections
353from, both IPv4 and IPv6 hosts.
354
355[horizontal]
356Option value type:: int
357Option value unit:: boolean
358Default value:: 0 (false)
359Applicable socket types:: all, when using TCP transports.
360
361
362ZMQ_IPV4ONLY: Use IPv4-only on socket
363~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
364
365Set the IPv4-only option for the socket. This option is deprecated.
366Please use the ZMQ_IPV6 option.
367
368[horizontal]
369Option value type:: int
370Option value unit:: boolean
371Default value:: 1 (true)
372Applicable socket types:: all, when using TCP transports.
373
374
375ZMQ_IMMEDIATE: Queue messages only to completed connections
376~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
377
378By default queues will fill on outgoing connections even if the connection has
379not completed. This can lead to "lost" messages on sockets with round-robin
380routing (REQ, PUSH, DEALER). If this option is set to `1`, messages shall be
381queued only to completed connections. This will cause the socket to block if
382there are no other connections, but will prevent queues from filling on pipes
383awaiting connection.
384
385[horizontal]
386Option value type:: int
387Option value unit:: boolean
388Default value:: 0 (false)
389Applicable socket types:: all, only for connection-oriented transports.
390
391
392ZMQ_ROUTER_MANDATORY: accept only routable messages on ROUTER sockets
393~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
394
395Sets the 'ROUTER' socket behavior when an unroutable message is encountered. A 
396value of `0` is the default and discards the message silently when it cannot be 
397routed.  A value of `1` returns an 'EHOSTUNREACH' error code if the message
398cannot be routed.
399
400[horizontal]
401Option value type:: int
402Option value unit:: 0, 1
403Default value:: 0
404Applicable socket types:: ZMQ_ROUTER
405
406
407ZMQ_ROUTER_RAW: switch ROUTER socket to raw mode
408~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
409
410Sets the raw mode on the 'ROUTER', when set to 1. When the ROUTER socket is in
411raw mode, and when using the tcp:// transport, it will read and write TCP data
412without 0MQ framing. This lets 0MQ applications talk to non-0MQ applications.
413When using raw mode, you cannot set explicit identities, and the ZMQ_MSGMORE
414flag is ignored when sending data messages. In raw mode you can close a specific
415connection by sending it a zero-length message (following the identity frame).
416
417[horizontal]
418Option value type:: int
419Option value unit:: 0, 1
420Default value:: 0
421Applicable socket types:: ZMQ_ROUTER
422
423
424ZMQ_XPUB_VERBOSE: provide all subscription messages on XPUB sockets
425~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
426
427Sets the 'XPUB' socket behavior on new subscriptions and unsubscriptions. 
428A value of '0' is the default and passes only new subscription messages to 
429upstream. A value of '1' passes all subscription messages upstream.
430
431[horizontal]
432Option value type:: int
433Option value unit:: 0, 1
434Default value:: 0
435Applicable socket types:: ZMQ_XPUB
436
437
438ZMQ_TCP_KEEPALIVE: Override SO_KEEPALIVE socket option
439~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
440Override 'SO_KEEPALIVE' socket option(where supported by OS).
441The default value of `-1` means to skip any overrides and leave it to OS default.
442
443[horizontal]
444Option value type:: int
445Option value unit:: -1,0,1
446Default value:: -1 (leave to OS default)
447Applicable socket types:: all, when using TCP transports.
448
449
450ZMQ_TCP_KEEPALIVE_IDLE: Override TCP_KEEPCNT(or TCP_KEEPALIVE on some OS)
451~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
452Override 'TCP_KEEPCNT'(or 'TCP_KEEPALIVE' on some OS) socket option(where supported by OS).
453The default value of `-1` means to skip any overrides and leave it to OS default.
454
455[horizontal]
456Option value type:: int
457Option value unit:: -1,>0
458Default value:: -1 (leave to OS default)
459Applicable socket types:: all, when using TCP transports.
460
461
462ZMQ_TCP_KEEPALIVE_CNT: Override TCP_KEEPCNT socket option
463~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
464Override 'TCP_KEEPCNT' socket option(where supported by OS).
465The default value of `-1` means to skip any overrides and leave it to OS default.
466
467[horizontal]
468Option value type:: int
469Option value unit:: -1,>0
470Default value:: -1 (leave to OS default)
471Applicable socket types:: all, when using TCP transports.
472
473
474ZMQ_TCP_KEEPALIVE_INTVL: Override TCP_KEEPINTVL socket option
475~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
476Override 'TCP_KEEPINTVL' socket option(where supported by OS).
477The default value of `-1` means to skip any overrides and leave it to OS default.
478
479[horizontal]
480Option value type:: int
481Option value unit:: -1,>0
482Default value:: -1 (leave to OS default)
483Applicable socket types:: all, when using TCP transports.
484
485
486ZMQ_TCP_ACCEPT_FILTER: Assign filters to allow new TCP connections
487~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
488Assign arbitrary number of filters that will be applied for each new TCP transport
489connection on a listening socket.
490If no filters applied, then TCP transport allows connections from any ip.
491If at least one filter is applied then new connection source ip should be matched.
492To clear all filters call zmq_setsockopt(socket, ZMQ_TCP_ACCEPT_FILTER, NULL, 0).
493Filter is a null-terminated string with ipv6 or ipv4 CIDR.
494
495[horizontal]
496Option value type:: binary data
497Option value unit:: N/A
498Default value:: no filters (allow from all)
499Applicable socket types:: all listening sockets, when using TCP transports.
500
501
502RETURN VALUE
503------------
504The _zmq_setsockopt()_ function shall return zero if successful. Otherwise it
505shall return `-1` and set 'errno' to one of the values defined below.
506
507ERRORS
508------
509*EINVAL*::
510The requested option _option_name_ is unknown, or the requested _option_len_ or
511_option_value_ is invalid.
512*ETERM*::
513The 0MQ 'context' associated with the specified 'socket' was terminated.
514*ENOTSOCK*::
515The provided 'socket' was invalid.
516*EINTR*::
517The operation was interrupted by delivery of a signal.
518
519
520EXAMPLE
521-------
522.Subscribing to messages on a 'ZMQ_SUB' socket
523----
524/* Subscribe to all messages */
525rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "", 0);
526assert (rc == 0);
527/* Subscribe to messages prefixed with "ANIMALS.CATS" */
528rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "ANIMALS.CATS", 12);
529----
530
531.Setting I/O thread affinity
532----
533int64_t affinity;
534/* Incoming connections on TCP port 5555 shall be handled by I/O thread 1 */
535affinity = 1;
536rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof affinity);
537assert (rc);
538rc = zmq_bind (socket, "tcp://lo:5555");
539assert (rc);
540/* Incoming connections on TCP port 5556 shall be handled by I/O thread 2 */
541affinity = 2;
542rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof affinity);
543assert (rc);
544rc = zmq_bind (socket, "tcp://lo:5556");
545assert (rc);
546----
547
548
549SEE ALSO
550--------
551linkzmq:zmq_getsockopt[3]
552linkzmq:zmq_socket[3]
553linkzmq:zmq[7]
554
555
556AUTHORS
557-------
558This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and
559Martin Lucina <mato@kotelna.sk>.