/doc/zmq_getsockopt.txt
Plain Text | 531 lines | 412 code | 119 blank | 0 comment | 0 complexity | 0edcc0def2fb34a2e915e6e0de2808a7 MD5 | raw file
Possible License(s): GPL-3.0, LGPL-3.0
- zmq_getsockopt(3)
- =================
- NAME
- ----
- zmq_getsockopt - get 0MQ socket options
- 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 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
- 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_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
- ZMQ_RCVMORE: More message data parts to follow
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The 'ZMQ_RCVMORE' option shall return True (1) if the message part last
- received from the 'socket' was a data part with more parts to follow. If there
- are no data parts to follow, this option shall return False (0).
- Refer to linkzmq:zmq_send[3] and linkzmq:zmq_recv[3] for a detailed description
- of multi-part messages.
- [horizontal]
- Option value type:: int
- Option value unit:: boolean
- Default value:: N/A
- Applicable socket types:: all
- ZMQ_SNDHWM: Retrieves high water mark for outbound messages
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The 'ZMQ_SNDHWM' option shall return 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.
- [horizontal]
- Option value type:: int
- Option value unit:: messages
- Default value:: 1000
- Applicable socket types:: all
- ZMQ_RCVHWM: Retrieve high water mark for inbound messages
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The 'ZMQ_RCVHWM' option shall return 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: 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_.
- [horizontal]
- 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 retrieve the identity of the specified 'socket'.
- Socket identity is used only by request/reply pattern. Namely, it can be used
- in tandem with ROUTER socket to route messages to the peer with specific
- identity.
- Identity should be at least one byte and at most 255 bytes long. Identities
- starting with binary zero are reserved for use by 0MQ infrastructure.
- [horizontal]
- 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'.
- [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: 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 milliseconds that a receiver can be absent from a
- multicast group before unrecoverable data loss will occur.
- [horizontal]
- Option value type:: int
- Option value unit:: milliseconds
- Default value:: 10000
- 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.
- [horizontal]
- Option value type:: int
- 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.
- [horizontal]
- Option value type:: int
- Option value unit:: bytes
- Default value:: 0
- Applicable socket types:: all
- ZMQ_LINGER: Retrieve linger period for socket shutdown
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The 'ZMQ_LINGER' option shall retrieve 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: Retrieve reconnection interval
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The 'ZMQ_RECONNECT_IVL' option shall retrieve 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: Retrieve maximum reconnection interval
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The 'ZMQ_RECONNECT_IVL_MAX' option shall retrieve 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 transport
- ZMQ_BACKLOG: Retrieve maximum length of the queue of outstanding connections
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The 'ZMQ_BACKLOG' option shall retrieve 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
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The option shall retrieve limit for the inbound messages. 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
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The option shall retrieve time-to-live used for outbound multicast packets.
- The default of 1 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 socket operation returns with EAGAIN
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Retrieve the timeout for recv 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 socket operation returns with EAGAIN
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Retrieve 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: Retrieve IPv6 socket status
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Retrieve 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: Retrieve IPv4-only socket override status
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Retrieve 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_DELAY_ATTACH_ON_CONNECT: Retrieve attach-on-connect value
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Retrieve the state of the attach on connect value. If set to `1`, will delay the
- attachment of a pipe on connect until the underlying connection has completed.
- 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, primarily when using TCP/IPC transports.
- ZMQ_FD: Retrieve file descriptor associated with the socket
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The 'ZMQ_FD' option shall retrieve the file descriptor associated with the
- specified 'socket'. The returned file descriptor can be used to integrate the
- socket into an existing event loop; the 0MQ library shall signal any pending
- events on the socket in an _edge-triggered_ fashion by making the file
- descriptor become ready for reading.
- NOTE: The ability to read from the returned file descriptor does not
- necessarily indicate that messages are available to be read from, or can be
- written to, the underlying socket; applications must retrieve the actual event
- state with a subsequent retrieval of the 'ZMQ_EVENTS' option.
- NOTE: The returned file descriptor is also used internally by the 'zmq_send'
- and 'zmq_recv' functions. As the descriptor is edge triggered, applications
- must update the state of 'ZMQ_EVENTS' after each invocation of 'zmq_send'
- or 'zmq_recv'.To be more explicit: after calling 'zmq_send' the socket may
- become readable (and vice versa) without triggering a read event on the
- file descriptor.
- CAUTION: The returned file descriptor is intended for use with a 'poll' or
- similar system call only. Applications must never attempt to read or write data
- to it directly, neither should they try to close it.
- [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: Retrieve socket event state
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The 'ZMQ_EVENTS' option shall retrieve the event state for the specified
- 'socket'. The returned value is a bit mask constructed by OR'ing a combination
- of the following event flags:
- *ZMQ_POLLIN*::
- Indicates that at least one message may be received from the specified socket
- without blocking.
- *ZMQ_POLLOUT*::
- Indicates that at least one message may be sent to the specified socket without
- blocking.
- The combination of a file descriptor returned by the 'ZMQ_FD' option being
- ready for reading but no actual events returned by a subsequent retrieval of
- the 'ZMQ_EVENTS' option is valid; applications should simply ignore this case
- and restart their polling operation/event loop.
- [horizontal]
- Option value type:: int
- Option value unit:: N/A (flags)
- Default value:: N/A
- Applicable socket types:: all
- ZMQ_LAST_ENDPOINT: Retrieve the last endpoint set
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The 'ZMQ_LAST_ENDPOINT' option shall retrieve the last endpoint bound for
- TCP and IPC transports. The returned value will be a string in the form of
- a ZMQ DSN. Note that if the TCP host is INADDR_ANY, indicated by a *, then
- the returned address will be 0.0.0.0 (for IPv4).
- [horizontal]
- Option value type:: character string
- Option value unit:: N/A
- Default value:: NULL
- Applicable socket types:: all, when binding TCP or IPC 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_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.
- 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.
- *ENOTSOCK*::
- The provided 'socket' was invalid.
- *EINTR*::
- The operation was interrupted by delivery of a signal.
- EXAMPLE
- -------
- .Retrieving the high water mark for outgoing messages
- ----
- /* Retrieve high water mark into sndhwm */
- int sndhwm;
- size_t sndhwm_size = sizeof (sndhwm);
- rc = zmq_getsockopt (socket, ZMQ_SNDHWM, &sndhwm, &sndhwm_size);
- assert (rc == 0);
- ----
- SEE ALSO
- --------
- linkzmq:zmq_setsockopt[3]
- linkzmq:zmq_socket[3]
- linkzmq:zmq[7]
- AUTHORS
- -------
- This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and
- Martin Lucina <mato@kotelna.sk>.