Imported Upstream version 2.0.7.dfsgupstream/2.0.7.dfsg

1 files changed, 240 insertions, 0 deletions

diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt
new file mode 100644
index 0000000..7886eaf
--- /dev/null
+++ b/doc/zmq_getsockopt.txt
@@ -0,0 +1,240 @@
+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_value' 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 linkzmq:zmq_send[3] and linkzmq:zmq_recv[3] for a detailed description
+of sending/receiving multi-part messages.
+
+[horizontal]
+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 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.
+
+The default 'ZMQ_HWM' value of zero means "no limit".
+
+[horizontal]
+Option value type:: int64_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.
+
+[horizontal]
+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_.
+
+[horizontal]
+Option value type:: int64_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 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.
+
+[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:: uint64_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.
+
+[horizontal]
+Option value type:: uint64_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.
+
+[horizontal]
+Option value type:: uint64_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.
+
+[horizontal]
+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.
+
+[horizontal]
+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 0MQ 'context' associated with the specified 'socket' was terminated.
+
+
+EXAMPLE
+-------
+.Retrieving the high water mark
+----
+/* Retrieve high water mark into hwm */
+int64_t hwm;
+rc = zmq_getsockopt (socket, ZMQ_HWM, &hwm, sizeof hwm);
+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 <mato@kotelna.sk>.