zmq_setsockopt(3)

SYNOPSIS

int zmq_setsockopt (void *socket, int option_name, const void *option_value, size_t option_len);

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 ØMQ 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_HWM: Set high water mark

The ZMQ_HWM option shall set the high water mark for the specified socket. -The high water mark is a hard limit on the maximum number of outstanding -messages ØMQ shall queue in memory for any single peer that the specified -socket is communicating with.

If this limit has been reached the socket shall enter an exceptional state and -depending on the socket type, ØMQ shall take appropriate action such as -blocking or dropping sent messages. Refer to the individual socket descriptions -in zmq_socket(3) for details on the exact action taken for each socket -type.

The default ZMQ_HWM value of zero means "no limit".

- - - - - - - - - - - - - - - - -

-Option value type - -	- -uint64_t - -
-Option value unit - -	- -messages - -
-Default value - -	- -0 - -
-Applicable socket types - -	- -all - -

ZMQ_SWAP: Set disk offload size

The ZMQ_SWAP option shall set the disk offload (swap) size for the specified -socket. A socket which has ZMQ_SWAP set to a non-zero value may exceed it’s -high water mark; in this case outstanding messages shall be offloaded to -storage on disk rather than held in memory.

The value of ZMQ_SWAP defines the maximum size of the swap space in bytes.

- - - - - - - - - - - - - - - - -

-Option value type - -	- -int64_t - -
-Option value unit - -	- -bytes - -
-Default value - -	- -0 - -
-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 ØMQ 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 -ØMQ 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 zmq_init(3) for details on allocating the number of I/O -threads for a specific context.

- - - - - - - - - - - - - - - - -

-Option value type - -	- -uint64_t - -
-Option value unit - -	- -N/A (bitmap) - -
-Default value - -	- -0 - -
-Applicable socket types - -	- -N/A - -

ZMQ_IDENTITY: Set socket identity

The ZMQ_IDENTITY option shall set the identity of the specified socket. -Socket identity determines if existing ØMQ infastructure (message queues, -forwarding devices) shall be identified with a specific application and -persist across multiple runs of the application.

If the socket has no identity, each run of an application is completely -separate from other runs. However, with identity set the socket shall re-use -any existing ØMQ infrastructure configured by the previous run(s). Thus the -application may receive messages that were sent in the meantime, message -queue limits shall be shared with previous run(s) and so on.

Identity should be at least one byte and at most 255 bytes long. Identities -starting with binary zero are reserved for use by ØMQ infrastructure.

- - - - - - - - - - - - - - - - -

-Option value type - -	- -binary data - -
-Option value unit - -	- -N/A - -
-Default value - -	- -NULL - -
-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. Mutiple 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.

- - - - - - - - - - - - - - - - -

-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.

- - - - - - - - - - - - - - - - -

-Option value type - -	- -binary data - -
-Option value unit - -	- -N/A - -
-Default value - -	- -N/A - -
-Applicable socket types - -	- -ZMQ_SUB - -

ZMQ_RATE: Set multicast data rate

The ZMQ_RATE option shall set the maximum send or receive data rate for -multicast transports such as zmq_pgm(7) using the specified socket.

- - - - - - - - - - - - - - - - -

-Option value type - -	- -int64_t - -
-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 seconds that a receiver can be absent from a multicast group -before unrecoverable data loss will occur.

- - - -

Caution

Excersize 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.

- - - - - - - - - - - - - - - - -

-Option value type - -	- -int64_t - -
-Option value unit - -	- -seconds - -
-Default value - -	- -10 - -
-Applicable socket types - -	- -all, when using multicast transports - -

ZMQ_MCAST_LOOP: Control multicast loopback

The ZMQ_MCAST_LOOP option shall control whether data sent via multicast -transports using the specified socket can also be received by the sending -host via loopback. A value of zero disables the loopback functionality, while -the default value of 1 enables the loopback functionality. Leaving multicast -loopback enabled when it is not required can have a negative impact on -performance. Where possible, disable ZMQ_MCAST_LOOP in production -environments.

- - - - - - - - - - - - - - - - -

-Option value type - -	- -int64_t - -
-Option value unit - -	- -boolean - -
-Default value - -	- -1 - -
-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.

- - - - - - - - - - - - - - - - -

-Option value type - -	- -uint64_t - -
-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.

- - - - - - - - - - - - - - - - -

-Option value type - -	- -uint64_t - -
-Option value unit - -	- -bytes - -
-Default value - -	- -0 - -
-Applicable socket types - -	- -all - -

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 ØMQ context associated with the specified socket was terminated. -
-
-EFAULT -: -
-The provided socket was not valid (NULL). -
-

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);

AUTHORS

The ØMQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <mato@kotelna.sk>.

-zmq_setsockopt(3) Manual Page -

NAME

SYNOPSIS

DESCRIPTION

ZMQ_HWM: Set high water mark

ZMQ_SWAP: Set disk offload size

ZMQ_AFFINITY: Set I/O thread affinity

ZMQ_IDENTITY: Set socket identity

ZMQ_SUBSCRIBE: Establish message filter

ZMQ_UNSUBSCRIBE: Remove message filter

ZMQ_RATE: Set multicast data rate

ZMQ_RECOVERY_IVL: Set multicast recovery interval

ZMQ_MCAST_LOOP: Control multicast loopback

ZMQ_SNDBUF: Set kernel transmit buffer size

ZMQ_RCVBUF: Set kernel receive buffer size

RETURN VALUE

ERRORS

EXAMPLE

SEE ALSO

AUTHORS