/extension/libzmq/doc/zmq_setsockopt.txt
Plain Text | 881 lines | 696 code | 185 blank | 0 comment | 0 complexity | 170177567e7ae2bf353fa6c7980a4b45 MD5 | raw file
Possible License(s): AGPL-3.0, LGPL-2.0, GPL-3.0, LGPL-3.0
- zmq_setsockopt(3)
- =================
- NAME
- ----
- zmq_setsockopt - set 0MQ socket options
- SYNOPSIS
- --------
- *int zmq_setsockopt (void '*socket', int 'option_name', const void '*option_value', size_t 'option_len');*
- Caution: All options, with the exception of ZMQ_SUBSCRIBE, ZMQ_UNSUBSCRIBE,
- ZMQ_LINGER, ZMQ_ROUTER_HANDOVER, ZMQ_ROUTER_MANDATORY, ZMQ_PROBE_ROUTER,
- ZMQ_XPUB_VERBOSE, ZMQ_REQ_CORRELATE, and ZMQ_REQ_RELAXED, only take effect for
- subsequent socket bind/connects.
- Specifically, security options take effect for subsequent bind/connect calls,
- and can be changed at any time to affect subsequent binds and/or connects.
- DESCRIPTION
- -----------
- The _zmq_setsockopt()_ function shall set the option specified by the
- 'option_name' argument to the value pointed to by the 'option_value' argument
- for the 0MQ socket pointed to by the 'socket' argument. The 'option_len'
- argument is the size of the option value in bytes.
- The following socket options can be set with the _zmq_setsockopt()_ function:
- ZMQ_AFFINITY: Set I/O thread affinity
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The 'ZMQ_AFFINITY' option shall set the I/O thread affinity for newly created
- connections on the specified 'socket'.
- Affinity determines which threads from the 0MQ I/O thread pool associated with
- the socket's _context_ shall handle newly created connections. A value of zero
- specifies no affinity, meaning that work shall be distributed fairly among all
- 0MQ I/O threads in the thread pool. For non-zero values, the lowest bit
- corresponds to thread 1, second lowest bit to thread 2 and so on. For example,
- a value of 3 specifies that subsequent connections on 'socket' shall be handled
- exclusively by I/O threads 1 and 2.
- See also linkzmq:zmq_init[3] for details on allocating the number of I/O
- threads for a specific _context_.
- [horizontal]
- Option value type:: uint64_t
- Option value unit:: N/A (bitmap)
- Default value:: 0
- Applicable socket types:: N/A
- 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_CONNECT_RID: Assign the next outbound connection id
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The 'ZMQ_CONNECT_RID' option sets the peer id of the next host connected
- via the zmq_connect() call, and immediately readies that connection for
- data transfer with the named id. This option applies only to the first
- subsequent call to zmq_connect(), calls thereafter use default connection
- behavior.
- Typical use is to set this socket option ahead of each zmq_connect() attempt
- to a new host. Each connection MUST be assigned a unique name. Assigning a
- name that is already in use is not allowed.
- Useful when connecting ROUTER to ROUTER, or STREAM to STREAM, as it
- allows for immediate sending to peers. Outbound id framing requirements
- for ROUTER and STREAM sockets apply.
- The peer id should be from 1 to 255 bytes long and MAY NOT start with
- binary zero.
- [horizontal]
- Option value type:: binary data
- Option value unit:: N/A
- Default value:: NULL
- Applicable socket types:: ZMQ_ROUTER, ZMQ_STREAM
- 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_RCVHWM' and 'ZMQ_SNDHWM' 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
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- 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_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_HANDSHAKE_IVL: Set maximum handshake interval
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The 'ZMQ_HANDSHAKE_IVL' option shall set the maximum handshake interval for
- the specified 'socket'. Handshaking is the exchange of socket configuration
- information (socket type, identity, security) that occurs when a connection
- is first opened, only for connection-oriented transports. If handshaking does
- not complete within the configured time, the connection shall be closed.
- The value 0 means no handshake time limit.
- [horizontal]
- Option value type:: int
- Option value unit:: milliseconds
- Default value:: 30000
- Applicable socket types:: all but ZMQ_STREAM, only for connection-oriented transports
- ZMQ_IDENTITY: Set socket identity
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The 'ZMQ_IDENTITY' option shall set the identity of the specified 'socket'
- when connecting to a ROUTER socket. The identity should be from 1 to 255
- bytes long and may contain any values.
- If two clients use the same identity when connecting to a ROUTER, the
- results shall depend on the ZMQ_ROUTER_HANDOVER option setting. If that
- is not set (or set to the default of zero), the ROUTER socket shall reject
- clients trying to connect with an already-used identity. If that option
- is set to 1, the ROUTER socket shall hand-over the connection to the new
- client and disconnect the existing one.
- [horizontal]
- Option value type:: binary data
- Option value unit:: N/A
- Default value:: NULL
- Applicable socket types:: ZMQ_REQ, ZMQ_REP, ZMQ_ROUTER, ZMQ_DEALER.
- 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:: boolean
- Default value:: 0 (false)
- Applicable socket types:: all, only for connection-oriented 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).
- [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:: boolean
- Default value:: 1 (true)
- Applicable socket types:: all, when using TCP transports.
- 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_LINGER: Set linger period for socket shutdown
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The 'ZMQ_LINGER' option shall set 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 disconnected with
- linkzmq:zmq_disconnect[3] or 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_disconnect()_ or
- _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 after a call to _zmq_disconnect()_ or _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_disconnect()_ or
- _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
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- 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
- 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: Set maximum reconnection interval
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The 'ZMQ_RECONNECT_IVL_MAX' option shall set 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 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.
- 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:: milliseconds
- Default value:: 10000
- Applicable socket types:: all, when using multicast transports
- 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:: 0, 1
- Default value:: 0
- Applicable socket types:: ZMQ_REQ
- 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.
- 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:: 0, 1
- Default value:: 0
- Applicable socket types:: ZMQ_REQ
- ZMQ_ROUTER_HANDOVER: handle duplicate client identities on ROUTER sockets
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- If two clients use the same identity when connecting to a ROUTER, the
- results shall depend on the ZMQ_ROUTER_HANDOVER option setting. If that
- is not set (or set to the default of zero), the ROUTER socket shall reject
- clients trying to connect with an already-used identity. If that option
- is set to 1, the ROUTER socket shall hand-over the connection to the new
- client and disconnect the existing one.
- [horizontal]
- Option value type:: int
- Option value unit:: 0, 1
- Default value:: 0
- 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
- cannot be routed.
- [horizontal]
- Option value type:: int
- Option value unit:: 0, 1
- Default value:: 0
- 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.
- When using raw mode, you cannot set explicit identities, and the ZMQ_SNDMORE
- flag is ignored when sending data messages. In raw mode you can close a specific
- connection by sending it a zero-length message (following the identity frame).
- NOTE: This option is deprecated, please use ZMQ_STREAM sockets instead.
- [horizontal]
- Option value type:: int
- Option value unit:: 0, 1
- Default value:: 0
- Applicable socket types:: ZMQ_ROUTER
- 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:: bytes
- Default value:: 0
- Applicable socket types:: all
- 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_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_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.
- 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:: 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
- filter is applied then new connection source ip should be matched. To clear
- all filters call zmq_setsockopt(socket, ZMQ_TCP_ACCEPT_FILTER, NULL, 0).
- Filter is a null-terminated string with ipv6 or ipv4 CIDR.
- [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 TCP 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_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: 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:: 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
- RETURN VALUE
- ------------
- The _zmq_setsockopt()_ function shall return zero if successful. Otherwise it
- shall return `-1` and set 'errno' to one of the values defined below.
- ERRORS
- ------
- *EINVAL*::
- The requested option _option_name_ is unknown, or the requested _option_len_ or
- _option_value_ is invalid.
- *ETERM*::
- The 0MQ 'context' associated with the specified 'socket' was terminated.
- *ENOTSOCK*::
- The provided 'socket' was invalid.
- *EINTR*::
- The operation was interrupted by delivery of a signal.
- EXAMPLE
- -------
- .Subscribing to messages on a 'ZMQ_SUB' socket
- ----
- /* Subscribe to all messages */
- rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "", 0);
- assert (rc == 0);
- /* Subscribe to messages prefixed with "ANIMALS.CATS" */
- rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "ANIMALS.CATS", 12);
- ----
- .Setting I/O thread affinity
- ----
- int64_t affinity;
- /* Incoming connections on TCP port 5555 shall be handled by I/O thread 1 */
- affinity = 1;
- rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof (affinity));
- assert (rc);
- rc = zmq_bind (socket, "tcp://lo:5555");
- assert (rc);
- /* Incoming connections on TCP port 5556 shall be handled by I/O thread 2 */
- affinity = 2;
- rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof (affinity));
- assert (rc);
- rc = zmq_bind (socket, "tcp://lo:5556");
- assert (rc);
- ----
- SEE ALSO
- --------
- linkzmq:zmq_getsockopt[3]
- linkzmq:zmq_socket[3]
- linkzmq:zmq_plain[7]
- linkzmq:zmq_curve[7]
- linkzmq:zmq[7]
- AUTHORS
- -------
- This page was written by the 0MQ community. To make a change please
- read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.