/doc/zmq_setsockopt.txt
Plain Text | 559 lines | 431 code | 128 blank | 0 comment | 0 complexity | 1460797296c3ff360b3b278dd1dac3fc 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_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>.