zmq_getsockopt(3)

SYNOPSIS

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

DESCRIPTION

The zmq_getsockopt() function shall retrieve the value for the option -specified by the option_name argument for the ØMQ socket pointed to by the -socket argument, and store it in the buffer pointed to by the option_value -argument. The option_len argument is the size in bytes of the buffer pointed -to by option_value; upon successful completion zmq_getsockopt() shall -modify the option_len argument to indicate the actual size of the option -value stored in the buffer.

The following options can be retrieved with the zmq_getsockopt() function:

ZMQ_RCVMORE: More message parts to follow

The ZMQ_RCVMORE option shall return a boolean value indicating if the -multi-part message currently being read from the specified socket has more -message parts to follow. If there are no message parts to follow or if the -message currently being read is not a multi-part message a value of zero shall -be returned. Otherwise, a value of 1 shall be returned.

Refer to zmq_send(3) and zmq_recv(3) for a detailed description -of sending/receiving multi-part messages.

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

-Option value type - -	- -int64_t - -
-Option value unit - -	- -boolean - -
-Default value - -	- -N/A - -
-Applicable socket types - -	- -all - -

ZMQ_HWM: Retrieve high water mark

The ZMQ_HWM option shall retrieve 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: Retrieve disk offload size

The ZMQ_SWAP option shall retrieve 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: Retrieve I/O thread affinity

The ZMQ_AFFINITY option shall retrieve 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: Retrieve socket identity

The ZMQ_IDENTITY option shall retrieve 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 can 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_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.

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

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

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

-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 controls whether data sent via multicast -transports can also be received by the sending host via loopback. A value of -zero indicates that the loopback functionality is disabled, while the default -value of 1 indicates that the loopback functionality is enabled. 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: 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.

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

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

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

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

RETURN VALUE

The zmq_getsockopt() 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, or the size of the buffer pointed to by -option_value, as specified by option_len, is insufficient for storing the -option value. -
-
-ETERM -: -
-The ØMQ context associated with the specified socket was terminated. -
-
-EFAULT -: -
-The provided socket was not valid (NULL). -
-

EXAMPLE

Retrieving the high water mark

/* Retrieve high water mark into hwm */
-int64_t hwm;
-size_t hwm_size = sizeof (hwm);
-rc = zmq_getsockopt (socket, ZMQ_HWM, &hwm, &hwm_size);
-assert (rc == 0);

AUTHORS

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

-zmq_getsockopt(3) Manual Page -

NAME

SYNOPSIS

DESCRIPTION

ZMQ_RCVMORE: More message parts to follow

ZMQ_HWM: Retrieve high water mark

ZMQ_SWAP: Retrieve disk offload size

ZMQ_AFFINITY: Retrieve I/O thread affinity

ZMQ_IDENTITY: Retrieve socket identity

ZMQ_RATE: Retrieve multicast data rate

ZMQ_RECOVERY_IVL: Get multicast recovery interval

ZMQ_MCAST_LOOP: Control multicast loopback

ZMQ_SNDBUF: Retrieve kernel transmit buffer size

ZMQ_RCVBUF: Retrieve kernel receive buffer size

RETURN VALUE

ERRORS

EXAMPLE

SEE ALSO

AUTHORS