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