2010-05-31 12:53:40 +02:00
|
|
|
zmq_getsockopt(3)
|
|
|
|
=================
|
|
|
|
|
|
|
|
|
|
|
|
NAME
|
|
|
|
----
|
|
|
|
|
|
|
|
zmq_getsockopt - get 0MQ socket options
|
|
|
|
|
|
|
|
|
|
|
|
SYNOPSIS
|
|
|
|
--------
|
2010-05-31 17:24:50 +02:00
|
|
|
*int zmq_getsockopt (void '*socket', int 'option_name', void '*option_value', size_t '*option_len');*
|
2010-05-31 12:53:40 +02:00
|
|
|
|
|
|
|
|
|
|
|
DESCRIPTION
|
|
|
|
-----------
|
|
|
|
The _zmq_getsockopt()_ function shall retrieve the value for the option
|
|
|
|
specified by the 'option_name' argument for the 0MQ 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
|
2010-05-31 17:24:50 +02:00
|
|
|
to by 'option_value'; upon successful completion _zmq_getsockopt()_ shall
|
2010-06-15 08:01:43 +02:00
|
|
|
modify the 'option_len' argument to indicate the actual size of the option
|
2010-05-31 17:24:50 +02:00
|
|
|
value stored in the buffer.
|
2010-05-31 12:53:40 +02:00
|
|
|
|
|
|
|
The following options can be retrieved with the _zmq_getsockopt()_ function:
|
|
|
|
|
|
|
|
|
2010-09-28 15:27:45 +02:00
|
|
|
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
|
|
|
|
|
|
|
|
|
2010-05-31 14:12:27 +02:00
|
|
|
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 linkzmq:zmq_send[3] and linkzmq:zmq_recv[3] for a detailed description
|
|
|
|
of sending/receiving multi-part messages.
|
|
|
|
|
2010-06-03 14:15:05 +02:00
|
|
|
[horizontal]
|
2010-05-31 14:12:27 +02:00
|
|
|
Option value type:: int64_t
|
|
|
|
Option value unit:: boolean
|
|
|
|
Default value:: N/A
|
|
|
|
Applicable socket types:: all
|
|
|
|
|
|
|
|
|
2010-05-31 12:53:40 +02:00
|
|
|
ZMQ_HWM: Retrieve high water mark
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2010-06-02 18:36:34 +02:00
|
|
|
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 0MQ 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, 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.
|
2010-05-31 12:53:40 +02:00
|
|
|
|
|
|
|
The default 'ZMQ_HWM' value of zero means "no limit".
|
|
|
|
|
2010-06-03 14:15:05 +02:00
|
|
|
[horizontal]
|
2010-08-11 17:00:12 +02:00
|
|
|
Option value type:: uint64_t
|
2010-05-31 12:53:40 +02:00
|
|
|
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
|
2010-06-02 18:36:34 +02:00
|
|
|
specified 'socket'. A socket which has 'ZMQ_SWAP' set to a non-zero value may
|
2010-09-04 15:54:34 +02:00
|
|
|
exceed it's high water mark; in this case outstanding messages shall be
|
2010-06-02 18:36:34 +02:00
|
|
|
offloaded to storage on disk rather than held in memory.
|
2010-05-31 12:53:40 +02:00
|
|
|
|
|
|
|
The value of 'ZMQ_SWAP' defines the maximum size of the swap space in bytes.
|
|
|
|
|
2010-06-03 14:15:05 +02:00
|
|
|
[horizontal]
|
2010-05-31 12:53:40 +02:00
|
|
|
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 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_.
|
|
|
|
|
2010-06-03 14:15:05 +02:00
|
|
|
[horizontal]
|
2010-08-11 17:00:12 +02:00
|
|
|
Option value type:: uint64_t
|
2010-05-31 12:53:40 +02:00
|
|
|
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 0MQ 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 0MQ 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 0MQ infrastructure.
|
|
|
|
|
2010-06-03 14:15:05 +02:00
|
|
|
[horizontal]
|
2010-05-31 12:53:40 +02:00
|
|
|
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'.
|
|
|
|
|
2010-06-03 14:15:05 +02:00
|
|
|
[horizontal]
|
2010-08-11 17:00:12 +02:00
|
|
|
Option value type:: int64_t
|
2010-05-31 12:53:40 +02:00
|
|
|
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.
|
|
|
|
|
2010-06-03 14:15:05 +02:00
|
|
|
[horizontal]
|
2010-08-11 17:00:12 +02:00
|
|
|
Option value type:: int64_t
|
2010-05-31 12:53:40 +02:00
|
|
|
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.
|
|
|
|
|
2010-06-03 14:15:05 +02:00
|
|
|
[horizontal]
|
2010-08-11 17:00:12 +02:00
|
|
|
Option value type:: int64_t
|
2010-05-31 12:53:40 +02:00
|
|
|
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.
|
|
|
|
|
2010-06-03 14:15:05 +02:00
|
|
|
[horizontal]
|
2010-05-31 12:53:40 +02:00
|
|
|
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.
|
|
|
|
|
2010-06-03 14:15:05 +02:00
|
|
|
[horizontal]
|
2010-05-31 12:53:40 +02:00
|
|
|
Option value type:: uint64_t
|
|
|
|
Option value unit:: bytes
|
|
|
|
Default value:: 0
|
|
|
|
Applicable socket types:: all
|
|
|
|
|
|
|
|
|
2010-10-16 10:53:29 +02:00
|
|
|
ZMQ_LINGER: Set linger period for socket shutdown
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The 'ZMQ_LINGER' option shall retrieve the period for pending outbound
|
|
|
|
messages to linger in memory after closing the socket. Value of -1 means
|
|
|
|
infinite. Pending messages will be kept until they are fully transferred to
|
|
|
|
the peer. Value of 0 means that all the pending messages are dropped immediately
|
|
|
|
when socket is closed. Positive value means number of milliseconds to keep
|
|
|
|
trying to send the pending messages before discarding them.
|
|
|
|
|
|
|
|
[horizontal]
|
|
|
|
Option value type:: int
|
|
|
|
Option value unit:: milliseconds
|
|
|
|
Default value:: -1
|
|
|
|
Applicable socket types:: all
|
|
|
|
|
|
|
|
|
2010-09-27 09:53:30 +02:00
|
|
|
ZMQ_FD: Retrieve file descriptor associated with the socket
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The 'ZMQ_FD' option shall retrieve file descriptor associated with the 0MQ
|
|
|
|
socket. The descriptor can be used to integrate 0MQ socket into an existing
|
|
|
|
event loop. It should never be used for anything else than polling -- such as
|
|
|
|
reading or writing. The descriptor signals edge-triggered IN event when
|
|
|
|
something has happened within the 0MQ socket. It does not necessarily mean that
|
|
|
|
the messages can be read or written. Check ZMQ_EVENTS option to find out whether
|
|
|
|
the 0MQ socket is readable or writeable.
|
|
|
|
|
|
|
|
[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: Check whether socket is readable and/or writeable
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The 'ZMQ_EVENTS' option shall retrieve event flags for the specified socket.
|
|
|
|
If a message can be read from the socket ZMQ_POLLIN flag is set. If message can
|
|
|
|
be written to the socket ZMQ_POLLOUT flag is set.
|
|
|
|
|
|
|
|
[horizontal]
|
|
|
|
Option value type:: uint32_t
|
|
|
|
Option value unit:: N/A (flags)
|
|
|
|
Default value:: N/A
|
|
|
|
Applicable socket types:: all
|
|
|
|
|
|
|
|
|
2010-05-31 12:53:40 +02:00
|
|
|
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 0MQ 'context' associated with the specified 'socket' was terminated.
|
Added error checking (EFAULT) for null arguments
* Fixed zmq_term, zmq_socket, zmq_close, zmq_setsockopt,
* zmq_getsockopt, zmq_bind, zmq_connect, zmq_send,
* zmq_recv, zmq_poll, zmq_device, zmq_stopwatch_stop
* Updated Reference Manual for these methods
2010-08-08 11:43:32 +02:00
|
|
|
*EFAULT*::
|
|
|
|
The provided 'socket' was not valid (NULL).
|
2010-09-08 08:39:27 +02:00
|
|
|
*EINTR*::
|
|
|
|
The operation was interrupted by delivery of a signal.
|
2010-05-31 12:53:40 +02:00
|
|
|
|
|
|
|
|
|
|
|
EXAMPLE
|
|
|
|
-------
|
|
|
|
.Retrieving the high water mark
|
|
|
|
----
|
|
|
|
/* Retrieve high water mark into hwm */
|
|
|
|
int64_t hwm;
|
2010-06-15 08:01:43 +02:00
|
|
|
size_t hwm_size = sizeof (hwm);
|
|
|
|
rc = zmq_getsockopt (socket, ZMQ_HWM, &hwm, &hwm_size);
|
2010-05-31 12:53:40 +02:00
|
|
|
assert (rc == 0);
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
|
|
SEE ALSO
|
|
|
|
--------
|
|
|
|
linkzmq:zmq_setsockopt[3]
|
|
|
|
linkzmq:zmq_socket[3]
|
|
|
|
linkzmq:zmq[7]
|
|
|
|
|
|
|
|
|
2010-09-04 15:55:11 +02:00
|
|
|
AUTHORS
|
|
|
|
-------
|
|
|
|
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
|
|
|
|
Martin Lucina <mato@kotelna.sk>.
|