diff options
Diffstat (limited to 'doc/zmq_setsockopt.txt')
| -rw-r--r-- | doc/zmq_setsockopt.txt | 773 |
1 files changed, 773 insertions, 0 deletions
diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt new file mode 100644 index 0000000..9eb1a95 --- /dev/null +++ b/doc/zmq_setsockopt.txt @@ -0,0 +1,773 @@ +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_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_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 +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_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_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_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 NOT start with binary zero. + +If two clients use the same identity when connecting to a ROUTER, the +ROUTER socket shall accept only the first such client and reject the +others. + +[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_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_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_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_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_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 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: 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_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_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_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_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_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_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_MSGMORE +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_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_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_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_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_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_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 +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>. |