PageRenderTime 20ms CodeModel.GetById 2ms app.highlight 7ms RepoModel.GetById 1ms app.codeStats 0ms

/extension/libzmq/doc/zmq_setsockopt.txt

https://github.com/mccheung/avbot
Plain Text | 881 lines | 696 code | 185 blank | 0 comment | 0 complexity | 170177567e7ae2bf353fa6c7980a4b45 MD5 | raw file
  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_HANDOVER, ZMQ_ROUTER_MANDATORY, ZMQ_PROBE_ROUTER,
 17ZMQ_XPUB_VERBOSE, ZMQ_REQ_CORRELATE, and ZMQ_REQ_RELAXED, only take effect for
 18subsequent socket bind/connects.
 19
 20Specifically, security options take effect for subsequent bind/connect calls,
 21and can be changed at any time to affect subsequent binds and/or connects.
 22
 23DESCRIPTION
 24-----------
 25The _zmq_setsockopt()_ function shall set the option specified by the
 26'option_name' argument to the value pointed to by the 'option_value' argument
 27for the 0MQ socket pointed to by the 'socket' argument. The 'option_len'
 28argument is the size of the option value in bytes.
 29
 30The following socket options can be set with the _zmq_setsockopt()_ function:
 31
 32
 33ZMQ_AFFINITY: Set I/O thread affinity
 34~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 35The 'ZMQ_AFFINITY' option shall set the I/O thread affinity for newly created
 36connections on the specified 'socket'.
 37
 38Affinity determines which threads from the 0MQ I/O thread pool associated with
 39the socket's _context_ shall handle newly created connections.  A value of zero
 40specifies no affinity, meaning that work shall be distributed fairly among all
 410MQ I/O threads in the thread pool. For non-zero values, the lowest bit
 42corresponds to thread 1, second lowest bit to thread 2 and so on.  For example,
 43a value of 3 specifies that subsequent connections on 'socket' shall be handled
 44exclusively by I/O threads 1 and 2.
 45
 46See also linkzmq:zmq_init[3] for details on allocating the number of I/O
 47threads for a specific _context_.
 48
 49[horizontal]
 50Option value type:: uint64_t
 51Option value unit:: N/A (bitmap)
 52Default value:: 0
 53Applicable socket types:: N/A
 54
 55
 56ZMQ_BACKLOG: Set maximum length of the queue of outstanding connections
 57~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 58The 'ZMQ_BACKLOG' option shall set the maximum length of the queue of
 59outstanding peer connections for the specified 'socket'; this only applies to
 60connection-oriented transports. For details refer to your operating system
 61documentation for the 'listen' function.
 62
 63[horizontal]
 64Option value type:: int
 65Option value unit:: connections
 66Default value:: 100
 67Applicable socket types:: all, only for connection-oriented transports.
 68
 69
 70ZMQ_CONNECT_RID: Assign the next outbound connection id 
 71~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 72The 'ZMQ_CONNECT_RID' option sets the peer id of the next host connected 
 73via the zmq_connect() call, and immediately readies that connection for 
 74data transfer with the named id.  This option applies only to the first
 75subsequent call to zmq_connect(), calls thereafter use default connection 
 76behavior. 
 77
 78Typical use is to set this socket option ahead of each zmq_connect() attempt 
 79to a new host. Each connection MUST be assigned a unique name. Assigning a 
 80name that is already in use is not allowed. 
 81
 82Useful when connecting ROUTER to ROUTER, or STREAM to STREAM, as it 
 83allows for immediate sending to peers. Outbound id framing requirements 
 84for ROUTER and STREAM sockets apply.
 85
 86The peer id should be from 1 to 255 bytes long and MAY NOT start with 
 87binary zero.
 88
 89[horizontal]
 90Option value type:: binary data
 91Option value unit:: N/A
 92Default value:: NULL
 93Applicable socket types:: ZMQ_ROUTER, ZMQ_STREAM
 94
 95
 96ZMQ_CONFLATE: Keep only last message
 97~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 98If set, a socket shall keep only one message in its inbound/outbound
 99queue, this message being the last message received/the last message
