From adf5b45d7160b31cbc04466716bf848e31c00b9f Mon Sep 17 00:00:00 2001 From: Pieter Hintjens Date: Wed, 1 Jan 2014 16:28:30 +0100 Subject: [PATCH] Reordered socket options - put into alphabetical order - there was no consistency in previous ordering --- doc/zmq_getsockopt.txt | 1008 +++++++++++++++++++-------------------- doc/zmq_setsockopt.txt | 1023 +++++++++++++++++++--------------------- 2 files changed, 1000 insertions(+), 1031 deletions(-) diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt index 9beeb15c..db3e2cdc 100644 --- a/doc/zmq_getsockopt.txt +++ b/doc/zmq_getsockopt.txt @@ -26,77 +26,6 @@ value stored in the buffer. The following options can be retrieved with the _zmq_getsockopt()_ function: -ZMQ_TYPE: Retrieve socket type -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_TYPE' option shall retrieve the socket type for the specified -'socket'. The socket type is specified at socket creation time and -cannot be modified afterwards. - -[horizontal] -Option value type:: int -Option value unit:: N/A -Default value:: N/A -Applicable socket types:: all - - -ZMQ_RCVMORE: More message data parts to follow -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RCVMORE' option shall return True (1) if the message part last -received from the 'socket' was a data part with more parts to follow. If there -are no data parts to follow, this option shall return False (0). - -Refer to linkzmq:zmq_send[3] and linkzmq:zmq_recv[3] for a detailed description -of multi-part messages. - -[horizontal] -Option value type:: int -Option value unit:: boolean -Default value:: N/A -Applicable socket types:: all - - -ZMQ_SNDHWM: Retrieves high water mark for outbound messages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_SNDHWM' option shall return the high water mark for outbound messages -on the specified 'socket'. The high water mark is a hard limit on the maximum -number of outstanding messages 0MQ shall queue in memory for any single peer -that the specified 'socket' is communicating with. A value of zero means no -limit. - -If this limit has been reached the socket shall enter an exceptional state and -depending on the socket type, 0MQ shall take appropriate action such as -blocking or dropping sent messages. Refer to the individual socket descriptions -in linkzmq:zmq_socket[3] for details on the exact action taken for each socket -type. - -[horizontal] -Option value type:: int -Option value unit:: messages -Default value:: 1000 -Applicable socket types:: all - - -ZMQ_RCVHWM: Retrieve high water mark for inbound messages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RCVHWM' option shall return the high water mark for inbound messages on -the specified 'socket'. The high water mark is a hard limit on the maximum -number of outstanding messages 0MQ shall queue in memory for any single peer -that the specified 'socket' is communicating with. A value of zero means no -limit. - -If this limit has been reached the socket shall enter an exceptional state and -depending on the socket type, 0MQ shall take appropriate action such as -blocking or dropping sent messages. Refer to the individual socket descriptions -in linkzmq:zmq_socket[3] for details on the exact action taken for each socket -type. - -[horizontal] -Option value type:: int -Option value unit:: messages -Default value:: 1000 -Applicable socket types:: all - - ZMQ_AFFINITY: Retrieve I/O thread affinity ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'ZMQ_AFFINITY' option shall retrieve the I/O thread affinity for newly @@ -120,143 +49,6 @@ Default value:: 0 Applicable socket types:: N/A -ZMQ_IDENTITY: Retrieve socket identity -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_IDENTITY' option shall retrieve the identity of the specified 'socket'. -Socket identity is used only by request/reply pattern. Namely, it can be used -in tandem with ROUTER socket to route messages to the peer with specific -identity. - -Identity should be at least one byte and at most 255 bytes long. Identities -starting with binary zero are reserved for use by 0MQ infrastructure. - -[horizontal] -Option value type:: binary data -Option value unit:: N/A -Default value:: NULL -Applicable socket types:: ZMQ_REP, ZMQ_REQ, ZMQ_ROUTER, ZMQ_DEALER. - - -ZMQ_RATE: Retrieve multicast data rate -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RATE' option shall retrieve the maximum send or receive data rate for -multicast transports using the specified 'socket'. - -[horizontal] -Option value type:: int -Option value unit:: kilobits per second -Default value:: 100 -Applicable socket types:: all, when using multicast transports - - -ZMQ_RECOVERY_IVL: Get multicast recovery interval -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RECOVERY_IVL' option shall retrieve the recovery interval for -multicast transports using the specified 'socket'. The recovery interval -determines the maximum time in milliseconds that a receiver can be absent from a -multicast group before unrecoverable data loss will occur. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: 10000 -Applicable socket types:: all, when using multicast transports - - -ZMQ_SNDBUF: Retrieve kernel transmit buffer size -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_SNDBUF' option shall retrieve the underlying kernel transmit buffer -size for the specified 'socket'. A value of zero means that the OS default is -in effect. For details refer to your operating system documentation for the -'SO_SNDBUF' socket option. - -[horizontal] -Option value type:: int -Option value unit:: bytes -Default value:: 0 -Applicable socket types:: all - - -ZMQ_RCVBUF: Retrieve kernel receive buffer size -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RCVBUF' option shall retrieve the underlying kernel receive buffer -size for the specified 'socket'. A value of zero means that the OS default is -in effect. For details refer to your operating system documentation for the -'SO_RCVBUF' socket option. - -[horizontal] -Option value type:: int -Option value unit:: bytes -Default value:: 0 -Applicable socket types:: all - - -ZMQ_LINGER: Retrieve linger period for socket shutdown -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_LINGER' option shall retrieve the linger period for the specified -'socket'. The linger period determines how long pending messages which have -yet to be sent to a peer shall linger in memory after a socket is closed with -linkzmq:zmq_close[3], and further affects the termination of the socket's -context with linkzmq:zmq_term[3]. The following outlines the different -behaviours: - -* The default value of '-1' specifies an infinite linger period. Pending - messages shall not be discarded after a call to _zmq_close()_; attempting to - terminate the socket's context with _zmq_term()_ shall block until all - pending messages have been sent to a peer. - -* The value of '0' specifies no linger period. Pending messages shall be - discarded immediately when the socket is closed with _zmq_close()_. - -* Positive values specify an upper bound for the linger period in milliseconds. - Pending messages shall not be discarded after a call to _zmq_close()_; - attempting to terminate the socket's context with _zmq_term()_ shall block - until either all pending messages have been sent to a peer, or the linger - period expires, after which any pending messages shall be discarded. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: -1 (infinite) -Applicable socket types:: all - - -ZMQ_RECONNECT_IVL: Retrieve reconnection interval -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RECONNECT_IVL' option shall retrieve the initial reconnection interval -for the specified 'socket'. The reconnection interval is the period 0MQ shall -wait between attempts to reconnect disconnected peers when using -connection-oriented transports. The value -1 means no reconnection. - -NOTE: The reconnection interval may be randomized by 0MQ to prevent -reconnection storms in topologies with a large number of peers per socket. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: 100 -Applicable socket types:: all, only for connection-oriented transports - - -ZMQ_RECONNECT_IVL_MAX: Retrieve maximum reconnection interval -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RECONNECT_IVL_MAX' option shall retrieve the maximum reconnection -interval for the specified 'socket'. This is the maximum period 0MQ shall wait -between attempts to reconnect. On each reconnect attempt, the previous interval -shall be doubled untill ZMQ_RECONNECT_IVL_MAX is reached. This allows for -exponential backoff strategy. Default value means no exponential backoff is -performed and reconnect interval calculations are only based on -ZMQ_RECONNECT_IVL. - -NOTE: Values less than ZMQ_RECONNECT_IVL will be ignored. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: 0 (only use ZMQ_RECONNECT_IVL) -Applicable socket types:: all, only for connection-oriented transport - - ZMQ_BACKLOG: Retrieve maximum length of the queue of outstanding connections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'ZMQ_BACKLOG' option shall retrieve the maximum length of the queue of @@ -271,302 +63,6 @@ Default value:: 100 Applicable socket types:: all, only for connection-oriented transports -ZMQ_MAXMSGSIZE: Maximum acceptable inbound message size -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The option shall retrieve limit for the inbound messages. If a peer sends -a message larger than ZMQ_MAXMSGSIZE it is disconnected. Value of -1 means -'no limit'. - -[horizontal] -Option value type:: int64_t -Option value unit:: bytes -Default value:: -1 -Applicable socket types:: all - - -ZMQ_MULTICAST_HOPS: Maximum network hops for multicast packets -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The option shall retrieve time-to-live used for outbound multicast packets. -The default of 1 means that the multicast packets don't leave the local network. - -[horizontal] -Option value type:: int -Option value unit:: network hops -Default value:: 1 -Applicable socket types:: all, when using multicast transports - - -ZMQ_RCVTIMEO: Maximum time before a socket operation returns with EAGAIN -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Retrieve the timeout for recv operation on the socket. If the value is `0`, -_zmq_recv(3)_ will return immediately, with a EAGAIN error if there is no -message to receive. If the value is `-1`, it will block until a message is -available. For all other values, it will wait for a message for that amount -of time before returning with an EAGAIN error. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: -1 (infinite) -Applicable socket types:: all - - -ZMQ_SNDTIMEO: Maximum time before a socket operation returns with EAGAIN -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Retrieve the timeout for send operation on the socket. If the value is `0`, -_zmq_send(3)_ will return immediately, with a EAGAIN error if the message -cannot be sent. If the value is `-1`, it will block until the message is sent. -For all other values, it will try to send the message for that amount of time -before returning with an EAGAIN error. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: -1 (infinite) -Applicable socket types:: all - - -ZMQ_IPV6: Retrieve IPv6 socket status -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Retrieve the IPv6 option for the socket. A value of `1` means IPv6 is -enabled on the socket, while `0` means the socket will use only IPv4. -When IPv6 is enabled the socket will connect to, or accept connections -from, both IPv4 and IPv6 hosts. - -[horizontal] -Option value type:: int -Option value unit:: boolean -Default value:: 0 (false) -Applicable socket types:: all, when using TCP transports. - - -ZMQ_IPV4ONLY: Retrieve IPv4-only socket override status -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Retrieve the IPv4-only option for the socket. This option is deprecated. -Please use the ZMQ_IPV6 option. - -[horizontal] -Option value type:: int -Option value unit:: boolean -Default value:: 1 (true) -Applicable socket types:: all, when using TCP transports. - - -ZMQ_TOS: Retrieve the Type-of-Service socket override status -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Retrieve the IP_TOS option for the socket. - -[horizontal] -Option value type:: int -Option value unit:: >0 -Default value:: 0 -Applicable socket types:: all, only for connection-oriented transports - - -ZMQ_IMMEDIATE: Retrieve attach-on-connect value -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Retrieve the state of the attach on connect value. If set to `1`, will delay the -attachment of a pipe on connect until the underlying connection has completed. -This will cause the socket to block if there are no other connections, but will -prevent queues from filling on pipes awaiting connection. - -[horizontal] -Option value type:: int -Option value unit:: boolean -Default value:: 0 (false) -Applicable socket types:: all, primarily when using TCP/IPC transports. - - -ZMQ_FD: Retrieve file descriptor associated with the socket -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_FD' option shall retrieve the file descriptor associated with the -specified 'socket'. The returned file descriptor can be used to integrate the -socket into an existing event loop; the 0MQ library shall signal any pending -events on the socket in an _edge-triggered_ fashion by making the file -descriptor become ready for reading. - -NOTE: The ability to read from the returned file descriptor does not -necessarily indicate that messages are available to be read from, or can be -written to, the underlying socket; applications must retrieve the actual event -state with a subsequent retrieval of the 'ZMQ_EVENTS' option. - -NOTE: The returned file descriptor is also used internally by the 'zmq_send' -and 'zmq_recv' functions. As the descriptor is edge triggered, applications -must update the state of 'ZMQ_EVENTS' after each invocation of 'zmq_send' -or 'zmq_recv'.To be more explicit: after calling 'zmq_send' the socket may -become readable (and vice versa) without triggering a read event on the -file descriptor. - -CAUTION: The returned file descriptor is intended for use with a 'poll' or -similar system call only. Applications must never attempt to read or write data -to it directly, neither should they try to close it. - -[horizontal] -Option value type:: int on POSIX systems, SOCKET on Windows -Option value unit:: N/A -Default value:: N/A -Applicable socket types:: all - - -ZMQ_EVENTS: Retrieve socket event state -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_EVENTS' option shall retrieve the event state for the specified -'socket'. The returned value is a bit mask constructed by OR'ing a combination -of the following event flags: - -*ZMQ_POLLIN*:: -Indicates that at least one message may be received from the specified socket -without blocking. - -*ZMQ_POLLOUT*:: -Indicates that at least one message may be sent to the specified socket without -blocking. - -The combination of a file descriptor returned by the 'ZMQ_FD' option being -ready for reading but no actual events returned by a subsequent retrieval of -the 'ZMQ_EVENTS' option is valid; applications should simply ignore this case -and restart their polling operation/event loop. - -[horizontal] -Option value type:: int -Option value unit:: N/A (flags) -Default value:: N/A -Applicable socket types:: all - - -ZMQ_LAST_ENDPOINT: Retrieve the last endpoint set -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_LAST_ENDPOINT' option shall retrieve the last endpoint bound for -TCP and IPC transports. The returned value will be a string in the form of -a ZMQ DSN. Note that if the TCP host is INADDR_ANY, indicated by a *, then -the returned address will be 0.0.0.0 (for IPv4). - -[horizontal] -Option value type:: NULL-terminated character string -Option value unit:: N/A -Default value:: NULL -Applicable socket types:: all, when binding TCP or IPC transports - - -ZMQ_TCP_KEEPALIVE: Override SO_KEEPALIVE socket option -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Override 'SO_KEEPALIVE' socket option(where supported by OS). -The default value of `-1` means to skip any overrides and leave it to OS default. - -[horizontal] -Option value type:: int -Option value unit:: -1,0,1 -Default value:: -1 (leave to OS default) -Applicable socket types:: all, when using TCP transports. - - -ZMQ_TCP_KEEPALIVE_IDLE: Override TCP_KEEPCNT(or TCP_KEEPALIVE on some OS) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Override 'TCP_KEEPCNT'(or 'TCP_KEEPALIVE' on some OS) socket option (where -supported by OS). The default value of `-1` means to skip any overrides and -leave it to OS default. - -[horizontal] -Option value type:: int -Option value unit:: -1,>0 -Default value:: -1 (leave to OS default) -Applicable socket types:: all, when using TCP transports. - - -ZMQ_TCP_KEEPALIVE_CNT: Override TCP_KEEPCNT socket option -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Override 'TCP_KEEPCNT' socket option(where supported by OS). -The default value of `-1` means to skip any overrides and leave it to OS default. - -[horizontal] -Option value type:: int -Option value unit:: -1,>0 -Default value:: -1 (leave to OS default) -Applicable socket types:: all, when using TCP transports. - - -ZMQ_TCP_KEEPALIVE_INTVL: Override TCP_KEEPINTVL socket option -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Override 'TCP_KEEPINTVL' socket option(where supported by OS). -The default value of `-1` means to skip any overrides and leave it to OS default. - -[horizontal] -Option value type:: int -Option value unit:: -1,>0 -Default value:: -1 (leave to OS default) -Applicable socket types:: all, when using TCP transports. - - -ZMQ_ZAP_IPC_CREDS: Retrieve IPC peer credentials state -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The 'ZMQ_ZAP_IPC_CREDS' option shall return True (1) if credentials of IPC -peers will be appended to the address sent in ZAP request messages and False -(0) otherwise. - -Refer to linkzmq:zmq_setsockopt[3] for more information. - -NOTE: IPC peer credentials are only available on platforms supporting the -SO_PEERCRED or LOCAL_PEERCRED socket options. - -[horizontal] -Option value type:: int -Option value unit:: boolean -Default value:: 0 (false) -Applicable socket types:: all listening sockets, when using IPC transports. - - -ZMQ_MECHANISM: Retrieve current security mechanism -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_MECHANISM' option shall retrieve the current security mechanism -for the socket. - -[horizontal] -Option value type:: int -Option value unit:: ZMQ_NULL, ZMQ_PLAIN, or ZMQ_CURVE -Default value:: ZMQ_NULL -Applicable socket types:: all, when using TCP or IPC transports - - -ZMQ_PLAIN_SERVER: Retrieve current PLAIN server role -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Returns the 'ZMQ_PLAIN_SERVER' option, if any, previously set on the socket. - -[horizontal] -Option value type:: int -Option value unit:: 0, 1 -Default value:: int -Applicable socket types:: all, when using TCP or IPC transports - - -ZMQ_PLAIN_USERNAME: Retrieve current PLAIN username -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_PLAIN_USERNAME' option shall retrieve the last username set for -the PLAIN security mechanism. The returned value shall be a NULL-terminated -string and MAY be empty. The returned size SHALL include the terminating -null byte. - -[horizontal] -Option value type:: NULL-terminated character string -Option value unit:: N/A -Default value:: null string -Applicable socket types:: all, when using TCP or IPC transports - - -ZMQ_PLAIN_PASSWORD: Retrieve current password -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_PLAIN_PASSWORD' option shall retrieve the last password set for -the PLAIN security mechanism. The returned value shall be a NULL-terminated -string and MAY be empty. The returned size SHALL include the terminating -null byte. - -[horizontal] -Option value type:: NULL-terminated character string -Option value unit:: N/A -Default value:: null string -Applicable socket types:: all, when using TCP or IPC transports - - ZMQ_CURVE_PUBLICKEY: Retrieve current CURVE public key ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -611,6 +107,491 @@ Default value:: null Applicable socket types:: all, when using TCP transport +ZMQ_EVENTS: Retrieve socket event state +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_EVENTS' option shall retrieve the event state for the specified +'socket'. The returned value is a bit mask constructed by OR'ing a combination +of the following event flags: + +*ZMQ_POLLIN*:: +Indicates that at least one message may be received from the specified socket +without blocking. + +*ZMQ_POLLOUT*:: +Indicates that at least one message may be sent to the specified socket without +blocking. + +The combination of a file descriptor returned by the 'ZMQ_FD' option being +ready for reading but no actual events returned by a subsequent retrieval of +the 'ZMQ_EVENTS' option is valid; applications should simply ignore this case +and restart their polling operation/event loop. + +[horizontal] +Option value type:: int +Option value unit:: N/A (flags) +Default value:: N/A +Applicable socket types:: all + + +ZMQ_FD: Retrieve file descriptor associated with the socket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_FD' option shall retrieve the file descriptor associated with the +specified 'socket'. The returned file descriptor can be used to integrate the +socket into an existing event loop; the 0MQ library shall signal any pending +events on the socket in an _edge-triggered_ fashion by making the file +descriptor become ready for reading. + +NOTE: The ability to read from the returned file descriptor does not +necessarily indicate that messages are available to be read from, or can be +written to, the underlying socket; applications must retrieve the actual event +state with a subsequent retrieval of the 'ZMQ_EVENTS' option. + +NOTE: The returned file descriptor is also used internally by the 'zmq_send' +and 'zmq_recv' functions. As the descriptor is edge triggered, applications +must update the state of 'ZMQ_EVENTS' after each invocation of 'zmq_send' +or 'zmq_recv'.To be more explicit: after calling 'zmq_send' the socket may +become readable (and vice versa) without triggering a read event on the +file descriptor. + +CAUTION: The returned file descriptor is intended for use with a 'poll' or +similar system call only. Applications must never attempt to read or write data +to it directly, neither should they try to close it. + +[horizontal] +Option value type:: int on POSIX systems, SOCKET on Windows +Option value unit:: N/A +Default value:: N/A +Applicable socket types:: all + + +ZMQ_IDENTITY: Retrieve socket identity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_IDENTITY' option shall retrieve the identity of the specified 'socket'. +Socket identity is used only by request/reply pattern. Namely, it can be used +in tandem with ROUTER socket to route messages to the peer with specific +identity. + +Identity should be at least one byte and at most 255 bytes long. Identities +starting with binary zero are reserved for use by 0MQ infrastructure. + +[horizontal] +Option value type:: binary data +Option value unit:: N/A +Default value:: NULL +Applicable socket types:: ZMQ_REP, ZMQ_REQ, ZMQ_ROUTER, ZMQ_DEALER. + + +ZMQ_IMMEDIATE: Retrieve attach-on-connect value +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Retrieve the state of the attach on connect value. If set to `1`, will delay the +attachment of a pipe on connect until the underlying connection has completed. +This will cause the socket to block if there are no other connections, but will +prevent queues from filling on pipes awaiting connection. + +[horizontal] +Option value type:: int +Option value unit:: boolean +Default value:: 0 (false) +Applicable socket types:: all, primarily when using TCP/IPC transports. + + +ZMQ_IPV4ONLY: Retrieve IPv4-only socket override status +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Retrieve the IPv4-only option for the socket. This option is deprecated. +Please use the ZMQ_IPV6 option. + +[horizontal] +Option value type:: int +Option value unit:: boolean +Default value:: 1 (true) +Applicable socket types:: all, when using TCP transports. + + +ZMQ_IPV6: Retrieve IPv6 socket status +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Retrieve the IPv6 option for the socket. A value of `1` means IPv6 is +enabled on the socket, while `0` means the socket will use only IPv4. +When IPv6 is enabled the socket will connect to, or accept connections +from, both IPv4 and IPv6 hosts. + +[horizontal] +Option value type:: int +Option value unit:: boolean +Default value:: 0 (false) +Applicable socket types:: all, when using TCP transports. + + +ZMQ_LAST_ENDPOINT: Retrieve the last endpoint set +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_LAST_ENDPOINT' option shall retrieve the last endpoint bound for +TCP and IPC transports. The returned value will be a string in the form of +a ZMQ DSN. Note that if the TCP host is INADDR_ANY, indicated by a *, then +the returned address will be 0.0.0.0 (for IPv4). + +[horizontal] +Option value type:: NULL-terminated character string +Option value unit:: N/A +Default value:: NULL +Applicable socket types:: all, when binding TCP or IPC transports + + +ZMQ_LINGER: Retrieve linger period for socket shutdown +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_LINGER' option shall retrieve the linger period for the specified +'socket'. The linger period determines how long pending messages which have +yet to be sent to a peer shall linger in memory after a socket is closed with +linkzmq:zmq_close[3], and further affects the termination of the socket's +context with linkzmq:zmq_term[3]. The following outlines the different +behaviours: + +* The default value of '-1' specifies an infinite linger period. Pending + messages shall not be discarded after a call to _zmq_close()_; attempting to + terminate the socket's context with _zmq_term()_ shall block until all + pending messages have been sent to a peer. + +* The value of '0' specifies no linger period. Pending messages shall be + discarded immediately when the socket is closed with _zmq_close()_. + +* Positive values specify an upper bound for the linger period in milliseconds. + Pending messages shall not be discarded after a call to _zmq_close()_; + attempting to terminate the socket's context with _zmq_term()_ shall block + until either all pending messages have been sent to a peer, or the linger + period expires, after which any pending messages shall be discarded. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: -1 (infinite) +Applicable socket types:: all + + +ZMQ_MAXMSGSIZE: Maximum acceptable inbound message size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The option shall retrieve limit for the inbound messages. If a peer sends +a message larger than ZMQ_MAXMSGSIZE it is disconnected. Value of -1 means +'no limit'. + +[horizontal] +Option value type:: int64_t +Option value unit:: bytes +Default value:: -1 +Applicable socket types:: all + + +ZMQ_MECHANISM: Retrieve current security mechanism +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_MECHANISM' option shall retrieve the current security mechanism +for the socket. + +[horizontal] +Option value type:: int +Option value unit:: ZMQ_NULL, ZMQ_PLAIN, or ZMQ_CURVE +Default value:: ZMQ_NULL +Applicable socket types:: all, when using TCP or IPC transports + + +ZMQ_MULTICAST_HOPS: Maximum network hops for multicast packets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The option shall retrieve time-to-live used for outbound multicast packets. +The default of 1 means that the multicast packets don't leave the local network. + +[horizontal] +Option value type:: int +Option value unit:: network hops +Default value:: 1 +Applicable socket types:: all, when using multicast transports + + +ZMQ_PLAIN_PASSWORD: Retrieve current password +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_PLAIN_PASSWORD' option shall retrieve the last password set for +the PLAIN security mechanism. The returned value shall be a NULL-terminated +string and MAY be empty. The returned size SHALL include the terminating +null byte. + +[horizontal] +Option value type:: NULL-terminated character string +Option value unit:: N/A +Default value:: null string +Applicable socket types:: all, when using TCP or IPC transports + + +ZMQ_PLAIN_SERVER: Retrieve current PLAIN server role +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Returns the 'ZMQ_PLAIN_SERVER' option, if any, previously set on the socket. + +[horizontal] +Option value type:: int +Option value unit:: 0, 1 +Default value:: int +Applicable socket types:: all, when using TCP or IPC transports + + +ZMQ_PLAIN_USERNAME: Retrieve current PLAIN username +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_PLAIN_USERNAME' option shall retrieve the last username set for +the PLAIN security mechanism. The returned value shall be a NULL-terminated +string and MAY be empty. The returned size SHALL include the terminating +null byte. + +[horizontal] +Option value type:: NULL-terminated character string +Option value unit:: N/A +Default value:: null string +Applicable socket types:: all, when using TCP or IPC transports + + +ZMQ_RATE: Retrieve multicast data rate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RATE' option shall retrieve the maximum send or receive data rate for +multicast transports using the specified 'socket'. + +[horizontal] +Option value type:: int +Option value unit:: kilobits per second +Default value:: 100 +Applicable socket types:: all, when using multicast transports + + +ZMQ_RCVBUF: Retrieve kernel receive buffer size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RCVBUF' option shall retrieve the underlying kernel receive buffer +size for the specified 'socket'. A value of zero means that the OS default is +in effect. For details refer to your operating system documentation for the +'SO_RCVBUF' socket option. + +[horizontal] +Option value type:: int +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +ZMQ_RCVHWM: Retrieve high water mark for inbound messages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RCVHWM' option shall return the high water mark for inbound messages on +the specified 'socket'. The high water mark is a hard limit on the maximum +number of outstanding messages 0MQ shall queue in memory for any single peer +that the specified 'socket' is communicating with. A value of zero means no +limit. + +If this limit has been reached the socket shall enter an exceptional state and +depending on the socket type, 0MQ shall take appropriate action such as +blocking or dropping sent messages. Refer to the individual socket descriptions +in linkzmq:zmq_socket[3] for details on the exact action taken for each socket +type. + +[horizontal] +Option value type:: int +Option value unit:: messages +Default value:: 1000 +Applicable socket types:: all + + +ZMQ_RCVMORE: More message data parts to follow +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RCVMORE' option shall return True (1) if the message part last +received from the 'socket' was a data part with more parts to follow. If there +are no data parts to follow, this option shall return False (0). + +Refer to linkzmq:zmq_send[3] and linkzmq:zmq_recv[3] for a detailed description +of multi-part messages. + +[horizontal] +Option value type:: int +Option value unit:: boolean +Default value:: N/A +Applicable socket types:: all + + +ZMQ_RCVTIMEO: Maximum time before a socket operation returns with EAGAIN +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Retrieve the timeout for recv operation on the socket. If the value is `0`, +_zmq_recv(3)_ will return immediately, with a EAGAIN error if there is no +message to receive. If the value is `-1`, it will block until a message is +available. For all other values, it will wait for a message for that amount +of time before returning with an EAGAIN error. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: -1 (infinite) +Applicable socket types:: all + + +ZMQ_RECONNECT_IVL: Retrieve reconnection interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RECONNECT_IVL' option shall retrieve the initial reconnection interval +for the specified 'socket'. The reconnection interval is the period 0MQ shall +wait between attempts to reconnect disconnected peers when using +connection-oriented transports. The value -1 means no reconnection. + +NOTE: The reconnection interval may be randomized by 0MQ to prevent +reconnection storms in topologies with a large number of peers per socket. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: 100 +Applicable socket types:: all, only for connection-oriented transports + + +ZMQ_RECONNECT_IVL_MAX: Retrieve maximum reconnection interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RECONNECT_IVL_MAX' option shall retrieve the maximum reconnection +interval for the specified 'socket'. This is the maximum period 0MQ shall wait +between attempts to reconnect. On each reconnect attempt, the previous interval +shall be doubled untill ZMQ_RECONNECT_IVL_MAX is reached. This allows for +exponential backoff strategy. Default value means no exponential backoff is +performed and reconnect interval calculations are only based on +ZMQ_RECONNECT_IVL. + +NOTE: Values less than ZMQ_RECONNECT_IVL will be ignored. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: 0 (only use ZMQ_RECONNECT_IVL) +Applicable socket types:: all, only for connection-oriented transport + + +ZMQ_RECOVERY_IVL: Get multicast recovery interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RECOVERY_IVL' option shall retrieve the recovery interval for +multicast transports using the specified 'socket'. The recovery interval +determines the maximum time in milliseconds that a receiver can be absent from a +multicast group before unrecoverable data loss will occur. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: 10000 +Applicable socket types:: all, when using multicast transports + + +ZMQ_SNDBUF: Retrieve kernel transmit buffer size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_SNDBUF' option shall retrieve the underlying kernel transmit buffer +size for the specified 'socket'. A value of zero means that the OS default is +in effect. For details refer to your operating system documentation for the +'SO_SNDBUF' socket option. + +[horizontal] +Option value type:: int +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +ZMQ_SNDHWM: Retrieves high water mark for outbound messages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_SNDHWM' option shall return the high water mark for outbound messages +on the specified 'socket'. The high water mark is a hard limit on the maximum +number of outstanding messages 0MQ shall queue in memory for any single peer +that the specified 'socket' is communicating with. A value of zero means no +limit. + +If this limit has been reached the socket shall enter an exceptional state and +depending on the socket type, 0MQ shall take appropriate action such as +blocking or dropping sent messages. Refer to the individual socket descriptions +in linkzmq:zmq_socket[3] for details on the exact action taken for each socket +type. + +[horizontal] +Option value type:: int +Option value unit:: messages +Default value:: 1000 +Applicable socket types:: all + + +ZMQ_SNDTIMEO: Maximum time before a socket operation returns with EAGAIN +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Retrieve the timeout for send operation on the socket. If the value is `0`, +_zmq_send(3)_ will return immediately, with a EAGAIN error if the message +cannot be sent. If the value is `-1`, it will block until the message is sent. +For all other values, it will try to send the message for that amount of time +before returning with an EAGAIN error. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: -1 (infinite) +Applicable socket types:: all + + +ZMQ_TCP_KEEPALIVE: Override SO_KEEPALIVE socket option +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Override 'SO_KEEPALIVE' socket option(where supported by OS). +The default value of `-1` means to skip any overrides and leave it to OS default. + +[horizontal] +Option value type:: int +Option value unit:: -1,0,1 +Default value:: -1 (leave to OS default) +Applicable socket types:: all, when using TCP transports. + + +ZMQ_TCP_KEEPALIVE_CNT: Override TCP_KEEPCNT socket option +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Override 'TCP_KEEPCNT' socket option(where supported by OS). +The default value of `-1` means to skip any overrides and leave it to OS default. + +[horizontal] +Option value type:: int +Option value unit:: -1,>0 +Default value:: -1 (leave to OS default) +Applicable socket types:: all, when using TCP transports. + + +ZMQ_TCP_KEEPALIVE_IDLE: Override TCP_KEEPCNT(or TCP_KEEPALIVE on some OS) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Override 'TCP_KEEPCNT'(or 'TCP_KEEPALIVE' on some OS) socket option (where +supported by OS). The default value of `-1` means to skip any overrides and +leave it to OS default. + +[horizontal] +Option value type:: int +Option value unit:: -1,>0 +Default value:: -1 (leave to OS default) +Applicable socket types:: all, when using TCP transports. + + +ZMQ_TCP_KEEPALIVE_INTVL: Override TCP_KEEPINTVL socket option +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Override 'TCP_KEEPINTVL' socket option(where supported by OS). +The default value of `-1` means to skip any overrides and leave it to OS default. + +[horizontal] +Option value type:: int +Option value unit:: -1,>0 +Default value:: -1 (leave to OS default) +Applicable socket types:: all, when using TCP transports. + + +ZMQ_TOS: Retrieve the Type-of-Service socket override status +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Retrieve the IP_TOS option for the socket. + +[horizontal] +Option value type:: int +Option value unit:: >0 +Default value:: 0 +Applicable socket types:: all, only for connection-oriented transports + + +ZMQ_TYPE: Retrieve socket type +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_TYPE' option shall retrieve the socket type for the specified +'socket'. The socket type is specified at socket creation time and +cannot be modified afterwards. + +[horizontal] +Option value type:: int +Option value unit:: N/A +Default value:: N/A +Applicable socket types:: all + + ZMQ_ZAP_DOMAIN: Retrieve RFC 27 authentication domain ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -625,6 +606,25 @@ Default value:: not set Applicable socket types:: all, when using TCP transport +ZMQ_ZAP_IPC_CREDS: Retrieve IPC peer credentials state +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The 'ZMQ_ZAP_IPC_CREDS' option shall return True (1) if credentials of IPC +peers will be appended to the address sent in ZAP request messages and False +(0) otherwise. + +Refer to linkzmq:zmq_setsockopt[3] for more information. + +NOTE: IPC peer credentials are only available on platforms supporting the +SO_PEERCRED or LOCAL_PEERCRED socket options. + +[horizontal] +Option value type:: int +Option value unit:: boolean +Default value:: 0 (false) +Applicable socket types:: all listening sockets, when using IPC transports. + + RETURN VALUE ------------ The _zmq_getsockopt()_ function shall return zero if successful. Otherwise it diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt index 152beca2..615a10d4 100644 --- a/doc/zmq_setsockopt.txt +++ b/doc/zmq_setsockopt.txt @@ -30,52 +30,6 @@ argument is the size of the option value in bytes. The following socket options can be set with the _zmq_setsockopt()_ function: -ZMQ_SNDHWM: Set high water mark for outbound messages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_SNDHWM' option shall set the high water mark for outbound messages on -the specified 'socket'. The high water mark is a hard limit on the maximum -number of outstanding messages 0MQ shall queue in memory for any single peer -that the specified 'socket' is communicating with. A value of zero means no -limit. - -If this limit has been reached the socket shall enter an exceptional state and -depending on the socket type, 0MQ shall take appropriate action such as -blocking or dropping sent messages. Refer to the individual socket descriptions -in linkzmq:zmq_socket[3] for details on the exact action taken for each socket -type. - -NOTE: 0MQ does not guarantee that the socket will accept as many as ZMQ_SNDHWM -messages, and the actual limit may be as much as 60-70% lower depending on the -flow of messages on the socket. - -[horizontal] -Option value type:: int -Option value unit:: messages -Default value:: 1000 -Applicable socket types:: all - - -ZMQ_RCVHWM: Set high water mark for inbound messages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RCVHWM' option shall set the high water mark for inbound messages on -the specified 'socket'. The high water mark is a hard limit on the maximum -number of outstanding messages 0MQ shall queue in memory for any single peer -that the specified 'socket' is communicating with. A value of zero means no -limit. - -If this limit has been reached the socket shall enter an exceptional state and -depending on the socket type, 0MQ shall take appropriate action such as -blocking or dropping sent messages. Refer to the individual socket descriptions -in linkzmq:zmq_socket[3] for details on the exact action taken for each socket -type. - -[horizontal] -Option value type:: int -Option value unit:: messages -Default value:: 1000 -Applicable socket types:: all - - ZMQ_AFFINITY: Set I/O thread affinity ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'ZMQ_AFFINITY' option shall set the I/O thread affinity for newly created @@ -99,38 +53,95 @@ Default value:: 0 Applicable socket types:: N/A -ZMQ_SUBSCRIBE: Establish message filter +ZMQ_BACKLOG: Set maximum length of the queue of outstanding connections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_BACKLOG' option shall set the maximum length of the queue of +outstanding peer connections for the specified 'socket'; this only applies to +connection-oriented transports. For details refer to your operating system +documentation for the 'listen' function. + +[horizontal] +Option value type:: int +Option value unit:: connections +Default value:: 100 +Applicable socket types:: all, only for connection-oriented transports. + + +ZMQ_CONFLATE: Keep only last message +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If set, a socket shall keep only one message in its inbound/outbound +queue, this message being the last message received/the last message +to be sent. Ignores 'ZMQ_RECVHWM' and 'ZMQ_SENDHWM' options. Does not +support multi-part messages, in particular, only one part of it is kept +in the socket internal queue. + +[horizontal] +Option value type:: int +Option value unit:: boolean +Default value:: 0 (false) +Applicable socket types:: ZMQ_PULL, ZMQ_PUSH, ZMQ_SUB, ZMQ_PUB, ZMQ_DEALER + + +ZMQ_CURVE_PUBLICKEY: Set CURVE public key +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sets the socket's long term public key. You must set this on CURVE client +sockets, see linkzmq:zmq_curve[7]. You can provide the key as 32 binary +bytes, or as a 40-character string encoded in the Z85 encoding format. +The public key must always be used with the matching secret key. To +generate a public/secret key pair, use linkzmq:zmq_curve_keypair[3]. + +[horizontal] +Option value type:: binary data or Z85 text string +Option value size:: 32 or 40 +Default value:: NULL +Applicable socket types:: all, when using TCP transport + + +ZMQ_CURVE_SECRETKEY: Set CURVE secret key +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sets the socket's long term secret key. You must set this on both CURVE +client and server sockets, see linkzmq:zmq_curve[7]. You can provide the +key as 32 binary bytes, or as a 40-character string encoded in the Z85 +encoding format. To generate a public/secret key pair, use +linkzmq:zmq_curve_keypair[3]. + +[horizontal] +Option value type:: binary data or Z85 text string +Option value size:: 32 or 40 +Default value:: NULL +Applicable socket types:: all, when using TCP transport + + +ZMQ_CURVE_SERVER: Set CURVE server role ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_SUBSCRIBE' option shall establish a new message filter on a 'ZMQ_SUB' -socket. Newly created 'ZMQ_SUB' sockets shall filter out all incoming messages, -therefore you should call this option to establish an initial message filter. - -An empty 'option_value' of length zero shall subscribe to all incoming -messages. A non-empty 'option_value' shall subscribe to all messages beginning -with the specified prefix. Multiple filters may be attached to a single -'ZMQ_SUB' socket, in which case a message shall be accepted if it matches at -least one filter. +Defines whether the socket will act as server for CURVE security, see +linkzmq:zmq_curve[7]. A value of '1' means the socket will act as +CURVE server. A value of '0' means the socket will not act as CURVE +server, and its security role then depends on other option settings. +Setting this to '0' shall reset the socket security to NULL. When you +set this you must also set the server's secret key using the +ZMQ_CURVE_SECRETKEY option. A server socket does not need to know +its own public key. [horizontal] -Option value type:: binary data -Option value unit:: N/A -Default value:: N/A -Applicable socket types:: ZMQ_SUB +Option value type:: int +Option value unit:: 0, 1 +Default value:: 0 +Applicable socket types:: all, when using TCP transport -ZMQ_UNSUBSCRIBE: Remove message filter -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_UNSUBSCRIBE' option shall remove an existing message filter on a -'ZMQ_SUB' socket. The filter specified must match an existing filter previously -established with the 'ZMQ_SUBSCRIBE' option. If the socket has several -instances of the same filter attached the 'ZMQ_UNSUBSCRIBE' option shall remove -only one instance, leaving the rest in place and functional. +ZMQ_CURVE_SERVERKEY: Set CURVE server key +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sets the socket's long term server key. You must set this on CURVE client +sockets, see linkzmq:zmq_curve[7]. You can provide the key as 32 binary +bytes, or as a 40-character string encoded in the Z85 encoding format. +This key must have been generated together with the server's secret key. [horizontal] -Option value type:: binary data -Option value unit:: N/A -Default value:: N/A -Applicable socket types:: ZMQ_SUB +Option value type:: binary data or Z85 text string +Option value size:: 32 or 40 +Default value:: NULL +Applicable socket types:: all, when using TCP transport ZMQ_IDENTITY: Set socket identity @@ -153,62 +164,105 @@ Default value:: NULL Applicable socket types:: ZMQ_REQ, ZMQ_REP, ZMQ_ROUTER, ZMQ_DEALER. -ZMQ_RATE: Set multicast data rate -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RATE' option shall set the maximum send or receive data rate for -multicast transports such as linkzmq:zmq_pgm[7] using the specified 'socket'. +ZMQ_IMMEDIATE: Queue messages only to completed connections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +By default queues will fill on outgoing connections even if the connection has +not completed. This can lead to "lost" messages on sockets with round-robin +routing (REQ, PUSH, DEALER). If this option is set to `1`, messages shall be +queued only to completed connections. This will cause the socket to block if +there are no other connections, but will prevent queues from filling on pipes +awaiting connection. [horizontal] Option value type:: int -Option value unit:: kilobits per second -Default value:: 100 -Applicable socket types:: all, when using multicast transports +Option value unit:: boolean +Default value:: 0 (false) +Applicable socket types:: all, only for connection-oriented transports. -ZMQ_RECOVERY_IVL: Set multicast recovery interval -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RECOVERY_IVL' option shall set the recovery interval for multicast -transports using the specified 'socket'. The recovery interval determines the -maximum time in milliseconds that a receiver can be absent from a multicast -group before unrecoverable data loss will occur. +ZMQ_IPC_FILTER_GID: Assign group ID filters to allow new IPC connections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Assign an arbitrary number of filters that will be applied for each new IPC +transport connection on a listening socket. If no IPC filters are applied, then +the IPC transport allows connections from any process. If at least one UID, +GID, or PID filter is applied then new connection credentials should be +matched. To clear all GID filters call zmq_setsockopt(socket, +ZMQ_IPC_FILTER_GID, NULL, 0). -CAUTION: Exercise care when setting large recovery intervals as the data -needed for recovery will be held in memory. For example, a 1 minute recovery -interval at a data rate of 1Gbps requires a 7GB in-memory buffer. +NOTE: GID filters are only available on platforms supporting SO_PEERCRED or +LOCAL_PEERCRED socket options (currently only Linux and later versions of +OS X). + +[horizontal] +Option value type:: gid_t +Option value unit:: N/A +Default value:: no filters (allow from all) +Applicable socket types:: all listening sockets, when using IPC transports. + + +ZMQ_IPC_FILTER_PID: Assign process ID filters to allow new IPC connections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Assign an arbitrary number of filters that will be applied for each new IPC +transport connection on a listening socket. If no IPC filters are applied, then +the IPC transport allows connections from any process. If at least one UID, +GID, or PID filter is applied then new connection credentials should be +matched. To clear all PID filters call zmq_setsockopt(socket, +ZMQ_IPC_FILTER_PID, NULL, 0). + +NOTE: PID filters are only available on platforms supporting the SO_PEERCRED +socket option (currently only Linux). + +[horizontal] +Option value type:: pid_t +Option value unit:: N/A +Default value:: no filters (allow from all) +Applicable socket types:: all listening sockets, when using IPC transports. + + +ZMQ_IPC_FILTER_UID: Assign user ID filters to allow new IPC connections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Assign an arbitrary number of filters that will be applied for each new IPC +transport connection on a listening socket. If no IPC filters are applied, then +the IPC transport allows connections from any process. If at least one UID, +GID, or PID filter is applied then new connection credentials should be +matched. To clear all UID filters call zmq_setsockopt(socket, +ZMQ_IPC_FILTER_UID, NULL, 0). + +NOTE: UID filters are only available on platforms supporting SO_PEERCRED or +LOCAL_PEERCRED socket options (currently only Linux and later versions of +OS X). + +[horizontal] +Option value type:: uid_t +Option value unit:: N/A +Default value:: no filters (allow from all) +Applicable socket types:: all listening sockets, when using IPC transports. + + +ZMQ_IPV4ONLY: Use IPv4-only on socket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Set the IPv4-only option for the socket. This option is deprecated. +Please use the ZMQ_IPV6 option. [horizontal] Option value type:: int -Option value unit:: milliseconds -Default value:: 10000 -Applicable socket types:: all, when using multicast transports +Option value unit:: boolean +Default value:: 1 (true) +Applicable socket types:: all, when using TCP transports. -ZMQ_SNDBUF: Set kernel transmit buffer size -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_SNDBUF' option shall set the underlying kernel transmit buffer size -for the 'socket' to the specified size in bytes. A value of zero means leave -the OS default unchanged. For details please refer to your operating system -documentation for the 'SO_SNDBUF' socket option. +ZMQ_IPV6: Enable IPv6 on socket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Set the IPv6 option for the socket. A value of `1` means IPv6 is +enabled on the socket, while `0` means the socket will use only IPv4. +When IPv6 is enabled the socket will connect to, or accept connections +from, both IPv4 and IPv6 hosts. [horizontal] Option value type:: int -Option value unit:: bytes -Default value:: 0 -Applicable socket types:: all - - -ZMQ_RCVBUF: Set kernel receive buffer size -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RCVBUF' option shall set the underlying kernel receive buffer size for -the 'socket' to the specified size in bytes. A value of zero means leave the -OS default unchanged. For details refer to your operating system documentation -for the 'SO_RCVBUF' socket option. - -[horizontal] -Option value type:: int -Option value unit:: bytes -Default value:: 0 -Applicable socket types:: all +Option value unit:: boolean +Default value:: 0 (false) +Applicable socket types:: all, when using TCP transports. ZMQ_LINGER: Set linger period for socket shutdown @@ -241,6 +295,154 @@ Default value:: -1 (infinite) Applicable socket types:: all +ZMQ_MAXMSGSIZE: Maximum acceptable inbound message size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Limits the size of the inbound message. If a peer sends a message larger than +ZMQ_MAXMSGSIZE it is disconnected. Value of -1 means 'no limit'. + +[horizontal] +Option value type:: int64_t +Option value unit:: bytes +Default value:: -1 +Applicable socket types:: all + + +ZMQ_MULTICAST_HOPS: Maximum network hops for multicast packets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sets the time-to-live field in every multicast packet sent from this socket. +The default is 1 which means that the multicast packets don't leave the local +network. + +[horizontal] +Option value type:: int +Option value unit:: network hops +Default value:: 1 +Applicable socket types:: all, when using multicast transports + + +ZMQ_PLAIN_PASSWORD: Set PLAIN security password +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sets the password for outgoing connections over TCP or IPC. If you set this +to a non-null value, the security mechanism used for connections shall be +PLAIN, see linkzmq:zmq_plain[7]. If you set this to a null value, the security +mechanism used for connections shall be NULL, see linkzmq:zmq_null[3]. + +[horizontal] +Option value type:: character string +Option value unit:: N/A +Default value:: not set +Applicable socket types:: all, when using TCP transport + + +ZMQ_PLAIN_SERVER: Set PLAIN server role +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Defines whether the socket will act as server for PLAIN security, see +linkzmq:zmq_plain[7]. A value of '1' means the socket will act as +PLAIN server. A value of '0' means the socket will not act as PLAIN +server, and its security role then depends on other option settings. +Setting this to '0' shall reset the socket security to NULL. + +[horizontal] +Option value type:: int +Option value unit:: 0, 1 +Default value:: 0 +Applicable socket types:: all, when using TCP transport + + +ZMQ_PLAIN_USERNAME: Set PLAIN security username +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sets the username for outgoing connections over TCP or IPC. If you set this +to a non-null value, the security mechanism used for connections shall be +PLAIN, see linkzmq:zmq_plain[7]. If you set this to a null value, the security +mechanism used for connections shall be NULL, see linkzmq:zmq_null[3]. + +[horizontal] +Option value type:: character string +Option value unit:: N/A +Default value:: not set +Applicable socket types:: all, when using TCP transport + + +ZMQ_PROBE_ROUTER: bootstrap connections to ROUTER sockets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +When set to 1, the socket will automatically send an empty message when a +new connection is made or accepted. You may set this on REQ, DEALER, or +ROUTER sockets connected to a ROUTER socket. The application must filter +such empty messages. The ZMQ_PROBE_ROUTER option in effect provides the +ROUTER application with an event signaling the arrival of a new peer. + +NOTE: do not set this option on a socket that talks to any other socket +types: the results are undefined. + +[horizontal] +Option value type:: int +Option value unit:: 0, 1 +Default value:: 0 +Applicable socket types:: ZMQ_ROUTER, ZMQ_DEALER, ZMQ_REQ + + +ZMQ_RATE: Set multicast data rate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RATE' option shall set the maximum send or receive data rate for +multicast transports such as linkzmq:zmq_pgm[7] using the specified 'socket'. + +[horizontal] +Option value type:: int +Option value unit:: kilobits per second +Default value:: 100 +Applicable socket types:: all, when using multicast transports + + +ZMQ_RCVBUF: Set kernel receive buffer size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RCVBUF' option shall set the underlying kernel receive buffer size for +the 'socket' to the specified size in bytes. A value of zero means leave the +OS default unchanged. For details refer to your operating system documentation +for the 'SO_RCVBUF' socket option. + +[horizontal] +Option value type:: int +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +ZMQ_RCVHWM: Set high water mark for inbound messages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RCVHWM' option shall set the high water mark for inbound messages on +the specified 'socket'. The high water mark is a hard limit on the maximum +number of outstanding messages 0MQ shall queue in memory for any single peer +that the specified 'socket' is communicating with. A value of zero means no +limit. + +If this limit has been reached the socket shall enter an exceptional state and +depending on the socket type, 0MQ shall take appropriate action such as +blocking or dropping sent messages. Refer to the individual socket descriptions +in linkzmq:zmq_socket[3] for details on the exact action taken for each socket +type. + +[horizontal] +Option value type:: int +Option value unit:: messages +Default value:: 1000 +Applicable socket types:: all + + +ZMQ_RCVTIMEO: Maximum time before a recv operation returns with EAGAIN +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sets the timeout for receive operation on the socket. If the value is `0`, +_zmq_recv(3)_ will return immediately, with a EAGAIN error if there is no +message to receive. If the value is `-1`, it will block until a message is +available. For all other values, it will wait for a message for that amount +of time before returning with an EAGAIN error. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: -1 (infinite) +Applicable socket types:: all + + ZMQ_RECONNECT_IVL: Set reconnection interval ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'ZMQ_RECONNECT_IVL' option shall set the initial reconnection interval for @@ -276,137 +478,59 @@ Default value:: 0 (only use ZMQ_RECONNECT_IVL) Applicable socket types:: all, only for connection-oriented transports -ZMQ_BACKLOG: Set maximum length of the queue of outstanding connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_BACKLOG' option shall set the maximum length of the queue of -outstanding peer connections for the specified 'socket'; this only applies to -connection-oriented transports. For details refer to your operating system -documentation for the 'listen' function. +ZMQ_RECOVERY_IVL: Set multicast recovery interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RECOVERY_IVL' option shall set the recovery interval for multicast +transports using the specified 'socket'. The recovery interval determines the +maximum time in milliseconds that a receiver can be absent from a multicast +group before unrecoverable data loss will occur. + +CAUTION: Exercise care when setting large recovery intervals as the data +needed for recovery will be held in memory. For example, a 1 minute recovery +interval at a data rate of 1Gbps requires a 7GB in-memory buffer. [horizontal] Option value type:: int -Option value unit:: connections -Default value:: 100 -Applicable socket types:: all, only for connection-oriented transports. - - -ZMQ_MAXMSGSIZE: Maximum acceptable inbound message size -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Limits the size of the inbound message. If a peer sends a message larger than -ZMQ_MAXMSGSIZE it is disconnected. Value of -1 means 'no limit'. - -[horizontal] -Option value type:: int64_t -Option value unit:: bytes -Default value:: -1 -Applicable socket types:: all - - -ZMQ_MULTICAST_HOPS: Maximum network hops for multicast packets -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sets the time-to-live field in every multicast packet sent from this socket. -The default is 1 which means that the multicast packets don't leave the local -network. - -[horizontal] -Option value type:: int -Option value unit:: network hops -Default value:: 1 +Option value unit:: milliseconds +Default value:: 10000 Applicable socket types:: all, when using multicast transports -ZMQ_RCVTIMEO: Maximum time before a recv operation returns with EAGAIN -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sets the timeout for receive operation on the socket. If the value is `0`, -_zmq_recv(3)_ will return immediately, with a EAGAIN error if there is no -message to receive. If the value is `-1`, it will block until a message is -available. For all other values, it will wait for a message for that amount -of time before returning with an EAGAIN error. +ZMQ_REQ_CORRELATE: match replies with requests +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The default behavior of REQ sockets is to rely on the ordering of messages to +match requests and responses and that is usually sufficient. When this option +is set to 1, the REQ socket will prefix outgoing messages with an extra frame +containing a request id. That means the full message is (request id, 0, +user frames...). The REQ socket will discard all incoming messages that don't +begin with these two frames. [horizontal] Option value type:: int -Option value unit:: milliseconds -Default value:: -1 (infinite) -Applicable socket types:: all - - -ZMQ_SNDTIMEO: Maximum time before a send operation returns with EAGAIN -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sets the timeout for send operation on the socket. If the value is `0`, -_zmq_send(3)_ will return immediately, with a EAGAIN error if the message -cannot be sent. If the value is `-1`, it will block until the message is sent. -For all other values, it will try to send the message for that amount of time -before returning with an EAGAIN error. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: -1 (infinite) -Applicable socket types:: all - - -ZMQ_IPV6: Enable IPv6 on socket -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Set the IPv6 option for the socket. A value of `1` means IPv6 is -enabled on the socket, while `0` means the socket will use only IPv4. -When IPv6 is enabled the socket will connect to, or accept connections -from, both IPv4 and IPv6 hosts. - -[horizontal] -Option value type:: int -Option value unit:: boolean -Default value:: 0 (false) -Applicable socket types:: all, when using TCP transports. - - -ZMQ_IPV4ONLY: Use IPv4-only on socket -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Set the IPv4-only option for the socket. This option is deprecated. -Please use the ZMQ_IPV6 option. - -[horizontal] -Option value type:: int -Option value unit:: boolean -Default value:: 1 (true) -Applicable socket types:: all, when using TCP transports. - - -ZMQ_TOS: Set the Type-of-Service on socket -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sets the ToS fields (Differentiated services (DS) and Explicit Congestion Notification -(ECN) field of the IP header. The ToS field is typically used to specify a packets -priority. The availability of this option is dependent on intermediate network -equipment that inspect the ToS field andprovide a path for low-delay, high-throughput, -highly-reliable service, etc. - -[horizontal] -Option value type:: int -Option value unit:: >0 +Option value unit:: 0, 1 Default value:: 0 -Applicable socket types:: all, only for connection-oriented transports +Applicable socket types:: ZMQ_REQ -ZMQ_IMMEDIATE: Queue messages only to completed connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +ZMQ_REQ_RELAXED: relax strict alternation between request and reply +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +By default, a REQ socket does not allow initiating a new request with +_zmq_send(3)_ until the reply to the previous one has been received. +When set to 1, sending another message is allowed and has the effect of +disconnecting the underlying connection to the peer from which the reply was +expected, triggering a reconnection attempt on transports that support it. +The request-reply state machine is reset and a new request is sent to the +next available peer. -By default queues will fill on outgoing connections even if the connection has -not completed. This can lead to "lost" messages on sockets with round-robin -routing (REQ, PUSH, DEALER). If this option is set to `1`, messages shall be -queued only to completed connections. This will cause the socket to block if -there are no other connections, but will prevent queues from filling on pipes -awaiting connection. +If set to 1, also enable ZMQ_REQ_CORRELATE to ensure correct matching of +requests and replies. Otherwise a late reply to an aborted request can be +reported as the reply to the superseding request. [horizontal] Option value type:: int -Option value unit:: boolean -Default value:: 0 (false) -Applicable socket types:: all, only for connection-oriented transports. +Option value unit:: 0, 1 +Default value:: 0 +Applicable socket types:: ZMQ_REQ ZMQ_ROUTER_HANDOVER: handle duplicate client identities on ROUTER sockets @@ -427,7 +551,6 @@ Applicable socket types:: ZMQ_ROUTER ZMQ_ROUTER_MANDATORY: accept only routable messages on ROUTER sockets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Sets the ROUTER socket behavior when an unroutable message is encountered. A value of `0` is the default and discards the message silently when it cannot be routed. A value of `1` returns an 'EHOSTUNREACH' error code if the message @@ -442,7 +565,6 @@ Applicable socket types:: ZMQ_ROUTER ZMQ_ROUTER_RAW: switch ROUTER socket to raw mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Sets the raw mode on the ROUTER, when set to 1. When the ROUTER socket is in raw mode, and when using the tcp:// transport, it will read and write TCP data without 0MQ framing. This lets 0MQ applications talk to non-0MQ applications. @@ -459,134 +581,81 @@ Default value:: 0 Applicable socket types:: ZMQ_ROUTER -ZMQ_PROBE_ROUTER: bootstrap connections to ROUTER sockets -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When set to 1, the socket will automatically send an empty message when a -new connection is made or accepted. You may set this on REQ, DEALER, or -ROUTER sockets connected to a ROUTER socket. The application must filter -such empty messages. The ZMQ_PROBE_ROUTER option in effect provides the -ROUTER application with an event signaling the arrival of a new peer. - -NOTE: do not set this option on a socket that talks to any other socket -types: the results are undefined. +ZMQ_SNDBUF: Set kernel transmit buffer size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_SNDBUF' option shall set the underlying kernel transmit buffer size +for the 'socket' to the specified size in bytes. A value of zero means leave +the OS default unchanged. For details please refer to your operating system +documentation for the 'SO_SNDBUF' socket option. [horizontal] Option value type:: int -Option value unit:: 0, 1 +Option value unit:: bytes Default value:: 0 -Applicable socket types:: ZMQ_ROUTER, ZMQ_DEALER, ZMQ_REQ +Applicable socket types:: all -ZMQ_XPUB_VERBOSE: provide all subscription messages on XPUB sockets -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +ZMQ_SNDHWM: Set high water mark for outbound messages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_SNDHWM' option shall set the high water mark for outbound messages on +the specified 'socket'. The high water mark is a hard limit on the maximum +number of outstanding messages 0MQ shall queue in memory for any single peer +that the specified 'socket' is communicating with. A value of zero means no +limit. -Sets the 'XPUB' socket behavior on new subscriptions and unsubscriptions. -A value of '0' is the default and passes only new subscription messages to -upstream. A value of '1' passes all subscription messages upstream. +If this limit has been reached the socket shall enter an exceptional state and +depending on the socket type, 0MQ shall take appropriate action such as +blocking or dropping sent messages. Refer to the individual socket descriptions +in linkzmq:zmq_socket[3] for details on the exact action taken for each socket +type. + +NOTE: 0MQ does not guarantee that the socket will accept as many as ZMQ_SNDHWM +messages, and the actual limit may be as much as 60-70% lower depending on the +flow of messages on the socket. [horizontal] Option value type:: int -Option value unit:: 0, 1 -Default value:: 0 -Applicable socket types:: ZMQ_XPUB +Option value unit:: messages +Default value:: 1000 +Applicable socket types:: all -ZMQ_REQ_CORRELATE: match replies with requests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The default behavior of REQ sockets is to rely on the ordering of messages to -match requests and responses and that is usually sufficient. When this option -is set to 1, the REQ socket will prefix outgoing messages with an extra frame -containing a request id. That means the full message is (request id, 0, -user frames...). The REQ socket will discard all incoming messages that don't -begin with these two frames. +ZMQ_SNDTIMEO: Maximum time before a send operation returns with EAGAIN +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sets the timeout for send operation on the socket. If the value is `0`, +_zmq_send(3)_ will return immediately, with a EAGAIN error if the message +cannot be sent. If the value is `-1`, it will block until the message is sent. +For all other values, it will try to send the message for that amount of time +before returning with an EAGAIN error. [horizontal] Option value type:: int -Option value unit:: 0, 1 -Default value:: 0 -Applicable socket types:: ZMQ_REQ +Option value unit:: milliseconds +Default value:: -1 (infinite) +Applicable socket types:: all -ZMQ_REQ_RELAXED: relax strict alternation between request and reply -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +ZMQ_SUBSCRIBE: Establish message filter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_SUBSCRIBE' option shall establish a new message filter on a 'ZMQ_SUB' +socket. Newly created 'ZMQ_SUB' sockets shall filter out all incoming messages, +therefore you should call this option to establish an initial message filter. -By default, a REQ socket does not allow initiating a new request with -_zmq_send(3)_ until the reply to the previous one has been received. -When set to 1, sending another message is allowed and has the effect of -disconnecting the underlying connection to the peer from which the reply was -expected, triggering a reconnection attempt on transports that support it. -The request-reply state machine is reset and a new request is sent to the -next available peer. - -If set to 1, also enable ZMQ_REQ_CORRELATE to ensure correct matching of -requests and replies. Otherwise a late reply to an aborted request can be -reported as the reply to the superseding request. +An empty 'option_value' of length zero shall subscribe to all incoming +messages. A non-empty 'option_value' shall subscribe to all messages beginning +with the specified prefix. Multiple filters may be attached to a single +'ZMQ_SUB' socket, in which case a message shall be accepted if it matches at +least one filter. [horizontal] -Option value type:: int -Option value unit:: 0, 1 -Default value:: 0 -Applicable socket types:: ZMQ_REQ - - -ZMQ_TCP_KEEPALIVE: Override SO_KEEPALIVE socket option -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Override 'SO_KEEPALIVE' socket option (where supported by OS). -The default value of `-1` means to skip any overrides and leave it to OS default. - -[horizontal] -Option value type:: int -Option value unit:: -1,0,1 -Default value:: -1 (leave to OS default) -Applicable socket types:: all, when using TCP transports. - - -ZMQ_TCP_KEEPALIVE_IDLE: Override TCP_KEEPCNT (or TCP_KEEPALIVE on some OS) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Override 'TCP_KEEPCNT'(or 'TCP_KEEPALIVE' on some OS) socket option (where -supported by OS). The default value of `-1` means to skip any overrides and -leave it to OS default. - -[horizontal] -Option value type:: int -Option value unit:: -1,>0 -Default value:: -1 (leave to OS default) -Applicable socket types:: all, when using TCP transports. - - -ZMQ_TCP_KEEPALIVE_CNT: Override TCP_KEEPCNT socket option -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Override 'TCP_KEEPCNT' socket option (where supported by OS). The default -value of `-1` means to skip any overrides and leave it to OS default. - -[horizontal] -Option value type:: int -Option value unit:: -1,>0 -Default value:: -1 (leave to OS default) -Applicable socket types:: all, when using TCP transports. - - -ZMQ_TCP_KEEPALIVE_INTVL: Override TCP_KEEPINTVL socket option -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Override 'TCP_KEEPINTVL' socket option(where supported by OS). The default -value of `-1` means to skip any overrides and leave it to OS default. - -[horizontal] -Option value type:: int -Option value unit:: -1,>0 -Default value:: -1 (leave to OS default) -Applicable socket types:: all, when using TCP transports. +Option value type:: binary data +Option value unit:: N/A +Default value:: N/A +Applicable socket types:: ZMQ_SUB ZMQ_TCP_ACCEPT_FILTER: Assign filters to allow new TCP connections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Assign an arbitrary number of filters that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one @@ -601,71 +670,115 @@ Default value:: no filters (allow from all) Applicable socket types:: all listening sockets, when using TCP transports. -ZMQ_IPC_FILTER_UID: Assign user ID filters to allow new IPC connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Assign an arbitrary number of filters that will be applied for each new IPC -transport connection on a listening socket. If no IPC filters are applied, then -the IPC transport allows connections from any process. If at least one UID, -GID, or PID filter is applied then new connection credentials should be -matched. To clear all UID filters call zmq_setsockopt(socket, -ZMQ_IPC_FILTER_UID, NULL, 0). - -NOTE: UID filters are only available on platforms supporting SO_PEERCRED or -LOCAL_PEERCRED socket options (currently only Linux and later versions of -OS X). +ZMQ_TCP_KEEPALIVE: Override SO_KEEPALIVE socket option +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Override 'SO_KEEPALIVE' socket option (where supported by OS). +The default value of `-1` means to skip any overrides and leave it to OS default. [horizontal] -Option value type:: uid_t -Option value unit:: N/A -Default value:: no filters (allow from all) -Applicable socket types:: all listening sockets, when using IPC transports. +Option value type:: int +Option value unit:: -1,0,1 +Default value:: -1 (leave to OS default) +Applicable socket types:: all, when using TCP transports. -ZMQ_IPC_FILTER_GID: Assign group ID filters to allow new IPC connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Assign an arbitrary number of filters that will be applied for each new IPC -transport connection on a listening socket. If no IPC filters are applied, then -the IPC transport allows connections from any process. If at least one UID, -GID, or PID filter is applied then new connection credentials should be -matched. To clear all GID filters call zmq_setsockopt(socket, -ZMQ_IPC_FILTER_GID, NULL, 0). - -NOTE: GID filters are only available on platforms supporting SO_PEERCRED or -LOCAL_PEERCRED socket options (currently only Linux and later versions of -OS X). +ZMQ_TCP_KEEPALIVE_CNT: Override TCP_KEEPCNT socket option +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Override 'TCP_KEEPCNT' socket option (where supported by OS). The default +value of `-1` means to skip any overrides and leave it to OS default. [horizontal] -Option value type:: gid_t -Option value unit:: N/A -Default value:: no filters (allow from all) -Applicable socket types:: all listening sockets, when using IPC transports. +Option value type:: int +Option value unit:: -1,>0 +Default value:: -1 (leave to OS default) +Applicable socket types:: all, when using TCP transports. -ZMQ_IPC_FILTER_PID: Assign process ID filters to allow new IPC connections +ZMQ_TCP_KEEPALIVE_IDLE: Override TCP_KEEPCNT (or TCP_KEEPALIVE on some OS) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Assign an arbitrary number of filters that will be applied for each new IPC -transport connection on a listening socket. If no IPC filters are applied, then -the IPC transport allows connections from any process. If at least one UID, -GID, or PID filter is applied then new connection credentials should be -matched. To clear all PID filters call zmq_setsockopt(socket, -ZMQ_IPC_FILTER_PID, NULL, 0). - -NOTE: PID filters are only available on platforms supporting the SO_PEERCRED -socket option (currently only Linux). +Override 'TCP_KEEPCNT' (or 'TCP_KEEPALIVE' on some OS) socket option (where +supported by OS). The default value of `-1` means to skip any overrides and +leave it to OS default. [horizontal] -Option value type:: pid_t +Option value type:: int +Option value unit:: -1,>0 +Default value:: -1 (leave to OS default) +Applicable socket types:: all, when using TCP transports. + + +ZMQ_TCP_KEEPALIVE_INTVL: Override TCP_KEEPINTVL socket option +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Override 'TCP_KEEPINTVL' socket option(where supported by OS). The default +value of `-1` means to skip any overrides and leave it to OS default. + +[horizontal] +Option value type:: int +Option value unit:: -1,>0 +Default value:: -1 (leave to OS default) +Applicable socket types:: all, when using TCP transports. + + +ZMQ_TOS: Set the Type-of-Service on socket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sets the ToS fields (Differentiated services (DS) and Explicit Congestion +Notification (ECN) field of the IP header. The ToS field is typically used +to specify a packets priority. The availability of this option is dependent +on intermediate network equipment that inspect the ToS field andprovide a +path for low-delay, high-throughput, highly-reliable service, etc. + +[horizontal] +Option value type:: int +Option value unit:: >0 +Default value:: 0 +Applicable socket types:: all, only for connection-oriented transports + + +ZMQ_UNSUBSCRIBE: Remove message filter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_UNSUBSCRIBE' option shall remove an existing message filter on a +'ZMQ_SUB' socket. The filter specified must match an existing filter previously +established with the 'ZMQ_SUBSCRIBE' option. If the socket has several +instances of the same filter attached the 'ZMQ_UNSUBSCRIBE' option shall remove +only one instance, leaving the rest in place and functional. + +[horizontal] +Option value type:: binary data Option value unit:: N/A -Default value:: no filters (allow from all) -Applicable socket types:: all listening sockets, when using IPC transports. +Default value:: N/A +Applicable socket types:: ZMQ_SUB + + +ZMQ_XPUB_VERBOSE: provide all subscription messages on XPUB sockets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sets the 'XPUB' socket behavior on new subscriptions and unsubscriptions. +A value of '0' is the default and passes only new subscription messages to +upstream. A value of '1' passes all subscription messages upstream. + +[horizontal] +Option value type:: int +Option value unit:: 0, 1 +Default value:: 0 +Applicable socket types:: ZMQ_XPUB + + +ZMQ_ZAP_DOMAIN: Set RFC 27 authentication domain +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the +default on all tcp:// connections), ZAP authentication only happens if you +set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always +made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 +for more details. + +[horizontal] +Option value type:: character string +Option value unit:: N/A +Default value:: not set +Applicable socket types:: all, when using TCP transport ZMQ_ZAP_IPC_CREDS: Append IPC peer credentials to ZAP address ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - If set, the credentials of IPC peers will be appended to the address sent in ZAP request messages. The new address will be formatted as ADDRESS:UID:GID:PID where UID and GID are the effective group and user IDs of the user owning the @@ -682,150 +795,6 @@ Default value:: 0 (false) Applicable socket types:: all listening sockets, when using IPC transports. -ZMQ_PLAIN_SERVER: Set PLAIN server role -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Defines whether the socket will act as server for PLAIN security, see -linkzmq:zmq_plain[7]. A value of '1' means the socket will act as -PLAIN server. A value of '0' means the socket will not act as PLAIN -server, and its security role then depends on other option settings. -Setting this to '0' shall reset the socket security to NULL. - -[horizontal] -Option value type:: int -Option value unit:: 0, 1 -Default value:: 0 -Applicable socket types:: all, when using TCP transport - - -ZMQ_PLAIN_USERNAME: Set PLAIN security username -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sets the username for outgoing connections over TCP or IPC. If you set this -to a non-null value, the security mechanism used for connections shall be -PLAIN, see linkzmq:zmq_plain[7]. If you set this to a null value, the security -mechanism used for connections shall be NULL, see linkzmq:zmq_null[3]. - -[horizontal] -Option value type:: character string -Option value unit:: N/A -Default value:: not set -Applicable socket types:: all, when using TCP transport - - -ZMQ_PLAIN_PASSWORD: Set PLAIN security password -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sets the password for outgoing connections over TCP or IPC. If you set this -to a non-null value, the security mechanism used for connections shall be -PLAIN, see linkzmq:zmq_plain[7]. If you set this to a null value, the security -mechanism used for connections shall be NULL, see linkzmq:zmq_null[3]. - -[horizontal] -Option value type:: character string -Option value unit:: N/A -Default value:: not set -Applicable socket types:: all, when using TCP transport - - -ZMQ_CURVE_SERVER: Set CURVE server role -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Defines whether the socket will act as server for CURVE security, see -linkzmq:zmq_curve[7]. A value of '1' means the socket will act as -CURVE server. A value of '0' means the socket will not act as CURVE -server, and its security role then depends on other option settings. -Setting this to '0' shall reset the socket security to NULL. When you -set this you must also set the server's secret key using the -ZMQ_CURVE_SECRETKEY option. A server socket does not need to know -its own public key. - -[horizontal] -Option value type:: int -Option value unit:: 0, 1 -Default value:: 0 -Applicable socket types:: all, when using TCP transport - - -ZMQ_CURVE_PUBLICKEY: Set CURVE public key -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sets the socket's long term public key. You must set this on CURVE client -sockets, see linkzmq:zmq_curve[7]. You can provide the key as 32 binary -bytes, or as a 40-character string encoded in the Z85 encoding format. -The public key must always be used with the matching secret key. To -generate a public/secret key pair, use linkzmq:zmq_curve_keypair[3]. - -[horizontal] -Option value type:: binary data or Z85 text string -Option value size:: 32 or 40 -Default value:: NULL -Applicable socket types:: all, when using TCP transport - - -ZMQ_CURVE_SECRETKEY: Set CURVE secret key -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sets the socket's long term secret key. You must set this on both CURVE -client and server sockets, see linkzmq:zmq_curve[7]. You can provide the -key as 32 binary bytes, or as a 40-character string encoded in the Z85 -encoding format. To generate a public/secret key pair, use -linkzmq:zmq_curve_keypair[3]. - -[horizontal] -Option value type:: binary data or Z85 text string -Option value size:: 32 or 40 -Default value:: NULL -Applicable socket types:: all, when using TCP transport - - -ZMQ_CURVE_SERVERKEY: Set CURVE server key -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sets the socket's long term server key. You must set this on CURVE client -sockets, see linkzmq:zmq_curve[7]. You can provide the key as 32 binary -bytes, or as a 40-character string encoded in the Z85 encoding format. -This key must have been generated together with the server's secret key. - -[horizontal] -Option value type:: binary data or Z85 text string -Option value size:: 32 or 40 -Default value:: NULL -Applicable socket types:: all, when using TCP transport - - -ZMQ_ZAP_DOMAIN: Set RFC 27 authentication domain -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the -default on all tcp:// connections), ZAP authentication only happens if you -set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always -made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 -for more details. - -[horizontal] -Option value type:: character string -Option value unit:: N/A -Default value:: not set -Applicable socket types:: all, when using TCP transport - - -ZMQ_CONFLATE: Keep only last message -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If set, a socket shall keep only one message in its inbound/outbound -queue, this message being the last message received/the last message -to be sent. -Ignores 'ZMQ_RECVHWM' and 'ZMQ_SENDHWM' options. -Does not supports multi-part messages, in particular, only one part of it -is kept in the socket internal queue. -[horizontal] -Option value type:: int -Option value unit:: boolean -Default value:: 0 (false) -Applicable socket types:: ZMQ_PULL, ZMQ_PUSH, ZMQ_SUB, ZMQ_PUB, ZMQ_DEALER - - RETURN VALUE ------------ The _zmq_setsockopt()_ function shall return zero if successful. Otherwise it