diff options
Diffstat (limited to 'doc/zmq_getsockopt.txt')
| -rw-r--r-- | doc/zmq_getsockopt.txt | 438 |
1 files changed, 0 insertions, 438 deletions
diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt deleted file mode 100644 index 50b80fd..0000000 --- a/doc/zmq_getsockopt.txt +++ /dev/null @@ -1,438 +0,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. - -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. - -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. - -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_IPV4ONLY: Retrieve IPv4-only socket override status -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Retrieve the underlying native socket type. A value of `1` will use IPv4 -sockets, while the value of `0` will use IPv6 sockets. An IPv6 socket -lets applications connect to and accept connections from both IPv4 and IPv6 -hosts. - -[horizontal] -Option value type:: int -Option value unit:: boolean -Default value:: 1 (true) -Applicable socket types:: all, when using TCP 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. - -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 - - -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 -------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. |