100to be sent. Ignores 'ZMQ_RCVHWM' and 'ZMQ_SNDHWM' options. Does not
101support multi-part messages, in particular, only one part of it is kept
102in the socket internal queue.
103
104[horizontal]
105Option value type:: int
106Option value unit:: boolean
107Default value:: 0 (false)
108Applicable socket types:: ZMQ_PULL, ZMQ_PUSH, ZMQ_SUB, ZMQ_PUB, ZMQ_DEALER
109
110
111ZMQ_CURVE_PUBLICKEY: Set CURVE public key
112~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
113Sets the socket's long term public key. You must set this on CURVE client
114sockets, see linkzmq:zmq_curve[7]. You can provide the key as 32 binary
115bytes, or as a 40-character string encoded in the Z85 encoding format.
116The public key must always be used with the matching secret key. To
117generate a public/secret key pair, use linkzmq:zmq_curve_keypair[3].
118
119[horizontal]
120Option value type:: binary data or Z85 text string
121Option value size:: 32 or 40
122Default value:: NULL
123Applicable socket types:: all, when using TCP transport
124
125
126ZMQ_CURVE_SECRETKEY: Set CURVE secret key
127~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
128Sets the socket's long term secret key. You must set this on both CURVE
129client and server sockets, see linkzmq:zmq_curve[7]. You can provide the
130key as 32 binary bytes, or as a 40-character string encoded in the Z85
131encoding format. To generate a public/secret key pair, use
132linkzmq:zmq_curve_keypair[3].
133
134[horizontal]
135Option value type:: binary data or Z85 text string
136Option value size:: 32 or 40
137Default value:: NULL
138Applicable socket types:: all, when using TCP transport
139
140
141ZMQ_CURVE_SERVER: Set CURVE server role
142~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
143Defines whether the socket will act as server for CURVE security, see
144linkzmq:zmq_curve[7]. A value of '1' means the socket will act as
145CURVE server. A value of '0' means the socket will not act as CURVE
146server, and its security role then depends on other option settings.
147Setting this to '0' shall reset the socket security to NULL. When you
148set this you must also set the server's secret key using the
149ZMQ_CURVE_SECRETKEY option. A server socket does not need to know
150its own public key.
151
152[horizontal]
153Option value type:: int
154Option value unit:: 0, 1
155Default value:: 0
156Applicable socket types:: all, when using TCP transport
157
158
159ZMQ_CURVE_SERVERKEY: Set CURVE server key
160~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
161Sets the socket's long term server key. You must set this on CURVE client
162sockets, see linkzmq:zmq_curve[7]. You can provide the key as 32 binary
163bytes, or as a 40-character string encoded in the Z85 encoding format.
164This key must have been generated together with the server's secret key.
165
166[horizontal]
167Option value type:: binary data or Z85 text string
168Option value size:: 32 or 40
169Default value:: NULL
170Applicable socket types:: all, when using TCP transport
171
172
173ZMQ_HANDSHAKE_IVL: Set maximum handshake interval
174~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
175The 'ZMQ_HANDSHAKE_IVL' option shall set the maximum handshake interval for
176the specified 'socket'. Handshaking is the exchange of socket configuration
177information (socket type, identity, security) that occurs when a connection
178is first opened, only for connection-oriented transports. If handshaking does
179not complete within the configured time, the connection shall be closed.
180The value 0 means no handshake time limit.
181
182[horizontal]
183Option value type:: int
184Option value unit:: milliseconds
185Default value:: 30000
186Applicable socket types:: all but ZMQ_STREAM, only for connection-oriented transports
187
188
189ZMQ_IDENTITY: Set socket identity
190~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
191The 'ZMQ_IDENTITY' option shall set the identity of the specified 'socket'
192when connecting to a ROUTER socket. The identity should be from 1 to 255
193bytes long and may contain any values.
194
195If two clients use the same identity when connecting to a ROUTER, the
196results shall depend on the ZMQ_ROUTER_HANDOVER option setting. If that
197is not set (or set to the default of zero), the ROUTER socket shall reject
198clients trying to connect with an already-used identity. If that option
199is set to 1, the ROUTER socket shall hand-over the connection to the new
200client and disconnect the existing one.
201
202[horizontal]
203Option value type:: binary data
204Option value unit:: N/A
205Default value:: NULL
206Applicable socket types:: ZMQ_REQ, ZMQ_REP, ZMQ_ROUTER, ZMQ_DEALER.
207
208
209ZMQ_IMMEDIATE: Queue messages only to completed connections
210~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
211By default queues will fill on outgoing connections even if the connection has
212not completed. This can lead to "lost" messages on sockets with round-robin
213routing (REQ, PUSH, DEALER). If this option is set to `1`, messages shall be
214queued only to completed connections. This will cause the socket to block if
215there are no other connections, but will prevent queues from filling on pipes
216awaiting connection.
217
218[horizontal]
219Option value type:: int
220Option value unit:: boolean
221Default value:: 0 (false)
222Applicable socket types:: all, only for connection-oriented transports.
223
224
225ZMQ_IPC_FILTER_GID: Assign group ID filters to allow new IPC connections
226~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
227Assign an arbitrary number of filters that will be applied for each new IPC
228transport connection on a listening socket. If no IPC filters are applied, then
229the IPC transport allows connections from any process. If at least one UID,
230GID, or PID filter is applied then new connection credentials should be
231matched. To clear all GID filters call zmq_setsockopt(socket,
232ZMQ_IPC_FILTER_GID, NULL, 0).
233
234NOTE: GID filters are only available on platforms supporting SO_PEERCRED or
235LOCAL_PEERCRED socket options (currently only Linux and later versions of
236OS X).
237
238[horizontal]
239Option value type:: gid_t
240Option value unit:: N/A
241Default value:: no filters (allow from all)
242Applicable socket types:: all listening sockets, when using IPC transports.
243
244
245ZMQ_IPC_FILTER_PID: Assign process ID filters to allow new IPC connections
246~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
247Assign an arbitrary number of filters that will be applied for each new IPC
248transport connection on a listening socket. If no IPC filters are applied, then
249the IPC transport allows connections from any process. If at least one UID,
250GID, or PID filter is applied then new connection credentials should be
251matched. To clear all PID filters call zmq_setsockopt(socket,
252ZMQ_IPC_FILTER_PID, NULL, 0).
253
254NOTE: PID filters are only available on platforms supporting the SO_PEERCRED
255socket option (currently only Linux).
256
257[horizontal]
258Option value type:: pid_t
259Option value unit:: N/A
260Default value:: no filters (allow from all)
261Applicable socket types:: all listening sockets, when using IPC transports.
262
263
264ZMQ_IPC_FILTER_UID: Assign user ID filters to allow new IPC connections
265~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
266Assign an arbitrary number of filters that will be applied for each new IPC
267transport connection on a listening socket. If no IPC filters are applied, then
268the IPC transport allows connections from any process. If at least one UID,
269GID, or PID filter is applied then new connection credentials should be
270matched. To clear all UID filters call zmq_setsockopt(socket,
271ZMQ_IPC_FILTER_UID, NULL, 0).
272
273NOTE: UID filters are only available on platforms supporting SO_PEERCRED or
274LOCAL_PEERCRED socket options (currently only Linux and later versions of
275OS X).
276
277[horizontal]
278Option value type:: uid_t
279Option value unit:: N/A
280Default value:: no filters (allow from all)
281Applicable socket types:: all listening sockets, when using IPC transports.
282
283
284ZMQ_IPV4ONLY: Use IPv4-only on socket
285~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
286Set the IPv4-only option for the socket. This option is deprecated.
287Please use the ZMQ_IPV6 option.
288
289[horizontal]
290Option value type:: int
291Option value unit:: boolean
292Default value:: 1 (true)
293Applicable socket types:: all, when using TCP transports.
294
295
296ZMQ_IPV6: Enable IPv6 on socket
297~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
298Set the IPv6 option for the socket. A value of `1` means IPv6 is
299enabled on the socket, while `0` means the socket will use only IPv4.
300When IPv6 is enabled the socket will connect to, or accept connections
301from, both IPv4 and IPv6 hosts.
302
303[horizontal]
304Option value type:: int
305Option value unit:: boolean
306Default value:: 0 (false)
307Applicable socket types:: all, when using TCP transports.
308
309
310ZMQ_LINGER: Set linger period for socket shutdown
311~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
312The 'ZMQ_LINGER' option shall set the linger period for the specified 'socket'.
313The linger period determines how long pending messages which have yet to be
314sent to a peer shall linger in memory after a socket is disconnected with
315linkzmq:zmq_disconnect[3] or closed with linkzmq:zmq_close[3], and further
316affects the termination of the socket's context with linkzmq:zmq_term[3]. The
317following outlines the different behaviours:
318
319* The default value of '-1' specifies an infinite linger period. Pending
320  messages shall not be discarded after a call to _zmq_disconnect()_ or
321  _zmq_close()_; attempting to terminate the socket's context with _zmq_term()_
322  shall block until all pending messages have been sent to a peer.
323
324* The value of '0' specifies no linger period. Pending messages shall be
325  discarded immediately after a call to _zmq_disconnect()_ or _zmq_close()_.
326
327* Positive values specify an upper bound for the linger period in milliseconds.
328  Pending messages shall not be discarded after a call to _zmq_disconnect()_ or
329  _zmq_close()_; attempting to terminate the socket's context with _zmq_term()_
330  shall block until either all pending messages have been sent to a peer, or the
331  linger period expires, after which any pending messages shall be discarded.
332
333[horizontal]
334Option value type:: int
335Option value unit:: milliseconds
336Default value:: -1 (infinite)
337Applicable socket types:: all
338
339
340ZMQ_MAXMSGSIZE: Maximum acceptable inbound message size
341~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
342Limits the size of the inbound message. If a peer sends a message larger than
343ZMQ_MAXMSGSIZE it is disconnected. Value of -1 means 'no limit'.
344
345[horizontal]
346Option value type:: int64_t
347Option value unit:: bytes
348Default value:: -1
349Applicable socket types:: all
350
351
352ZMQ_MULTICAST_HOPS: Maximum network hops for multicast packets
353~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
354Sets the time-to-live field in every multicast packet sent from this socket.
355The default is 1 which means that the multicast packets don't leave the local
356network.
357
358[horizontal]
359Option value type:: int
360Option value unit:: network hops
361Default value:: 1
362Applicable socket types:: all, when using multicast transports
363
364
365ZMQ_PLAIN_PASSWORD: Set PLAIN security password
366~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
367Sets the password for outgoing connections over TCP or IPC. If you set this
368to a non-null value, the security mechanism used for connections shall be
369PLAIN, see linkzmq:zmq_plain[7]. If you set this to a null value, the security
370mechanism used for connections shall be NULL, see linkzmq:zmq_null[3].
371
372[horizontal]
373Option value type:: character string
374Option value unit:: N/A
375Default value:: not set
376Applicable socket types:: all, when using TCP transport
377
378
379ZMQ_PLAIN_SERVER: Set PLAIN server role
380~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
381Defines whether the socket will act as server for PLAIN security, see
382linkzmq:zmq_plain[7]. A value of '1' means the socket will act as
383PLAIN server. A value of '0' means the socket will not act as PLAIN
384server, and its security role then depends on other option settings.
385Setting this to '0' shall reset the socket security to NULL.
386
387[horizontal]
388Option value type:: int
389Option value unit:: 0, 1
390Default value:: 0
391Applicable socket types:: all, when using TCP transport
392
393
394ZMQ_PLAIN_USERNAME: Set PLAIN security username
395~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
396Sets the username for outgoing connections over TCP or IPC. If you set this
397to a non-null value, the security mechanism used for connections shall be
398PLAIN, see linkzmq:zmq_plain[7]. If you set this to a null value, the security
399mechanism used for connections shall be NULL, see linkzmq:zmq_null[3].
400
401[horizontal]
402Option value type:: character string
403Option value unit:: N/A
404Default value:: not set
405Applicable socket types:: all, when using TCP transport
406
407
408ZMQ_PROBE_ROUTER: bootstrap connections to ROUTER sockets
409~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
410When set to 1, the socket will automatically send an empty message when a
411new connection is made or accepted. You may set this on REQ, DEALER, or
412ROUTER sockets connected to a ROUTER socket. The application must filter
413such empty messages. The ZMQ_PROBE_ROUTER option in effect provides the
414ROUTER application with an event signaling the arrival of a new peer.
415
416NOTE: do not set this option on a socket that talks to any other socket
417types: the results are undefined.
418
419[horizontal]
420Option value type:: int
421Option value unit:: 0, 1
422Default value:: 0
423Applicable socket types:: ZMQ_ROUTER, ZMQ_DEALER, ZMQ_REQ
424
425
426ZMQ_RATE: Set multicast data rate
427~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
428The 'ZMQ_RATE' option shall set the maximum send or receive data rate for
429multicast transports such as linkzmq:zmq_pgm[7] using the specified 'socket'.
430
431[horizontal]
432Option value type:: int
433Option value unit:: kilobits per second
434Default value:: 100
435Applicable socket types:: all, when using multicast transports
436
437
438ZMQ_RCVBUF: Set kernel receive buffer size
439~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
440The 'ZMQ_RCVBUF' option shall set the underlying kernel receive buffer size for
441the 'socket' to the specified size in bytes.  A value of zero means leave the
442OS default unchanged. For details refer to your operating system documentation
443for the 'SO_RCVBUF' socket option.
444
445[horizontal]
446Option value type:: int
447Option value unit:: bytes
448Default value:: 0
449Applicable socket types:: all
450
451
452ZMQ_RCVHWM: Set high water mark for inbound messages
453~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
454The 'ZMQ_RCVHWM' option shall set the high water mark for inbound messages on
455the specified 'socket'. The high water mark is a hard limit on the maximum
456number of outstanding messages 0MQ shall queue in memory for any single peer
457that the specified 'socket' is communicating with. A value of zero means no
458limit.
459
460If this limit has been reached the socket shall enter an exceptional state and
461depending on the socket type, 0MQ shall take appropriate action such as
462blocking or dropping sent messages. Refer to the individual socket descriptions
463in linkzmq:zmq_socket[3] for details on the exact action taken for each socket
464type.
465
466[horizontal]
467Option value type:: int
468Option value unit:: messages
469Default value:: 1000
470Applicable socket types:: all
471
472
473ZMQ_RCVTIMEO: Maximum time before a recv operation returns with EAGAIN
474~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
475Sets the timeout for receive operation on the socket. If the value is `0`,
476_zmq_recv(3)_ will return immediately, with a EAGAIN error if there is no
477message to receive. If the value is `-1`, it will block until a message is
478available. For all other values, it will wait for a message for that amount
479of time before returning with an EAGAIN error.
480
481[horizontal]
482Option value type:: int
483Option value unit:: milliseconds
484Default value:: -1 (infinite)
485Applicable socket types:: all
486
487
488ZMQ_RECONNECT_IVL: Set reconnection interval
489~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
490The 'ZMQ_RECONNECT_IVL' option shall set the initial reconnection interval for
491the specified 'socket'.  The reconnection interval is the period 0MQ
492shall wait between attempts to reconnect disconnected peers when using
493connection-oriented transports. The value -1 means no reconnection.
494
495NOTE: The reconnection interval may be randomized by 0MQ to prevent
496reconnection storms in topologies with a large number of peers per socket.
497
498[horizontal]
499Option value type:: int
500Option value unit:: milliseconds
501Default value:: 100
502Applicable socket types:: all, only for connection-oriented transports
503
504
505ZMQ_RECONNECT_IVL_MAX: Set maximum reconnection interval
506~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
507The 'ZMQ_RECONNECT_IVL_MAX' option shall set the maximum reconnection interval
508for the specified 'socket'.  This is the maximum period 0MQ shall wait between
509attempts to reconnect. On each reconnect attempt, the previous interval shall be
510doubled untill ZMQ_RECONNECT_IVL_MAX is reached. This allows for exponential
511backoff strategy. Default value means no exponential backoff is performed and
512reconnect interval calculations are only based on ZMQ_RECONNECT_IVL.
513
514NOTE:  Values less than ZMQ_RECONNECT_IVL will be ignored.
515
516[horizontal]
517Option value type:: int
518Option value unit:: milliseconds
519Default value:: 0 (only use ZMQ_RECONNECT_IVL)
520Applicable socket types:: all, only for connection-oriented transports
521
522
523ZMQ_RECOVERY_IVL: Set multicast recovery interval
524~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
525The 'ZMQ_RECOVERY_IVL' option shall set the recovery interval for multicast
526transports using the specified 'socket'. The recovery interval determines the
527maximum time in milliseconds that a receiver can be absent from a multicast
528group before unrecoverable data loss will occur.
529
530CAUTION: Exercise care when setting large recovery intervals as the data
531needed for recovery will be held in memory. For example, a 1 minute recovery
532interval at a data rate of 1Gbps requires a 7GB in-memory buffer.
533
534[horizontal]
535Option value type:: int
536Option value unit:: milliseconds
537Default value:: 10000
538Applicable socket types:: all, when using multicast transports
539
540
541ZMQ_REQ_CORRELATE: match replies with requests
542~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
543The default behavior of REQ sockets is to rely on the ordering of messages to
544match requests and responses and that is usually sufficient. When this option
545is set to 1, the REQ socket will prefix outgoing messages with an extra frame
546containing a request id. That means the full message is (request id, 0,
547user frames...). The REQ socket will discard all incoming messages that don't
548begin with these two frames.
549
550[horizontal]
551Option value type:: int
552Option value unit:: 0, 1
553Default value:: 0
554Applicable socket types:: ZMQ_REQ
555
556
557ZMQ_REQ_RELAXED: relax strict alternation between request and reply
558~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
559By default, a REQ socket does not allow initiating a new request with
560_zmq_send(3)_ until the reply to the previous one has been received.
561When set to 1, sending another message is allowed and has the effect of
562disconnecting the underlying connection to the peer from which the reply was
563expected, triggering a reconnection attempt on transports that support it.
564The request-reply state machine is reset and a new request is sent to the
565next available peer.
566
567If set to 1, also enable ZMQ_REQ_CORRELATE to ensure correct matching of
568requests and replies. Otherwise a late reply to an aborted request can be
569reported as the reply to the superseding request.
570
571[horizontal]
572Option value type:: int
573Option value unit:: 0, 1
574Default value:: 0
575Applicable socket types:: ZMQ_REQ
576
577
578ZMQ_ROUTER_HANDOVER: handle duplicate client identities on ROUTER sockets
579~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
580If two clients use the same identity when connecting to a ROUTER, the
581results shall depend on the ZMQ_ROUTER_HANDOVER option setting. If that
582is not set (or set to the default of zero), the ROUTER socket shall reject
583clients trying to connect with an already-used identity. If that option
584is set to 1, the ROUTER socket shall hand-over the connection to the new
585client and disconnect the existing one.
586
587[horizontal]
588Option value type:: int
589Option value unit:: 0, 1
590Default value:: 0
591Applicable socket types:: ZMQ_ROUTER
592
593
594ZMQ_ROUTER_MANDATORY: accept only routable messages on ROUTER sockets
595~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
596Sets the ROUTER socket behavior when an unroutable message is encountered. A
597value of `0` is the default and discards the message silently when it cannot be
598routed.  A value of `1` returns an 'EHOSTUNREACH' error code if the message
599cannot be routed.
600
601[horizontal]
602Option value type:: int
603Option value unit:: 0, 1
604Default value:: 0
605Applicable socket types:: ZMQ_ROUTER
606
607
608ZMQ_ROUTER_RAW: switch ROUTER socket to raw mode
609~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
610Sets the raw mode on the ROUTER, when set to 1. When the ROUTER socket is in
611raw mode, and when using the tcp:// transport, it will read and write TCP data
612without 0MQ framing. This lets 0MQ applications talk to non-0MQ applications.
613When using raw mode, you cannot set explicit identities, and the ZMQ_SNDMORE
614flag is ignored when sending data messages. In raw mode you can close a specific
615connection by sending it a zero-length message (following the identity frame).
616
617NOTE: This option is deprecated, please use ZMQ_STREAM sockets instead.
618
619[horizontal]
620Option value type:: int
621Option value unit:: 0, 1
622Default value:: 0
623Applicable socket types:: ZMQ_ROUTER
624
625
626ZMQ_SNDBUF: Set kernel transmit buffer size
627~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
628The 'ZMQ_SNDBUF' option shall set the underlying kernel transmit buffer size
629for the 'socket' to the specified size in bytes.  A value of zero means leave
630the OS default unchanged. For details please refer to your operating system
631documentation for the 'SO_SNDBUF' socket option.
632
633[horizontal]
634Option value type:: int
635Option value unit:: bytes
636Default value:: 0
637Applicable socket types:: all
638
639
640ZMQ_SNDHWM: Set high water mark for outbound messages
641~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
642The 'ZMQ_SNDHWM' option shall set the high water mark for outbound messages on
643the specified 'socket'. The high water mark is a hard limit on the maximum
644number of outstanding messages 0MQ shall queue in memory for any single peer
645that the specified 'socket' is communicating with. A value of zero means no
646limit.
647
648If this limit has been reached the socket shall enter an exceptional state and
649depending on the socket type, 0MQ shall take appropriate action such as
650blocking or dropping sent messages. Refer to the individual socket descriptions
651in linkzmq:zmq_socket[3] for details on the exact action taken for each socket
652type.
653
654NOTE: 0MQ does not guarantee that the socket will accept as many as ZMQ_SNDHWM
655messages, and the actual limit may be as much as 60-70% lower depending on the
656flow of messages on the socket.
657
658[horizontal]
659Option value type:: int
660Option value unit:: messages
661Default value:: 1000
662Applicable socket types:: all
663
664
665ZMQ_SNDTIMEO: Maximum time before a send operation returns with EAGAIN
666~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
667Sets the timeout for send operation on the socket. If the value is `0`,
668_zmq_send(3)_ will return immediately, with a EAGAIN error if the message
669cannot be sent. If the value is `-1`, it will block until the message is sent.
670For all other values, it will try to send the message for that amount of time
671before returning with an EAGAIN error.
672
673[horizontal]
674Option value type:: int
675Option value unit:: milliseconds
676Default value:: -1 (infinite)
677Applicable socket types:: all
678
679
680ZMQ_SUBSCRIBE: Establish message filter
681~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
682The 'ZMQ_SUBSCRIBE' option shall establish a new message filter on a 'ZMQ_SUB'
683socket. Newly created 'ZMQ_SUB' sockets shall filter out all incoming messages,
684therefore you should call this option to establish an initial message filter.
685
686An empty 'option_value' of length zero shall subscribe to all incoming
687messages. A non-empty 'option_value' shall subscribe to all messages beginning
688with the specified prefix. Multiple filters may be attached to a single
689'ZMQ_SUB' socket, in which case a message shall be accepted if it matches at
690least one filter.
691
692[horizontal]
693Option value type:: binary data
694Option value unit:: N/A
695Default value:: N/A
696Applicable socket types:: ZMQ_SUB
697
698
699ZMQ_TCP_ACCEPT_FILTER: Assign filters to allow new TCP connections
700~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
701Assign an arbitrary number of filters that will be applied for each new TCP
702transport connection on a listening socket. If no filters are applied, then
703the TCP transport allows connections from any IP address. If at least one
704filter is applied then new connection source ip should be matched. To clear
705all filters call zmq_setsockopt(socket, ZMQ_TCP_ACCEPT_FILTER, NULL, 0).
706Filter is a null-terminated string with ipv6 or ipv4 CIDR.
707
708[horizontal]
709Option value type:: binary data
710Option value unit:: N/A
711Default value:: no filters (allow from all)
712Applicable socket types:: all listening sockets, when using TCP transports.
713
714
715ZMQ_TCP_KEEPALIVE: Override SO_KEEPALIVE socket option
716~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
717Override 'SO_KEEPALIVE' socket option (where supported by OS).
718The default value of `-1` means to skip any overrides and leave it to OS default.
719
720[horizontal]
721Option value type:: int
722Option value unit:: -1,0,1
723Default value:: -1 (leave to OS default)
724Applicable socket types:: all, when using TCP transports.
725
726
727ZMQ_TCP_KEEPALIVE_CNT: Override TCP_KEEPCNT socket option
728~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
729Override 'TCP_KEEPCNT' socket option (where supported by OS). The default
730value of `-1` means to skip any overrides and leave it to OS default.
731
732[horizontal]
733Option value type:: int
734Option value unit:: -1,>0
735Default value:: -1 (leave to OS default)
736Applicable socket types:: all, when using TCP transports.
737
738
739ZMQ_TCP_KEEPALIVE_IDLE: Override TCP_KEEPCNT (or TCP_KEEPALIVE on some OS)
740~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
741Override 'TCP_KEEPCNT' (or 'TCP_KEEPALIVE' on some OS) socket option (where
742supported by OS). The default value of `-1` means to skip any overrides and
743leave it to OS default.
744
745[horizontal]
746Option value type:: int
747Option value unit:: -1,>0
748Default value:: -1 (leave to OS default)
749Applicable socket types:: all, when using TCP transports.
750
751
752ZMQ_TCP_KEEPALIVE_INTVL: Override TCP_KEEPINTVL socket option
753~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
754Override 'TCP_KEEPINTVL' socket option(where supported by OS). The default
755value of `-1` means to skip any overrides and leave it to OS default.
756
757[horizontal]
758Option value type:: int
759Option value unit:: -1,>0
760Default value:: -1 (leave to OS default)
761Applicable socket types:: all, when using TCP transports.
762
763
764ZMQ_TOS: Set the Type-of-Service on socket
765~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
766Sets the ToS fields (Differentiated services (DS) and Explicit Congestion
767Notification (ECN) field of the IP header. The ToS field is typically used
768to specify a packets priority. The availability of this option is dependent
769on intermediate network equipment that inspect the ToS field andprovide a
770path for low-delay, high-throughput, highly-reliable service, etc.
771
772[horizontal]
773Option value type:: int
774Option value unit:: >0
775Default value:: 0
776Applicable socket types:: all, only for connection-oriented transports
777
778
779ZMQ_UNSUBSCRIBE: Remove message filter
780~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
781The 'ZMQ_UNSUBSCRIBE' option shall remove an existing message filter on a
782'ZMQ_SUB' socket. The filter specified must match an existing filter previously
783established with the 'ZMQ_SUBSCRIBE' option. If the socket has several
784instances of the same filter attached the 'ZMQ_UNSUBSCRIBE' option shall remove
785only one instance, leaving the rest in place and functional.
786
787[horizontal]
788Option value type:: binary data
789Option value unit:: N/A
790Default value:: N/A
791Applicable socket types:: ZMQ_SUB
792
793
794ZMQ_XPUB_VERBOSE: provide all subscription messages on XPUB sockets
795~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
796Sets the 'XPUB' socket behavior on new subscriptions and unsubscriptions.
797A value of '0' is the default and passes only new subscription messages to
798upstream. A value of '1' passes all subscription messages upstream.
799
800[horizontal]
801Option value type:: int
802Option value unit:: 0, 1
803Default value:: 0
804Applicable socket types:: ZMQ_XPUB
805
806
807ZMQ_ZAP_DOMAIN: Set RFC 27 authentication domain
808~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
809Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the
810default on all tcp:// connections), ZAP authentication only happens if you
811set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always
812made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27
813for more details.
814
815[horizontal]
816Option value type:: character string
817Option value unit:: N/A
818Default value:: not set
819Applicable socket types:: all, when using TCP transport
820
821
822RETURN VALUE
823------------
824The _zmq_setsockopt()_ function shall return zero if successful. Otherwise it
825shall return `-1` and set 'errno' to one of the values defined below.
826
827ERRORS
828------
829*EINVAL*::
830The requested option _option_name_ is unknown, or the requested _option_len_ or
831_option_value_ is invalid.
832*ETERM*::
833The 0MQ 'context' associated with the specified 'socket' was terminated.
834*ENOTSOCK*::
835The provided 'socket' was invalid.
836*EINTR*::
837The operation was interrupted by delivery of a signal.
838
839
840EXAMPLE
841-------
842.Subscribing to messages on a 'ZMQ_SUB' socket
843----
844/* Subscribe to all messages */
845rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "", 0);
846assert (rc == 0);
847/* Subscribe to messages prefixed with "ANIMALS.CATS" */
848rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "ANIMALS.CATS", 12);
849----
850
851.Setting I/O thread affinity
852----
853int64_t affinity;
854/* Incoming connections on TCP port 5555 shall be handled by I/O thread 1 */
855affinity = 1;
856rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof (affinity));
857assert (rc);
858rc = zmq_bind (socket, "tcp://lo:5555");
859assert (rc);
860/* Incoming connections on TCP port 5556 shall be handled by I/O thread 2 */
861affinity = 2;
862rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof (affinity));
863assert (rc);
864rc = zmq_bind (socket, "tcp://lo:5556");
865assert (rc);
866----
867
868
869SEE ALSO
870--------
871linkzmq:zmq_getsockopt[3]
872linkzmq:zmq_socket[3]
873linkzmq:zmq_plain[7]
874linkzmq:zmq_curve[7]
875linkzmq:zmq[7]
876
877
878AUTHORS
879-------
880This page was written by the 0MQ community. To make a change please
881read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.