libzmq Documentation

echo "deb http://download.opensuse.org/repositories/network:/messaging:/zeromq:/release-stable/Debian_9.0/ ./" >> /etc/apt/sources.list
wget https://download.opensuse.org/repositories/network:/messaging:/zeromq:/release-stable/Debian_9.0/Release.key -O- | sudo apt-key add
apt-get install libzmq3-dev

brew install zeromq

void tearDown ()
{
	teardown_test_context ();
}

export XXX=xxx
export YYY=yyy
...
cd <libzmq>/builds/android
./

export NDK_VERSION=android-ndk-r23c

export NDK_VERSION="android-ndk-r23b"
export ANDROID_NDK_ROOT=$HOME/${NDK_VERSION}

export ANDROID_NDK_ROOT=/tmp/${NDK_VERSION}

export MIN_SDK_VERSION=21   # Default value if unset

export ANDROID_BUILD_DIR=${HOME}/android_build

${ANDROID_BUILD_DIR}/prefix/<arch>/lib

ANDROID_BUILD_DIR="no"

ANDROID_BUILD_DIR/prefix/<arch>/lib

""          : LIBZMQ is built without any encryption support.
"libsodium" : LIBZMQ is built with LIBSODIUM encryption support (see below).

export XXX=xxx
export YYY=yyy
...

cd <libzmq>/builds/android
./build.sh [ arm | arm64 | x86 | x86_64 ]

export XXX=xxx
export YYY=yyy
cd <libzmq>/builds/android
./ci_build.sh

c++ -Wc,xplink -Wl,xplink ... -+ -o myprog myprog.cpp -lzmq

./myprog

c++ -Wc,xplink -Wc,dll ... -+ -c -o myprog.o myprog.cpp
c++ -Wl,xplink -o myprog myprog.o /PATH/TO/libzmq.x

LIBPATH=/DIR/OF/LIBZMQ.SO:/lib:/usr/lib:...    # if not in default path
export LIBPATH
./myprog

#include <signal.h>
...
signal(SIGPIPE, SIG_IGN);

_XOPEN_SOURCE_EXTENDED=1

_OPEN_SYS_SOCK_IPV6

_OPEN_THREADS=3

_UNIX03_THREADS=1

/* ---- Special case for z/OS Unix Services: openedition ---- */
#include 
#ifndef   NI_MAXHOST
#define   NI_MAXHOST 1025
#endif

cd src
make zmq.o

HANDLE epoll_create(int size);
HANDLE epoll_create1(int flags);

int epoll_close(HANDLE ephnd);

int epoll_ctl(HANDLE ephnd,
              int op,
              SOCKET sock,
              struct epoll_event* event);

int epoll_wait(HANDLE ephnd,
               struct epoll_event* events,
               int maxevents,
               int timeout);

typedef union epoll_data {
  void* ptr;
  int fd;
  uint32_t u32;
  uint64_t u64;
  SOCKET sock;        /* Windows specific */
  HANDLE hnd;         /* Windows specific */
} epoll_data_t;

struct epoll_event {
  uint32_t events;    /* Epoll events and flags */
  epoll_data_t data;  /* User data variable */
};

The 0MQ 'context' keeps the list of sockets and manages the async I/O thread
and internal queries.

Before using any 0MQ library functions you must create a 0MQ 'context'. When
you exit your application you must destroy the 'context'. These functions let
you work with 'contexts':

Create a new 0MQ context::
 * xref:zmq_ctx_new.adoc[zmq_ctx_new]

Work with context properties::
 * xref:zmq_ctx_set.adoc[zmq_ctx_set]
 * xref:zmq_ctx_get.adoc[zmq_ctx_get]

Destroy a 0MQ context::
 * xref:zmq_ctx_shutdown.adoc[zmq_ctx_shutdown]
 * xref:zmq_ctx_term.adoc[zmq_ctx_term]

Thread safety
^^^^^^^^^^^^^
A 0MQ 'context' is thread safe and may be shared among as many application
threads as necessary, without any additional locking required on the part of
the caller.

Individual 0MQ 'sockets' are _not_ thread safe except in the case where full
memory barriers are issued when migrating a socket from one thread to another.
In practice this means applications can create a socket in one thread with
_zmq_socket()_ and then pass it to a _newly created_ thread as part of thread
initialisation, for example via a structure passed as an argument to
_pthread_create()_.


Multiple contexts
^^^^^^^^^^^^^^^^^
Multiple 'contexts' may coexist within a single application. Thus, an
application can use 0MQ directly and at the same time make use of any number of
additional libraries or components which themselves make use of 0MQ as long as
the above guidelines regarding thread safety are adhered to.


Messages

0MQ sockets present an abstraction of an asynchronous _message queue_, with the
exact queueing semantics depending on the socket type in use. See
xref:zmq_socket.adoc[zmq_socket] for the socket types provided.

The following functions are provided to work with sockets:

Creating a socket::
 * xref:zmq_socket.adoc[zmq_socket]

Closing a socket::
 * xref:zmq_close.adoc[zmq_close]

Manipulating socket options::
 * xref:zmq_getsockopt.adoc[zmq_getsockopt]
 * xref:zmq_setsockopt.adoc[zmq_setsockopt]

Establishing a message flow::
 * xref:zmq_bind.adoc[zmq_bind]
 * xref:zmq_connect.adoc[zmq_connect]

Sending and receiving messages::
 * xref:zmq_msg_send.adoc[zmq_msg_send]
 * xref:zmq_msg_recv.adoc[zmq_msg_recv]
 * xref:zmq_send.adoc[zmq_send]
 * xref:zmq_recv.adoc[zmq_recv]
 * xref:zmq_send_const.adoc[zmq_send_const]

Monitoring socket events::
 * xref:zmq_socket_monitor.adoc[zmq_socket_monitor]

.Input/output multiplexing
0MQ provides a mechanism for applications to multiplex input/output events over
a set containing both 0MQ sockets and standard sockets. This mechanism mirrors
the standard _poll()_ system call, and is described in detail in
xref:zmq_poll.adoc[zmq_poll] This API is deprecated, however.

There is a new DRAFT API with multiple zmq_poller_* function, which is described
in xref:zmq_poller.adoc[zmq_poller]


Transports

0MQ provides 'proxies' to create fanout and fan-in topologies. A proxy connects
a 'frontend' socket to a 'backend' socket and switches all messages between the
two sockets, opaquely. A proxy may optionally capture all traffic to a third
socket. To start a proxy in an application thread, use xref:zmq_proxy.adoc[zmq_proxy]


Security

The 'ZMQ_IO_THREADS' argument returns the size of the 0MQ thread pool
for this context.


ZMQ_MAX_SOCKETS: Get maximum number of sockets

The 'ZMQ_MAX_MSGSZ' argument returns the maximum size of a message
allowed for this context. Default value is INT_MAX.


ZMQ_ZERO_COPY_RECV: Get message decoding strategy

The 'ZMQ_SOCKET_LIMIT' argument returns the largest number of sockets that
xref:zmq_ctx_set.adoc[zmq_ctx_set] will accept.


ZMQ_IPV6: Set IPv6 option
~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_IPV6' argument returns the IPv6 option for the context.


ZMQ_BLOCKY: Get blocky setting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_BLOCKY' argument returns 1 if the context will block on terminate,
zero if the "block forever on context termination" gambit was disabled by
setting ZMQ_BLOCKY to false on all new contexts.


ZMQ_THREAD_SCHED_POLICY: Get scheduling policy for I/O threads

The 'ZMQ_THREAD_NAME_PREFIX' argument gets the numeric prefix of each thread
created for the internal context's thread pool.


ZMQ_MSG_T_SIZE: Get the zmq_msg_t size at runtime
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_MSG_T_SIZE' argument returns the size of the zmq_msg_t structure at
runtime, as defined in the include/zmq.h public header.
This is useful for example for FFI bindings that can't simply do a sizeof().


== RETURN VALUE
The _zmq_ctx_get()_ function returns a value of 0 or greater if successful.
Otherwise it returns `-1` and sets 'errno' to one of the values defined
below.


== ERRORS
*EINVAL*::
The requested option _option_name_ is unknown.
*EFAULT*::
The provided 'context' is invalid.


== EXAMPLE
.Setting a limit on the number of sockets
----
void *context = zmq_ctx_new ();
zmq_ctx_set (context, ZMQ_MAX_SOCKETS, 256);
int max_sockets = zmq_ctx_get (context, ZMQ_MAX_SOCKETS);
assert (max_sockets == 256);
----
.Switching off the context deadlock gambit
----
zmq_ctx_set (ctx, ZMQ_BLOCKY, false);
----


== SEE ALSO
* xref:zmq_ctx_set.adoc[zmq_ctx_set]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Ctx Get Ext (`doc/zmq_ctx_get_ext.adoc`)

= zmq_ctx_get_ext(3)


== NAME

zmq_ctx_get_ext - get extended context options


== SYNOPSIS
*int zmq_ctx_get_ext (void '*context', int 'option_name', void '*option_value', size_t '*option_len');*


== DESCRIPTION
The _zmq_ctx_get()_ function shall retrieve the value for the option
specified by the 'option_name' 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_ctx_get_ext()_ shall
modify the 'option_len' argument to indicate the actual size of the option
value stored in the buffer.

The _zmq_ctx_get_ext()_ function accepts all the option names accepted by
_zmq_ctx_get()_.
Options that make most sense to retrieve using _zmq_ctx_get_ext()_ instead of
_zmq_ctx_get()_ are:

ZMQ_THREAD_NAME_PREFIX: Get name prefix for I/O threads

By default the context will block, forever, on a zmq_ctx_term call. The
assumption behind this behavior is that abrupt termination will cause
message loss. Most real applications use some form of handshaking to ensure
applications receive termination messages, and then terminate the context
with 'ZMQ_LINGER' set to zero on all sockets. This setting is an easier way
to get the same result. When 'ZMQ_BLOCKY' is set to false, all new sockets
are given a linger timeout of zero. You must still close all sockets before
calling zmq_ctx_term.

[horizontal]
Default value:: true (old behavior)


ZMQ_IO_THREADS: Set number of I/O threads

The 'ZMQ_THREAD_SCHED_POLICY' argument sets the scheduling policy for
internal context's thread pool. This option is not available on windows.
Supported values for this option can be found in sched.h file,
or at http://man7.org/linux/man-pages/man2/sched_setscheduler.2.html.
This option only applies before creating any sockets on the context.

[horizontal]
Default value:: -1


ZMQ_THREAD_PRIORITY: Set scheduling priority for I/O threads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_THREAD_PRIORITY' argument sets scheduling priority for
internal context's thread pool. This option is not available on windows.
Supported values for this option depend on chosen scheduling policy.
On Linux, when the scheduler policy is SCHED_OTHER, SCHED_IDLE or SCHED_BATCH, the OS scheduler
will not use the thread priority but rather the thread "nice value"; in such cases,
if 'ZMQ_THREAD_PRIORITY' is set to a strictly positive value,
the system call "nice" will be used to set the nice value to -20 (max priority) instead of
adjusting the thread priority (which must be zero for those scheduling policies).
Details can be found in sched.h file, or at http://man7.org/linux/man-pages/man2/sched_setscheduler.2.html.
This option only applies before creating any sockets on the context.

[horizontal]
Default value:: -1


ZMQ_THREAD_AFFINITY_CPU_ADD: Add a CPU to list of affinity for I/O threads

The 'ZMQ_THREAD_AFFINITY_CPU_REMOVE' argument removes a specific CPU to the affinity list for the internal
context's thread pool. This option is only supported on Linux.
This option only applies before creating any sockets on the context.
The default affinity list is empty and means that no explicit CPU-affinity will be set on
internal context's threads.

[horizontal]
Default value:: -1


ZMQ_THREAD_NAME_PREFIX: Set name prefix for I/O threads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_THREAD_NAME_PREFIX' argument sets a numeric prefix to each thread
created for the internal context's thread pool. This option is only supported on Linux.
This option is useful to help  debugging done via "top -H" or "gdb"; in case
multiple processes on the system are using ZeroMQ it is useful to provide through
this context option an application-specific prefix to distinguish ZeroMQ background
threads that belong to different processes.
This option only applies before creating any sockets on the context.

[horizontal]
Default value:: -1



ZMQ_MAX_MSGSZ: Set maximum message size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_MAX_MSGSZ' argument sets the maximum allowed size
of a message sent in the context. You can query the maximal
allowed value with xref:zmq_ctx_get.adoc[zmq_ctx_get] using the
'ZMQ_MAX_MSGSZ' option.

[horizontal]
Default value:: INT_MAX
Maximum value:: INT_MAX


ZMQ_ZERO_COPY_RECV: Specify message decoding strategy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_ZERO_COPY_RECV' argument specifies whether the message decoder should
use a zero copy strategy when receiving messages. The zero copy strategy can
lead to increased memory usage in some cases. This option allows you to use the
older copying strategy. You can query the value of this option with
xref:zmq_ctx_get.adoc[zmq_ctx_get] using the 'ZMQ_ZERO_COPY_RECV' option.
NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Default value:: 1


ZMQ_MAX_SOCKETS: Set maximum number of sockets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_MAX_SOCKETS' argument sets the maximum number of sockets allowed
on the context. You can query the maximal allowed value with
xref:zmq_ctx_get.adoc[zmq_ctx_get] using the 'ZMQ_SOCKET_LIMIT' option.

[horizontal]
Default value:: 1023


ZMQ_IPV6: Set IPv6 option
~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_IPV6' argument sets the IPv6 value for all sockets created in
the context from this point onwards. A value of `1` means IPv6 is
enabled, while `0` means the socket will use only IPv4. When IPv6 is
enabled, a socket will connect to, or accept connections from, both
IPv4 and IPv6 hosts.

[horizontal]
Default value:: 0


== RETURN VALUE
The _zmq_ctx_set()_ function returns zero if successful. Otherwise it
returns `-1` and sets 'errno' to one of the values defined below.


== ERRORS
*EINVAL*::
The requested option _option_name_ is unknown.


== EXAMPLE
.Setting a limit on the number of sockets
----
void *context = zmq_ctx_new ();
zmq_ctx_set (context, ZMQ_MAX_SOCKETS, 256);
int max_sockets = zmq_ctx_get (context, ZMQ_MAX_SOCKETS);
assert (max_sockets == 256);
----


== SEE ALSO
* xref:zmq_ctx_get.adoc[zmq_ctx_get]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Ctx Set Ext (`doc/zmq_ctx_set_ext.adoc`)

= zmq_ctx_set_ext(3)


== NAME

zmq_ctx_set_ext - set extended context options


== SYNOPSIS
*int zmq_ctx_set_ext (void '*context', int 'option_name', const void '*option_value', size_t 'option_len');*


== DESCRIPTION

The _zmq_ctx_set_ext()_ function shall set the option specified by the
'option_name' argument to the value pointed to by the 'option_value' argument
for the 0MQ context pointed to by the 'context' argument. The 'option_len'
argument is the size of the option value in bytes. For options taking a value of
type "character string", the provided byte data should either contain no zero
bytes, or end in a single zero byte (terminating ASCII NUL character).

The _zmq_ctx_set_ext()_ function accepts all the option names accepted by
_zmq_ctx_set()_.
Options that make most sense to set using _zmq_ctx_set_ext()_ instead of
_zmq_ctx_set()_ are the following options:

ZMQ_THREAD_NAME_PREFIX: Set name prefix for I/O threads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_THREAD_NAME_PREFIX' argument sets a string prefix to each thread
created for the internal context's thread pool. This option is only supported on Linux.
This option is useful to help  debugging done via "top -H" or "gdb"; in case
multiple processes on the system are using ZeroMQ it is useful to provide through
this context option an application-specific prefix to distinguish ZeroMQ background
threads that belong to different processes.
This option only applies before creating any sockets on the context.

[horizontal]
Option value type:: character string
Option value unit:: N/A
Default value:: empty string


== RETURN VALUE
The _zmq_ctx_set_ext()_ function returns zero if successful. Otherwise it
returns `-1` and sets 'errno' to one of the values defined below.


== ERRORS
*EINVAL*::
The requested option _option_name_ is unknown.
*EFAULT*::
The provided 'context' is invalid.


== EXAMPLE
.Setting a prefix on internal ZMQ thread names:
----
void *context = zmq_ctx_new ();
const char prefix[] = "MyApp";
size_t prefixLen = sizeof(prefix);
zmq_ctx_set (context, ZMQ_THREAD_NAME_PREFIX, &prefix, &prefixLen);

char buff[256];
size_t buffLen = sizeof(buff);
int rc = zmq_ctx_get (context, ZMQ_THREAD_NAME_PREFIX, &buff, &buffLen);
assert (rc == 0);
assert (buffLen == prefixLen);

----


== SEE ALSO
* xref:zmq_ctx_set.adoc[zmq_ctx_set]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Ctx Shutdown (`doc/zmq_ctx_shutdown.adoc`)

= zmq_ctx_shutdown(3)


== NAME
zmq_ctx_shutdown - shutdown a 0MQ context


== SYNOPSIS
*int zmq_ctx_shutdown (void '*context');*


== DESCRIPTION
The _zmq_ctx_shutdown()_ function shall shutdown the 0MQ context 'context'.

Context shutdown will cause any blocking operations currently in progress on 
sockets open within 'context' to return immediately with an error code of ETERM.
With the exception of _zmq_close()_, any further operations on sockets open within
'context' shall fail with an error code of ETERM. No further sockets can be created
using _zmq_socket()_ on a context for which _zmq_ctx_shutdown()_ has been called,
it will return and set errno to ETERM.

This function is optional, client code is still required to call the xref:zmq_ctx_term.adoc[zmq_ctx_term]
function to free all resources allocated by zeromq.


== RETURN VALUE
The _zmq_ctx_shutdown()_ function shall return zero if successful. Otherwise
it shall return `-1` and set 'errno' to one of the values defined below.


== ERRORS
*EFAULT*::
The provided 'context' was invalid.


== SEE ALSO
* xref:zmq.adoc[zmq]
* xref:zmq_init.adoc[zmq_init]
* xref:zmq_ctx_term.adoc[zmq_ctx_term]
* xref:zmq_close.adoc[zmq_close]
* xref:zmq_setsockopt.adoc[zmq_setsockopt]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Ctx Term (`doc/zmq_ctx_term.adoc`)

= zmq_ctx_term(3)


== NAME
zmq_ctx_term - terminate a 0MQ context


== SYNOPSIS
*int zmq_ctx_term (void '*context');*


== DESCRIPTION
The _zmq_ctx_term()_ function shall destroy the 0MQ context 'context'.

Context termination is performed in the following steps:

1. Any blocking operations currently in progress on sockets open within
   'context' shall return immediately with an error code of ETERM.  With the
   exception of _zmq_close()_, any further operations on sockets open within
   'context' shall fail with an error code of ETERM.

2. After interrupting all blocking calls, _zmq_ctx_term()_ shall _block_ until
   the following conditions are satisfied:

   * All sockets open within 'context' have been closed with _zmq_close()_.

   * For each socket within 'context', all messages sent by the application
     with _zmq_send()_ have either been physically transferred to a network
     peer, or the socket's linger period set with the _ZMQ_LINGER_ socket
     option has expired.

For further details regarding socket linger behaviour refer to the _ZMQ_LINGER_
option in xref:zmq_setsockopt.adoc[zmq_setsockopt]

This function replaces the deprecated functions xref:zmq_term.adoc[zmq_term] and
xref:zmq_ctx_destroy.adoc[zmq_ctx_destroy]


== RETURN VALUE
The _zmq_ctx_term()_ function shall return zero if successful. Otherwise
it shall return `-1` and set 'errno' to one of the values defined below.


== ERRORS
*EFAULT*::
The provided 'context' was invalid.
*EINTR*::
Termination was interrupted by a signal. It can be restarted if needed.


== SEE ALSO
* xref:zmq.adoc[zmq]
* xref:zmq_init.adoc[zmq_init]
* xref:zmq_close.adoc[zmq_close]
* xref:zmq_setsockopt.adoc[zmq_setsockopt]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Curve (`doc/zmq_curve.adoc`)

= zmq_curve(7)


== NAME
zmq_curve - secure authentication and confidentiality


== SYNOPSIS
The CURVE mechanism defines a mechanism for secure authentication and 
confidentiality for communications between a client and a server. CURVE 
is intended for use on public networks. The CURVE mechanism is defined 
by this document: <http://rfc.zeromq.org/spec:25>.


== CLIENT AND SERVER ROLES
A socket using CURVE can be either client or server, at any moment, but 
not both. The role is independent of bind/connect direction.

A socket can change roles at any point by setting new options. The role
affects all zmq_connect and zmq_bind calls that follow it.

To become a CURVE server, the application sets the ZMQ_CURVE_SERVER option
on the socket, and then sets the ZMQ_CURVE_SECRETKEY option to provide the
socket with its long-term secret key. The application does not provide the
socket with its long-term public key, which is used only by clients.

To become a CURVE client, the application sets the ZMQ_CURVE_SERVERKEY 
option with the long-term public key of the server it intends to connect
to, or accept connections from, next. The application then sets the 
ZMQ_CURVE_PUBLICKEY and ZMQ_CURVE_SECRETKEY options with its client 
long-term key pair.

If the server does authentication it will be based on the client's long
term public key.

== KEY ENCODING
The standard representation for keys in source code is either 32 bytes of
base 256 (binary) data, or 40 characters of base 85 data encoded using the
Z85 algorithm defined by http://rfc.zeromq.org/spec:32.

The Z85 algorithm is designed to produce printable key strings for use in
configuration files, the command line, and code. There is a reference
implementation in C at https://github.com/zeromq/rfc/tree/master/src.

    
== TEST KEY VALUES
For test cases, the client shall use this long-term key pair (specified
as hexadecimal and in Z85):

----
public: 
    BB88471D65E2659B30C55A5321CEBB5AAB2B70A398645C26DCA2B2FCB43FC518
    Yne@$w-vo<fVvi]a<NY6T1ed:M$fCG*[IaLV{hID

secret: 
    7BB864B489AFA3671FBE69101F94B38972F24816DFB01B51656B3FEC8DFD0888
    D:)Q[IlAW!ahhC2ac:9*A}h:p?([4%wOTJ%JR%cs
----

And the server shall use this long-term key pair (specified as hexadecimal 
and in Z85):

----
public: 
    54FCBA24E93249969316FB617C872BB0C1D1FF14800427C594CBFACF1BC2D652
    rq:rM>}U?@Lns47E1%kR.o@n%FcmmsL/@{H8]yf7

secret: 
    8E0BDD697628B91D8F245587EE95C5B04D48963F79259877B49CD9063AEAD3B7
    JTKVSB%%)wK0E.X)V>+}o?pNmC{O&4W4b!Ni{Lh6
----

== SEE ALSO
* xref:zmq_z85_encode.adoc[zmq_z85_encode]
* xref:zmq_z85_decode.adoc[zmq_z85_decode]
* xref:zmq_setsockopt.adoc[zmq_setsockopt]
* xref:zmq_null.adoc[zmq_null]
* xref:zmq_plain.adoc[zmq_plain]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Curve Keypair (`doc/zmq_curve_keypair.adoc`)

= zmq_curve_keypair(3)


== NAME
zmq_curve_keypair - generate a new CURVE keypair


== SYNOPSIS
*int zmq_curve_keypair (char *z85_public_key, char *z85_secret_key);*


== DESCRIPTION
The _zmq_curve_keypair()_ function shall return a newly generated random
keypair consisting of a public key and a secret key. The caller provides
two buffers, each at least 41 octets large, in which this method will
store the keys. The keys are encoded using xref:zmq_z85_encode.adoc[zmq_z85_encode].


== RETURN VALUE
The _zmq_curve_keypair()_ function shall return 0 if successful, else it
shall return `-1` and set 'errno' to one of the values defined below.


== ERRORS
*ENOTSUP*::
The libzmq library was not built with cryptographic support (libsodium).


== EXAMPLE
.Generating a new CURVE keypair
----
char public_key [41];
char secret_key [41];
int rc = zmq_curve_keypair (public_key, secret_key);
assert (rc == 0);
----


== SEE ALSO
* xref:zmq_z85_encode.adoc[zmq_z85_encode]
* xref:zmq_z85_decode.adoc[zmq_z85_decode]
* xref:zmq_curve.adoc[zmq_curve]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Curve Public (`doc/zmq_curve_public.adoc`)

= zmq_curve_public(3)


== NAME
zmq_curve_public - derive the public key from a private key


== SYNOPSIS
*int zmq_curve_public (char *z85_public_key, char *z85_secret_key);*


== DESCRIPTION
The _zmq_curve_public()_ function shall derive the public key from a
private key. The caller provides two buffers, each at least 41 octets
large. In z85_secret_key the caller shall provide the private key, and
the function will store the public key in z85_public_key. The keys are
encoded using xref:zmq_z85_encode.adoc[zmq_z85_encode].


== RETURN VALUE
The _zmq_curve_public()_ function shall return 0 if successful, else it
shall return `-1` and set 'errno' to one of the values defined below.


== ERRORS
*ENOTSUP*::
The libzmq library was not built with cryptographic support (libsodium).


== EXAMPLE
.Deriving the public key from a CURVE private key
----
char public_key [41];
char secret_key [41];
int rc = zmq_curve_keypair (public_key, secret_key);
assert (rc == 0);
char derived_public[41];
rc = zmq_curve_public (derived_public, secret_key);
assert (rc == 0);
assert (!strcmp (derived_public, public_key));
----


== SEE ALSO
* xref:zmq_z85_encode.adoc[zmq_z85_encode]
* xref:zmq_z85_decode.adoc[zmq_z85_decode]
* xref:zmq_curve_keypair.adoc[zmq_curve_keypair]
* xref:zmq_curve.adoc[zmq_curve]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Disconnect (`doc/zmq_disconnect.adoc`)

= zmq_disconnect(3)


== NAME
zmq_disconnect - Disconnect a socket from an endpoint


== SYNOPSIS
*int zmq_disconnect (void '*socket', const char '*endpoint');*


== DESCRIPTION
The _zmq_disconnect()_ function shall disconnect a socket specified
by the 'socket' argument from the endpoint specified by the 'endpoint'
argument. Note the actual disconnect system call might occur at a later time.

Upon disconnection the will also stop receiving messages originating from
this endpoint. Moreover, the socket will no longer be able
to queue outgoing messages to this endpoint. The outgoing message queue
associated with the endpoint will be discarded. However, if the socket's linger
period is non-zero, libzmq will still attempt to transmit these discarded messages,
until the linger period expires.

The 'endpoint' argument is as described in xref:zmq_connect.adoc[zmq_connect]

NOTE: The default setting of _ZMQ_LINGER_ does not discard unsent messages;
this behaviour may cause the application to block when calling _zmq_ctx_term()_.
For details refer to xref:zmq_setsockopt.adoc[zmq_setsockopt] and xref:zmq_ctx_term.adoc[zmq_ctx_term]

== RETURN VALUE
The _zmq_disconnect()_ function shall return zero if successful. Otherwise it
shall return `-1` and set 'errno' to one of the values defined below.

== ERRORS
*EINVAL*::
The endpoint supplied is invalid.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*ENOENT*::
The provided endpoint is not in use by the socket.


== EXAMPLE
.Connecting a subscriber socket to an in-process and a TCP transport
----
/* Create a ZMQ_SUB socket */
void *socket = zmq_socket (context, ZMQ_SUB);
assert (socket);
/* Connect it to the host server001, port 5555 using a TCP transport */
rc = zmq_connect (socket, "tcp://server001:5555");
assert (rc == 0);
/* Disconnect from the previously connected endpoint */
rc = zmq_disconnect (socket, "tcp://server001:5555");
assert (rc == 0);
----

== SEE ALSO
* xref:zmq_connect.adoc[zmq_connect]
* xref:zmq_socket.adoc[zmq_socket]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Disconnect Peer (`doc/zmq_disconnect_peer.adoc`)

= zmq_disconnect_peer(3)


== NAME
zmq_disconnect_peer - disconnect a specific peer connection by routing id.


== SYNOPSIS
*int zmq_disconnect_peer (void '*socket', uint32_t 'routing_id');*


== DESCRIPTION
The _zmq_disconnect_peer()_ function disconnects a specific connection from a
socket given the peer 'routing_id'. After a successful disconnection, attempts
to send messages addressed with that 'routing_id' will fail with 'EHOSTUNREACH'
until a new connection with a different 'routing_id' is established.

This function is supported on socket types that manage per-peer routing ids:
'ZMQ_SERVER' and 'ZMQ_PEER'. Calling it on other socket types will fail with
'ENOTSUP'.


== RETURN VALUE
The _zmq_disconnect_peer()_ function returns `0` if successful. Otherwise it
returns `-1` and sets 'errno' to one of the values defined below.


== ERRORS
*EHOSTUNREACH*::
No connection exists for the given 'routing_id'.
*ENOTSUP*::
The socket type does not support disconnecting by 'routing_id'.
*ENOTSOCK*::
The provided 'socket' was invalid.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.


== EXAMPLE
.Disconnect a peer by routing id
----
void *server = zmq_socket (context, ZMQ_SERVER);
assert (server);
assert (zmq_bind (server, "tcp://*:5555") == 0);
/* ... receive a message and read its routing id ... */
uint32_t routing_id = /* obtained from zmq_msg_routing_id(...) */;
/* Disconnect that specific peer */
int rc = zmq_disconnect_peer (server, routing_id);
assert (rc == 0);
/* Any attempt to send to that routing id now will fail with EHOSTUNREACH */
----


== SEE ALSO
* xref:zmq_connect_peer.adoc[zmq_connect_peer]
* xref:zmq_disconnect.adoc[zmq_disconnect]
* xref:zmq_msg_routing_id.adoc[zmq_msg_routing_id]
* xref:zmq_msg_set_routing_id.adoc[zmq_msg_set_routing_id]
* xref:zmq_socket.adoc[zmq_socket]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Errno (`doc/zmq_errno.adoc`)

= zmq_errno(3)


== NAME
zmq_errno - retrieve value of errno for the calling thread


== SYNOPSIS
*int zmq_errno (void);*


== DESCRIPTION
The _zmq_errno()_ function shall retrieve the value of the 'errno' variable for
the calling thread.

The _zmq_errno()_ function is provided to assist users on non-POSIX systems who
are experiencing issues with retrieving the correct value of 'errno' directly.
Specifically, users on Win32 systems whose application is using a different C
run-time library from the C run-time library in use by 0MQ will need to use
_zmq_errno()_ for correct operation.

IMPORTANT: Users not experiencing issues with retrieving the correct value of
'errno' should not use this function and should instead access the 'errno'
variable directly.


== RETURN VALUE
The _zmq_errno()_ function shall return the value of the 'errno' variable for
the calling thread.


== ERRORS
No errors are defined.


== SEE ALSO
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Getsockopt (`doc/zmq_getsockopt.adoc`)

= 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_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 xref:zmq_init.adoc[zmq_init] 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_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_BINDTODEVICE: Retrieve name of device the socket is bound to
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_BINDTODEVICE' option retrieves the name of the device this socket is
bound to, eg. an interface or VRF. If a socket is bound to an interface, only
packets received from that interface are processed by the socket. If device
is a VRF device, then subsequent binds/connects to that socket use addresses
in the VRF routing table.

[horizontal]
Option value type:: character string
Option value unit:: N/A
Default value:: not set
Applicable socket types:: all, when using TCP or UDP transports.


ZMQ_CONNECT_TIMEOUT: Retrieve connect() timeout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieves how long to wait before timing-out a connect() system call.
The connect() system call normally takes a long time before it returns a
time out error. Setting this option allows the library to time out the call
at an earlier interval.

[horizontal]
Option value type:: int
Option value unit:: milliseconds
Default value:: 0 (disabled)
Applicable socket types:: all, when using TCP transports.


ZMQ_CURVE_PUBLICKEY: Retrieve current CURVE public key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Retrieves the current long term public key for the socket. You can
provide either a 32 byte buffer, to retrieve the binary key value, or
a 41 byte buffer, to retrieve the key in a printable Z85 format.
NOTE: to fetch a printable key, the buffer must be 41 bytes large
to hold the 40-char key value and one null byte.

[horizontal]
Option value type:: binary data or Z85 text string
Option value size:: 32 or 41
Default value:: null
Applicable socket types:: all, when using TCP transport


ZMQ_CURVE_SECRETKEY: Retrieve current CURVE secret key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Retrieves the current long term secret key for the socket. You can
provide either a 32 byte buffer, to retrieve the binary key value, or
a 41 byte buffer, to retrieve the key in a printable Z85 format.
NOTE: to fetch a printable key, the buffer must be 41 bytes large
to hold the 40-char key value and one null byte.

[horizontal]
Option value type:: binary data or Z85 text string
Option value size:: 32 or 41
Default value:: null
Applicable socket types:: all, when using TCP transport


ZMQ_CURVE_SERVERKEY: Retrieve current CURVE server key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Retrieves the current server key for the client socket. You can
provide either a 32 byte buffer, to retrieve the binary key value, or
a 41-byte buffer, to retrieve the key in a printable Z85 format.
NOTE: to fetch a printable key, the buffer must be 41 bytes large
to hold the 40-char key value and one null byte.

[horizontal]
Option value type:: binary data or Z85 text string
Option value size:: 32 or 41
Default value:: null
Applicable socket types:: all, when using TCP transport


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_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_GSSAPI_PLAINTEXT: Retrieve GSSAPI plaintext or encrypted status
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Returns the 'ZMQ_GSSAPI_PLAINTEXT' option, if any, previously set on the
socket.  A value of '1' means  that communications will be plaintext.  A value
of '0' means communications will be encrypted.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 0 (false)
Applicable socket types:: all, when using TCP or IPC transports


ZMQ_GSSAPI_PRINCIPAL: Retrieve the name of the GSSAPI principal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_GSSAPI_PRINCIPAL' option shall retrieve the principal name set for the
GSSAPI security mechanism. The returned value shall be a NULL-terminated string
and MAY be empty. The returned size SHALL include the terminating null byte.

[horizontal]
Option value type:: NULL-terminated character string
Option value unit:: N/A
Default value:: null string
Applicable socket types:: all, when using TCP or IPC transports


ZMQ_GSSAPI_SERVER: Retrieve current GSSAPI server role
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Returns the 'ZMQ_GSSAPI_SERVER' option, if any, previously set on the socket.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 0 (false)
Applicable socket types:: all, when using TCP or IPC transports


ZMQ_GSSAPI_SERVICE_PRINCIPAL: Retrieve the name of the GSSAPI service principal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_GSSAPI_SERVICE_PRINCIPAL' option shall retrieve the principal name of
the GSSAPI server to which a GSSAPI client socket intends to connect.  The
returned value shall be a NULL-terminated string and MAY be empty. The returned
size SHALL include the terminating null byte.

[horizontal]
Option value type:: NULL-terminated character string
Option value unit:: N/A
Default value:: null string
Applicable socket types:: all, when using TCP or IPC transports

ZMQ_GSSAPI_SERVICE_PRINCIPAL_NAMETYPE: Retrieve nametype for service principal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Returns the 'ZMQ_GSSAPI_SERVICE_PRINCIPAL_NAMETYPE' option, if any, previously
set on the socket.  A value of 'ZMQ_GSSAPI_NT_HOSTBASED' (0) means the name
specified with 'ZMQ_GSSAPI_SERVICE_PRINCIPAL' is interpreted as a host based
name.  A value of 'ZMQ_GSSAPI_NT_USER_NAME' (1) means it is interpreted as
a local user name.  A value of 'ZMQ_GSSAPI_NT_KRB5_PRINCIPAL' (2) means it
is interpreted as an unparsed principal name string (valid only with the
krb5 GSSAPI mechanism).

[horizontal]
Option value type:: int
Option value unit:: 0, 1, 2
Default value:: 0 (ZMQ_GSSAPI_NT_HOSTBASED)
Applicable socket types:: all, when using TCP or IPC transports

ZMQ_GSSAPI_PRINCIPAL_NAMETYPE: Retrieve nametype for service principal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Returns the 'ZMQ_GSSAPI_PRINCIPAL_NAMETYPE' option, if any, previously
set on the socket.  A value of 'ZMQ_GSSAPI_NT_HOSTBASED' (0) means the name
specified with 'ZMQ_GSSAPI_PRINCIPAL' is interpreted as a host based
name.  A value of 'ZMQ_GSSAPI_NT_USER_NAME' (1) means it is interpreted as
a local user name.  A value of 'ZMQ_GSSAPI_NT_KRB5_PRINCIPAL' (2) means it
is interpreted as an unparsed principal name string (valid only with the
krb5 GSSAPI mechanism).

[horizontal]
Option value type:: int
Option value unit:: 0, 1, 2
Default value:: 0 (ZMQ_GSSAPI_NT_HOSTBASED)
Applicable socket types:: all, when using TCP or IPC transports

ZMQ_HANDSHAKE_IVL: Retrieve maximum handshake interval
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_HANDSHAKE_IVL' option shall retrieve the maximum handshake interval
for the specified 'socket'. Handshaking is the exchange of socket configuration
information (socket type, routing id, security) that occurs when a connection
is first opened, only for connection-oriented transports. If handshaking does
not complete within the configured time, the connection shall be closed.
The value 0 means no handshake time limit.

[horizontal]
Option value type:: int
Option value unit:: milliseconds
Default value:: 30000
Applicable socket types:: all but ZMQ_STREAM, only for connection-oriented transports


ZMQ_IDENTITY: Retrieve socket identity
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This option name is now deprecated. Use ZMQ_ROUTING_ID instead.
ZMQ_IDENTITY remains as an alias for now.


ZMQ_IMMEDIATE: 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_INVERT_MATCHING: Retrieve inverted filtering status
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Returns the value of the 'ZMQ_INVERT_MATCHING' option. A value of `1`
means the socket uses inverted prefix matching.

On 'PUB' and 'XPUB' sockets, this causes messages to be sent to all
connected sockets 'except' those subscribed to a prefix that matches
the message. On 'SUB' sockets, this causes only incoming messages that
do 'not' match any of the socket's subscriptions to be received by the user.

Whenever 'ZMQ_INVERT_MATCHING' is set to 1 on a 'PUB' socket, all 'SUB'
sockets connecting to it must also have the option set to 1. Failure to
do so will have the 'SUB' sockets reject everything the 'PUB' socket sends
them. 'XSUB' sockets do not need to do this because they do not filter
incoming messages.

[horizontal]
Option value type:: int
Option value unit:: 0,1
Default value:: 0
Applicable socket types:: ZMQ_PUB, ZMQ_XPUB, ZMQ_SUB


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_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_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).
Note: not supported on GNU/Hurd with IPC due to non-working getsockname().

[horizontal]
Option value type:: NULL-terminated character string
Option value unit:: N/A
Default value:: NULL
Applicable socket types:: all, when binding TCP or IPC transports


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
xref:zmq_close.adoc[zmq_close], and further affects the termination of the socket's
context with xref:zmq_ctx_term.adoc[zmq_ctx_term] 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_ctx_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_ctx_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_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_MECHANISM: Retrieve current security mechanism
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_MECHANISM' option shall retrieve the current security mechanism
for the socket.

[horizontal]
Option value type:: int
Option value unit:: ZMQ_NULL, ZMQ_PLAIN, ZMQ_CURVE, or ZMQ_GSSAPI
Default value:: ZMQ_NULL
Applicable socket types:: all, when using TCP or IPC transports


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_MULTICAST_MAXTPDU: Maximum transport data unit size for multicast packets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_MULTICAST_MAXTPDU' option shall retrieve the maximum transport
data unit size used for outbound multicast packets.

This must be set at or below the minimum Maximum Transmission Unit (MTU) for
all network paths over which multicast reception is required.

[horizontal]
Option value type:: int
Option value unit:: bytes
Default value:: 1500
Applicable socket types:: all, when using multicast transports


ZMQ_PLAIN_PASSWORD: Retrieve current password
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_PLAIN_PASSWORD' option shall retrieve the last password set for
the PLAIN security mechanism. The returned value shall be a NULL-terminated
string and MAY be empty. The returned size SHALL include the terminating
null byte.

[horizontal]
Option value type:: NULL-terminated character string
Option value unit:: N/A
Default value:: null string
Applicable socket types:: all, when using TCP or IPC transports


ZMQ_PLAIN_SERVER: Retrieve current PLAIN server role
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Returns the 'ZMQ_PLAIN_SERVER' option, if any, previously set on the socket.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: int
Applicable socket types:: all, when using TCP or IPC transports


ZMQ_PLAIN_USERNAME: Retrieve current PLAIN username
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_PLAIN_USERNAME' option shall retrieve the last username set for
the PLAIN security mechanism. The returned value shall be a NULL-terminated
string and MAY be empty. The returned size SHALL include the terminating
null byte.

[horizontal]
Option value type:: NULL-terminated character string
Option value unit:: N/A
Default value:: null string
Applicable socket types:: all, when using TCP or IPC transports


ZMQ_USE_FD: Retrieve the pre-allocated socket file descriptor
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_USE_FD' option shall retrieve the pre-allocated file
descriptor that has been assigned to a ZMQ socket, if any. -1 shall be
returned if a pre-allocated file descriptor was not set for the socket.

[horizontal]
Option value type:: int
Option value unit:: file descriptor
Default value:: -1
Applicable socket types:: all bound sockets, when using IPC or TCP transport


ZMQ_PRIORITY: Retrieve the Priority on socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Gets the protocol-defined priority for all packets to be sent on this
socket, where supported by the OS.

[horizontal]
Option value type:: int
Option value unit:: >0
Default value:: 0
Applicable socket types:: all, only for connection-oriented transports


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_RCVBUF: Retrieve kernel receive buffer size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_RCVBUF' option shall retrieve the underlying kernel receive buffer
size for the specified 'socket'. 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:: 8192
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 xref:zmq_socket.adoc[zmq_socket] 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_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 xref:zmq_send.adoc[zmq_send] and xref:zmq_recv.adoc[zmq_recv] 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_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_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 max reconnection interval
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_RECONNECT_IVL_MAX' option shall retrieve the max reconnection interval
for the specified 'socket'. 0MQ shall wait at most the configured interval between
reconnection attempts. The interval grows exponentionally (i.e.: it is doubled)
with each attempt until it reaches ZMQ_RECONNECT_IVL_MAX. Default value means
that the reconnect interval is based exclusively on ZMQ_RECONNECT_IVL and no
exponential backoff is performed.

NOTE:  Value has to be greater or equal than ZMQ_RECONNECT_IVL, or else it will
       be ignored.

[horizontal]
Option value type:: int
Option value unit:: milliseconds
Default value:: 0 (ZMQ_RECONNECT_IVL will be used)
Applicable socket types:: all, only for connection-oriented transport


ZMQ_RECONNECT_STOP: Retrieve condition where reconnection will stop
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_RECONNECT_STOP' option shall retrieve the conditions under which
automatic reconnection will stop.

The 'ZMQ_RECONNECT_STOP_CONN_REFUSED' option will stop reconnection when 0MQ
receives the ECONNREFUSED return code from the connect.  This indicates that
there is no code bound to the specified endpoint.

[horizontal]
Option value type:: int
Option value unit:: 'ZMQ_RECONNECT_STOP_CONN_REFUSED'
Default value:: 0
Applicable socket types:: all, only for connection-oriented 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_ROUTING_ID: Retrieve socket routing id
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_ROUTING_ID' option shall retrieve the routing id of the specified 'socket'.
Routing ids are used only by the request/reply pattern. Specifically, it can be used
in tandem with ROUTER socket to route messages to the peer with a specific
routing id.

A routing id must be at least one byte and at most 255 bytes long. Identities
starting with a zero byte are reserved for use by the 0MQ infrastructure.

[horizontal]
Option value type:: binary data
Option value unit:: N/A
Default value:: NULL
Applicable socket types:: ZMQ_REP, ZMQ_REQ, ZMQ_ROUTER, ZMQ_DEALER.


ZMQ_SNDBUF: Retrieve kernel transmit buffer size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_SNDBUF' option shall retrieve the underlying kernel transmit buffer
size for the specified 'socket'. 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:: 8192
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 xref:zmq_socket.adoc[zmq_socket] 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_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_SOCKS_PROXY: Retrieve SOCKS5 proxy address
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_SOCKS_PROXY' option shall retrieve the SOCKS5 proxy address in string
format. The returned value shall be a NULL-terminated string and MAY be empty.
The returned size SHALL include the terminating null byte.

[horizontal]
Option value type:: NULL-terminated character string
Option value unit:: N/A
Default value:: null string
Applicable socket types:: all, when using TCP 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_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_IDLE: Override TCP_KEEPIDLE (or TCP_KEEPALIVE on some OS)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Override 'TCP_KEEPIDLE'(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_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.


ZMQ_TCP_MAXRT: Retrieve Max TCP Retransmit Timeout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
On OSes where it is supported, retrieves how long before an unacknowledged TCP
retransmit times out. The system normally attempts many TCP retransmits
following an exponential backoff strategy. This means that after a network
outage, it may take a long time before the session can be re-established.
Setting this option allows the timeout to happen at a shorter interval.

[horizontal]
Option value type:: int
Option value unit:: milliseconds
Default value:: 0 (leave to OS default)
Applicable socket types:: all, when using TCP transports.


ZMQ_THREAD_SAFE: Retrieve socket thread safety
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_THREAD_SAFE' option shall retrieve a boolean value indicating whether
or not the socket is threadsafe. See xref:zmq_socket.adoc[zmq_socket] for which sockets are
thread-safe.

[horizontal]
Option value type:: int
Option value unit:: boolean
Applicable socket types:: all


ZMQ_TOS: Retrieve the Type-of-Service socket override status
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieve the IP_TOS option for the socket.

[horizontal]
Option value type:: int
Option value unit:: >0
Default value:: 0
Applicable socket types:: all, only for connection-oriented transports


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_ZAP_DOMAIN: Retrieve RFC 27 authentication domain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The 'ZMQ_ZAP_DOMAIN' option shall retrieve the last ZAP domain set for
the socket. The returned value shall be a NULL-terminated string and MAY
be empty. An empty string means that ZAP authentication is disabled.
The returned size SHALL include the terminating null byte.

[horizontal]
Option value type:: character string
Option value unit:: N/A
Default value:: not set
Applicable socket types:: all, when using TCP transport


ZMQ_ZAP_ENFORCE_DOMAIN: Retrieve ZAP domain handling mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_ZAP_ENFORCE_DOMAIN' option shall retrieve the flag that determines
whether a ZAP domain is strictly required or not.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 0
Applicable socket types:: all, when using ZAP


ZMQ_VMCI_BUFFER_SIZE: Retrieve buffer size of the VMCI socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `ZMQ_VMCI_BUFFER_SIZE` option shall retrieve the size of the underlying
buffer for the socket. Used during negotiation before the connection is established.

[horizontal]
Option value type:: uint64_t
Option value unit:: bytes
Default value:: 65546
Applicable socket types:: all, when using VMCI transport


ZMQ_VMCI_BUFFER_MIN_SIZE: Retrieve min buffer size of the VMCI socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `ZMQ_VMCI_BUFFER_MIN_SIZE` option shall retrieve the min size of the underlying
buffer for the socket. Used during negotiation before the connection is established.

[horizontal]
Option value type:: uint64_t
Option value unit:: bytes
Default value:: 128
Applicable socket types:: all, when using VMCI transport


ZMQ_VMCI_BUFFER_MAX_SIZE: Retrieve max buffer size of the VMCI socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `ZMQ_VMCI_BUFFER_MAX_SIZE` option shall retrieve the max size of the underlying
buffer for the socket. Used during negotiation before the connection is established.

[horizontal]
Option value type:: uint64_t
Option value unit:: bytes
Default value:: 262144
Applicable socket types:: all, when using VMCI transport


ZMQ_VMCI_CONNECT_TIMEOUT: Retrieve connection timeout of the VMCI socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `ZMQ_VMCI_CONNECT_TIMEOUT` option shall retrieve connection timeout
for the socket.

[horizontal]
Option value type:: int
Option value unit:: milliseconds
Default value:: -1
Applicable socket types:: all, when using VMCI transport


ZMQ_MULTICAST_LOOP: Retrieve multicast local loopback configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieve the current multicast loopback configuration. A value of `1`
means that the multicast packets sent on this socket will be looped
back to local listening interface.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 1
Applicable socket types:: ZMQ_RADIO, when using UDP multicast transport


ZMQ_ROUTER_NOTIFY: Retrieve router socket notification settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieve the current notification settings of a router socket. The returned
value is a bitmask composed of ZMQ_NOTIFY_CONNECT and ZMQ_NOTIFY_DISCONNECT
flags, meaning connect and disconnect notifications are enabled, respectively.
A value of '0' means the notifications are off.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: 0, ZMQ_NOTIFY_CONNECT, ZMQ_NOTIFY_DISCONNECT, ZMQ_NOTIFY_CONNECT | ZMQ_NOTIFY_DISCONNECT
Default value:: 0
Applicable socket types:: ZMQ_ROUTER


ZMQ_IN_BATCH_SIZE: Maximal receive batch size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Gets the maximal amount of messages that can be received in a single
'recv' system call.

Cannot be zero.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: messages
Default value:: 8192
Applicable socket types:: All, when using TCP, IPC, PGM or NORM transport.


ZMQ_OUT_BATCH_SIZE: Maximal send batch size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Gets the maximal amount of messages that can be sent in a single
'send' system call.

Cannot be zero.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: messages
Default value:: 8192
Applicable socket types:: All, when using TCP, IPC, PGM or NORM transport.


ZMQ_TOPICS_COUNT: Number of topic subscriptions received
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Gets the number of topic (prefix) subscriptions either
* received on a (X)PUB socket from all the connected (X)SUB sockets or
* acknowledged on an (X)SUB socket from all the connected (X)PUB sockets

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: N/A
Default value:: 0
Applicable socket types:: ZMQ_PUB, ZMQ_XPUB, ZMQ_SUB, ZMQ_XSUB


ZMQ_NORM_MODE: Retrieve NORM Sender Mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Gets the NORM sender mode to control the operation of the NORM transport. NORM
supports fixed rate operation (0='ZMQ_NORM_FIXED'), congestion control mode 
(1='ZMQ_NORM_CC'), loss-tolerant congestion control (2='ZMQ_NORM_CCL'), explicit
congestion notification (ECN)-enabled congestion control (3='ZMQ_NORM_CCE'), and
ECN-only congestion control (4='ZMQ_NORM_CCE_ECNONLY'). The default value is 
TCP-friendly congestion control mode. Fixed rate mode (using datarate set by
'ZMQ_RATE') offers better performance, but care must be taken to prevent data
loss.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: 0, 1, 2, 3, 4
Default value:: 1 ('ZMQ_NORM_CC')
Applicable socket types:: All, when using NORM transport.


ZMQ_NORM_UNICAST_NACK: Retrieve NORM Unicast NACK mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieves status of NORM unicast NACK mode setting for multicast receivers. If
set, NORM receiver will send Negative ACKnowledgements (NACKs) back to the
sender using unicast instead of multicast.  NORM transport endpoints specifying
a unicast address will use unicast NACKs by default (without setting
'ZMQ_NORM_UNICAST_NACK').

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: boolean
Default value:: 0 (false)
Applicable socket types:: All, when using NORM transport.


ZMQ_NORM_BUFFER_SIZE: Retrieve NORM buffer size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Gets NORM buffer size for NORM transport sender, receiver, and stream.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: kilobytes
Default value:: 2048
Applicable socket types:: All, when using NORM transport.


ZMQ_NORM_SEGMENT_SIZE: Retrieve NORM segment size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Gets NORM sender segment size, which is the maximum message payload size of
individual NORM messages (ZMQ messages may be split over multiple NORM
messages).  Ideally, this value should fit within the system/network maximum
transmission unit (MTU) after accounting for additional NORM message headers
(up to 48 bytes).

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: bytes
Default value:: 1400
Applicable socket types:: All, when using NORM transport.


ZMQ_NORM_BLOCK_SIZE: Retrieve NORM block size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Gets NORM sender block size, which is the number of segments in a NORM FEC
coding block. NORM repair operations take place at block boundaries. Maximum
value is 255, but parity packets ('ZMQ_NORM_NUM_PARITY') are limited to a value
of (255 - 'ZMQ_NORM_BLOCK_SIZE'). Minimum value is ('ZMQ_NORM_NUM_PARITY' + 1).
Effective value may be different based on the settings of 'ZMQ_NORM_NUM_PARITY'
and 'ZMQ_NORM_NUM_AUTOPARITY' if invalid settings are provided.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: >0, <=255
Default value:: 16
Applicable socket types:: All, when using NORM transport.


ZMQ_NORM_NUM_PARITY: Retrieve NORM parity segment setting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Gets the maximum number of NORM parity symbol segments that the sender is
willing to calculate per FEC coding block for the purpose of reparing lost data.
Maximum value is 255, but is further limited to a value of
(255 - 'ZMQ_NORM_BLOCK_SIZE'). Minimum value is 'ZMQ_NORM_NUM_AUTOPARITY'.
Effective value may be different based on the setting of
'ZMQ_NORM_NUM_AUTOPARITY' if invalid settings are provided.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: >0, <255
Default value:: 4
Applicable socket types:: All, when using NORM transport.


ZMQ_NORM_NUM_AUTOPARITY: Retrieve proactive NORM parity segment setting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Gets the number of NORM parity symbol segments that the sender will proactively
send at the end of each FEC coding block. By default, no proactive parity
segments will be sent; instead, parity segments will only be sent in response to
repair requests (NACKs). Maximum value is 255, but is further limited to a 
maximum value of 'ZMQ_NORM_NUM_PARITY'.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: >=0, <255
Default value:: 0
Applicable socket types:: All, when using NORM transport.


ZMQ_NORM_PUSH: Retrieve NORM push mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Gets status of NORM stream push mode, which alters the behavior of the sender
when enqueueing new data. By default, NORM will stop accepting new messages
while waiting for old data to be transmitted and/or repaired. Enabling push mode
discards the oldest data (which may be pending repair or may never have been
transmitted) in favor of accepting new data. This may be useful in cases where
it is more important to quickly deliver new data instead of reliably delivering
older data.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: boolean
Default value:: 0 (false)
Applicable socket types:: All, when using NORM transport.


== 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
* xref:zmq_setsockopt.adoc[zmq_setsockopt]
* xref:zmq_socket.adoc[zmq_socket]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Gssapi (`doc/zmq_gssapi.adoc`)

= zmq_gssapi(7)


== NAME
zmq_gssapi - secure authentication and confidentiality


== SYNOPSIS

The GSSAPI mechanism defines a mechanism for secure authentication and
confidentiality for communications between a client and a server using the
Generic Security Service Application Program Interface (GSSAPI).  The GSSAPI
mechanism can be used on both public and private networks.  GSSAPI itself is
defined in IETF RFC-2743: <http://tools.ietf.org/html/rfc2743>. The ZeroMQ
GSSAPI mechanism is defined by this document: <http://rfc.zeromq.org/spec:38>.


== CLIENT AND SERVER ROLES
A socket using GSSAPI can be either client or server, but not both.

To become a GSSAPI server, the application sets the ZMQ_GSSAPI_SERVER
option on the socket.

To become a GSSAPI client, the application sets the ZMQ_GSSAPI_SERVICE_PRINCIPAL
option to the name of the principal on the server to which it intends to
connect.

On client or server, the application may additionally set the
ZMQ_GSSAPI_PRINCIPAL option to provide the socket with the name of the
principal for whom GSSAPI credentials should be acquired.  If this option
is not set, default credentials are used.


== OPTIONAL ENCRYPTION
By default, the GSSAPI mechanism will encrypt all communications between client
and server.  If encryption is not desired (e.g. on private networks), the
client and server applications can disable it by setting the
ZMQ_GSSAPI_PLAINTEXT option.  Both the client and server must set this option
to the same value.


== PRINCIPAL NAMES
Principal names specified with the ZMQ_GSSAPI_SERVICE_PRINCIPAL or
ZMQ_GSSAPI_PRINCIPAL options are interpreted as "host based" name types
by default.  The ZMQ_GSSAPI_PRINCIPAL_NAMETYPE and
ZMQ_GSSAPI_SERVICE_PRINCIPAL_NAMETYPE options may be used to change the
name type to one of:

*ZMQ_GSSAPI_NT_HOSTBASED*::
The name should be of the form "service" or "service@hostname",
which will parse into a principal of "service/hostname"
in the local realm.  This is the default name type.
*ZMQ_GSSAPI_NT_USER_NAME*::
The name should be a local username, which will parse into a single-component
principal in the local realm.
*ZMQ_GSSAPI_NT_KRB5_PRINCIPAL*::
The name is a principal name string.  This name type only works with
the krb5 GSSAPI mechanism.


== SEE ALSO
* xref:zmq_setsockopt.adoc[zmq_setsockopt]
* xref:zmq_null.adoc[zmq_null]
* xref:zmq_curve.adoc[zmq_curve]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Has (`doc/zmq_has.adoc`)

= zmq_has(3)


== NAME
zmq_has - check a ZMQ capability


== SYNOPSIS
*int zmq_has (const char *capability);*


== DESCRIPTION
The _zmq_has()_ function shall report whether a specified capability is
available in the library. This allows bindings and applications to probe
a library directly, for transport and security options.

Capabilities shall be lowercase strings. The following capabilities are
defined:

* ipc - the library supports the ipc:// protocol
* pgm - the library supports the pgm:// protocol
* tipc - the library supports the tipc:// protocol
* norm - the library supports the norm:// protocol
* curve - the library supports the CURVE security mechanism
* gssapi - the library supports the GSSAPI security mechanism
* draft - the library is built with the draft api

When this method is provided, the zmq.h header file will define
ZMQ_HAS_CAPABILITIES.

== RETURN VALUE
The _zmq_has()_ function shall return 1 if the specified capability is
provided. Otherwise it shall return 0.


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Inproc (`doc/zmq_inproc.adoc`)

= zmq_inproc(7)


== NAME
zmq_inproc - 0MQ local in-process (inter-thread) communication transport


== SYNOPSIS
The in-process transport passes messages via memory directly between threads
sharing a single 0MQ 'context'.

NOTE: No I/O threads are involved in passing messages using the 'inproc'
transport. Therefore, if you are using a 0MQ 'context' for in-process messaging
only you can initialise the 'context' with zero I/O threads. See
xref:zmq_init.adoc[zmq_init] for details.


== ADDRESSING
A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.

For the in-process transport, the transport is `inproc`, and the meaning of
the 'address' part is defined below.


Assigning a local address to a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When assigning a local address to a 'socket' using _zmq_bind()_ with the
'inproc' transport, the 'endpoint' shall be interpreted as an arbitrary string
identifying the 'name' to create. The 'name' must be unique within the 0MQ
'context' associated with the 'socket' and may be up to 256 characters in
length.  No other restrictions are placed on the format of the 'name'.


Connecting a socket
~~~~~~~~~~~~~~~~~~~
When connecting a 'socket' to a peer address using _zmq_connect()_ with the
'inproc' transport, the 'endpoint' shall be interpreted as an arbitrary string
identifying the 'name' to connect to.  Before version 4.0 he 'name' must have
been previously created by assigning it to at least one 'socket' within the
same 0MQ 'context' as the 'socket' being connected.  Since version 4.0 the
order of _zmq_bind()_ and _zmq_connect()_ does not matter just like for the tcp
transport type.


== EXAMPLES
.Assigning a local address to a socket
----
//  Assign the in-process name "#1"
rc = zmq_bind(socket, "inproc://#1");
assert (rc == 0);
//  Assign the in-process name "my-endpoint"
rc = zmq_bind(socket, "inproc://my-endpoint");
assert (rc == 0);
----

.Connecting a socket
----
//  Connect to the in-process name "#1"
rc = zmq_connect(socket, "inproc://#1");
assert (rc == 0);
//  Connect to the in-process name "my-endpoint"
rc = zmq_connect(socket, "inproc://my-endpoint");
assert (rc == 0);
----


== SEE ALSO
* xref:zmq_bind.adoc[zmq_bind]
* xref:zmq_connect.adoc[zmq_connect]
* xref:zmq_ipc.adoc[zmq_ipc]
* xref:zmq_tcp.adoc[zmq_tcp]
* xref:zmq_pgm.adoc[zmq_pgm]
* xref:zmq_vmci.adoc[zmq_vmci]
* xref:zmq_vsock.adoc[zmq_vsock]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Ipc (`doc/zmq_ipc.adoc`)

= zmq_ipc(7)


== NAME
zmq_ipc - 0MQ local inter-process communication transport


== SYNOPSIS
The inter-process transport passes messages between local processes using a
system-dependent IPC mechanism.

NOTE: The inter-process transport is currently only implemented on operating
systems that provide UNIX domain sockets.


== ADDRESSING
A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.

For the inter-process transport, the transport is `ipc`, and the meaning of
the 'address' part is defined below.


Binding a socket
~~~~~~~~~~~~~~~~
When binding a 'socket' to a local address using _zmq_bind()_ with the 'ipc'
transport, the 'endpoint' shall be interpreted as an arbitrary string
identifying the 'pathname' to create. The 'pathname' must be unique within the
operating system namespace used by the 'ipc' implementation, and must fulfill
any restrictions placed by the operating system on the format and length of a
'pathname'.

When the address is wild-card `*`, _zmq_bind()_ shall generate a unique temporary
pathname. The caller should retrieve this pathname using the ZMQ_LAST_ENDPOINT
socket option. See xref:zmq_getsockopt.adoc[zmq_getsockopt] for details.

NOTE: any existing binding to the same endpoint shall be overridden. That is,
if a second process binds to an endpoint already bound by a process, this
will succeed and the first process will lose its binding. In this behaviour,
the 'ipc' transport is not consistent with the 'tcp' or 'inproc' transports.

NOTE: the endpoint pathname must be writable by the process. When the endpoint
starts with '/', e.g., `ipc:///pathname`, this will be an _absolute_ pathname.
If the endpoint specifies a directory that does not exist, the bind shall fail.

NOTE: on Linux only, when the endpoint pathname starts with `@`, the abstract
namespace shall be used.  The abstract namespace is independent of the
filesystem and if a process attempts to bind an endpoint already bound by a
process, it will fail.  See unix(7) for details.

NOTE: IPC pathnames have a maximum size that depends on the operating system.
On Linux, the maximum is 113 characters including the "ipc://" prefix (107
characters for the real path name).

Unbinding wild-card address from a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When wild-card `*` 'endpoint' was used in _zmq_bind()_, the caller should use
real 'endpoint' obtained from the ZMQ_LAST_ENDPOINT socket option to unbind
this 'endpoint' from a socket using _zmq_unbind()_.

Connecting a socket
~~~~~~~~~~~~~~~~~~~
When connecting a 'socket' to a peer address using _zmq_connect()_ with the
'ipc' transport, the 'endpoint' shall be interpreted as an arbitrary string
identifying the 'pathname' to connect to.  The 'pathname' must have been
previously created within the operating system namespace by assigning it to a
'socket' with _zmq_bind()_.


== EXAMPLES
.Assigning a local address to a socket
----
//  Assign the pathname "/tmp/feeds/0"
rc = zmq_bind(socket, "ipc:///tmp/feeds/0");
assert (rc == 0);
----

.Connecting a socket
----
//  Connect to the pathname "/tmp/feeds/0"
rc = zmq_connect(socket, "ipc:///tmp/feeds/0");
assert (rc == 0);
----

== SEE ALSO
* xref:zmq_bind.adoc[zmq_bind]
* xref:zmq_connect.adoc[zmq_connect]
* xref:zmq_inproc.adoc[zmq_inproc]
* xref:zmq_tcp.adoc[zmq_tcp]
* xref:zmq_pgm.adoc[zmq_pgm]
* xref:zmq_vmci.adoc[zmq_vmci]
* xref:zmq_vsock.adoc[zmq_vsock]
* xref:zmq_getsockopt.adoc[zmq_getsockopt]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Msg Close (`doc/zmq_msg_close.adoc`)

= zmq_msg_close(3)


== NAME
zmq_msg_close - release 0MQ message


== SYNOPSIS
*int zmq_msg_close (zmq_msg_t '*msg');*


== DESCRIPTION
The _zmq_msg_close()_ function shall inform the 0MQ infrastructure that any
resources associated with the message object referenced by 'msg' are no longer
required and may be released. Actual release of resources associated with the
message object shall be postponed by 0MQ until all users of the message or
underlying data buffer have indicated it is no longer required.

Applications should ensure that _zmq_msg_close()_ is called once a message is
no longer required, otherwise memory leaks may occur. Note that this is NOT
necessary after a successful _zmq_msg_send()_.

CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.


== RETURN VALUE
The _zmq_msg_close()_ function shall return zero if successful. Otherwise
it shall return `-1` and set 'errno' to one of the values defined below.


== ERRORS
*EFAULT*::
Invalid message.


== SEE ALSO
* xref:zmq_msg_init.adoc[zmq_msg_init]
* xref:zmq_msg_init_size.adoc[zmq_msg_init_size]
* xref:zmq_msg_init_buffer.adoc[zmq_msg_init_buffer]
* xref:zmq_msg_init_data.adoc[zmq_msg_init_data]
* xref:zmq_msg_data.adoc[zmq_msg_data]
* xref:zmq_msg_size.adoc[zmq_msg_size]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Msg Copy (`doc/zmq_msg_copy.adoc`)

= zmq_msg_copy(3)


== NAME
zmq_msg_copy - copy content of a message to another message


== SYNOPSIS
*int zmq_msg_copy (zmq_msg_t '*dest', zmq_msg_t '*src');*


== DESCRIPTION
The _zmq_msg_copy()_ function shall copy the message object referenced by 'src'
to the message object referenced by 'dest'. The original content of 'dest', if
any, shall be released. You must initialise 'dest' before copying to it.

CAUTION: The implementation may choose not to physically copy the message
content, rather to share the underlying buffer between 'src' and 'dest'. Avoid
modifying message content after a message has been copied with
_zmq_msg_copy()_, doing so can result in undefined behaviour. If what you need
is an actual hard copy, initialize a new message using _zmq_msg_init_buffer()_
with the message content.

CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.


== RETURN VALUE
The _zmq_msg_copy()_ function shall return zero if successful. Otherwise it
shall return `-1` and set 'errno' to one of the values defined below.


== ERRORS
*EFAULT*::
Invalid message.


== EXAMPLE
.Copying a message
----
zmq_msg_t msg;
zmq_msg_init_buffer (&msg, "Hello, World", 12);
zmq_msg_t copy;
zmq_msg_init (&copy);
zmq_msg_copy (&copy, &msg);
...
zmq_msg_close (&copy);
zmq_msg_close (&msg);
----

== SEE ALSO
* xref:zmq_msg_move.adoc[zmq_msg_move]
* xref:zmq_msg_init.adoc[zmq_msg_init]
* xref:zmq_msg_init_size.adoc[zmq_msg_init_size]
* xref:zmq_msg_init_buffer.adoc[zmq_msg_init_buffer]
* xref:zmq_msg_init_data.adoc[zmq_msg_init_data]
* xref:zmq_msg_close.adoc[zmq_msg_close]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Msg Data (`doc/zmq_msg_data.adoc`)

= zmq_msg_data(3)


== NAME
zmq_msg_data - retrieve pointer to message content


== SYNOPSIS
*void *zmq_msg_data (zmq_msg_t '*msg');*


== DESCRIPTION
The _zmq_msg_data()_ function shall return a pointer to the message content of
the message object referenced by 'msg'.

CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.


== RETURN VALUE
Upon successful completion, _zmq_msg_data()_ shall return a pointer to the
message content.


== ERRORS
No errors are defined.


== SEE ALSO
* xref:zmq_msg_size.adoc[zmq_msg_size]
* xref:zmq_msg_init.adoc[zmq_msg_init]
* xref:zmq_msg_init_size.adoc[zmq_msg_init_size]
* xref:zmq_msg_init_buffer.adoc[zmq_msg_init_buffer]
* xref:zmq_msg_init_data.adoc[zmq_msg_init_data]
* xref:zmq_msg_close.adoc[zmq_msg_close]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Msg Get (`doc/zmq_msg_get.adoc`)

= zmq_msg_get(3)


== NAME
zmq_msg_get - get message property


== SYNOPSIS
*int zmq_msg_get (zmq_msg_t '*message', int 'property');*


== DESCRIPTION
The _zmq_msg_get()_ function shall return the value for the property
specified by the 'property' argument for the message pointed to by the
'message' argument.

The following properties can be retrieved with the _zmq_msg_get()_ function:

*ZMQ_MORE*::
Indicates that there are more message frames to follow after the 'message'.

*ZMQ_SRCFD*::
Returns the file descriptor of the socket the 'message' was read from. This
allows application to retrieve the remote endpoint via 'getpeername(2)'. Be
aware that the respective socket might be closed already, reused even.
Currently only implemented for TCP sockets.

*ZMQ_SHARED*::
Indicates that a message MAY share underlying storage with another copy of
this message.

== RETURN VALUE
The _zmq_msg_get()_ function shall return the value for the property if
successful. Otherwise it shall return `-1` and set 'errno' to one of the
values defined below.


== ERRORS
*EINVAL*::
The requested _property_ is unknown.


== EXAMPLE
.Receiving a multi-frame message
----
zmq_msg_t frame;
while (true) {
    //  Create an empty 0MQ message to hold the message frame
    int rc = zmq_msg_init (&frame);
    assert (rc == 0);
    //  Block until a message is available to be received from socket
    rc = zmq_msg_recv (socket, &frame, 0);
    assert (rc != -1);
    if (zmq_msg_get (&frame, ZMQ_MORE))
        fprintf (stderr, "more\n");
    else {
        fprintf (stderr, "end\n");
        break;
    }
    zmq_msg_close (&frame);
}
----


== SEE ALSO
* xref:zmq_msg_set.adoc[zmq_msg_set]
* xref:zmq_msg_init.adoc[zmq_msg_init]
* xref:zmq_msg_close.adoc[zmq_msg_close]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Msg Gets (`doc/zmq_msg_gets.adoc`)

= zmq_msg_gets(3)


== NAME
zmq_msg_gets - get message metadata property


== SYNOPSIS
*const char *zmq_msg_gets (zmq_msg_t '*message', const char *'property');*


== DESCRIPTION
The _zmq_msg_gets()_ function shall return the string value for the metadata
property specified by the 'property' argument for the message pointed to by
the 'message' argument. Both the 'property' argument and the 'value'
shall be NULL-terminated UTF8-encoded strings.

Metadata is defined on a per-connection basis during the ZeroMQ connection
handshake as specified in <rfc.zeromq.org/spec:37>. Applications can set
metadata properties using xref:zmq_setsockopt.adoc[zmq_setsockopt] option ZMQ_METADATA.
Application metadata properties must be prefixed with 'X-'.

In addition to application metadata, the following ZMTP properties can be
retrieved with the _zmq_msg_gets()_ function:

    Socket-Type
    Routing-Id

Note: 'Identity' is a deprecated alias for 'Routing-Id'.

Additionally, when available for the underlying transport, the *Peer-Address*
property will return the IP address of the remote endpoint as returned by
getnameinfo(2).

The names of these properties are also defined in _zmq.h_ as
_ZMQ_MSG_PROPERTY_SOCKET_TYPE_ _ZMQ_MSG_PROPERTY_ROUTING_ID_, and 
_ZMQ_MSG_PROPERTY_PEER_ADDRESS_.
Currently, these definitions are only available as a DRAFT API.

Other properties may be defined based on the underlying security mechanism,
see ZAP authenticated connection sample below.

== RETURN VALUE
The _zmq_msg_gets()_ function shall return the string value for the property
if successful. Otherwise it shall return NULL and set 'errno' to one of the
values defined below. The caller shall not modify or free the returned value,
which shall be owned by the message. The encoding of the property and value
shall be UTF8.


== ERRORS
*EINVAL*::
The requested _property_ is unknown.


== EXAMPLE
.Getting the ZAP authenticated user id for a message:
----
zmq_msg_t msg;
zmq_msg_init (&msg);
rc = zmq_msg_recv (&msg, dealer, 0);
assert (rc != -1);
const char *user_id = zmq_msg_gets (&msg, ZMQ_MSG_PROPERTY_USER_ID);
zmq_msg_close (&msg);
----


== SEE ALSO
* xref:zmq.adoc[zmq]
* xref:zmq_setsockopt.adoc[zmq_setsockopt]

== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Msg Init (`doc/zmq_msg_init.adoc`)

= zmq_msg_init(3)


== NAME
zmq_msg_init - initialise empty 0MQ message


== SYNOPSIS
*int zmq_msg_init (zmq_msg_t '*msg');*


== DESCRIPTION
The _zmq_msg_init()_ function shall initialise the message object referenced by
'msg' to represent an empty message.  This function is most useful when called
before receiving a message with _zmq_msg_recv()_.

CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.

CAUTION: The functions _zmq_msg_init()_, _zmq_msg_init_data()_,
_zmq_msg_init_size()_ and _zmq_msg_init_buffer()_ are mutually exclusive.
Never initialise the same 'zmq_msg_t' twice.


== RETURN VALUE
The _zmq_msg_init()_ function always returns zero.


== ERRORS
No errors are defined.


== EXAMPLE
.Receiving a message from a socket
----
zmq_msg_t msg;
rc = zmq_msg_init (&msg);
assert (rc == 0);
int nbytes = zmq_msg_recv (socket, &msg, 0);
assert (nbytes != -1);
----


== SEE ALSO
* xref:zmq_msg_init_size.adoc[zmq_msg_init_size]
* xref:zmq_msg_init_buffer.adoc[zmq_msg_init_buffer]
* xref:zmq_msg_init_data.adoc[zmq_msg_init_data]
* xref:zmq_msg_close.adoc[zmq_msg_close]
* xref:zmq_msg_data.adoc[zmq_msg_data]
* xref:zmq_msg_size.adoc[zmq_msg_size]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Msg Init Buffer (`doc/zmq_msg_init_buffer.adoc`)

= zmq_msg_init_buffer(3)


== NAME
zmq_msg_init_buffer - initialise 0MQ message with buffer copy


== SYNOPSIS
*int zmq_msg_init_buffer (zmq_msg_t '*msg', const void '*buf', size_t 'size');*


== DESCRIPTION
The _zmq_msg_init_buffer()_ function shall allocate any resources required to
store a message 'size' bytes long and initialise the message object referenced
by 'msg' to represent a copy of the buffer referenced by the 'buf' and
'size' arguments.

The implementation shall choose whether to store message content on the stack
(small messages) or on the heap (large messages).

CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.

CAUTION: The functions _zmq_msg_init()_, _zmq_msg_init_data()_,
_zmq_msg_init_buffer()_ and _zmq_msg_init_buffer()_ are mutually exclusive.
Never initialise the same 'zmq_msg_t' twice.


== RETURN VALUE
The _zmq_msg_init_buffer()_ function shall return zero if successful. Otherwise
it shall return `-1` and set 'errno' to one of the values defined below.


== ERRORS
*ENOMEM*::
Insufficient storage space is available.


== SEE ALSO
* xref:zmq_msg_init_data.adoc[zmq_msg_init_data]
* xref:zmq_msg_init_size.adoc[zmq_msg_init_size]
* xref:zmq_msg_init.adoc[zmq_msg_init]
* xref:zmq_msg_close.adoc[zmq_msg_close]
* xref:zmq_msg_data.adoc[zmq_msg_data]
* xref:zmq_msg_size.adoc[zmq_msg_size]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Msg Init Data (`doc/zmq_msg_init_data.adoc`)

= zmq_msg_init_data(3)


== NAME
zmq_msg_init_data - initialise 0MQ message from a supplied buffer


== SYNOPSIS
*typedef void (zmq_free_fn) (void '*data', void '*hint');*

*int zmq_msg_init_data (zmq_msg_t '*msg', void '*data', size_t 'size', zmq_free_fn '*ffn', void '*hint');*


== DESCRIPTION
The _zmq_msg_init_data()_ function shall initialise the message object
referenced by 'msg' to represent the content referenced by the buffer located
at address 'data', 'size' bytes long. No copy of 'data' shall be performed and
0MQ shall take ownership of the supplied buffer.

If provided, the deallocation function 'ffn' shall be called once the data
buffer is no longer required by 0MQ, with the 'data' and 'hint' arguments
supplied to _zmq_msg_init_data()_.

CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.

CAUTION: The deallocation function 'ffn' needs to be thread-safe, since it
will be called from an arbitrary thread.

CAUTION: If the deallocation function is not provided, the allocated memory
will not be freed, and this may cause a memory leak.


CAUTION: The functions _zmq_msg_init()_, _zmq_msg_init_data()_,
_zmq_msg_init_size()_ and _zmq_msg_init_buffer()_ are mutually exclusive.
Never initialise the same 'zmq_msg_t' twice.


== RETURN VALUE
The _zmq_msg_init_data()_ function shall return zero if successful. Otherwise
it shall return `-1` and set 'errno' to one of the values defined below.


== ERRORS
*ENOMEM*::
Insufficient storage space is available.



== EXAMPLE
.Initialising a message from a supplied buffer
----
void my_free (void *data, void *hint) 
{
    free (data);
}

    /*  ...  */

void *data = malloc (6);
assert (data);
memcpy (data, "ABCDEF", 6);
zmq_msg_t msg;
rc = zmq_msg_init_data (&msg, data, 6, my_free, NULL);
assert (rc == 0);
----


== SEE ALSO
* xref:zmq_msg_init_size.adoc[zmq_msg_init_size]
* xref:zmq_msg_init_buffer.adoc[zmq_msg_init_buffer]
* xref:zmq_msg_init.adoc[zmq_msg_init]
* xref:zmq_msg_close.adoc[zmq_msg_close]
* xref:zmq_msg_data.adoc[zmq_msg_data]
* xref:zmq_msg_size.adoc[zmq_msg_size]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Msg Init Size (`doc/zmq_msg_init_size.adoc`)

= zmq_msg_init_size(3)


== NAME
zmq_msg_init_size - initialise 0MQ message of a specified size


== SYNOPSIS
*int zmq_msg_init_size (zmq_msg_t '*msg', size_t 'size');*


== DESCRIPTION
The _zmq_msg_init_size()_ function shall allocate any resources required to
store a message 'size' bytes long and initialise the message object referenced
by 'msg' to represent the newly allocated message.

The implementation shall choose whether to store message content on the stack
(small messages) or on the heap (large messages). For performance reasons
_zmq_msg_init_size()_ shall not clear the message data.

CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.

CAUTION: The functions _zmq_msg_init()_, _zmq_msg_init_data()_,
_zmq_msg_init_size()_ and _zmq_msg_init_buffer()_ are mutually exclusive.
Never initialise the same 'zmq_msg_t' twice.


== RETURN VALUE
The _zmq_msg_init_size()_ function shall return zero if successful. Otherwise
it shall return `-1` and set 'errno' to one of the values defined below.


== ERRORS
*ENOMEM*::
Insufficient storage space is available.


== SEE ALSO
* xref:zmq_msg_init_data.adoc[zmq_msg_init_data]
* xref:zmq_msg_init_buffer.adoc[zmq_msg_init_buffer]
* xref:zmq_msg_init.adoc[zmq_msg_init]
* xref:zmq_msg_close.adoc[zmq_msg_close]
* xref:zmq_msg_data.adoc[zmq_msg_data]
* xref:zmq_msg_size.adoc[zmq_msg_size]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Msg More (`doc/zmq_msg_more.adoc`)

= zmq_msg_more(3)


== NAME
zmq_msg_more - indicate if there are more message parts to receive


== SYNOPSIS
*int zmq_msg_more (zmq_msg_t '*message');*


== DESCRIPTION
The _zmq_msg_more()_ function indicates whether this is part of a multi-part
message, and there are further parts to receive. This method can safely be
called after _zmq_msg_close()_. This method is identical to _zmq_msg_get()_
with an argument of ZMQ_MORE.


== RETURN VALUE
The _zmq_msg_more()_ function shall return zero if this is the final part of
a multi-part message, or the only part of a single-part message. It shall
return 1 if there are further parts to receive.


== EXAMPLE
.Receiving a multi-part message
----
zmq_msg_t part;
while (true) {
    //  Create an empty 0MQ message to hold the message part
    int rc = zmq_msg_init (&part);
    assert (rc == 0);
    //  Block until a message is available to be received from socket
    rc = zmq_msg_recv (socket, &part, 0);
    assert (rc != -1);
    if (zmq_msg_more (&part))
        fprintf (stderr, "more\n");
    else {
        fprintf (stderr, "end\n");
        break;
    }
    zmq_msg_close (&part);
}
----


== SEE ALSO
* xref:zmq_msg_get.adoc[zmq_msg_get]
* xref:zmq_msg_set.adoc[zmq_msg_set]
* xref:zmq_msg_init.adoc[zmq_msg_init]
* xref:zmq_msg_close.adoc[zmq_msg_close]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Msg Move (`doc/zmq_msg_move.adoc`)

= zmq_msg_move(3)


== NAME
zmq_msg_move - move content of a message to another message


== SYNOPSIS
*int zmq_msg_move (zmq_msg_t '*dest', zmq_msg_t '*src');*


== DESCRIPTION
The _zmq_msg_move()_ function shall move the content of the message object
referenced by 'src' to the message object referenced by 'dest'. No actual
copying of message content is performed, 'dest' is simply updated to reference
the new content. 'src' becomes an empty message after calling _zmq_msg_move()_.
The original content of 'dest', if any, shall be released.

CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.


== RETURN VALUE
The _zmq_msg_move()_ function shall return zero if successful. Otherwise it
shall return `-1` and set 'errno' to one of the values defined below.


== ERRORS
*EFAULT*::
Invalid message.


== SEE ALSO
* xref:zmq_msg_copy.adoc[zmq_msg_copy]
* xref:zmq_msg_init.adoc[zmq_msg_init]
* xref:zmq_msg_init_size.adoc[zmq_msg_init_size]
* xref:zmq_msg_init_buffer.adoc[zmq_msg_init_buffer]
* xref:zmq_msg_init_data.adoc[zmq_msg_init_data]
* xref:zmq_msg_close.adoc[zmq_msg_close]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Msg Recv (`doc/zmq_msg_recv.adoc`)

= zmq_msg_recv(3)


== NAME
zmq_msg_recv - receive a message part from a socket


== SYNOPSIS
*int zmq_msg_recv (zmq_msg_t '*msg', void '*socket', int 'flags');*


== DESCRIPTION
The _zmq_msg_recv()_ function is identical to xref:zmq_recvmsg.adoc[zmq_recvmsg], which
shall be deprecated in future versions. _zmq_msg_recv()_ is more consistent
with other message manipulation functions.

The _zmq_msg_recv()_ function shall receive a message part from the socket
referenced by the 'socket' argument and store it in the message referenced by
the 'msg' argument. Any content previously stored in 'msg' shall be properly
deallocated. If there are no message parts available on the specified 'socket'
the _zmq_msg_recv()_ function shall block until the request can be satisfied.
The 'flags' argument is a combination of the flags defined below:

*ZMQ_DONTWAIT*::
Specifies that the operation should be performed in non-blocking mode. If there
are no messages available on the specified 'socket', the _zmq_msg_recv()_
function shall fail with 'errno' set to EAGAIN.


Multi-part messages
~~~~~~~~~~~~~~~~~~~
A 0MQ message is composed of 1 or more message parts. Each message
part is an independent 'zmq_msg_t' in its own right. 0MQ ensures atomic
delivery of messages: peers shall receive either all _message parts_ of a
message or none at all. The total number of message parts is unlimited except
by available memory.

An application that processes multi-part messages must use the _ZMQ_RCVMORE_
xref:zmq_getsockopt.adoc[zmq_getsockopt] option after calling _zmq_msg_recv()_ to determine if
there are further parts to receive.


== RETURN VALUE
The _zmq_msg_recv()_ function shall return number of bytes in the message
if successful. Otherwise it shall return `-1` and set 'errno' to one of the
values defined below.


== ERRORS
*EAGAIN*::
Either the timeout set via the socket-option ZMQ_RCVTIMEO (see xref:zmq_setsockopt.adoc[zmq_setsockopt])
has been reached (flag ZMQ_DONTWAIT not set) without being able to read a message
from the socket or there are no messages available at the moment (flag ZMQ_DONTWAIT set)
and the operation would block.
*ENOTSUP*::
The _zmq_msg_recv()_ operation is not supported by this socket type.
*EFSM*::
The _zmq_msg_recv()_ operation cannot be performed on this socket at the moment
due to the socket not being in the appropriate state.  This error may occur with
socket types that switch between several states, such as ZMQ_REP.  See the
_messaging patterns_ section of xref:zmq_socket.adoc[zmq_socket] for more information.
*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 before a message was
available.
*EFAULT*::
The message passed to the function was invalid.


== EXAMPLE
.Receiving a message from a socket
----
/* Create an empty 0MQ message */
zmq_msg_t msg;
int rc = zmq_msg_init (&msg);
assert (rc == 0);
/* Block until a message is available to be received from socket */
rc = zmq_msg_recv (&msg, socket, 0);
assert (rc != -1);
/* Release message */
zmq_msg_close (&msg);
----

.Receiving a multi-part message
----
int more;
size_t more_size = sizeof (more);
do {
    /* Create an empty 0MQ message to hold the message part */
    zmq_msg_t part;
    int rc = zmq_msg_init (&part);
    assert (rc == 0);
    /* Block until a message is available to be received from socket */
    rc = zmq_msg_recv (&part, socket, 0);
    assert (rc != -1);
    /* Determine if more message parts are to follow */
    rc = zmq_getsockopt (socket, ZMQ_RCVMORE, &more, &more_size);
    assert (rc == 0);
    zmq_msg_close (&part);
} while (more);
----


== SEE ALSO
* xref:zmq_recv.adoc[zmq_recv]
* xref:zmq_send.adoc[zmq_send]
* xref:zmq_msg_send.adoc[zmq_msg_send]
* xref:zmq_getsockopt.adoc[zmq_getsockopt]
* xref:zmq_setsockopt.adoc[zmq_setsockopt]
* xref:zmq_socket.adoc[zmq_socket]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Msg Routing Id (`doc/zmq_msg_routing_id.adoc`)

= zmq_msg_routing_id(3)


== NAME
zmq_msg_routing_id - return routing ID for message, if any


== SYNOPSIS
*uint32_t zmq_msg_routing_id (zmq_msg_t '*message');*


== DESCRIPTION
The _zmq_msg_routing_id()_ function returns the routing ID for the message,
if any. The routing ID is set on all messages received from a 'ZMQ_SERVER'
socket. To send a message to a 'ZMQ_SERVER' socket you must set the routing
ID of a connected 'ZMQ_CLIENT' peer. Routing IDs are transient.


== RETURN VALUE
The _zmq_msg_routing_id()_ function shall return zero if there is no routing
ID, otherwise it shall return an unsigned 32-bit integer greater than zero.


== EXAMPLE
.Receiving a client message and routing ID
----
void *ctx = zmq_ctx_new ();
assert (ctx);

void *server = zmq_socket (ctx, ZMQ_SERVER);
assert (server);
int rc = zmq_bind (server, "tcp://127.0.0.1:8080");
assert (rc == 0);

zmq_msg_t message;
rc = zmq_msg_init (&message);
assert (rc == 0);

//  Receive a message from socket
rc = zmq_msg_recv (server, &message, 0);
assert (rc != -1);
uint32_t routing_id = zmq_msg_routing_id (&message);
assert (routing_id);
----


== SEE ALSO
* xref:zmq_msg_set_routing_id.adoc[zmq_msg_set_routing_id]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Msg Send (`doc/zmq_msg_send.adoc`)

= zmq_msg_send(3)


== NAME
zmq_msg_send - send a message part on a socket


== SYNOPSIS
*int zmq_msg_send (zmq_msg_t '*msg', void '*socket', int 'flags');*


== DESCRIPTION
The _zmq_msg_send()_ function is identical to xref:zmq_sendmsg.adoc[zmq_sendmsg], which
shall be deprecated in future versions. _zmq_msg_send()_ is more consistent
with other message manipulation functions.

The _zmq_msg_send()_ function shall queue the message referenced by the 'msg'
argument to be sent to the socket referenced by the 'socket' argument.  The
'flags' argument is a combination of the flags defined below:

*ZMQ_DONTWAIT*::
For socket types (DEALER, PUSH) that block (either with ZMQ_IMMEDIATE option set
and no peer available, or all peers having full high-water mark), specifies that
the operation should be performed in non-blocking mode. If the message cannot be
queued on the 'socket', the _zmq_msg_send()_ function shall fail with 'errno' set
to EAGAIN.

*ZMQ_SNDMORE*::
Specifies that the message being sent is a multi-part message, and that further
message parts are to follow. Refer to the section regarding multi-part messages
below for a detailed description.

The _zmq_msg_t_ structure passed to _zmq_msg_send()_ is nullified on a
successful call. If you want to send the same message to multiple sockets you
have to copy it (e.g. using _zmq_msg_copy()_). If the call fails, the
_zmq_msg_t_ structure stays intact, and must be consumed by another call to
_zmq_msg_send()_ on the same or another socket, or released using
_zmq_msg_close()_ to avoid a memory leak.

NOTE: A successful invocation of _zmq_msg_send()_ does not indicate that the
message has been transmitted to the network, only that it has been queued on
the 'socket' and 0MQ has assumed responsibility for the message. You do not need
to call _zmq_msg_close()_ after a successful _zmq_msg_send()_.


Multi-part messages
~~~~~~~~~~~~~~~~~~~
A 0MQ message is composed of 1 or more message parts. Each message
part is an independent 'zmq_msg_t' in its own right. 0MQ ensures atomic
delivery of messages: peers shall receive either all _message parts_ of a
message or none at all. The total number of message parts is unlimited except
by available memory.

An application that sends multi-part messages must use the _ZMQ_SNDMORE_ flag
when sending each message part except the final one.

== RETURN VALUE
The _zmq_msg_send()_ function shall return number of bytes in the message
if successful (if number of bytes is higher than 'MAX_INT', the function will
return 'MAX_INT'). Otherwise it shall return `-1` and set 'errno' to one of the
values defined below.


== ERRORS
*EAGAIN*::
Non-blocking mode was requested and the message cannot be sent at the moment.
*ENOTSUP*::
The _zmq_msg_send()_ operation is not supported by this socket type.
*EINVAL*::
The sender tried to send multipart data, which the socket type does not allow.
*EFSM*::
The _zmq_msg_send()_ operation cannot be performed on this socket at the moment
due to the socket not being in the appropriate state.  This error may occur with
socket types that switch between several states, such as ZMQ_REP.  See the
_messaging patterns_ section of xref:zmq_socket.adoc[zmq_socket] for more information.
*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 before the message was
sent.
*EFAULT*::
Invalid message.
*EHOSTUNREACH*::
The message cannot be routed.


== EXAMPLE
.Filling in a message and sending it to a socket
----
/* Create a new message, allocating 6 bytes for message content */
zmq_msg_t msg;
int rc = zmq_msg_init_size (&msg, 6);
assert (rc == 0);
/* Fill in message content with 'AAAAAA' */
memset (zmq_msg_data (&msg), 'A', 6);
/* Send the message to the socket */
rc = zmq_msg_send (&msg, socket, 0);
assert (rc == 6);
----

.Sending a multi-part message
----
/* Send a multi-part message consisting of three parts to socket */
rc = zmq_msg_send (&part1, socket, ZMQ_SNDMORE);
rc = zmq_msg_send (&part2, socket, ZMQ_SNDMORE);
/* Final part; no more parts to follow */
rc = zmq_msg_send (&part3, socket, 0);
----


== SEE ALSO
* xref:zmq_recv.adoc[zmq_recv]
* xref:zmq_send.adoc[zmq_send]
* xref:zmq_msg_recv.adoc[zmq_msg_recv]
* xref:zmq_socket.adoc[zmq_socket]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Msg Set (`doc/zmq_msg_set.adoc`)

= zmq_msg_set(3)


== NAME

zmq_msg_set - set message property


== SYNOPSIS
*int zmq_msg_set (zmq_msg_t '*message', int 'property', int 'value');*


== DESCRIPTION
The _zmq_msg_set()_ function shall set the property specified by the
'property' argument to the value of the 'value' argument for the 0MQ
message fragment pointed to by the 'message' argument.

Currently the _zmq_msg_set()_ function does not support any property names.


== RETURN VALUE
The _zmq_msg_set()_ 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 property _property_ is unknown.


== SEE ALSO
* xref:zmq_msg_get.adoc[zmq_msg_get]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Msg Set Routing Id (`doc/zmq_msg_set_routing_id.adoc`)

= zmq_msg_set_routing_id(3)


== NAME

zmq_msg_set_routing_id - set routing ID property on message


== SYNOPSIS
*int zmq_msg_set_routing_id (zmq_msg_t '*message', uint32_t 'routing_id');*


== DESCRIPTION
The _zmq_msg_set_routing_id()_ function sets the 'routing_id' specified, on the
the message pointed to by the 'message' argument. The 'routing_id' must be
greater than zero. To get a valid routing ID, you must receive a message
from a 'ZMQ_SERVER' socket, and use the libzmq:zmq_msg_routing_id method.
Routing IDs are transient.


== RETURN VALUE
The _zmq_msg_set_routing_id()_ function shall return zero if successful. Otherwise it
shall return `-1` and set 'errno' to one of the values defined below.


== ERRORS
*EINVAL*::
The provided 'routing_id' is zero.


== SEE ALSO
* xref:zmq_msg_routing_id.adoc[zmq_msg_routing_id]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Msg Size (`doc/zmq_msg_size.adoc`)

= zmq_msg_size(3)


== NAME
zmq_msg_size - retrieve message content size in bytes


== SYNOPSIS
*size_t zmq_msg_size (zmq_msg_t '*msg');*


== DESCRIPTION
The _zmq_msg_size()_ function shall return the size in bytes of the content of
the message object referenced by 'msg'.

CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.


== RETURN VALUE
Upon successful completion, _zmq_msg_size()_ shall return the size of the
message content in bytes.


== ERRORS
No errors are defined.


== SEE ALSO
* xref:zmq_msg_data.adoc[zmq_msg_data]
* xref:zmq_msg_init.adoc[zmq_msg_init]
* xref:zmq_msg_init_size.adoc[zmq_msg_init_size]
* xref:zmq_msg_init_buffer.adoc[zmq_msg_init_buffer]
* xref:zmq_msg_init_data.adoc[zmq_msg_init_data]
* xref:zmq_msg_close.adoc[zmq_msg_close]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Null (`doc/zmq_null.adoc`)

= zmq_null(7)


== NAME
zmq_null - no security or confidentiality


== SYNOPSIS
The NULL mechanism is defined by the ZMTP 3.0 specification: 
<http://rfc.zeromq.org/spec:23>. This is the default security mechanism
for ZeroMQ sockets.


== SEE ALSO
* xref:zmq_plain.adoc[zmq_plain]
* xref:zmq_curve.adoc[zmq_curve]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Pgm (`doc/zmq_pgm.adoc`)

= zmq_pgm(7)


== NAME
zmq_pgm - 0MQ reliable multicast transport using PGM


== SYNOPSIS
PGM (Pragmatic General Multicast) is a protocol for reliable multicast
transport of data over IP networks.


== DESCRIPTION
0MQ implements two variants of PGM, the standard protocol where PGM datagrams
are layered directly on top of IP datagrams as defined by RFC 3208 (the 'pgm'
transport) and "Encapsulated PGM" or EPGM where PGM datagrams are encapsulated
inside UDP datagrams (the 'epgm' transport).

The 'pgm' and 'epgm' transports can only be used with the 'ZMQ_PUB' and
'ZMQ_SUB' socket types.

Further, PGM sockets are rate limited by default. For details, refer to the
'ZMQ_RATE', and 'ZMQ_RECOVERY_IVL' options documented in
xref:zmq_setsockopt.adoc[zmq_setsockopt]

CAUTION: The 'pgm' transport implementation requires access to raw IP sockets.
Additional privileges may be required on some operating systems for this
operation. Applications not requiring direct interoperability with other PGM
implementations are encouraged to use the 'epgm' transport instead which does
not require any special privileges.


== ADDRESSING
A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.

For the PGM transport, the transport is `pgm`, and for the EPGM protocol the
transport is `epgm`. The meaning of the 'address' part is defined below.


Connecting a socket
~~~~~~~~~~~~~~~~~~~
When connecting a socket to a peer address using _zmq_connect()_ with the 'pgm'
or 'epgm' transport, the 'endpoint' shall be interpreted as an 'interface'
followed by a semicolon, followed by a 'multicast address', followed by a colon
and a port number.

An 'interface' may be specified by either of the following:

* The interface name as defined by the operating system.
* The primary IPv4 address assigned to the interface, in its numeric
  representation.

NOTE: Interface names are not standardised in any way and should be assumed to
be arbitrary and platform dependent. On Win32 platforms no short interface
names exist, thus only the primary IPv4 address may be used to specify an
'interface'. The 'interface' part can be omitted, in that case the default one
will be selected.

A 'multicast address' is specified by an IPv4 multicast address in its numeric
representation.


== WIRE FORMAT
Consecutive PGM datagrams are interpreted by 0MQ as a single continuous stream
of data where 0MQ messages are not necessarily aligned with PGM datagram
boundaries and a single 0MQ message may span several PGM datagrams. This stream
of data consists of 0MQ messages encapsulated in 'frames' as described in
xref:zmq_tcp.adoc[zmq_tcp]


PGM datagram payload
~~~~~~~~~~~~~~~~~~~~
The following ABNF grammar represents the payload of a single PGM datagram as
used by 0MQ:

....
datagram               = (offset data)
offset                 = 2OCTET
data                   = *OCTET
....

In order for late joining consumers to be able to identify message boundaries,
each PGM datagram payload starts with a 16-bit unsigned integer in network byte
order specifying either the offset of the first message 'frame' in the datagram
or containing the value `0xFFFF` if the datagram contains solely an
intermediate part of a larger message.

Note that offset specifies where the first message begins rather than the first
message part. Thus, if there are trailing message parts at the beginning of
the packet the offset ignores them and points to first initial message part
in the packet.

The following diagram illustrates the layout of a single PGM datagram payload:

....
+------------------+----------------------+
| offset (16 bits) |         data         |
+------------------+----------------------+
....

The following diagram further illustrates how three example 0MQ frames are laid
out in consecutive PGM datagram payloads:

....
First datagram payload
+--------------+-------------+---------------------+
| Frame offset |   Frame 1   |   Frame 2, part 1   |
|    0x0000    | (Message 1) | (Message 2, part 1) |
+--------------+-------------+---------------------+

Second datagram payload
+--------------+---------------------+
| Frame offset |   Frame 2, part 2   |
| 0xFFFF       | (Message 2, part 2) |
+--------------+---------------------+

Third datagram payload
+--------------+----------------------------+-------------+
| Frame offset |   Frame 2, final 8 bytes   |   Frame 3   |
| 0x0008       | (Message 2, final 8 bytes) | (Message 3) |
+--------------+----------------------------+-------------+
....


== CONFIGURATION

The PGM is protocol is capable of multicasting data at high rates (500Mbps+)
with large messages (1MB+), however it requires setting the relevant ZMQ socket
options that are documented in xref:zmq_setsockopt.adoc[zmq_setsockopt]:

* The 'ZMQ_RATE' should be set sufficiently high, e.g. 1Gbps
* The 'ZMQ_RCVBUF' should be increased on the subscriber, e.g. 4MB
* The 'ZMQ_SNDBUF' should be increased on the publisher, e.g. 4MB

It's important to note that the 'ZMQ_RCVBUF' and 'ZMQ_SNDBUF' options are
limited by the underlying host OS tx/rx buffer size limit. On linux, these can
be increased for the current session with the following commands:

....
# set tx/rx buffers to 4MB (default can also be read as the initial buffer size)
sudo sysctl -w net.core.rmem_max=4194304
sudo sysctl -w net.core.wmem_max=4194304
sudo sysctl -w net.core.rmem_default=4194304
sudo sysctl -w net.core.wmem_default=4194304
....


== EXAMPLE
.Connecting a socket
----
//  Connecting to the multicast address 239.192.1.1, port 5555,
//  using the first Ethernet network interface on Linux
//  and the Encapsulated PGM protocol
rc = zmq_connect(socket, "epgm://eth0;239.192.1.1:5555");
assert (rc == 0);
//  Connecting to the multicast address 239.192.1.1, port 5555,
//  using the network interface with the address 192.168.1.1
//  and the standard PGM protocol
rc = zmq_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555");
assert (rc == 0);
----


== SEE ALSO
* xref:zmq_connect.adoc[zmq_connect]
* xref:zmq_setsockopt.adoc[zmq_setsockopt]
* xref:zmq_tcp.adoc[zmq_tcp]
* xref:zmq_ipc.adoc[zmq_ipc]
* xref:zmq_inproc.adoc[zmq_inproc]
* xref:zmq_vmci.adoc[zmq_vmci]
* xref:zmq_vsock.adoc[zmq_vsock]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Plain (`doc/zmq_plain.adoc`)

= zmq_plain(7)


== NAME
zmq_plain - clear-text authentication


== SYNOPSIS
The PLAIN mechanism defines a simple username/password mechanism that 
lets a server authenticate a client. PLAIN makes no attempt at security 
or confidentiality. It is intended for use on internal networks where 
security requirements are low. The PLAIN mechanism is defined by this 
document: <http://rfc.zeromq.org/spec:24>.


== USAGE
To use PLAIN, the server shall set the ZMQ_PLAIN_SERVER option, and the 
client shall set the ZMQ_PLAIN_USERNAME and ZMQ_PLAIN_PASSWORD socket 
options. Which peer binds, and which connects, is not relevant.


== SEE ALSO
* xref:zmq_setsockopt.adoc[zmq_setsockopt]
* xref:zmq_null.adoc[zmq_null]
* xref:zmq_curve.adoc[zmq_curve]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Poll (`doc/zmq_poll.adoc`)

= zmq_poll(3)


== NAME
zmq_poll - input/output multiplexing


== SYNOPSIS

*int zmq_poll (zmq_pollitem_t '*items', int 'nitems', long 'timeout');*


== DESCRIPTION
The _zmq_poll()_ function provides a mechanism for applications to multiplex
input/output events in a level-triggered fashion over a set of sockets. Each
member of the array pointed to by the 'items' argument is a *zmq_pollitem_t*
structure. The 'nitems' argument specifies the number of items in the 'items'
array. The *zmq_pollitem_t* structure is defined as follows:

["literal", subs="quotes"]
typedef struct
{
    void '*socket';
    zmq_fd_t 'fd';
    short 'events';
    short 'revents';
} zmq_pollitem_t;

For each *zmq_pollitem_t* item, _zmq_poll()_ shall examine either the 0MQ
socket referenced by 'socket' *or* the standard socket specified by the file
descriptor 'fd', for the event(s) specified in 'events'. If both 'socket' and
'fd' are set in a single *zmq_pollitem_t*, the 0MQ socket referenced by
'socket' shall take precedence and the value of 'fd' shall be ignored.

For each *zmq_pollitem_t* item, _zmq_poll()_ shall first clear the 'revents'
member, and then indicate any requested events that have occurred by setting the
bit corresponding to the event condition in the 'revents' member.

If none of the requested events have occurred on any *zmq_pollitem_t* item,
_zmq_poll()_ shall wait 'timeout' milliseconds for an event to occur on
any of the requested items. If the value of 'timeout' is `0`, _zmq_poll()_
shall return immediately. If the value of 'timeout' is `-1`, _zmq_poll()_ shall
block indefinitely until a requested event has occurred on at least one
*zmq_pollitem_t*.

The 'events' and 'revents' members of *zmq_pollitem_t* are bit masks constructed
by OR'ing a combination of the following event flags:

*ZMQ_POLLIN*::
For 0MQ sockets, at least one message may be received from the 'socket' without
blocking. For standard sockets this is equivalent to the 'POLLIN' flag of the
_poll()_ system call and generally means that at least one byte of data may be
read from 'fd' without blocking.

*ZMQ_POLLOUT*::
For 0MQ sockets, at least one message may be sent to the 'socket' without
blocking. For standard sockets this is equivalent to the 'POLLOUT' flag of the
_poll()_ system call and generally means that at least one byte of data may be
written to 'fd' without blocking.

*ZMQ_POLLERR*::
For standard sockets, this flag is passed through _zmq_poll()_ to the
underlying _poll()_ system call and generally means that some sort of error
condition is present on the socket specified by 'fd'. For 0MQ sockets this flag
has no effect if set in 'events', and shall never be returned in 'revents' by
_zmq_poll()_.

*ZMQ_POLLPRI*::
For 0MQ sockets this flags is of no use. For standard sockets this means there
is urgent data to read. Refer to the POLLPRI flag for more information.
For file descriptor, refer to your use case: as an example, GPIO interrupts
are signaled through a POLLPRI event.
This flag has no effect on Windows.

NOTE: The _zmq_poll()_ function may be implemented or emulated using operating
system interfaces other than _poll()_, and as such may be subject to the limits
of those interfaces in ways not defined in this documentation.

== THREAD SAFETY
The *zmq_pollitem_t* array must only be used by the thread which 
will/is calling _zmq_poll_.

If a socket is contained in multiple *zmq_pollitem_t* arrays, each owned by a
different thread, the socket itself needs to be thread-safe (Server, Client, ...).
Otherwise, behaviour is undefined.


== RETURN VALUE
Upon successful completion, the _zmq_poll()_ function shall return the number
of *zmq_pollitem_t* structures with events signaled in 'revents' or `0` if no
events have been signaled. Upon failure, _zmq_poll()_ shall return `-1` and set
'errno' to one of the values defined below.


== ERRORS
*ETERM*::
At least one of the members of the 'items' array refers to a 'socket' whose
associated 0MQ 'context' was terminated.
*EFAULT*::
The provided 'items' was not valid (NULL).
*EINTR*::
The operation was interrupted by delivery of a signal before any events were
available.


== EXAMPLE
.Polling indefinitely for input events on both a 0MQ socket and a standard socket.
----
zmq_pollitem_t items [2];
/* First item refers to 0MQ socket 'socket' */
items[0].socket = socket;
items[0].events = ZMQ_POLLIN;
/* Second item refers to standard socket 'fd' */
items[1].socket = NULL;
items[1].fd = fd;
items[1].events = ZMQ_POLLIN;
/* Poll for events indefinitely */
int rc = zmq_poll (items, 2, -1);
assert (rc >= 0);
/* Returned events will be stored in items[].revents */
----


== SEE ALSO
* xref:zmq_socket.adoc[zmq_socket]
* xref:zmq_send.adoc[zmq_send]
* xref:zmq_recv.adoc[zmq_recv]
* xref:zmq.adoc[zmq]

Your operating system documentation for the _poll()_ system call.


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Poller (`doc/zmq_poller.adoc`)

= zmq_poller(3)


== NAME
zmq_poller - input/output multiplexing


== SYNOPSIS

*void *zmq_poller_new (void);*

*int zmq_poller_destroy (void '****poller_p');*

*int zmq_poller_size (void '*poller');*

*int zmq_poller_add (void '*poller', void '*socket', void '*user_data', short 'events');*

*int zmq_poller_modify (void '*poller', void '*socket', short 'events');*

*int zmq_poller_remove (void '*poller', void '*socket');*

*int zmq_poller_add_fd (void '*poller', int 'fd', void '*user_data', short 'events');*

*int zmq_poller_modify_fd (void '*poller', int 'fd', short 'events');*

*int zmq_poller_remove_fd (void '*poller', int 'fd');*

*int zmq_poller_wait (void '*poller',
                          zmq_poller_event_t '*event',
                          long 'timeout');*

*int zmq_poller_wait_all (void '*poller',
                          zmq_poller_event_t '*events',
                          int 'n_events',
                          long 'timeout');*

*int zmq_poller_fd (void '*poller', zmq_fd_t '*fd');*

== DESCRIPTION
The _zmq_poller_*_ functions provide a mechanism for applications to multiplex
input/output events in a level-triggered fashion over a set of sockets.

_zmq_poller_new_ and _zmq_poller_destroy_ manage the lifetime of a poller
instance. _zmq_poller_new_ creates and returns a new poller instance, while
_zmq_poller_destroy_ destroys it. A pointer to a valid poller must be passed
as the _poller_p_ argument of _zmq_poller_destroy_. In particular,
_zmq_poller_destroy_ may not be called multiple times for the same poller
instance. _zmq_poller_destroy_ sets the passed pointer to NULL in case of a
successful execution. _zmq_poller_destroy_ implicitly unregisters all
registered sockets and file descriptors.

_zmq_poller_size_ queries the number of sockets or file descriptors registered
with a poller. The initial size of a poller is 0, a successful add operation
increases the size by 1 and a successful remove operation decreases the size
by 1. The size is unaffected by the events specified.

_zmq_poller_add_, _zmq_poller_modify_ and _zmq_poller_remove_ manage the 0MQ
sockets registered with a poller.

_zmq_poller_add_ registers a new _socket_ with a given _poller_. Both _poller_
and _socket_ must point to valid 0MQ objects. The _events_ parameter specifies
which event types the client wants to subscribe to. It is legal to specify no
events (i.e. 0), and activate them later with _zmq_poller_modify_.
In addition, _user_data_ may be specified, which is not used by the poller, but
passed back to the caller when an event was signalled in a call to
_zmq_poller_wait_ or _zmq_poller_wait_all_. _user_data_ may be NULL. If it is
not NULL, it must be a valid pointer. Otherwise, behaviour is undefined.
You must only add a socket to a single poller instance once (unless 
_zmq_poller_remove_ has been called for that socket before). You may
add a socket to multiple poller instances, if the socket itself
is explicitly thread-safe (Server, Client, ...). If the socket is not,
you may invoke undefined behavior.

_zmq_poller_modify_ modifies the subscribed events for a socket. It is
legal to specify no events (i.e. 0) to disable events temporarily, and
reactivate them later with another call to _zmq_poller_modify_.

_zmq_poller_remove_ removes a socket registration completely.
_zmq_poller_remove_ must be called before a socket is closed with _zmq_close_.

Note that it is not necessary to call _zmq_poller_remove_ for any socket
before calling _zmq_poller_destroy_.

Also note that calling _zmq_poller_remove_ is not equivalent to calling
_zmq_poller_modify_ with no events. _zmq_poller_modify_ does not free resources
associated with the socket registration, and requires that the _socket_
remains valid.

_zmq_poller_add_fd_, _zmq_poller_modify_fd_ and _zmq_poller_remove_fd_ are
analogous to the previous functions but manage regular file descriptors
registered with a poller. On Windows, these functions can only be used with
WinSock sockets.

In the following, 0MQ sockets added with _zmq_poller_add_ and file descriptors
added with _zmq_poller_add_fd_ are referred to as 'registered objects'.

The *zmq_poller_event_t* structure is defined as follows:

["literal", subs="quotes"]
typedef struct
{
    void *socket;
    zmq_fd_t fd;
    void *user_data;
    short events;
} zmq_poller_event_t;

For each registered object, _zmq_poller_wait_all()_ shall examine the
registered objects for the event(s) currently registered.

If none of the registered events have occurred, _zmq_poller_wait_all_ shall 
wait 'timeout' milliseconds for an event to occur on any of the registered 
objects. If the value of 'timeout' is `0`, _zmq_poller_wait_all_ shall 
return immediately. If the value of 'timeout' is `-1`, _zmq_poller_wait_all_ 
shall block indefinitely until one event has occurred on any of the 
registered objects.

The 'events' argument _zmq_poller_wait_all_ must be a pointer to an array of
at least 'n_events' elements. Behaviour is undefined if 'events' does not point
to an array of at least 'n_events' elements.

_zmq_poller_wait_all_ returns at most 'n_events' events. If more than
'n_events' events were signalled, only an unspecified subset of the signalled 
events is returned through 'events'. 

A caller is advised to ensure that 'n_events' is equal to the number of 
registered objects. Otherwise, a livelock situation may result: If more than 
'n_events' registered objects have an active event on each call to 
_zmq_poller_wait_all_, it might happen that the same subset of registered 
objects is always returned, and the caller never notices the events on the 
others. The number of objects registered can be queried with
_zmq_poller_size_.

_zmq_poller_wait_all_ returns the number of valid elements. The valid elements
are placed in positions '0' to 'n_events - 1' in the 'events' array. All
members of a valid element are set to valid values by _zmq_poller_wait_all_.
For socket events 'socket' is non-null and 'fd' is an operating system
specific value for an invalid socket (-1 or INVALID_SOCKET). For fd events
'socket' is NULL and 'fd' is a valid file descriptor.
The client does therefore not need to initialize the contents of the events
array before a call to _zmq_poller_wait_all_. It is unspecified whether the
the remaining elements of 'events' are written to by _zmq_poller_wait_all_.

_zmq_poller_fd_ queries the file descriptor associated with the zmq_poller,
and stores it in the address pointer to by 'fd'.
The zmq_poller is only guaranteed to have a file descriptor if
at least one thread-safe socket is currently registered.

Note that closing a socket that is registered in a poller leads to undefined
behavior. The socket must be unregistered first.

== EVENT TYPES

The 'events' parameter of _zmq_poller_add_ and _zmq_poller_modify_, and the
'events' member of the zmq_poller_event_t structure are bit masks constructed
by OR'ing a combination of the following event flags:

*ZMQ_POLLIN*::
For 0MQ sockets, at least one message may be received from the 'socket' without
blocking. For standard sockets this is equivalent to the 'POLLIN' flag of the
_poll()_ system call and generally means that at least one byte of data may be
read from 'fd' without blocking.

*ZMQ_POLLOUT*::
For 0MQ sockets, at least one message may be sent to the 'socket' without
blocking. For standard sockets this is equivalent to the 'POLLOUT' flag of the
_poll()_ system call and generally means that at least one byte of data may be
written to 'fd' without blocking.

*ZMQ_POLLERR*::
For 0MQ sockets this flag has no effect on the _zmq_poller_add_ and
_zmq_poller_modify_ functions, and is never set in the
'events' member of the zmq_poller_event_t structure.
For standard sockets, this flag is passed through _zmq_poller_wait_all_ to the
underlying _poll()_ system call and generally means that some sort of error
condition is present on the socket specified by 'fd'.

*ZMQ_POLLPRI*::
For 0MQ sockets this flag has no effect on the _zmq_poller_add_ and
_zmq_poller_modify_ functions, and is never set in the
'events' member of the zmq_poller_event_t structure.
For standard sockets this means there
is urgent data to read. Refer to the POLLPRI flag for more information.
For a file descriptor, refer to your OS documentation: as an example, GPIO
interrupts are signaled through a POLLPRI event.
This flag has no effect on Windows.

NOTE: The _zmq_poller_*_ functions may be implemented or emulated using operating
system interfaces other than _poll()_, and as such may be subject to the limits
of those interfaces in ways not defined in this documentation.

== THREAD SAFETY
Like most other 0MQ objects, a poller is not thread-safe. All operations must
be called from the same thread. Otherwise, behaviour is undefined.

In addition to that, if you want to add a socket to multiple existing poller
instances, the socket itself needs to be thread-safe (Server, Client, ...).
Otherwise, behaviour is undefined. 

== RETURN VALUE
_zmq_poller_new_ returns a valid pointer to a poller, or NULL in case of a failure.

All functions that return an int, return -1 in case of a failure. In that case,
zmq_errno() can be used to query the type of the error as described below.

_zmq_poller_wait_all_ returns the number of events signalled and returned in 
the events array. It never returns 0.

All other functions return 0 in case of a successful execution.

== ERRORS
On _zmq_poller_new_:

*ENOMEM*::
A new poller could not be allocated successfully.

On _zmq_poller_destroy_:

*EFAULT*::
_poller_p_ did not point to a valid poller. Note that passing an invalid pointer (e.g.
pointer to deallocated memory) may cause undefined behaviour (e.g. an access violation).

On _zmq_poller_size_:

*EFAULT*::
_poller_ did not point to a valid poller. Note that passing an
invalid pointer (e.g. pointer to deallocated memory) may cause undefined
behaviour (e.g. an access violation).

On _zmq_poller_add_, _zmq_poller_modify_ and _zmq_poller_remove_:

*EFAULT*::
_poller_ did not point to a valid poller. Note that passing an
invalid pointer (e.g. pointer to deallocated memory) may cause undefined
behaviour (e.g. an access violation).
*ENOTSOCK*::
_socket_ did not point to a valid socket. Note that passing an
invalid pointer (e.g. pointer to deallocated memory) may cause undefined
behaviour (e.g. an access violation).

On _zmq_poller_add_:

*EMFILE*::
TODO

On _zmq_poller_add_ or _zmq_poller_add_fd_:

*ENOMEM*::
Necessary resources could not be allocated.
*EINVAL*::
_socket_ resp. _fd_ was already registered with the poller.

On _zmq_poller_modify_, _zmq_poller_modify_fd_, _zmq_poller_remove_ or
_zmq_poller_remove_fd_:

*EINVAL*::
_socket_ resp. _fd_ was not registered with the poller.

On _zmq_poller_add_fd_, _zmq_poller_modify_fd_ and _zmq_poller_remove_fd_:

*EBADF*::
The _fd_ specified was the retired fd.

On _zmq_poller_wait_ and _zmq_poller_wait_all_:

*ENOMEM*::
Necessary resources could not be allocated.
*ETERM*::
At least one of the registered objects is a 'socket' whose associated 0MQ 
'context' was terminated.
*EFAULT*::
The provided 'events' was NULL, or 'poller' did not point to a valid poller,
or there are no registered objects or all event subscriptions are disabled
and 'timeout' was negative.
*EINTR*::
The operation was interrupted by delivery of a signal before any events were
available.
*EAGAIN*::
No registered event was signalled before the timeout was reached.

On _zmq_poller_fd_:

*EINVAL*::
The poller has no associated file descriptor.
*EFAULT*::
The provided 'poller' did not point to a valid poller.

== EXAMPLE
.Polling indefinitely for input events on both a 0MQ socket and a standard socket.
----
void *poller = zmq_poller_new ();

/* First item refers to 0MQ socket 'socket' */
zmq_poller_add (poller, socket, NULL, ZMQ_POLLIN);
/* Second item refers to standard socket 'fd' */
zmq_poller_add_fd (poller, fd, NULL, ZMQ_POLLIN);

zmq_poller_event_t events [2];
/* Poll for events indefinitely */
int rc = zmq_poller_wait_all (poller, events, 2, -1);
assert (rc >= 0);
/* Returned events will be stored in 'events' */
for (int i = 0; i < 2; ++i) {
    if (events[i].socket == socket && events[i].events & ZMQ_POLLIN) {
        // ...
    } else if (events[i].fd == fd && events[i].events & ZMQ_POLLIN)) {
        // ...
    }
}
zmq_poller_destroy (&poller);
----


== SEE ALSO
* xref:zmq_socket.adoc[zmq_socket]
* xref:zmq_send.adoc[zmq_send]
* xref:zmq_recv.adoc[zmq_recv]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Ppoll (`doc/zmq_ppoll.adoc`)

= zmq_poll(3)


== NAME
zmq_ppoll - input/output multiplexing with signal mask


== SYNOPSIS

*int zmq_ppoll (zmq_pollitem_t '*items', int 'nitems', long 'timeout', const sigset_t '*sigmask');*


== DESCRIPTION
The relationship between _zmq_poll()_ and _zmq_ppoll()_ is analogous to the
relationship between poll(2) and ppoll(2) and between select(2) and
pselect(2): _zmq_ppoll()_ allows an application to safely wait until either a
file descriptor becomes ready or until a signal is caught.

When using _zmq_ppoll()_ with 'sigmask' set to NULL, its behavior is identical
to that of _zmq_poll()_. See xref:zmq_poll.adoc[zmq_poll] for more on this.

To make full use of _zmq_ppoll()_, a non-NULL pointer to a signal mask must be
constructed and passed to 'sigmask'. See sigprocmask(2) for more details. When
this is done, inside the actual _ppoll()_ (or _pselect()_, see note below)
system call, an atomic operation consisting of three steps is performed:
  1. The current signal mask is replaced by the one pointed to by 'sigmask'.
  2. The actual _poll()_ call is done.
  3. The original signal mask is restored.
Because these operations are done atomically, there is no opportunity for race
conditions in between the calls changing the signal mask and the poll/select
system call. This means that only during this (atomic) call, we can unblock
certain signals, so that they can be handled *at that time only*, not outside
of the call. This means that effectively, we extend our poller into a function
that not only watches sockets for changes, but also watches the "POSIX signal
socket" for incoming signals. At other times, these signals will be blocked,
and we will not have to deal with interruptions in system calls at these other
times.

NOTE: The _zmq_ppoll()_ function may be implemented or emulated using operating
system interfaces other than _ppoll()_, and as such may be subject to the
limits of those interfaces in ways not defined in this documentation.

NOTE: There is no _ppoll_ or _pselect_ on Windows, so _zmq_ppoll()_ is not
supported in Windows builds. It is still callable, but its 'sigmask' has void
pointer type (because 'sigset_t' is also not available on Windows) and
_zmq_ppoll()_ will return with an error (see error section below).

== THREAD SAFETY
The *zmq_pollitem_t* array must only be used by the thread which
will/is calling _zmq_ppoll_.

If a socket is contained in multiple *zmq_pollitem_t* arrays, each owned by a
different thread, the socket itself needs to be thead-safe (Server, Client, ...).
Otherwise, behaviour is undefined.


== RETURN VALUE
Upon successful completion, the _zmq_ppoll()_ function shall return the number
of *zmq_pollitem_t* structures with events signaled in 'revents' or `0` if no
events have been signaled. Upon failure, _zmq_ppoll()_ shall return `-1` and set
'errno' to one of the values defined below.


== ERRORS
*ETERM*::
At least one of the members of the 'items' array refers to a 'socket' whose
associated 0MQ 'context' was terminated.
*EFAULT*::
The provided 'items' was not valid (NULL).
*EINTR*::
The operation was interrupted by delivery of a signal before any events were
available.
*EINTR*::
The operation was interrupted by delivery of a signal before any events were
available.
*ENOTSUP*::
_zmq_ppoll()_ was not activated in this build.


== EXAMPLE
.Polling indefinitely for input events on both a 0MQ socket and a standard socket.
See the _example section_ of xref:zmq_poll.adoc[zmq_poll] One only needs to replace
the _zmq_poll_ call with _zmq_ppoll_ and add a _NULL_ argument for the 'sigmask'
parameter.

.Handle SIGTERM during _zmq_ppoll_ (and block it otherwise).
----
// simple global signal handler for SIGTERM
static bool sigterm_received = false;
void handle_sigterm (int signum) {
    sigterm_received = true;
}

// set up signal mask and install handler for SIGTERM
sigset_t sigmask, sigmask_without_sigterm;
sigemptyset(&sigmask);
sigaddset(&sigmask, SIGTERM);
sigprocmask(SIG_BLOCK, &sigmask, &sigmask_without_sigterm);
struct sigaction sa;
memset(&sa, '\0', sizeof(sa));
sa.sa_handler = handle_sigterm;

// poll
zmq_pollitem_t items [1];
// Just one item, which refers to 0MQ socket 'socket' */
items[0].socket = socket;
items[0].events = ZMQ_POLLIN;
// Poll for events indefinitely, but also exit on SIGTERM
int rc = zmq_poll (items, 2, -1, &sigmask_without_sigterm);
if (rc < 0 && errno == EINTR && sigterm_received) {
  // do your SIGTERM business
} else {
  // do your non-SIGTERM error handling
}
----


== SEE ALSO
* xref:zmq_poll.adoc[zmq_poll]
* xref:zmq_socket.adoc[zmq_socket]
* xref:zmq_send.adoc[zmq_send]
* xref:zmq_recv.adoc[zmq_recv]
* xref:zmq.adoc[zmq]

Your operating system documentation for the _poll()_ system call.


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Proxy (`doc/zmq_proxy.adoc`)

= zmq_proxy(3)

== NAME
zmq_proxy - start built-in 0MQ proxy


== SYNOPSIS
*int zmq_proxy (void '*frontend', void '*backend', void '*capture');*


== DESCRIPTION
The _zmq_proxy()_ function starts the built-in 0MQ proxy in the current
application thread.

The proxy connects a frontend socket to a backend socket. Conceptually, data
flows from frontend to backend. Depending on the socket types, replies may flow
in the opposite direction. The direction is conceptual only; the proxy is fully
symmetric and there is no technical difference between frontend and backend.

Before calling _zmq_proxy()_ you must set any socket options, and connect or
bind both frontend and backend sockets. The two conventional proxy models are:

_zmq_proxy()_ runs in the current thread and returns only if/when the current
context is closed.

If the capture socket is not NULL, the proxy shall send all messages, received
on both frontend and backend, to the capture socket. The capture socket should
be a 'ZMQ_PUB', 'ZMQ_DEALER', 'ZMQ_PUSH', or 'ZMQ_PAIR' socket.

Refer to xref:zmq_socket.adoc[zmq_socket] for a description of the available socket types.

== EXAMPLE USAGE

Shared Queue
~~~~~~~~~~~~

When the frontend is a ZMQ_ROUTER socket, and the backend is a ZMQ_DEALER
socket, the proxy shall act as a shared queue that collects requests from a
set of clients, and distributes these fairly among a set of services.
Requests shall be fair-queued from frontend connections and distributed evenly
across backend connections. Replies shall automatically return to the client
that made the original request.

Forwarder
~~~~~~~~~

When the frontend is a ZMQ_XSUB socket, and the backend is a ZMQ_XPUB socket,
the proxy shall act as a message forwarder that collects messages from a set
of publishers and forwards these to a set of subscribers. This may be used to
bridge networks transports, e.g. read on tcp:// and forward on pgm://.

Streamer
~~~~~~~~

When the frontend is a ZMQ_PULL socket, and the backend is a ZMQ_PUSH socket,
the proxy shall collect tasks from a set of clients and forwards these to a set
of workers using the pipeline pattern.

== RETURN VALUE
The _zmq_proxy()_ function always returns `-1` and 'errno' set to *ETERM* or
*EINTR* (the 0MQ 'context' associated with either of the specified sockets was
terminated) or *EFAULT* (the provided 'frontend' or 'backend' was invalid).


== EXAMPLE
.Creating a shared queue proxy
----
//  Create frontend and backend sockets
void *frontend = zmq_socket (context, ZMQ_ROUTER);
assert (frontend);
void *backend = zmq_socket (context, ZMQ_DEALER);
assert (backend);
//  Bind both sockets to TCP ports
assert (zmq_bind (frontend, "tcp://*:5555") == 0);
assert (zmq_bind (backend, "tcp://*:5556") == 0);
//  Start the queue proxy, which runs until ETERM
zmq_proxy (frontend, backend, NULL);
----


== SEE ALSO
* xref:zmq_bind.adoc[zmq_bind]
* xref:zmq_connect.adoc[zmq_connect]
* xref:zmq_socket.adoc[zmq_socket]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Proxy Steerable (`doc/zmq_proxy_steerable.adoc`)

= zmq_proxy_steerable(3)

== NAME
zmq_proxy_steerable - built-in 0MQ proxy with control flow


== SYNOPSIS
*int zmq_proxy_steerable (const void '*frontend', const void '*backend', 
     const void '*capture', const void '*control');*


== DESCRIPTION

The _zmq_proxy_steerable()_ function is a variant of the _zmq_proxy()_ function.
It accepts a fourth _control_ socket.  When the _control_ socket is _NULL_ the
two functions operate identically.

When a _control_ socket of type _REP_ or _PAIR_ is provided to the proxy function the
application may send commands to the proxy.  The following commands are
supported.

_PAUSE_::
    The proxy will cease transferring messages between its endpoints.  _REP_ control socket will reply with an empty message. No response otherwise.

_RESUME_::
    The proxy will resume transferring messages between its endpoints.  _REP_ control socket will reply with an empty message. No response otherwise. 

_TERMINATE_::
    The proxy function will exit with a return value of 0.  _REP_ control socket will reply with an empty message. No response otherwise.

_STATISTICS_::
    The proxy state will remain unchanged and reply with a set of simple summary values of the messages that have been sent through the proxy as described next. Control socket must support sending.

There are eight statistics values, each of size _uint64_t_ in the multi-part
message reply to the _STATISTICS_ command.  These are:

- number of messages received by the frontend socket

- number of bytes received by the frontend socket

- number of messages sent by the frontend socket

- number of bytes sent by the frontend socket

- number of messages received by the backend socket

- number of bytes received by the backend socket

- number of messages sent by the backend socket

- number of bytes sent by the backend socket

Message totals count each part in a multipart message individually.


== RETURN VALUE
The _zmq_proxy_steerable()_ function returns 0 if TERMINATE is received on its
control socket.  Otherwise, it returns -1 and errno set to ETERM or EINTR (the
0MQ context associated with either of the specified sockets was terminated) or
EFAULT (the provided frontend or backend was invalid).


== EXAMPLE
.Create a function to run the proxy
----
// Create the frontend and backend sockets to be proxied
void *frontend = zmq_socket (context, ZMQ_ROUTER);
void *backend = zmq_socket (context, ZMQ_DEALER);

// Create the proxy control socket
void *control = zmq_socket (context, ZMQ_REP);

// Bind the sockets.  
zmq_bind (frontend, "tcp://*:5555");
zmq_bind (backend, "tcp://*:5556");
zmq_bind (control, "tcp://*:5557");

zmq_proxy_steerable(frontend, backend, NULL, control);
----
.Code in another thread/process to steer the proxy.
----
void *control = zmq_socket (context, ZMQ_REQ);
zmq_connect (control, "tcp://*:5557");

zmq_msg_t msg;

zmq_send (control, "PAUSE", 5, 0);
zmq_msg_recv (&msg, control, 0));

zmq_send (control, "RESUME", 6, 0);
zmq_msg_recv (&msg, control, 0));

zmq_send (control, "STATISTICS", 10, 0);
while (1) {
    zmq_msg_recv (&msg, control, 0));
    printf(" %lu", *(uint64_t *)zmq_msg_data (&msg));
    if (!zmq_msg_get (&msg, ZMQ_MORE))
        break;
}
printf("\n");

zmq_send (control, "TERMINATE", 9, 0);
zmq_msg_recv (&msg, control, 0));

zmq_close(frontend);
zmq_close(backend);
zmq_close(control);
----


== SEE ALSO
* xref:zmq_proxy.adoc[zmq_proxy]
* xref:zmq_bind.adoc[zmq_bind]
* xref:zmq_connect.adoc[zmq_connect]
* xref:zmq_socket.adoc[zmq_socket]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Recv (`doc/zmq_recv.adoc`)

= zmq_recv(3)


== NAME
zmq_recv - receive a message part from a socket


== SYNOPSIS
*int zmq_recv (void '*socket', void '*buf', size_t 'len', int 'flags');*


== DESCRIPTION
The _zmq_recv()_ function shall receive a message from the socket referenced
by the 'socket' argument and store it in the buffer referenced by the 'buf'
argument. Any bytes exceeding the length specified by the 'len' argument shall
be truncated. If there are no messages available on the specified 'socket'
the _zmq_recv()_ function shall block until the request can be satisfied.
The 'flags' argument is a combination of the flags defined below: The 'buf'
argument may be null if len is zero.

*ZMQ_DONTWAIT*::
Specifies that the operation should be performed in non-blocking mode. If there
are no messages available on the specified 'socket', the _zmq_recv()_
function shall fail with 'errno' set to EAGAIN.


Multi-part messages
~~~~~~~~~~~~~~~~~~~
A 0MQ message is composed of 1 or more message parts. 0MQ ensures atomic
delivery of messages: peers shall receive either all _message parts_ of a
message or none at all. The total number of message parts is unlimited except
by available memory.

An application that processes multi-part messages must use the _ZMQ_RCVMORE_
xref:zmq_getsockopt.adoc[zmq_getsockopt] option after calling _zmq_recv()_ to determine if
there are further parts to receive.

== RETURN VALUE
The _zmq_recv()_ function shall return number of bytes in the message
if successful. Note that the value can exceed the value of the 'len' parameter
in case the message was truncated. If not successful the function shall return
`-1` and set 'errno' to one of the values defined below.


== ERRORS
*EAGAIN*::
Either the timeout set via the socket-option ZMQ_RCVTIMEO (see xref:zmq_setsockopt.adoc[zmq_setsockopt])
has been reached (flag ZMQ_DONTWAIT not set) without being able to read a message
from the socket or there are no messages available at the moment (flag ZMQ_DONTWAIT set)
and the operation would block.
*ENOTSUP*::
The _zmq_recv()_ operation is not supported by this socket type.
*EFSM*::
The _zmq_recv()_ operation cannot be performed on this socket at the moment
due to the socket not being in the appropriate state.  This error may occur with
socket types that switch between several states, such as ZMQ_REP.  See the
_messaging patterns_ section of xref:zmq_socket.adoc[zmq_socket] for more information.
*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 before a message was
available.


== EXAMPLE
.Receiving a message from a socket
----
char buf [256];
nbytes = zmq_recv (socket, buf, 256, 0);
assert (nbytes != -1);
----


== SEE ALSO
* xref:zmq_send.adoc[zmq_send]
* xref:zmq_getsockopt.adoc[zmq_getsockopt]
* xref:zmq_setsockopt.adoc[zmq_setsockopt]
* xref:zmq_socket.adoc[zmq_socket]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Recvmsg (`doc/zmq_recvmsg.adoc`)

= zmq_recvmsg(3)


== NAME
zmq_recvmsg - receive a message part from a socket


== SYNOPSIS
*int zmq_recvmsg (void '*socket', zmq_msg_t '*msg', int 'flags');*


== DESCRIPTION
The _zmq_recvmsg()_ function shall receive a message part from the socket
referenced by the 'socket' argument and store it in the message referenced by
the 'msg' argument. Any content previously stored in 'msg' shall be properly
deallocated. If there are no message parts available on the specified 'socket'
the _zmq_recvmsg()_ function shall block until the request can be satisfied.
The 'flags' argument is a combination of the flags defined below:

*ZMQ_DONTWAIT*::
Specifies that the operation should be performed in non-blocking mode. If there
are no messages available on the specified 'socket', the _zmq_recvmsg()_
function shall fail with 'errno' set to EAGAIN.

NOTE: this API method is deprecated in favor of zmq_msg_recv(3).


Multi-part messages
~~~~~~~~~~~~~~~~~~~
A 0MQ message is composed of 1 or more message parts. Each message
part is an independent 'zmq_msg_t' in its own right. 0MQ ensures atomic
delivery of messages: peers shall receive either all _message parts_ of a
message or none at all. The total number of message parts is unlimited except
by available memory.

An application that processes multi-part messages must use the _ZMQ_RCVMORE_
xref:zmq_getsockopt.adoc[zmq_getsockopt] option after calling _zmq_recvmsg()_ to determine if
there are further parts to receive.


== RETURN VALUE
The _zmq_recvmsg()_ function shall return number of bytes in the message
if successful. Otherwise it shall return `-1` and set 'errno' to one of the
values defined below.


== ERRORS
*EAGAIN*::
Either the timeout set via the socket-option ZMQ_RCVTIMEO (see xref:zmq_setsockopt.adoc[zmq_setsockopt])
has been reached (flag ZMQ_DONTWAIT not set) without being able to read a message
from the socket or there are no messages available at the moment (flag ZMQ_DONTWAIT set)
and the operation would block.
*ENOTSUP*::
The _zmq_recvmsg()_ operation is not supported by this socket type.
*EFSM*::
The _zmq_recvmsg()_ operation cannot be performed on this socket at the moment
due to the socket not being in the appropriate state.  This error may occur with
socket types that switch between several states, such as ZMQ_REP.  See the
_messaging patterns_ section of xref:zmq_socket.adoc[zmq_socket] for more information.
*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 before a message was
available.
*EFAULT*::
The message passed to the function was invalid.


== EXAMPLE
.Receiving a message from a socket
----
/* Create an empty 0MQ message */
zmq_msg_t msg;
int rc = zmq_msg_init (&msg);
assert (rc == 0);
/* Block until a message is available to be received from socket */
rc = zmq_recvmsg (socket, &msg, 0);
assert (rc != -1);
/* Release message */
zmq_msg_close (&msg);
----

.Receiving a multi-part message
----
int more;
size_t more_size = sizeof (more);
do {
    /* Create an empty 0MQ message to hold the message part */
    zmq_msg_t part;
    int rc = zmq_msg_init (&part);
    assert (rc == 0);
    /* Block until a message is available to be received from socket */
    rc = zmq_recvmsg (socket, &part, 0);
    assert (rc != -1);
    /* Determine if more message parts are to follow */
    rc = zmq_getsockopt (socket, ZMQ_RCVMORE, &more, &more_size);
    assert (rc == 0);
    zmq_msg_close (&part);
} while (more);
----


== SEE ALSO
* xref:zmq_recv.adoc[zmq_recv]
* xref:zmq_send.adoc[zmq_send]
* xref:zmq_getsockopt.adoc[zmq_getsockopt]
* xref:zmq_setsockopt.adoc[zmq_setsockopt]
* xref:zmq_socket.adoc[zmq_socket]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Send (`doc/zmq_send.adoc`)

= zmq_send(3)


== NAME
zmq_send - send a message part on a socket


== SYNOPSIS
*int zmq_send (void '*socket', const void '*buf', size_t 'len', int 'flags');*


== DESCRIPTION
The _zmq_send()_ function shall queue a message created from the buffer
referenced by the 'buf' and 'len' arguments. The 'flags' argument is
a combination of the flags defined below:

*ZMQ_DONTWAIT*::
For socket types (DEALER, PUSH) that block (either with ZMQ_IMMEDIATE option set
and no peer available, or all peers having full high-water mark), specifies that
the operation should be performed in non-blocking mode. If the message cannot be
queued on the 'socket', the _zmq_send()_ function shall fail with 'errno' set
to EAGAIN.

*ZMQ_SNDMORE*::
Specifies that the message being sent is a multi-part message, and that further
message parts are to follow. Refer to the section regarding multi-part messages
below for a detailed description.

NOTE: A successful invocation of _zmq_send()_ does not indicate that the
message has been transmitted to the network, only that it has been queued on
the 'socket' and 0MQ has assumed responsibility for the message.


Multi-part messages
~~~~~~~~~~~~~~~~~~~
A 0MQ message is composed of 1 or more message parts. 0MQ ensures atomic
delivery of messages: peers shall receive either all _message parts_ of a
message or none at all. The total number of message parts is unlimited except
by available memory.

An application that sends multi-part messages must use the _ZMQ_SNDMORE_ flag
when sending each message part except the final one.


== RETURN VALUE
The _zmq_send()_ function shall return number of bytes in the message
if successful. Otherwise it shall return `-1` and set 'errno' to one of the
values defined below.


== ERRORS
*EAGAIN*::
Non-blocking mode was requested and the message cannot be sent at the moment.
*ENOTSUP*::
The _zmq_send()_ operation is not supported by this socket type.
*EINVAL*::
The sender tried to send multipart data, which the socket type does not allow.
*EFSM*::
The _zmq_send()_ operation cannot be performed on this socket at the moment
due to the socket not being in the appropriate state.  This error may occur with
socket types that switch between several states, such as ZMQ_REP.  See the
_messaging patterns_ section of xref:zmq_socket.adoc[zmq_socket] for more information.
*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 before the message was
sent.
*EHOSTUNREACH*::
The message cannot be routed.


== EXAMPLE
.Sending a multi-part message
----
/* Send a multi-part message consisting of three parts to socket */
rc = zmq_send (socket, "ABC", 3, ZMQ_SNDMORE);
assert (rc == 3);
rc = zmq_send (socket, "DEFGH", 5, ZMQ_SNDMORE);
assert (rc == 5);
/* Final part; no more parts to follow */
rc = zmq_send (socket, "JK", 2, 0);
assert (rc == 2);
----

== SEE ALSO
* xref:zmq_send_const.adoc[zmq_send_const]
* xref:zmq_recv.adoc[zmq_recv]
* xref:zmq_socket.adoc[zmq_socket]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Send Const (`doc/zmq_send_const.adoc`)

= zmq_send_const(3)


== NAME
zmq_send_const - send a constant-memory message part on a socket


== SYNOPSIS
*int zmq_send_const (void '*socket', const void '*buf', size_t 'len', int 'flags');*


== DESCRIPTION
The _zmq_send_const()_ function shall queue a message created from the buffer
referenced by the 'buf' and 'len' arguments. The message buffer is assumed
to be constant-memory and will therefore not be copied or deallocated
in any way. The 'flags' argument is a combination of the flags defined below:

*ZMQ_DONTWAIT*::
For socket types (DEALER, PUSH) that block (either with ZMQ_IMMEDIATE option set
and no peer available, or all peers having full high-water mark), specifies that
the operation should be performed in non-blocking mode. If the message cannot be
queued on the 'socket', the _zmq_send_const()_ function shall fail with 'errno' set
to EAGAIN.

*ZMQ_SNDMORE*::
Specifies that the message being sent is a multi-part message, and that further
message parts are to follow. Refer to the section regarding multi-part messages
below for a detailed description.

NOTE: A successful invocation of _zmq_send_const()_ does not indicate that the
message has been transmitted to the network, only that it has been queued on
the 'socket' and 0MQ has assumed responsibility for the message.


Multi-part messages
~~~~~~~~~~~~~~~~~~~
A 0MQ message is composed of 1 or more message parts. 0MQ ensures atomic
delivery of messages: peers shall receive either all _message parts_ of a
message or none at all. The total number of message parts is unlimited except
by available memory.

An application that sends multi-part messages must use the _ZMQ_SNDMORE_ flag
when sending each message part except the final one.


== RETURN VALUE
The _zmq_send_const()_ function shall return number of bytes in the message
if successful. Otherwise it shall return `-1` and set 'errno' to one of the
values defined below.


== ERRORS
*EAGAIN*::
Non-blocking mode was requested and the message cannot be sent at the moment.
*ENOTSUP*::
The _zmq_send_const()_ operation is not supported by this socket type.
*EFSM*::
The _zmq_send_const()_ operation cannot be performed on this socket at the moment
due to the socket not being in the appropriate state.  This error may occur with
socket types that switch between several states, such as ZMQ_REP.  See the
_messaging patterns_ section of xref:zmq_socket.adoc[zmq_socket] for more information.
*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 before the message was
sent.
*EHOSTUNREACH*::
The message cannot be routed.


== EXAMPLE
.Sending a multi-part message
----
/* Send a multi-part message consisting of three parts to socket */
rc = zmq_send_const (socket, "ABC", 3, ZMQ_SNDMORE);
assert (rc == 3);
rc = zmq_send_const (socket, "DEFGH", 5, ZMQ_SNDMORE);
assert (rc == 5);
/* Final part; no more parts to follow */
rc = zmq_send_const (socket, "JK", 2, 0);
assert (rc == 2);
----

== SEE ALSO
* xref:zmq_send.adoc[zmq_send]
* xref:zmq_recv.adoc[zmq_recv]
* xref:zmq_socket.adoc[zmq_socket]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Sendmsg (`doc/zmq_sendmsg.adoc`)

= zmq_sendmsg(3)


== NAME
zmq_sendmsg - send a message part on a socket


== SYNOPSIS
*int zmq_sendmsg (void '*socket', zmq_msg_t '*msg', int 'flags');*


== DESCRIPTION
The _zmq_sendmsg()_ function shall queue the message referenced by the 'msg'
argument to be sent to the socket referenced by the 'socket' argument.  The
'flags' argument is a combination of the flags defined below:

*ZMQ_DONTWAIT*::
For socket types (DEALER, PUSH) that block (either with ZMQ_IMMEDIATE option set
and no peer available, or all peers having full high-water mark), specifies that
the operation should be performed in non-blocking mode. If the message cannot be
queued on the 'socket', the _zmq_sendmsg()_ function shall fail with 'errno' set
to EAGAIN.

*ZMQ_SNDMORE*::
Specifies that the message being sent is a multi-part message, and that further
message parts are to follow. Refer to the section regarding multi-part messages
below for a detailed description.

The _zmq_msg_t_ structure passed to _zmq_sendmsg()_ is nullified during the
call. If you want to send the same message to multiple sockets you have to copy
it (e.g. using _zmq_msg_copy()_).

NOTE: A successful invocation of _zmq_sendmsg()_ does not indicate that the
message has been transmitted to the network, only that it has been queued on
the 'socket' and 0MQ has assumed responsibility for the message.

NOTE: this API method is deprecated in favor of zmq_msg_send(3).

Multi-part messages
~~~~~~~~~~~~~~~~~~~
A 0MQ message is composed of 1 or more message parts. Each message
part is an independent 'zmq_msg_t' in its own right. 0MQ ensures atomic
delivery of messages: peers shall receive either all _message parts_ of a
message or none at all. The total number of message parts is unlimited except
by available memory.

An application that sends multi-part messages must use the _ZMQ_SNDMORE_ flag
when sending each message part except the final one.

== RETURN VALUE
The _zmq_sendmsg()_ function shall return number of bytes in the message
if successful. Otherwise it shall return `-1` and set 'errno' to one of the
values defined below.


== ERRORS
*EAGAIN*::
Non-blocking mode was requested and the message cannot be sent at the moment.
*ENOTSUP*::
The _zmq_sendmsg()_ operation is not supported by this socket type.
*EINVAL*::
The sender tried to send multipart data, which the socket type does not allow.
*EFSM*::
The _zmq_sendmsg()_ operation cannot be performed on this socket at the moment
due to the socket not being in the appropriate state.  This error may occur with
socket types that switch between several states, such as ZMQ_REP.  See the
_messaging patterns_ section of xref:zmq_socket.adoc[zmq_socket] for more information.
*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 before the message was
sent.
*EFAULT*::
Invalid message.
*EHOSTUNREACH*::
The message cannot be routed.


== EXAMPLE
.Filling in a message and sending it to a socket
----
/* Create a new message, allocating 6 bytes for message content */
zmq_msg_t msg;
int rc = zmq_msg_init_size (&msg, 6);
assert (rc == 0);
/* Fill in message content with 'AAAAAA' */
memset (zmq_msg_data (&msg), 'A', 6);
/* Send the message to the socket */
rc = zmq_sendmsg (socket, &msg, 0);
assert (rc == 6);
----

.Sending a multi-part message
----
/* Send a multi-part message consisting of three parts to socket */
rc = zmq_sendmsg (socket, &part1, ZMQ_SNDMORE);
rc = zmq_sendmsg (socket, &part2, ZMQ_SNDMORE);
/* Final part; no more parts to follow */
rc = zmq_sendmsg (socket, &part3, 0);
----


== SEE ALSO
* xref:zmq_recv.adoc[zmq_recv]
* xref:zmq_socket.adoc[zmq_socket]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Setsockopt (`doc/zmq_setsockopt.adoc`)

= zmq_setsockopt(3)


== NAME

zmq_setsockopt - set 0MQ socket options


== SYNOPSIS
*int zmq_setsockopt (void '*socket', int 'option_name', const void '*option_value', size_t 'option_len');*

Caution: All options, with the exception of ZMQ_SUBSCRIBE, ZMQ_UNSUBSCRIBE,
ZMQ_LINGER, ZMQ_ROUTER_HANDOVER, ZMQ_ROUTER_MANDATORY, ZMQ_PROBE_ROUTER,
ZMQ_XPUB_VERBOSE, ZMQ_XPUB_VERBOSER, ZMQ_REQ_CORRELATE,
ZMQ_REQ_RELAXED, ZMQ_SNDHWM and ZMQ_RCVHWM, only take effect for
subsequent socket bind/connects.

Specifically, security options take effect for subsequent bind/connect calls,
and can be changed at any time to affect subsequent binds and/or connects.

== DESCRIPTION
The _zmq_setsockopt()_ function shall set the option specified by the
'option_name' argument to the value pointed to by the 'option_value' argument
for the 0MQ socket pointed to by the 'socket' argument. The 'option_len'
argument is the size of the option value in bytes. For options taking a value of
type "character string", the provided byte data should either contain no zero
bytes, or end in a single zero byte (terminating ASCII NUL character).

The following socket options can be set with the _zmq_setsockopt()_ function:


ZMQ_AFFINITY: Set I/O thread affinity
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_AFFINITY' option shall set 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 xref:zmq_init.adoc[zmq_init] 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_BACKLOG: Set maximum length of the queue of outstanding connections
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_BACKLOG' option shall set 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_BINDTODEVICE: Set name of device to bind the socket to
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_BINDTODEVICE' option binds this socket to a particular device, eg.
an interface or VRF. If a socket is bound to an interface, only packets
received from that particular interface are processed by the socket. If device
is a VRF device, then subsequent binds/connects to that socket use addresses
in the VRF routing table.

NOTE: requires setting CAP_NET_RAW on the compiled program.

[horizontal]
Option value type:: character string
Option value unit:: N/A
Default value:: not set
Applicable socket types:: all, when using TCP or UDP transports.


ZMQ_BUSY_POLL: This removes delays caused by the interrupt and the resultant context switch.

This option name is now deprecated. Use ZMQ_CONNECT_ROUTING_ID instead.
ZMQ_CONNECT_RID remains as an alias for now.


ZMQ_CONNECT_ROUTING_ID: Assign the next outbound routing id

If set, a socket shall keep only one message in its inbound/outbound
queue, this message being the last message received/the last message
to be sent. Ignores 'ZMQ_RCVHWM' and 'ZMQ_SNDHWM' options. Does not
support multi-part messages, in particular, only one part of it is kept
in the socket internal queue.

NOTE: If recv is not called on the inbound socket, the queue and memory will
grow with each message received. Use xref:zmq_getsockopt.adoc[zmq_getsockopt] with ZMQ_EVENTS
to trigger the conflation of the messages.

[horizontal]
Option value type:: int
Option value unit:: boolean
Default value:: 0 (false)
Applicable socket types:: ZMQ_PULL, ZMQ_PUSH, ZMQ_SUB, ZMQ_PUB, ZMQ_DEALER


ZMQ_CONNECT_TIMEOUT: Set connect() timeout

Sets the socket's long term public key. You must set this on CURVE client
sockets, see xref:zmq_curve.adoc[zmq_curve] You can provide the key as 32 binary
bytes, or as a 40-character string encoded in the Z85 encoding format and
terminated in a null byte. The public key must always be used with the
matching secret key. To generate a public/secret key pair, use
xref:zmq_curve_keypair.adoc[zmq_curve_keypair] To derive the public key from a secret key,
use xref:zmq_curve_public.adoc[zmq_curve_public]

NOTE: an option value size of 40 is supported for backwards compatibility,
though is deprecated.

[horizontal]
Option value type:: binary data or Z85 text string
Option value size:: 32 or 41
Default value:: NULL
Applicable socket types:: all, when using TCP transport


ZMQ_CURVE_SECRETKEY: Set CURVE secret key

Defines whether the socket will act as server for CURVE security, see
xref:zmq_curve.adoc[zmq_curve] A value of '1' means the socket will act as
CURVE server. A value of '0' means the socket will not act as CURVE
server, and its security role then depends on other option settings.
Setting this to '0' shall reset the socket security to NULL. When you
set this you must also set the server's secret key using the
ZMQ_CURVE_SECRETKEY option. A server socket does not need to know
its own public key.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 0
Applicable socket types:: all, when using TCP transport


ZMQ_CURVE_SERVERKEY: Set CURVE server key

When set, the socket will generate a disconnect message when accepted peer has been disconnected.
You may set this on ROUTER, SERVER and PEER sockets.
The combination with ZMQ_HEARTBEAT_IVL is powerful and simplify protocols, when heartbeat recognize a connection drop it
will generate a disconnect message that can match the protocol of the application.

[horizontal]
Option value type:: binary data
Option value unit:: N/A
Default value:: NULL
Applicable socket types:: ZMQ_ROUTER, ZMQ_SERVER and ZMQ_PEER


ZMQ_HICCUP_MSG: set a hiccup message that the socket will generate when connected peer temporarily disconnect

Defines whether communications on the socket will be encrypted, see
xref:zmq_gssapi.adoc[zmq_gssapi] A value of '1' means  that communications will be
plaintext.  A value of '0' means communications will be encrypted.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 0 (false)
Applicable socket types:: all, when using TCP transport


ZMQ_GSSAPI_PRINCIPAL: Set name of GSSAPI principal

Defines whether the socket will act as server for GSSAPI security, see
xref:zmq_gssapi.adoc[zmq_gssapi] A value of '1' means the socket will act as GSSAPI
server. A value of '0' means the socket will act as GSSAPI client.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 0 (false)
Applicable socket types:: all, when using TCP transport


ZMQ_GSSAPI_SERVICE_PRINCIPAL: Set name of GSSAPI service principal

Sets the name type of the GSSAPI service principal.  A value of
'ZMQ_GSSAPI_NT_HOSTBASED' (0) means the name specified with
'ZMQ_GSSAPI_SERVICE_PRINCIPAL' is interpreted as a host based name.  A value
of 'ZMQ_GSSAPI_NT_USER_NAME' (1) means it is interpreted as a local user name.
A value of 'ZMQ_GSSAPI_NT_KRB5_PRINCIPAL' (2) means it is interpreted as an
unparsed principal name string (valid only with the krb5 GSSAPI mechanism).

[horizontal]
Option value type:: int
Option value unit:: 0, 1, 2
Default value:: 0 (ZMQ_GSSAPI_NT_HOSTBASED)
Applicable socket types:: all, when using TCP or IPC transport

ZMQ_GSSAPI_PRINCIPAL_NAMETYPE: Set name type of principal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the name type of the GSSAPI principal.  A value of
'ZMQ_GSSAPI_NT_HOSTBASED' (0) means the name specified with
'ZMQ_GSSAPI_PRINCIPAL' is interpreted as a host based name.  A value of
'ZMQ_GSSAPI_NT_USER_NAME' (1) means it is interpreted as a local user name.
A value of 'ZMQ_GSSAPI_NT_KRB5_PRINCIPAL' (2) means it is interpreted as an
unparsed principal name string (valid only with the krb5 GSSAPI mechanism).

[horizontal]
Option value type:: int
Option value unit:: 0, 1, 2
Default value:: 0 (ZMQ_GSSAPI_NT_HOSTBASED)
Applicable socket types:: all, when using TCP or IPC transport

ZMQ_HANDSHAKE_IVL: Set maximum handshake interval
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_HANDSHAKE_IVL' option shall set the maximum handshake interval for
the specified 'socket'. Handshaking is the exchange of socket configuration
information (socket type, routing id, security) that occurs when a connection
is first opened, only for connection-oriented transports. If handshaking does
not complete within the configured time, the connection shall be closed.
The value 0 means no handshake time limit.

[horizontal]
Option value type:: int
Option value unit:: milliseconds
Default value:: 30000
Applicable socket types:: all but ZMQ_STREAM, only for connection-oriented transports

ZMQ_HELLO_MSG: set an hello message that will be sent when a new peer connect

The 'ZMQ_HEARTBEAT_IVL' option shall set the interval between sending ZMTP heartbeats
for the specified 'socket'. If this option is set and is greater than 0, then a 'PING'
ZMTP command will be sent every 'ZMQ_HEARTBEAT_IVL' milliseconds.

[horizontal]
Option value type:: int
Option value unit:: milliseconds
Default value:: 0
Applicable socket types:: all, when using connection-oriented transports


ZMQ_HEARTBEAT_TIMEOUT: Set timeout for ZMTP heartbeats
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_HEARTBEAT_TIMEOUT' option shall set how long to wait before timing-out a
connection after sending a 'PING' ZMTP command and not receiving any traffic. This
option is only valid if 'ZMQ_HEARTBEAT_IVL' is also set, and is greater than 0. The
connection will time out if there is no traffic received after sending the 'PING'
command, but the received traffic does not have to be a 'PONG' command - any received
traffic will cancel the timeout.

[horizontal]
Option value type:: int
Option value unit:: milliseconds
Default value:: 0 normally, ZMQ_HEARTBEAT_IVL if it is set
Applicable socket types:: all, when using connection-oriented transports


ZMQ_HEARTBEAT_TTL: Set the TTL value for ZMTP heartbeats
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_HEARTBEAT_TTL' option shall set the timeout on the remote peer for ZMTP
heartbeats. If this option is greater than 0, the remote side shall time out the
connection if it does not receive any more traffic within the TTL period. This option
does not have any effect if 'ZMQ_HEARTBEAT_IVL' is not set or is 0. Internally, this
value is rounded down to the nearest decisecond, any value less than 100 will have
no effect.

[horizontal]
Option value type:: int
Option value unit:: milliseconds
Default value:: 0
Maximum value:: 6553599 (which is 2^16-1 deciseconds)
Applicable socket types:: all, when using connection-oriented transports


ZMQ_IDENTITY: Set socket identity
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This option name is now deprecated. Use ZMQ_ROUTING_ID instead.
ZMQ_IDENTITY remains as an alias for now.


ZMQ_IMMEDIATE: Queue messages only to completed connections
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default queues will fill on outgoing connections even if the connection has
not completed. This can lead to "lost" messages on sockets with round-robin
routing (REQ, PUSH, DEALER). If this option is set to `1`, messages shall be
queued only to completed connections. 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, only for connection-oriented transports.


ZMQ_INVERT_MATCHING: Invert message filtering
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Reverses the filtering behavior of PUB-SUB sockets, when set to 1.

On 'PUB' and 'XPUB' sockets, this causes messages to be sent to all
connected sockets 'except' those subscribed to a prefix that matches
the message. On 'SUB' sockets, this causes only incoming messages that
do 'not' match any of the socket's subscriptions to be received by the user.

Whenever 'ZMQ_INVERT_MATCHING' is set to 1 on a 'PUB' socket, all 'SUB'
sockets connecting to it must also have the option set to 1. Failure to
do so will have the 'SUB' sockets reject everything the 'PUB' socket sends
them. 'XSUB' sockets do not need to do this because they do not filter
incoming messages.

[horizontal]
Option value type:: int
Option value unit:: 0,1
Default value:: 0
Applicable socket types:: ZMQ_PUB, ZMQ_XPUB, ZMQ_SUB


ZMQ_IPV6: Enable IPv6 on socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Set 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_LINGER: Set linger period for socket shutdown
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_LINGER' option shall set 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 disconnected with
xref:zmq_disconnect.adoc[zmq_disconnect] or closed with xref:zmq_close.adoc[zmq_close], and further
affects the termination of the socket's context with xref:zmq_ctx_term.adoc[zmq_ctx_term]
The following outlines the different behaviours:

* A value of '-1' specifies an infinite linger period. Pending
  messages shall not be discarded after a call to _zmq_disconnect()_ or
  _zmq_close()_; attempting to terminate the socket's context with _zmq_ctx_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 after a call to _zmq_disconnect()_ or _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_disconnect()_ or
  _zmq_close()_; attempting to terminate the socket's context with _zmq_ctx_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_MAXMSGSIZE: Maximum acceptable inbound message size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Limits the size of the inbound message. 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_METADATA: Add application metadata properties to a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The _ZMQ_METADATA_ option shall add application metadata to the specified _socket_,
the metadata is exchanged with peers during connection setup. A metadata property is
specified as a string, delimited by a colon, starting with the metadata _property_
followed by the metadata value, for example "X-key:value".
_Property_ names are restricted to maximum 255 characters and must be prefixed by "X-".
Multiple application metadata properties can be added to a socket by executing zmq_setsockopt()
multiple times. As the argument is a null-terminated string, binary data must be encoded
before it is added e.g. using Z85 (xref:zmq_z85_encode.adoc[zmq_z85_encode]).


NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: character string
Option value unit:: N/A
Default value:: not set
Applicable socket types:: all


ZMQ_MULTICAST_HOPS: Maximum network hops for multicast packets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the time-to-live field in every multicast packet sent from this socket.
The default is 1 which 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_MULTICAST_MAXTPDU: Maximum transport data unit size for multicast packets

Sets the password for outgoing connections over TCP or IPC. If you set this
to a non-null value, the security mechanism used for connections shall be
PLAIN, see xref:zmq_plain.adoc[zmq_plain] If you set this to a null value, the security
mechanism used for connections shall be NULL, see xref:zmq_null.adoc[zmq_null]

[horizontal]
Option value type:: character string
Option value unit:: N/A
Default value:: not set
Applicable socket types:: all, when using TCP transport


ZMQ_PLAIN_SERVER: Set PLAIN server role
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Defines whether the socket will act as server for PLAIN security, see
xref:zmq_plain.adoc[zmq_plain] A value of '1' means the socket will act as
PLAIN server. A value of '0' means the socket will not act as PLAIN
server, and its security role then depends on other option settings.
Setting this to '0' shall reset the socket security to NULL.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 0
Applicable socket types:: all, when using TCP transport


ZMQ_PLAIN_USERNAME: Set PLAIN security username

When set to a positive integer value before zmq_bind is called on the socket,
the socket shall use the corresponding file descriptor for connections over
TCP or IPC instead of allocating a new file descriptor.
Useful for writing systemd socket activated services. If set to -1 (default),
a new file descriptor will be allocated instead (default behaviour).

NOTE: if set after calling zmq_bind, this option shall have no effect.
NOTE: the file descriptor passed through MUST have been ran through the "bind"
      and "listen" system calls beforehand. Also, socket option that would
      normally be passed through zmq_setsockopt like TCP buffers length,
      IP_TOS or SO_REUSEADDR MUST be set beforehand by the caller, as they
      must be set before the socket is bound.

[horizontal]
Option value type:: int
Option value unit:: file descriptor
Default value:: -1
Applicable socket types:: all bound sockets, when using IPC or TCP transport


ZMQ_PRIORITY: Set the Priority on socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the protocol-defined priority for all packets to be sent on this
socket, where supported by the OS. In Linux, values greater than 6
require admin capability (CAP_NET_ADMIN)

[horizontal]
Option value type:: int
Option value unit:: >0
Default value:: 0
Applicable socket types:: all, only for connection-oriented transports


ZMQ_PROBE_ROUTER: bootstrap connections to ROUTER sockets

The 'ZMQ_RATE' option shall set the maximum send or receive data rate for
multicast transports such as xref:zmq_pgm.adoc[zmq_pgm] 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_RCVBUF: Set kernel receive buffer size

The 'ZMQ_RCVHWM' option shall set 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 xref:zmq_socket.adoc[zmq_socket] for details on the exact action taken for each socket
type.

NOTE: 0MQ does not guarantee that the socket will be able to queue as many as ZMQ_RCVHWM
messages, and the actual limit may be lower or higher, depending on socket transport.
A notable example is for sockets using TCP transport; see xref:zmq_tcp.adoc[zmq_tcp]

[horizontal]
Option value type:: int
Option value unit:: messages
Default value:: 1000
Applicable socket types:: all


ZMQ_RCVTIMEO: Maximum time before a recv operation returns with EAGAIN

The 'ZMQ_RECONNECT_IVL' option shall set 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: Set max reconnection interval

The 'ZMQ_RECONNECT_STOP' option shall set the conditions under which automatic
reconnection will stop.  This can be useful when a process binds to a
wild-card port, where the OS supplies an ephemeral port.

The 'ZMQ_RECONNECT_STOP_CONN_REFUSED' option will stop reconnection when 0MQ
receives the ECONNREFUSED return code from the connect.  This indicates that
there is no code bound to the specified endpoint.

The 'ZMQ_RECONNECT_STOP_HANDSHAKE_FAILED' option will stop reconnection if
the 0MQ handshake fails.  This can be used to detect and/or prevent errant
connection attempts to non-0MQ sockets.  Note that when specifying this option
you may also want to set `ZMQ_HANDSHAKE_IVL` -- the default handshake interval
is 30000 (30 seconds), which is typically too large.

The 'ZMQ_RECONNECT_STOP_AFTER_DISCONNECT' option will stop reconnection when
zmq_disconnect() has been called. This can be useful when the user's request failed
(server not ready), as the socket does not need to continue to reconnect after
user disconnect actively.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: 0, ZMQ_RECONNECT_STOP_CONN_REFUSED, ZMQ_RECONNECT_STOP_HANDSHAKE_FAILED, ZMQ_RECONNECT_STOP_CONN_REFUSED | ZMQ_RECONNECT_STOP_HANDSHAKE_FAILED
Default value:: 0
Applicable socket types:: all, only for connection-oriented transports (ZMQ_HANDSHAKE_IVL is
not applicable for ZMQ_STREAM sockets)


ZMQ_RECOVERY_IVL: Set multicast recovery interval
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_RECOVERY_IVL' option shall set 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.

CAUTION: Exercise care when setting large recovery intervals as the data
needed for recovery will be held in memory. For example, a 1 minute recovery
interval at a data rate of 1Gbps requires a 7GB in-memory buffer.

[horizontal]
Option value type:: int
Option value unit:: milliseconds
Default value:: 10000
Applicable socket types:: all, when using multicast transports


ZMQ_REQ_CORRELATE: match replies with requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The default behaviour of REQ sockets is to rely on the ordering of messages to
match requests and responses and that is usually sufficient. When this option
is set to 1, the REQ socket will prefix outgoing messages with an extra frame
containing a request id. That means the full message is (request id, 0,
user frames...). The REQ socket will discard all incoming messages that don't
begin with these two frames.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 0
Applicable socket types:: ZMQ_REQ


ZMQ_REQ_RELAXED: relax strict alternation between request and reply

If two clients use the same routing id when connecting to a ROUTER, the
results shall depend on the ZMQ_ROUTER_HANDOVER option setting. If that
is not set (or set to the default of zero), the ROUTER socket shall reject
clients trying to connect with an already-used routing id. If that option
is set to 1, the ROUTER socket shall hand-over the connection to the new
client and disconnect the existing one.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 0
Applicable socket types:: ZMQ_ROUTER


ZMQ_ROUTER_MANDATORY: accept only routable messages on ROUTER sockets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the ROUTER socket behaviour when an unroutable message is encountered. A
value of `0` is the default and discards the message silently when it cannot be
routed or the peers SNDHWM is reached.  A value of `1` returns an
'EHOSTUNREACH' error code if the message cannot be routed or 'EAGAIN' error
code if the SNDHWM is reached and ZMQ_DONTWAIT was used. Without ZMQ_DONTWAIT
it will block until the SNDTIMEO is reached or a spot in the send queue opens
up.

When ZMQ_ROUTER_MANDATORY is set to `1`, 'ZMQ_POLLOUT' events will be generated
if one or more messages can be sent to at least one of the peers. If
ZMQ_ROUTER_MANDATORY is set to `0`, the socket will generate a 'ZMQ_POLLOUT'
event on every call to 'zmq_poll' resp. 'zmq_poller_wait_all'.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 0
Applicable socket types:: ZMQ_ROUTER


ZMQ_ROUTER_RAW: switch ROUTER socket to raw mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the raw mode on the ROUTER, when set to 1. When the ROUTER socket is in
raw mode, and when using the tcp:// transport, it will read and write TCP data
without 0MQ framing. This lets 0MQ applications talk to non-0MQ applications.
When using raw mode, you cannot set explicit identities, and the ZMQ_SNDMORE
flag is ignored when sending data messages. In raw mode you can close a specific
connection by sending it a zero-length message (following the routing id frame).

NOTE: This option is deprecated, please use ZMQ_STREAM sockets instead.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 0
Applicable socket types:: ZMQ_ROUTER


ZMQ_ROUTING_ID: Set socket routing id
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_ROUTING_ID' option shall set the routing id of the specified 'socket'
when connecting to a ROUTER socket.

A routing id must be at least one byte and at most 255 bytes long. Identities
starting with a zero byte are reserved for use by the 0MQ infrastructure.

If two clients use the same routing id when connecting to a ROUTER, the
results shall depend on the ZMQ_ROUTER_HANDOVER option setting. If that
is not set (or set to the default of zero), the ROUTER socket shall reject
clients trying to connect with an already-used routing id. If that option
is set to 1, the ROUTER socket shall hand-over the connection to the new
client and disconnect the existing one.

[horizontal]
Option value type:: binary data
Option value unit:: N/A
Default value:: NULL
Applicable socket types:: ZMQ_REQ, ZMQ_REP, ZMQ_ROUTER, ZMQ_DEALER.


ZMQ_SNDBUF: Set kernel transmit buffer size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_SNDBUF' option shall set the underlying kernel transmit buffer size
for the 'socket' to the specified size in bytes.  A value of -1 means leave
the OS default unchanged. For details please refer to your operating system
documentation for the 'SO_SNDBUF' socket option.

[horizontal]
Option value type:: int
Option value unit:: bytes
Default value:: -1
Applicable socket types:: all


ZMQ_SNDHWM: Set high water mark for outbound messages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_SNDHWM' option shall set 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 xref:zmq_socket.adoc[zmq_socket] for details on the exact action taken for each socket
type.

NOTE: 0MQ does not guarantee that the socket will accept as many as ZMQ_SNDHWM
messages, and the actual limit may be as much as 90% lower depending on the
flow of messages on the socket. The socket may even be able to accept more messages
than the ZMQ_SNDHWM threshold; a notable example is for sockets using TCP transport;
see xref:zmq_tcp.adoc[zmq_tcp]

[horizontal]
Option value type:: int
Option value unit:: messages
Default value:: 1000
Applicable socket types:: all


ZMQ_SNDTIMEO: Maximum time before a send operation returns with EAGAIN
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets 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_SOCKS_PROXY: Set SOCKS5 proxy address
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the SOCKS5 proxy address that shall be used by the socket for the TCP
connection(s). Supported authentication methods are: no authentication
or basic authentication when setup with ZMQ_SOCKS_USERNAME. If the endpoints
are domain names instead of addresses they shall not be resolved and they
shall be forwarded unchanged to the SOCKS proxy service in the client
connection request message (address type 0x03 domain name).

[horizontal]
Option value type:: character string
Option value unit:: N/A
Default value:: not set
Applicable socket types:: all, when using TCP transport


ZMQ_SOCKS_USERNAME: Set SOCKS username and select basic authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the username for authenticated connection to the SOCKS5 proxy.
If you set this to a non-null and non-empty value, the authentication
method used for the SOCKS5 connection shall be basic authentication.
In this case, use ZMQ_SOCKS_PASSWORD option in order to set the password.
If you set this to a null value or empty value, the authentication method
shall be no authentication, the default.

[horizontal]
Option value type:: character string
Option value unit:: N/A
Default value:: not set
Applicable socket types:: all, when using TCP transport


ZMQ_SOCKS_PASSWORD: Set SOCKS basic authentication password
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the password for authenticating to the SOCKS5 proxy server.
This is used only when the SOCKS5 authentication method has been
set to basic authentication through the ZMQ_SOCKS_USERNAME option.
Setting this to a null value (the default) is equivalent to an
empty password string.

[horizontal]
Option value type:: character string
Option value unit:: N/A
Default value:: not set
Applicable socket types:: all, when using TCP transport


ZMQ_STREAM_NOTIFY: send connect and disconnect notifications
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Enables connect and disconnect notifications on a STREAM socket, when set
to 1. When notifications are enabled, the socket delivers a zero-length
message when a peer connects or disconnects.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 1
Applicable socket types:: ZMQ_STREAM


ZMQ_SUBSCRIBE: Establish message filter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_SUBSCRIBE' option shall establish a new message filter on a 'ZMQ_SUB'
socket. Newly created 'ZMQ_SUB' sockets shall filter out all incoming messages,
therefore you should call this option to establish an initial message filter.

An empty 'option_value' of length zero shall subscribe to all incoming
messages. A non-empty 'option_value' shall subscribe to all messages beginning
with the specified prefix. Multiple filters may be attached to a single
'ZMQ_SUB' socket, in which case a message shall be accepted if it matches at
least one filter.

[horizontal]
Option value type:: binary data
Option value unit:: N/A
Default value:: N/A
Applicable socket types:: ZMQ_SUB


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_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_IDLE: Override TCP_KEEPIDLE (or TCP_KEEPALIVE on some OS)

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.


ZMQ_TCP_MAXRT: Set TCP Maximum Retransmit Timeout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
On OSes where it is supported, sets how long before an unacknowledged TCP
retransmit times out. The system normally attempts many TCP retransmits
following an exponential backoff strategy. This means that after a network
outage, it may take a long time before the session can be re-established.
Setting this option allows the timeout to happen at a shorter interval.

[horizontal]
Option value type:: int
Option value unit:: milliseconds
Default value:: 0 (leave to OS default)
Applicable socket types:: all, when using TCP transports.


ZMQ_TOS: Set the Type-of-Service on socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the ToS fields (Differentiated services (DS) and Explicit Congestion
Notification (ECN) field of the IP header. The ToS field is typically used
to specify a packets priority. The availability of this option is dependent
on intermediate network equipment that inspect the ToS field and provide a
path for low-delay, high-throughput, highly-reliable service, etc.

[horizontal]
Option value type:: int
Option value unit:: >0
Default value:: 0
Applicable socket types:: all, only for connection-oriented transports


ZMQ_UNSUBSCRIBE: Remove message filter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_UNSUBSCRIBE' option shall remove an existing message filter on a
'ZMQ_SUB' socket. The filter specified must match an existing filter previously
established with the 'ZMQ_SUBSCRIBE' option. If the socket has several
instances of the same filter attached the 'ZMQ_UNSUBSCRIBE' option shall remove
only one instance, leaving the rest in place and functional.

[horizontal]
Option value type:: binary data
Option value unit:: N/A
Default value:: N/A
Applicable socket types:: ZMQ_SUB


ZMQ_XPUB_VERBOSE: pass duplicate subscribe messages on XPUB socket

Sets the 'XPUB' socket behaviour on new duplicated subscriptions and
unsubscriptions. If enabled, the socket passes all subscribe and unsubscribe
messages to the caller. If disabled, only the first subscription to each filter and
the last unsubscription from each filter will be passed. The default is 0
(disabled).

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 0
Applicable socket types:: ZMQ_XPUB


ZMQ_XPUB_MANUAL: change the subscription handling to manual
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the 'XPUB' socket subscription handling mode manual/automatic.
A value of '0' is the default and subscription requests will be handled automatically.
A value of '1' will change the subscription requests handling to manual,
with manual mode subscription requests are not added to the subscription list.
To add subscription the user need to call setsockopt with ZMQ_SUBSCRIBE on XPUB socket.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 0
Applicable socket types:: ZMQ_XPUB


ZMQ_XPUB_MANUAL_LAST_VALUE: change the subscription handling to manual
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This option is similar to ZMQ_XPUB_MANUAL.
The difference is that ZMQ_XPUB_MANUAL_LAST_VALUE changes the 'XPUB' socket
behaviour to send the first message to the last subscriber after the socket
receives a subscription and call setsockopt with ZMQ_SUBSCRIBE on 'XPUB' socket.
This prevents duplicated messages when using last value caching(LVC).

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 0
Applicable socket types:: ZMQ_XPUB


ZMQ_XPUB_NODROP: do not silently drop messages if SENDHWM is reached
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the 'XPUB' socket behaviour to return error EAGAIN if SENDHWM is
reached and the message could not be send.

A value of `0` is the default and drops the message silently when the peers
SNDHWM is reached.  A value of `1` returns an 'EAGAIN' error code if the
SNDHWM is reached and ZMQ_DONTWAIT was used.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 0
Applicable socket types:: ZMQ_XPUB, ZMQ_PUB


ZMQ_XPUB_WELCOME_MSG: set welcome message that will be received by subscriber when connecting

Sets the 'XSUB' socket behaviour on duplicated unsubscriptions. If enabled, the socket
passes all unsubscribe messages to the caller. If disabled, only the last unsubscription
from each filter will be passed. The default is 0 (disabled).

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 0
Applicable socket types:: ZMQ_XSUB


ZMQ_ONLY_FIRST_SUBSCRIBE: Process only first subscribe/unsubscribe in a multipart message

Sets the domain for ZAP (ZMQ RFC 27) authentication. A ZAP domain must be
specified to enable authentication. When the ZAP domain is empty, which is
the default, ZAP authentication is disabled. This is not compatible with
previous versions of libzmq, so it can be controlled by ZMQ_ZAP_ENFORCE_DOMAIN
which for now is disabled by default.
See http://rfc.zeromq.org/spec:27 for more details.

[horizontal]
Option value type:: character string
Option value unit:: N/A
Default value:: empty
Applicable socket types:: all, when using TCP transport


ZMQ_ZAP_ENFORCE_DOMAIN: Set ZAP domain handling to strictly adhere the RFC

Assign an arbitrary number of filters that will be applied for each new TCP
transport connection on a listening socket. If no filters are applied, then
the TCP transport allows connections from any IP address. If at least one
filter is applied then new connection source ip should be matched. To clear
all filters call zmq_setsockopt(socket, ZMQ_TCP_ACCEPT_FILTER, NULL, 0).
Filter is a null-terminated string with ipv6 or ipv4 CIDR.

NOTE: This option is deprecated, please use authentication via the ZAP API
and IP address allowing / blocking.

[horizontal]
Option value type:: binary data
Option value unit:: N/A
Default value:: no filters (allow from all)
Applicable socket types:: all listening sockets, when using TCP transports.


ZMQ_IPC_FILTER_GID: Assign group ID filters to allow new IPC connections

Assign an arbitrary number of filters that will be applied for each new IPC
transport connection on a listening socket. If no IPC filters are applied, then
the IPC transport allows connections from any process. If at least one UID,
GID, or PID filter is applied then new connection credentials should be
matched. To clear all PID filters call zmq_setsockopt(socket,
ZMQ_IPC_FILTER_PID, NULL, 0).

NOTE: PID filters are only available on platforms supporting the SO_PEERCRED
socket option (currently only Linux).

NOTE: This option is deprecated, please use authentication via the ZAP API
and IPC allowing / blocking.

[horizontal]
Option value type:: pid_t
Option value unit:: N/A
Default value:: no filters (allow from all)
Applicable socket types:: all listening sockets, when using IPC transports.


ZMQ_IPC_FILTER_UID: Assign user ID filters to allow new IPC connections
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Assign an arbitrary number of filters that will be applied for each new IPC
transport connection on a listening socket. If no IPC filters are applied, then
the IPC transport allows connections from any process. If at least one UID,
GID, or PID filter is applied then new connection credentials should be
matched. To clear all UID filters call zmq_setsockopt(socket,
ZMQ_IPC_FILTER_UID, NULL, 0).

NOTE: UID filters are only available on platforms supporting SO_PEERCRED or
LOCAL_PEERCRED socket options (currently only Linux and later versions of
OS X).

NOTE: This option is deprecated, please use authentication via the ZAP API
and IPC allowing / blocking.

[horizontal]
Option value type:: uid_t
Option value unit:: N/A
Default value:: no filters (allow from all)
Applicable socket types:: all listening sockets, when using IPC transports.


ZMQ_IPV4ONLY: Use IPv4-only on socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Set 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_VMCI_BUFFER_SIZE: Set buffer size of the VMCI socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `ZMQ_VMCI_BUFFER_SIZE` option shall set the size of the underlying
buffer for the socket. Used during negotiation before the connection is established.

[horizontal]
Option value type:: uint64_t
Option value unit:: bytes
Default value:: 65546
Applicable socket types:: all, when using VMCI transport


ZMQ_VMCI_BUFFER_MIN_SIZE: Set min buffer size of the VMCI socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `ZMQ_VMCI_BUFFER_MIN_SIZE` option shall set the min size of the underlying
buffer for the socket. Used during negotiation before the connection is established.

[horizontal]
Option value type:: uint64_t
Option value unit:: bytes
Default value:: 128
Applicable socket types:: all, when using VMCI transport


ZMQ_VMCI_BUFFER_MAX_SIZE: Set max buffer size of the VMCI socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `ZMQ_VMCI_BUFFER_MAX_SIZE` option shall set the max size of the underlying
buffer for the socket. Used during negotiation before the connection is established.

[horizontal]
Option value type:: uint64_t
Option value unit:: bytes
Default value:: 262144
Applicable socket types:: all, when using VMCI transport


ZMQ_VMCI_CONNECT_TIMEOUT: Set connection timeout of the VMCI socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `ZMQ_VMCI_CONNECT_TIMEOUT` option shall set connection timeout
for the socket.

[horizontal]
Option value type:: int
Option value unit:: milliseconds
Default value:: -1
Applicable socket types:: all, when using VMCI transport


ZMQ_MULTICAST_LOOP: Control multicast local loopback
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For multicast UDP sender sockets this option sets whether the data
sent should be looped back on local listening sockets.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 1
Applicable socket types:: ZMQ_RADIO, when using UDP multicast transport


ZMQ_ROUTER_NOTIFY: Send connect and disconnect notifications
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Enable connect and disconnect notifications on a ROUTER socket.
When enabled, the socket delivers a zero-length message (with routing-id
as first frame) when a peer connects or disconnects. It's possible
to notify both events for a peer by OR-ing the flag values. This option
only applies to stream oriented (tcp, ipc) transports.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: 0, ZMQ_NOTIFY_CONNECT, ZMQ_NOTIFY_DISCONNECT, ZMQ_NOTIFY_CONNECT | ZMQ_NOTIFY_DISCONNECT
Default value:: 0
Applicable socket types:: ZMQ_ROUTER


ZMQ_IN_BATCH_SIZE: Maximal receive batch size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the maximal amount of messages that can be received in a single
'recv' system call. WARNING: this option should almost never be changed.
The default has been chosen to offer the best compromise between latency and
throughtput. In the vast majority of cases, changing this option will result in
worst result if not outright breakages.

Cannot be zero.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: messages
Default value:: 8192
Applicable socket types:: All, when using TCP, IPC, PGM or NORM transport.


ZMQ_OUT_BATCH_SIZE: Maximal send batch size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the maximal amount of messages that can be sent in a single
'send' system call. WARNING: this option should almost never be changed.
The default has been chosen to offer the best compromise between latency and
throughtput. In the vast majority of cases, changing this option will result in
worst result if not outright breakages.

Cannot be zero.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: messages
Default value:: 8192
Applicable socket types:: All, when using TCP, IPC, PGM or NORM transport.


ZMQ_NORM_MODE: NORM Sender Mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the NORM sender mode to control the operation of the NORM transport. NORM
supports fixed rate operation (0='ZMQ_NORM_FIXED'), congestion control mode 
(1='ZMQ_NORM_CC'), loss-tolerant congestion control (2='ZMQ_NORM_CCL'), explicit
congestion notification (ECN)-enabled congestion control (3='ZMQ_NORM_CCE'), and
ECN-only congestion control (4='ZMQ_NORM_CCE_ECNONLY'). The default value is 
TCP-friendly congestion control mode. Fixed rate mode (using datarate set by
'ZMQ_RATE') offers better performance, but care must be taken to prevent data
loss.  ECN modes will set one of the ECN Capable Transport bits in the given
'ZMQ_TOS' if it is not set already.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: 0, 1, 2, 3, 4
Default value:: 1 ('ZMQ_NORM_CC')
Applicable socket types:: All, when using NORM transport.


ZMQ_NORM_UNICAST_NACK: Set NORM Unicast NACK mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If set, NORM receiver will send Negative ACKnowledgements (NACKs) back to the
sender using unicast instead of multicast.  NORM transport endpoints specifying
a unicast address will enable this by default, but it is disabled by default for
multicast addresses.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: boolean
Default value:: 0 (false)
Applicable socket types:: All, when using NORM transport.


ZMQ_NORM_BUFFER_SIZE: Set NORM buffer size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets NORM buffer size for NORM transport sender, receiver, and stream.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: kilobytes
Default value:: 2048
Applicable socket types:: All, when using NORM transport.


ZMQ_NORM_SEGMENT_SIZE: Set NORM segment size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets NORM sender segment size, which is the maximum message payload size of
individual NORM messages (ZMQ messages may be split over multiple NORM
messages).  Ideally, this value should fit within the system/network maximum
transmission unit (MTU) after accounting for additional NORM message headers
(up to 48 bytes).

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: bytes
Default value:: 1400
Applicable socket types:: All, when using NORM transport.


ZMQ_NORM_BLOCK_SIZE: Set NORM block size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets NORM sender block size, which is the number of segments in a NORM FEC
coding block. NORM repair operations take place at block boundaries. Maximum
value is 255, but parity packets ('ZMQ_NORM_NUM_PARITY') are limited to a value
of (255 - 'ZMQ_NORM_BLOCK_SIZE'). Minimum value is ('ZMQ_NORM_NUM_PARITY' + 1).
Effective value may be different based on the settings of 'ZMQ_NORM_NUM_PARITY'
and 'ZMQ_NORM_NUM_AUTOPARITY' if invalid settings are provided.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: >0, <=255
Default value:: 16
Applicable socket types:: All, when using NORM transport.


ZMQ_NORM_NUM_PARITY: Set number of NORM parity segments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the maximum number of NORM parity symbol segments that the sender is
willing to calculate per FEC coding block for the purpose of reparing lost data.
Maximum value is 255, but is further limited to a value of
(255 - 'ZMQ_NORM_BLOCK_SIZE'). Minimum value is 'ZMQ_NORM_NUM_AUTOPARITY'.
Effective value may be different based on the setting of
'ZMQ_NORM_NUM_AUTOPARITY' if invalid settings are provided.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: >0, <255
Default value:: 4
Applicable socket types:: All, when using NORM transport.


ZMQ_NORM_NUM_AUTOPARITY: Set number of proactive NORM parity segments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the number of NORM parity symbol segments that the sender will proactively
send at the end of each FEC coding block. By default, no proactive parity
segments will be sent; instead, parity segments will only be sent in response to
repair requests (NACKs). Maximum value is 255, but is further limited to a 
maximum value of 'ZMQ_NORM_NUM_PARITY'.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: >=0, <255
Default value:: 0
Applicable socket types:: All, when using NORM transport.


ZMQ_NORM_PUSH: Enable NORM push mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Enables NORM stream push mode, which alters the behavior of the sender when
enqueueing new data. By default, NORM will stop accepting new messages while
waiting for old data to be transmitted and/or repaired. Enabling push mode
discards the oldest data (which may be pending repair or may never have been
transmitted) in favor of accepting new data. This may be useful in cases where
it is more important to quickly deliver new data instead of reliably delivering
older data.

NOTE: in DRAFT state, not yet available in stable releases.

[horizontal]
Option value type:: int
Option value unit:: boolean
Default value:: 0 (false)
Applicable socket types:: All, when using NORM transport.


== RETURN VALUE
The _zmq_setsockopt()_ 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.
*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
.Subscribing to messages on a 'ZMQ_SUB' socket
----
/* Subscribe to all messages */
rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "", 0);
assert (rc == 0);
/* Subscribe to messages prefixed with "ANIMALS.CATS" */
rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "ANIMALS.CATS", 12);
----

.Setting I/O thread affinity
----
int64_t affinity;
/* Incoming connections on TCP port 5555 shall be handled by I/O thread 1 */
affinity = 1;
rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof (affinity));
assert (rc);
rc = zmq_bind (socket, "tcp://lo:5555");
assert (rc);
/* Incoming connections on TCP port 5556 shall be handled by I/O thread 2 */
affinity = 2;
rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof (affinity));
assert (rc);
rc = zmq_bind (socket, "tcp://lo:5556");
assert (rc);
----


== SEE ALSO
* xref:zmq_getsockopt.adoc[zmq_getsockopt]
* xref:zmq_socket.adoc[zmq_socket]
* xref:zmq_plain.adoc[zmq_plain]
* xref:zmq_curve.adoc[zmq_curve]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Socket (`doc/zmq_socket.adoc`)

= zmq_socket(3)


== NAME
zmq_socket - create 0MQ socket


== SYNOPSIS
*void *zmq_socket (void '*context', int 'type');*


== DESCRIPTION
The 'zmq_socket()' function shall create a 0MQ socket within the specified
'context' and return an opaque handle to the newly created socket. The 'type'
argument specifies the socket type, which determines the semantics of
communication over the socket.

The newly created socket is initially unbound, and not associated with any
endpoints. In order to establish a message flow a socket must first be
connected to at least one endpoint with xref:zmq_connect.adoc[zmq_connect], or at least one
endpoint must be created for accepting incoming connections with
xref:zmq_bind.adoc[zmq_bind]

.Key differences to conventional sockets
Generally speaking, conventional sockets present a _synchronous_ interface to
either connection-oriented reliable byte streams (SOCK_STREAM), or
connection-less unreliable datagrams (SOCK_DGRAM). In comparison, 0MQ sockets
present an abstraction of an asynchronous _message queue_, with the exact
queueing semantics depending on the socket type in use. Where conventional
sockets transfer streams of bytes or discrete datagrams, 0MQ sockets transfer
discrete _messages_.

0MQ sockets being _asynchronous_ means that the timings of the physical
connection setup and tear down, reconnect and effective delivery are transparent
to the user and organized by 0MQ itself. Further, messages may be _queued_ in
the event that a peer is unavailable to receive them.

Conventional sockets allow only strict one-to-one (two peers), many-to-one
(many clients, one server), or in some cases one-to-many (multicast)
relationships. With the exception of 'ZMQ_PAIR' and 'ZMQ_CHANNEL', 0MQ sockets may be connected
*to multiple endpoints* using _zmq_connect()_, while simultaneously accepting
incoming connections *from multiple endpoints* bound to the socket using
_zmq_bind()_, thus allowing many-to-many relationships.

.Thread safety
0MQ has both thread safe socket type and _not_ thread safe socket types.
Applications MUST NOT use a _not_ thread safe socket
from multiple threads under any circumstances. Doing so results in undefined
behaviour.

Following are the thread safe sockets:
* ZMQ_CLIENT
* ZMQ_SERVER
* ZMQ_DISH
* ZMQ_RADIO
* ZMQ_SCATTER
* ZMQ_GATHER
* ZMQ_PEER
* ZMQ_CHANNEL

.Socket types
The following sections present the socket types defined by 0MQ, grouped by the
general _messaging pattern_ which is built from related socket types.


Client-server pattern
~~~~~~~~~~~~~~~~~~~~~

The client-server pattern is used to allow a single 'ZMQ_SERVER' _server_ talk
to one or more 'ZMQ_CLIENT' _clients_. The client always starts the conversation,
after which either peer can send messages asynchronously, to the other.

The client-server pattern is formally defined by http://rfc.zeromq.org/spec:41.

NOTE: Server-client is still in draft phase.

ZMQ_CLIENT
^^^^^^^^^^
A 'ZMQ_CLIENT' socket talks to a 'ZMQ_SERVER' socket. Either peer can connect,
though the usual and recommended model is to bind the 'ZMQ_SERVER' and connect
the 'ZMQ_CLIENT'.

If the 'ZMQ_CLIENT' socket has established a connection, xref:zmq_send.adoc[zmq_send]
will accept messages, queue them, and send them as rapidly as the network
allows. The outgoing buffer limit is defined by the high water mark for the
socket. If the outgoing buffer is full, or, for connection-oriented transports,
if the ZMQ_IMMEDIATE option is set and there is no connected peer,
xref:zmq_send.adoc[zmq_send] will block.
The 'ZMQ_CLIENT' socket will not drop messages.

When a 'ZMQ_CLIENT' socket is connected to multiple 'ZMQ_SERVER' sockets,
outgoing messages are distributed between connected peers on a round-robin
basis. Likewise, the 'ZMQ_CLIENT' socket receives messages fairly from each
connected peer. This usage is sensible only for stateless protocols.

'ZMQ_CLIENT' sockets are threadsafe and can be used from multiple threads
at the same time. Note that replies from a 'ZMQ_SERVER' socket will go to
the first client thread that calls xref:zmq_msg_recv.adoc[zmq_msg_recv] If you need to get
replies back to the originating thread, use one 'ZMQ_CLIENT' socket per
thread.

NOTE: 'ZMQ_CLIENT' sockets are threadsafe. They do not accept the ZMQ_SNDMORE
option on sends not ZMQ_RCVMORE on receives. This limits them to single part
data. The intention is to extend the API to allow scatter/gather of multi-part
data.

[horizontal]
.Summary of ZMQ_CLIENT characteristics
Compatible peer sockets:: 'ZMQ_SERVER'
Direction:: Bidirectional
Send/receive pattern:: Unrestricted
Outgoing routing strategy:: Round-robin
Incoming routing strategy:: Fair-queued
Action in mute state:: Block


ZMQ_SERVER
^^^^^^^^^^
A 'ZMQ_SERVER' socket talks to a set of 'ZMQ_CLIENT' sockets. A 'ZMQ_SERVER'
socket can only reply to an incoming message: the 'ZMQ_CLIENT' peer must
always initiate a conversation.

Each received message has a 'routing_id' that is a 32-bit unsigned integer.
The application can fetch this with xref:zmq_msg_routing_id.adoc[zmq_msg_routing_id] To send
a message to a given 'ZMQ_CLIENT' peer the application must set the peer's
'routing_id' on the message, using xref:zmq_msg_set_routing_id.adoc[zmq_msg_set_routing_id]

If the 'routing_id' is not specified, or does not refer to a connected client
peer, the send call will fail with EHOSTUNREACH. If the outgoing buffer for
the client peer is full, the send call shall block, unless ZMQ_DONTWAIT is
used in the send, in which case it shall fail with EAGAIN. The 'ZMQ_SERVER'
socket shall not drop messages in any case.

NOTE: 'ZMQ_SERVER' sockets are threadsafe. They do not accept the ZMQ_SNDMORE
option on sends not ZMQ_RCVMORE on receives. This limits them to single part
data. The intention is to extend the API to allow scatter/gather of multi-part
data.

[horizontal]
.Summary of ZMQ_SERVER characteristics
Compatible peer sockets:: 'ZMQ_CLIENT'
Direction:: Bidirectional
Send/receive pattern:: Unrestricted
Outgoing routing strategy:: See text
Incoming routing strategy:: Fair-queued
Action in mute state:: Return EAGAIN


Radio-dish pattern
~~~~~~~~~~~~~~~~~~

The radio-dish pattern is used for one-to-many distribution of data from
a single _publisher_ to multiple _subscribers_ in a fan out fashion.

Radio-dish is using groups (vs Pub-sub topics), Dish sockets can join a group
and each message sent by Radio sockets belong to a group.

Groups are null terminated strings limited to 16 chars length (including null).
The intention is to increase the length to 40 chars (including null).
The encoding of groups shall be UTF8.

Groups are matched using exact matching (vs prefix matching of PubSub).

NOTE: Radio-dish is still in draft phase.

ZMQ_RADIO
^^^^^^^^^
A socket of type 'ZMQ_RADIO' is used by a _publisher_ to distribute data.
Each message belong to a group, a group is specified with xref:zmq_msg_set_group.adoc[zmq_msg_set_group]
Messages are distributed to all members of a group.
The xref:zmq_recv.adoc[zmq_recv] function is not implemented for this socket type.

When a 'ZMQ_RADIO' socket enters the 'mute' state due to having reached the
high water mark for a _subscriber_, then any messages that would be sent to the
_subscriber_ in question shall instead be dropped until the mute state
ends. The _zmq_send()_ function shall never block for this socket type.

NOTE: 'ZMQ_RADIO' sockets are threadsafe. They do not accept the ZMQ_SNDMORE
option on sends. This limits them to single part data.

[horizontal]
.Summary of ZMQ_RADIO characteristics
Compatible peer sockets:: 'ZMQ_DISH'
Direction:: Unidirectional
Send/receive pattern:: Send only
Incoming routing strategy:: N/A
Outgoing routing strategy:: Fan out
Action in mute state:: Drop


ZMQ_DISH
^^^^^^^^
A socket of type 'ZMQ_DISH' is used by a _subscriber_ to subscribe to groups
distributed by a _radio_. Initially a 'ZMQ_DISH' socket is not subscribed to
any groups, use xref:zmq_join.adoc[zmq_join] to
join a group.
To get the group the message belong to call xref:zmq_msg_group.adoc[zmq_msg_group]
The _zmq_send()_ function is not implemented for this socket type.

NOTE: 'ZMQ_DISH' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives.
This limits them to single part data.

[horizontal]
.Summary of ZMQ_DISH characteristics
Compatible peer sockets:: 'ZMQ_RADIO'
Direction:: Unidirectional
Send/receive pattern:: Receive only
Incoming routing strategy:: Fair-queued
Outgoing routing strategy:: N/A


Publish-subscribe pattern
~~~~~~~~~~~~~~~~~~~~~~~~~
The publish-subscribe pattern is used for one-to-many distribution of data from
a single _publisher_ to multiple _subscribers_ in a fan out fashion.

The publish-subscribe pattern is formally defined by http://rfc.zeromq.org/spec:29.

ZMQ_PUB
^^^^^^^
A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data.
Messages sent are distributed in a fan out fashion to all connected peers.
The xref:zmq_recv.adoc[zmq_recv] function is not implemented for this socket type.

When a 'ZMQ_PUB' socket enters the 'mute' state due to having reached the
high water mark for a _subscriber_, then any messages that would be sent to the
_subscriber_ in question shall instead be dropped until the mute state
ends. The _zmq_send()_ function shall never block for this socket type.

[horizontal]
.Summary of ZMQ_PUB characteristics
Compatible peer sockets:: 'ZMQ_SUB', 'ZMQ_XSUB'
Direction:: Unidirectional
Send/receive pattern:: Send only
Incoming routing strategy:: N/A
Outgoing routing strategy:: Fan out
Action in mute state:: Drop


ZMQ_SUB
^^^^^^^
A socket of type 'ZMQ_SUB' is used by a _subscriber_ to subscribe to data
distributed by a _publisher_. Initially a 'ZMQ_SUB' socket is not subscribed to
any messages, use the 'ZMQ_SUBSCRIBE' option of xref:zmq_setsockopt.adoc[zmq_setsockopt] to
specify which messages to subscribe to. The _zmq_send()_ function is not
implemented for this socket type.

[horizontal]
.Summary of ZMQ_SUB characteristics
Compatible peer sockets:: 'ZMQ_PUB', 'ZMQ_XPUB'
Direction:: Unidirectional
Send/receive pattern:: Receive only
Incoming routing strategy:: Fair-queued
Outgoing routing strategy:: N/A


ZMQ_XPUB
^^^^^^^^
Same as ZMQ_PUB except that you can receive subscriptions from the peers
in form of incoming messages. Subscription message is a byte 1 (for
subscriptions) or byte 0 (for unsubscriptions) followed by the subscription
body. Messages without a sub/unsub prefix are also received, but have no
effect on subscription status.

[horizontal]
.Summary of ZMQ_XPUB characteristics
Compatible peer sockets:: 'ZMQ_SUB', 'ZMQ_XSUB'
Direction:: Unidirectional
Send/receive pattern:: Send messages, receive subscriptions
Incoming routing strategy:: N/A
Outgoing routing strategy:: Fan out
Action in mute state:: Drop


ZMQ_XSUB
^^^^^^^^
Same as ZMQ_SUB except that you subscribe by sending subscription messages to
the socket. Subscription message is a byte 1 (for subscriptions) or byte 0
(for unsubscriptions) followed by the subscription body. Messages without a
sub/unsub prefix may also be sent, but have no effect on subscription status.

[horizontal]
.Summary of ZMQ_XSUB characteristics
Compatible peer sockets:: 'ZMQ_PUB', 'ZMQ_XPUB'
Direction:: Unidirectional
Send/receive pattern:: Receive messages, send subscriptions
Incoming routing strategy:: Fair-queued
Outgoing routing strategy:: N/A
Action in mute state:: Drop


Pipeline pattern
~~~~~~~~~~~~~~~~
The pipeline pattern is used for distributing data to _nodes_ arranged in
a pipeline. Data always flows down the pipeline, and each stage of the pipeline
is connected to at least one _node_. When a pipeline stage is connected to
multiple _nodes_ data is round-robined among all connected _nodes_.

The pipeline pattern is formally defined by http://rfc.zeromq.org/spec:30.

ZMQ_PUSH
^^^^^^^^
A socket of type 'ZMQ_PUSH' is used by a pipeline _node_ to send messages
to downstream pipeline _nodes_. Messages are round-robined to all connected
downstream _nodes_. The _zmq_recv()_ function is not implemented for this
socket type.

When a 'ZMQ_PUSH' socket enters the 'mute' state due to having reached the
high water mark for all downstream _nodes_, or, for connection-oriented transports,
if the ZMQ_IMMEDIATE option is set and there are no downstream _nodes_ at all,
then any xref:zmq_send.adoc[zmq_send] operations on the socket shall block until the mute
state ends or at least one downstream _node_ becomes available for sending;
messages are not discarded.

[horizontal]
.Summary of ZMQ_PUSH characteristics
Compatible peer sockets:: 'ZMQ_PULL'
Direction:: Unidirectional
Send/receive pattern:: Send only
Incoming routing strategy:: N/A
Outgoing routing strategy:: Round-robin
Action in mute state:: Block


ZMQ_PULL
^^^^^^^^
A socket of type 'ZMQ_PULL' is used by a pipeline _node_ to receive messages
from upstream pipeline _nodes_. Messages are fair-queued from among all
connected upstream _nodes_. The _zmq_send()_ function is not implemented for
this socket type.

[horizontal]
.Summary of ZMQ_PULL characteristics
Compatible peer sockets:: 'ZMQ_PUSH'
Direction:: Unidirectional
Send/receive pattern:: Receive only
Incoming routing strategy:: Fair-queued
Outgoing routing strategy:: N/A
Action in mute state:: Block

Scatter-gather pattern
~~~~~~~~~~~~~~~~~~~~~~
The scatter-gather pattern is the thread-safe version of the pipeline pattern.
The scatter-gather pattern is used for distributing data to _nodes_ arranged in
a pipeline. Data always flows down the pipeline, and each stage of the pipeline
is connected to at least one _node_. When a pipeline stage is connected to
multiple _nodes_ data is round-robined among all connected _nodes_.

ZMQ_SCATTER
^^^^^^^^^^^
A socket of type 'ZMQ_SCATTER' is used by a scatter-gather _node_ to send messages
to downstream scatter-gather _nodes_. Messages are round-robined to all connected
downstream _nodes_. The _zmq_recv()_ function is not implemented for this
socket type.

When a 'ZMQ_SCATTER' socket enters the 'mute' state due to having reached the
high water mark for all downstream _nodes_, or, for connection-oriented transports,
if the ZMQ_IMMEDIATE option is set and there are no downstream _nodes_ at all,
then any xref:zmq_send.adoc[zmq_send] operations on the socket shall block until the mute
state ends or at least one downstream _node_ becomes available for sending;
messages are not discarded.

NOTE: 'ZMQ_SCATTER' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives.
This limits them to single part data.

[horizontal]
.Summary of ZMQ_SCATTER characteristics
Compatible peer sockets:: 'ZMQ_SCATTER'
Direction:: Unidirectional
Send/receive pattern:: Send only
Incoming routing strategy:: N/A
Outgoing routing strategy:: Round-robin
Action in mute state:: Block


ZMQ_GATHER
^^^^^^^^^^
A socket of type 'ZMQ_GATHER' is used by a scatter-gather _node_ to receive messages
from upstream scatter-gather _nodes_. Messages are fair-queued from among all
connected upstream _nodes_. The _zmq_send()_ function is not implemented for
this socket type.

NOTE: 'ZMQ_GATHER' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives.
This limits them to single part data.

[horizontal]
.Summary of ZMQ_GATHER characteristics
Compatible peer sockets:: 'ZMQ_GATHER'
Direction:: Unidirectional
Send/receive pattern:: Receive only
Incoming routing strategy:: Fair-queued
Outgoing routing strategy:: N/A
Action in mute state:: Block


Exclusive pair pattern
~~~~~~~~~~~~~~~~~~~~~~
The exclusive pair pattern is used to connect a peer to precisely one other
peer. This pattern is used for inter-thread communication across the inproc
transport.

The exclusive pair pattern is formally defined by http://rfc.zeromq.org/spec:31.

ZMQ_PAIR
^^^^^^^^
A socket of type 'ZMQ_PAIR' can only be connected to a single peer at any one
time.  No message routing or filtering is performed on messages sent over a
'ZMQ_PAIR' socket.

When a 'ZMQ_PAIR' socket enters the 'mute' state due to having reached the
high water mark for the connected peer, or, for connection-oriented transports,
if the ZMQ_IMMEDIATE option is set and there is no connected peer, then
any xref:zmq_send.adoc[zmq_send] operations on the socket shall block until the peer
becomes available for sending; messages are not discarded.

While 'ZMQ_PAIR' sockets can be used over transports other than xref:zmq_inproc.adoc[zmq_inproc],
their inability to auto-reconnect coupled with the fact new incoming connections will
be terminated while any previous connections (including ones in a closing state)
exist makes them unsuitable for TCP in most cases.

NOTE: 'ZMQ_PAIR' sockets are designed for inter-thread communication across
the xref:zmq_inproc.adoc[zmq_inproc] transport and do not implement functionality such
as auto-reconnection.

[horizontal]
.Summary of ZMQ_PAIR characteristics
Compatible peer sockets:: 'ZMQ_PAIR'
Direction:: Bidirectional
Send/receive pattern:: Unrestricted
Incoming routing strategy:: N/A
Outgoing routing strategy:: N/A
Action in mute state:: Block


Peer-to-peer pattern
~~~~~~~~~~~~~~~~~~~~

The peer-to-peer pattern is used to connect a peer to multiple peers.
Peer can both connect and bind and mix both of them with the same socket.
The peer-to-peer pattern is useful to build peer-to-peer networks (e.g zyre, bitcoin, torrent)
where a peer can both accept connections from other peers or connect to them.

NOTE: Peer-to-peer is still in draft phase.

ZMQ_PEER
^^^^^^^^
A 'ZMQ_PEER' socket talks to a set of 'ZMQ_PEER' sockets.

To connect and fetch the 'routing_id' of the peer use xref:zmq_connect_peer.adoc[zmq_connect_peer]
and to disconnect a specific peer by its 'routing_id' use xref:zmq_disconnect_peer.adoc[zmq_disconnect_peer].

Each received message has a 'routing_id' that is a 32-bit unsigned integer.
The application can fetch this with xref:zmq_msg_routing_id.adoc[zmq_msg_routing_id]

To send a message to a given 'ZMQ_PEER' peer the application must set the peer's
'routing_id' on the message, using xref:zmq_msg_set_routing_id.adoc[zmq_msg_set_routing_id]

If the 'routing_id' is not specified, or does not refer to a connected client
peer, the send call will fail with EHOSTUNREACH. If the outgoing buffer for
the peer is full, the send call shall block, unless ZMQ_DONTWAIT is
used in the send, in which case it shall fail with EAGAIN. The 'ZMQ_PEER'
socket shall not drop messages in any case.

NOTE: 'ZMQ_PEER' sockets are threadsafe. They do not accept the ZMQ_SNDMORE
option on sends not ZMQ_RCVMORE on receives. This limits them to single part
data.

[horizontal]
.Summary of ZMQ_PEER characteristics
Compatible peer sockets:: 'ZMQ_PEER'
Direction:: Bidirectional
Send/receive pattern:: Unrestricted
Outgoing routing strategy:: See text
Incoming routing strategy:: Fair-queued
Action in mute state:: Return EAGAIN

Channel pattern
~~~~~~~~~~~~~~~
The channel pattern is the thread-safe version of the exclusive pair pattern.
The channel pattern is used to connect a peer to precisely one other
peer. This pattern is used for inter-thread communication across the inproc
transport.

NOTE: Channel is still in draft phase.

ZMQ_CHANNEL
^^^^^^^^^^^
A socket of type 'ZMQ_CHANNEL' can only be connected to a single peer at any one
time.  No message routing or filtering is performed on messages sent over a
'ZMQ_CHANNEL' socket.

When a 'ZMQ_CHANNEL' socket enters the 'mute' state due to having reached the
high water mark for the connected peer, or, for connection-oriented transports,
if the ZMQ_IMMEDIATE option is set and there is no connected peer, then
any xref:zmq_send.adoc[zmq_send] operations on the socket shall block until the peer
becomes available for sending; messages are not discarded.

While 'ZMQ_CHANNEL' sockets can be used over transports other than xref:zmq_inproc.adoc[zmq_inproc],
their inability to auto-reconnect coupled with the fact new incoming connections will
be terminated while any previous connections (including ones in a closing state)
exist makes them unsuitable for TCP in most cases.

NOTE: 'ZMQ_CHANNEL' sockets are designed for inter-thread communication across
the xref:zmq_inproc.adoc[zmq_inproc] transport and do not implement functionality such
as auto-reconnection.

NOTE: 'ZMQ_CHANNEL' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives.
This limits them to single part data.

[horizontal]
.Summary of ZMQ_CHANNEL characteristics
Compatible peer sockets:: 'ZMQ_CHANNEL'
Direction:: Bidirectional
Send/receive pattern:: Unrestricted
Incoming routing strategy:: N/A
Outgoing routing strategy:: N/A
Action in mute state:: Block

Native Pattern
~~~~~~~~~~~~~~
The native pattern is used for communicating with TCP peers and allows
asynchronous requests and replies in either direction.


ZMQ_STREAM
^^^^^^^^^^
A socket of type 'ZMQ_STREAM' is used to send and receive TCP data from a
non-0MQ peer, when using the tcp:// transport. A 'ZMQ_STREAM' socket can
act as client and/or server, sending and/or receiving TCP data asynchronously.

When receiving TCP data, a 'ZMQ_STREAM' socket shall prepend a message part
containing the _routing id_ of the originating peer to the message before passing
it to the application. Messages received are fair-queued from among all
connected peers.

When sending TCP data, a 'ZMQ_STREAM' socket shall remove the first part of the
message and use it to determine the _routing id_ of the peer the message shall be
routed to, and unroutable messages shall cause an EHOSTUNREACH or EAGAIN error.

To open a connection to a server, use the zmq_connect call, and then fetch the
socket routing id using the zmq_getsockopt call with the ZMQ_ROUTING_ID option.

To close a specific connection, send the routing id frame followed by a
zero-length message (see EXAMPLE section).

When a connection is made, a zero-length message will be received by the
application.  Similarly, when the peer disconnects (or the connection is lost),
a zero-length message will be received by the application.

You must send one routing id frame followed by one data frame. The ZMQ_SNDMORE
flag is required for routing id frames but is ignored on data frames.

[horizontal]
.Summary of ZMQ_STREAM characteristics
Compatible peer sockets:: none.
Direction:: Bidirectional
Send/receive pattern:: Unrestricted
Outgoing routing strategy:: See text
Incoming routing strategy:: Fair-queued
Action in mute state:: EAGAIN


Request-reply pattern
~~~~~~~~~~~~~~~~~~~~~
The request-reply pattern is used for sending requests from a ZMQ_REQ _client_
to one or more ZMQ_REP _services_, and receiving subsequent replies to each
request sent.

The request-reply pattern is formally defined by http://rfc.zeromq.org/spec:28.

ZMQ_REQ
^^^^^^^
A socket of type 'ZMQ_REQ' is used by a _client_ to send requests to and
receive replies from a _service_. This socket type allows only an alternating
sequence of _zmq_send(request)_ and subsequent _zmq_recv(reply)_ calls. Each
request sent is round-robined among all _services_, and each reply received is
matched with the last issued request.

For connection-oriented transports, If the ZMQ_IMMEDIATE option is set and there
is no service available, then any send operation on the socket shall block until
at least one _service_ becomes available. The REQ socket shall not discard messages.

[horizontal]
.Summary of ZMQ_REQ characteristics
Compatible peer sockets:: 'ZMQ_REP', 'ZMQ_ROUTER'
Direction:: Bidirectional
Send/receive pattern:: Send, Receive, Send, Receive, ...
Outgoing routing strategy:: Round-robin
Incoming routing strategy:: Last peer
Action in mute state:: Block


ZMQ_REP
^^^^^^^
A socket of type 'ZMQ_REP' is used by a _service_ to receive requests from and
send replies to a _client_. This socket type allows only an alternating
sequence of _zmq_recv(request)_ and subsequent _zmq_send(reply)_ calls. Each
request received is fair-queued from among all _clients_, and each reply sent
is routed to the _client_ that issued the last request. If the original
requester does not exist any more the reply is silently discarded.

[horizontal]
.Summary of ZMQ_REP characteristics
Compatible peer sockets:: 'ZMQ_REQ', 'ZMQ_DEALER'
Direction:: Bidirectional
Send/receive pattern:: Receive, Send, Receive, Send, ...
Incoming routing strategy:: Fair-queued
Outgoing routing strategy:: Last peer


ZMQ_DEALER
^^^^^^^^^^
A socket of type 'ZMQ_DEALER' is an advanced pattern used for extending
request/reply sockets. Each message sent is round-robined among all connected
peers, and each message received is fair-queued from all connected peers.

When a 'ZMQ_DEALER' socket enters the 'mute' state due to having reached the
high water mark for all peers, or, for connection-oriented transports, if the
ZMQ_IMMEDIATE option is set and there are no peers at all, then any
xref:zmq_send.adoc[zmq_send] operations on the socket shall block until the mute state
ends or at least one peer becomes available for sending; messages are not discarded.

When a 'ZMQ_DEALER' socket is connected to a 'ZMQ_REP' socket each message sent
must consist of an empty message part, the _delimiter_, followed by one or more
_body parts_.

[horizontal]
.Summary of ZMQ_DEALER characteristics
Compatible peer sockets:: 'ZMQ_ROUTER', 'ZMQ_REP', 'ZMQ_DEALER'
Direction:: Bidirectional
Send/receive pattern:: Unrestricted
Outgoing routing strategy:: Round-robin
Incoming routing strategy:: Fair-queued
Action in mute state:: Block


ZMQ_ROUTER
^^^^^^^^^^
A socket of type 'ZMQ_ROUTER' is an advanced socket type used for extending
request/reply sockets. When receiving messages a 'ZMQ_ROUTER' socket shall
prepend a message part containing the _routing id_ of the originating peer to the
message before passing it to the application. Messages received are fair-queued
from among all connected peers. When sending messages a 'ZMQ_ROUTER' socket shall
remove the first part of the message and use it to determine the _routing id _ of
the peer the message shall be routed to. If the peer does not exist anymore, or
has never existed, the message shall be silently discarded. However, if
'ZMQ_ROUTER_MANDATORY' socket option is set to '1', the socket shall fail
with EHOSTUNREACH in both cases.

When a 'ZMQ_ROUTER' socket enters the 'mute' state due to having reached the
high water mark for all peers, then any messages sent to the socket shall be dropped
until the mute state ends. Likewise, any messages routed to a peer for which
the individual high water mark has been reached shall also be dropped. If,
'ZMQ_ROUTER_MANDATORY' is set to '1', the socket shall block or return EAGAIN in
both cases.

When a 'ZMQ_ROUTER' socket has 'ZMQ_ROUTER_MANDATORY' flag set to '1', the
socket shall generate 'ZMQ_POLLIN' events upon reception of messages from one
or more peers. Likewise, the socket shall generate 'ZMQ_POLLOUT' events when
at least one message can be sent to one or more peers.

When a 'ZMQ_REQ' socket is connected to a 'ZMQ_ROUTER' socket, in addition to the
_routing id_ of the originating peer each message received shall contain an empty
_delimiter_ message part. Hence, the entire structure of each received message
as seen by the application becomes: one or more _routing id_ parts, _delimiter_
part, one or more _body parts_. When sending replies to a 'ZMQ_REQ' socket the
application must include the _delimiter_ part.

[horizontal]
.Summary of ZMQ_ROUTER characteristics
Compatible peer sockets:: 'ZMQ_DEALER', 'ZMQ_REQ', 'ZMQ_ROUTER'
Direction:: Bidirectional
Send/receive pattern:: Unrestricted
Outgoing routing strategy:: See text
Incoming routing strategy:: Fair-queued
Action in mute state:: Drop (see text)


== RETURN VALUE
The _zmq_socket()_ function shall return an opaque handle to the newly created
socket if successful. Otherwise, it shall return NULL and set 'errno' to one of
the values defined below.


== ERRORS
*EINVAL*::
The requested socket 'type' is invalid.
*EFAULT*::
The provided 'context' is invalid.
*EMFILE*::
The limit on the total number of open 0MQ sockets has been reached.
*ETERM*::
The context specified was shutdown or terminated.

== EXAMPLE
.Creating a simple HTTP server using ZMQ_STREAM
----
void *ctx = zmq_ctx_new ();
assert (ctx);
/* Create ZMQ_STREAM socket */
void *socket = zmq_socket (ctx, ZMQ_STREAM);
assert (socket);
int rc = zmq_bind (socket, "tcp://*:8080");
assert (rc == 0);
/* Data structure to hold the ZMQ_STREAM routing id */
uint8_t routing_id [256];
size_t routing_id_size = 256;
/* Data structure to hold the ZMQ_STREAM received data */
uint8_t raw [256];
size_t raw_size = 256;
while (1) {
	/*  Get HTTP request; routing id frame and then request */
	routing_id_size = zmq_recv (socket, routing_id, 256, 0);
	assert (routing_id_size > 0);
	do {
		raw_size = zmq_recv (socket, raw, 256, 0);
		assert (raw_size >= 0);
	} while (raw_size == 256);
	/* Prepares the response */
	char http_response [] =
		"HTTP/1.0 200 OK\r\n"
		"Content-Type: text/plain\r\n"
		"\r\n"
		"Hello, World!";
	/* Sends the routing id frame followed by the response */
	zmq_send (socket, routing_id, routing_id_size, ZMQ_SNDMORE);
	zmq_send (socket, http_response, strlen (http_response), 0);
	/* Closes the connection by sending the routing id frame followed by a zero response */
	zmq_send (socket, routing_id, routing_id_size, ZMQ_SNDMORE);
	zmq_send (socket, 0, 0, 0);
}
zmq_close (socket);
zmq_ctx_destroy (ctx);
----


== SEE ALSO
* xref:zmq_init.adoc[zmq_init]
* xref:zmq_setsockopt.adoc[zmq_setsockopt]
* xref:zmq_bind.adoc[zmq_bind]
* xref:zmq_connect.adoc[zmq_connect]
* xref:zmq_send.adoc[zmq_send]
* xref:zmq_recv.adoc[zmq_recv]
* xref:zmq_inproc.adoc[zmq_inproc]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Socket Monitor (`doc/zmq_socket_monitor.adoc`)

= zmq_socket_monitor(3)


== NAME

zmq_socket_monitor - monitor socket events


== SYNOPSIS
*int zmq_socket_monitor (void '*socket', char '*endpoint', int 'events');*


== DESCRIPTION
The _zmq_socket_monitor()_ method lets an application thread track
socket events (like connects) on a ZeroMQ socket. Each call to this
method creates a 'ZMQ_PAIR' socket and binds that to the specified
inproc:// 'endpoint'. To collect the socket events, you must create
your own 'ZMQ_PAIR' socket, and connect that to the endpoint.

Note that there is also a DRAFT function xref:zmq_socket_monitor_versioned.adoc[zmq_socket_monitor_versioned],
which allows to subscribe to events that provide more information.
Calling zmq_socket_monitor is equivalent to calling 'zmq_socket_monitor_versioned'
with the 'event_version' parameter set to 1, with the exception of error cases.

The 'events' argument is a bitmask of the socket events you wish to
monitor, see 'Supported events' below. To monitor all events, use the
event value ZMQ_EVENT_ALL. NOTE: as new events are added, the catch-all
value will start returning them. An application that relies on a strict
and fixed sequence of events must not use ZMQ_EVENT_ALL in order to
guarantee compatibility with future versions.

Each event is sent as two frames. The first frame contains an event
number (16 bits), and an event value (32 bits) that provides additional
data according to the event number. The second frame contains a string
that specifies the affected endpoint.

----
The _zmq_socket_monitor()_ method supports only connection-oriented
transports, that is, TCP, IPC, and TIPC.
----

Supported events
----------------

ZMQ_EVENT_CONNECTED
~~~~~~~~~~~~~~~~~~~
The socket has successfully connected to a remote peer. The event value
is the file descriptor (FD) of the underlying network socket. Warning:
there is no guarantee that the FD is still valid by the time your code
receives this event.

ZMQ_EVENT_CONNECT_DELAYED
~~~~~~~~~~~~~~~~~~~~~~~~~
A connect request on the socket is pending. The event value is unspecified.

ZMQ_EVENT_CONNECT_RETRIED
~~~~~~~~~~~~~~~~~~~~~~~~~
A connect request failed, and is now being retried. The event value is the
reconnect interval in milliseconds. Note that the reconnect interval is
recalculated at each retry.

ZMQ_EVENT_LISTENING
~~~~~~~~~~~~~~~~~~~
The socket was successfully bound to a network interface. The event value
is the FD of the underlying network socket. Warning: there is no guarantee
that the FD is still valid by the time your code receives this event.

ZMQ_EVENT_BIND_FAILED
~~~~~~~~~~~~~~~~~~~~~
The socket could not bind to a given interface. The event value is the
errno generated by the system bind call.

ZMQ_EVENT_ACCEPTED
~~~~~~~~~~~~~~~~~~
The socket has accepted a connection from a remote peer. The event value is
the FD of the underlying network socket. Warning: there is no guarantee that
the FD is still valid by the time your code receives this event.

ZMQ_EVENT_ACCEPT_FAILED
~~~~~~~~~~~~~~~~~~~~~~~
The socket has rejected a connection from a remote peer. The event value is
the errno generated by the accept call.

ZMQ_EVENT_CLOSED
~~~~~~~~~~~~~~~~
The socket was closed. The event value is the FD of the (now closed) network
socket.

ZMQ_EVENT_CLOSE_FAILED
~~~~~~~~~~~~~~~~~~~~~~
The socket close failed. The event value is the errno returned by the system
call. Note that this event occurs only on IPC transports.

ZMQ_EVENT_DISCONNECTED
~~~~~~~~~~~~~~~~~~~~~~
The socket was disconnected unexpectedly. The event value is the FD of the
underlying network socket. Warning: this socket will be closed.

ZMQ_EVENT_MONITOR_STOPPED
~~~~~~~~~~~~~~~~~~~~~~~~~
Monitoring on this socket ended.

ZMQ_EVENT_HANDSHAKE_FAILED_NO_DETAIL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Unspecified error during handshake.
The event value is an errno.

ZMQ_EVENT_HANDSHAKE_SUCCEEDED
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ZMTP security mechanism handshake succeeded.
The event value is unspecified.

ZMQ_EVENT_HANDSHAKE_FAILED_PROTOCOL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ZMTP security mechanism handshake failed due to some mechanism protocol
error, either between the ZMTP mechanism peers, or between the mechanism
server and the ZAP handler. This indicates a configuration or implementation
error in either peer resp. the ZAP handler.
The event value is one of the ZMQ_PROTOCOL_ERROR_* values:
ZMQ_PROTOCOL_ERROR_ZMTP_UNSPECIFIED
ZMQ_PROTOCOL_ERROR_ZMTP_UNEXPECTED_COMMAND
ZMQ_PROTOCOL_ERROR_ZMTP_INVALID_SEQUENCE
ZMQ_PROTOCOL_ERROR_ZMTP_KEY_EXCHANGE
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_UNSPECIFIED
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_MESSAGE
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_HELLO
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_INITIATE
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_ERROR
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_READY
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_WELCOME
ZMQ_PROTOCOL_ERROR_ZMTP_INVALID_METADATA
ZMQ_PROTOCOL_ERROR_ZMTP_CRYPTOGRAPHIC
ZMQ_PROTOCOL_ERROR_ZMTP_MECHANISM_MISMATCH
ZMQ_PROTOCOL_ERROR_ZAP_UNSPECIFIED
ZMQ_PROTOCOL_ERROR_ZAP_MALFORMED_REPLY
ZMQ_PROTOCOL_ERROR_ZAP_BAD_REQUEST_ID
ZMQ_PROTOCOL_ERROR_ZAP_BAD_VERSION
ZMQ_PROTOCOL_ERROR_ZAP_INVALID_STATUS_CODE
ZMQ_PROTOCOL_ERROR_ZAP_INVALID_METADATA

ZMQ_EVENT_HANDSHAKE_FAILED_AUTH
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ZMTP security mechanism handshake failed due to an authentication failure.
The event value is the status code returned by the ZAP handler (i.e. 300,
400 or 500).



== RETURN VALUE
The _zmq_socket_monitor()_ function returns a value of 0 or greater if
successful. Otherwise it returns `-1` and sets 'errno' to one of the values
defined below.


== ERRORS
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.

*EPROTONOSUPPORT*::
The requested 'transport' protocol is not supported. Monitor sockets are
required to use the inproc:// transport.

*EINVAL*::
The endpoint supplied is invalid.

== EXAMPLE
.Monitoring client and server sockets
----
//  Read one event off the monitor socket; return value and address
//  by reference, if not null, and event number by value. Returns -1
//  in case of error.

static int
get_monitor_event (void *monitor, int *value, char **address)
{
    //  First frame in message contains event number and value
    zmq_msg_t msg;
    zmq_msg_init (&msg);
    if (zmq_msg_recv (&msg, monitor, 0) == -1)
        return -1;              //  Interrupted, presumably
    assert (zmq_msg_more (&msg));

    uint8_t *data = (uint8_t *) zmq_msg_data (&msg);
    uint16_t event = *(uint16_t *) (data);
    if (value)
        *value = *(uint32_t *) (data + 2);

    //  Second frame in message contains event address
    zmq_msg_init (&msg);
    if (zmq_msg_recv (&msg, monitor, 0) == -1)
        return -1;              //  Interrupted, presumably
    assert (!zmq_msg_more (&msg));

    if (address) {
        uint8_t *data = (uint8_t *) zmq_msg_data (&msg);
        size_t size = zmq_msg_size (&msg);
        *address = (char *) malloc (size + 1);
        memcpy (*address, data, size);
        (*address)[size] = 0;
    }
    return event;
}

int main (void)
{
    void *ctx = zmq_ctx_new ();
    assert (ctx);

    //  We'll monitor these two sockets
    void *client = zmq_socket (ctx, ZMQ_DEALER);
    assert (client);
    void *server = zmq_socket (ctx, ZMQ_DEALER);
    assert (server);

    //  Socket monitoring only works over inproc://
    int rc = zmq_socket_monitor (client, "tcp://127.0.0.1:9999", 0);
    assert (rc == -1);
    assert (zmq_errno () == EPROTONOSUPPORT);

    //  Monitor all events on client and server sockets
    rc = zmq_socket_monitor (client, "inproc://monitor-client", ZMQ_EVENT_ALL);
    assert (rc == 0);
    rc = zmq_socket_monitor (server, "inproc://monitor-server", ZMQ_EVENT_ALL);
    assert (rc == 0);

    //  Create two sockets for collecting monitor events
    void *client_mon = zmq_socket (ctx, ZMQ_PAIR);
    assert (client_mon);
    void *server_mon = zmq_socket (ctx, ZMQ_PAIR);
    assert (server_mon);

    //  Connect these to the inproc endpoints so they'll get events
    rc = zmq_connect (client_mon, "inproc://monitor-client");
    assert (rc == 0);
    rc = zmq_connect (server_mon, "inproc://monitor-server");
    assert (rc == 0);

    //  Now do a basic ping test
    rc = zmq_bind (server, "tcp://127.0.0.1:9998");
    assert (rc == 0);
    rc = zmq_connect (client, "tcp://127.0.0.1:9998");
    assert (rc == 0);
    bounce (client, server);

    //  Close client and server
    close_zero_linger (client);
    close_zero_linger (server);

    //  Now collect and check events from both sockets
    int event = get_monitor_event (client_mon, NULL, NULL);
    if (event == ZMQ_EVENT_CONNECT_DELAYED)
        event = get_monitor_event (client_mon, NULL, NULL);
    assert (event == ZMQ_EVENT_CONNECTED);
    event = get_monitor_event (client_mon, NULL, NULL);
    assert (event == ZMQ_EVENT_HANDSHAKE_SUCCEEDED);
    event = get_monitor_event (client_mon, NULL, NULL);
    assert (event == ZMQ_EVENT_MONITOR_STOPPED);

    //  This is the flow of server events
    event = get_monitor_event (server_mon, NULL, NULL);
    assert (event == ZMQ_EVENT_LISTENING);
    event = get_monitor_event (server_mon, NULL, NULL);
    assert (event == ZMQ_EVENT_ACCEPTED);
    event = get_monitor_event (server_mon, NULL, NULL);
    assert (event == ZMQ_EVENT_HANDSHAKE_SUCCEEDED);
    event = get_monitor_event (server_mon, NULL, NULL);
    assert (event == ZMQ_EVENT_CLOSED);
    event = get_monitor_event (server_mon, NULL, NULL);
    assert (event == ZMQ_EVENT_MONITOR_STOPPED);

    //  Close down the sockets
    close_zero_linger (client_mon);
    close_zero_linger (server_mon);
    zmq_ctx_term (ctx);

    return 0 ;
}
----


== SEE ALSO
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Socket Monitor Versioned (`doc/zmq_socket_monitor_versioned.adoc`)

= zmq_socket_monitor_versioned(3)


== NAME

zmq_socket_monitor_versioned - monitor socket events


== SYNOPSIS
*int zmq_socket_monitor_versioned (void '*socket', char '*endpoint', uint64_t 'events', int 'event_version', int 'type');*

*int zmq_socket_monitor_pipes_stats (void '*socket');*


== DESCRIPTION
The _zmq_socket_monitor_versioned()_ method lets an application thread track
socket events (like connects) on a ZeroMQ socket. Each call to this
method creates a 'ZMQ_PAIR' socket and binds that to the specified
inproc:// 'endpoint'. To collect the socket events, you must create
your own 'ZMQ_PAIR' socket, and connect that to the endpoint.

The 'events' argument is a bitmask of the socket events you wish to
monitor, see 'Supported events' below. To monitor all events for a version, use
the event value ZMQ_EVENT_ALL_V<version>, e.g. ZMQ_EVENT_ALL_V1. For non-DRAFT event
versions, this value will not change in the future, so new event types will only be
added in new versions (note that this is a change over zmq_socket_monitor and the
unversioned ZMQ_EVENT_ALL).

Note that event_version 2 is currently in DRAFT mode. The protocol may be
changed at any time for event_versions in DRAFT.

ZMQ_CURRENT_EVENT_VERSION and ZMQ_CURRENT_EVENT_VERSION_DRAFT are always defined
to the most recent stable or DRAFT event version, which are currently 1 resp. 2

This page describes the protocol for 'event_version' 2 only. For the protocol
used with 'event_version' 1, please refer to xref:zmq_socket_monitor.adoc[zmq_socket_monitor]

Each event is sent in multiple frames. The first frame contains an event
number (64 bits). The number and content of further frames depend on this
event number.

Unless it is specified differently, the second frame contains the number of
value frames that will follow it as a 64 bits integer. The third frame to N-th
frames contain an event value (64 bits) that provides additional data according
to the event number. Each event type might have a different number of values.
The second-to-last and last frames contain strings that specifies the affected
connection or endpoint. The former frame contains a string denoting the local
endpoint, while the latter frame contains a string denoting the remote endpoint.
Either of these may be empty, depending on the event type and whether the
connection uses a bound or connected local endpoint.

Note that the format of the second and further frames, and also the number of
frames, may be different for events added in the future.

The 'type' argument is used to specify the type of the monitoring socket.
Supported types are 'ZMQ_PAIR', 'ZMQ_PUB' and 'ZMQ_PUSH'. Note that consumers
of the events will have to be compatible with the socket type, for instance a
monitoring socket of type 'ZMQ_PUB' will require consumers of type 'ZMQ_SUB'.
In the case that the monitoring socket type is of 'ZMQ_PUB', the multipart
message topic is the event number, thus consumers should subscribe to the
events they want to receive.

The _zmq_socket_monitor_pipes_stats()_ method triggers an event of type
ZMQ_EVENT_PIPES_STATS for each connected peer of the monitored socket.
NOTE: _zmq_socket_monitor_pipes_stats()_ is in DRAFT state.

----
Monitoring events are only generated by some transports: At the moment these
are SOCKS, TCP, IPC, and TIPC. Note that it is not an error to call
'zmq_socket_monitor_versioned' on a socket that is connected or bound to some
other transport, as this may not be known at the time
'zmq_socket_monitor_versioned' is called. Also, a socket can be connected/bound
to multiple endpoints using different transports.

----

Supported events (v1)
----------------

ZMQ_EVENT_CONNECTED
~~~~~~~~~~~~~~~~~~~
The socket has successfully connected to a remote peer. The event value
is the file descriptor (FD) of the underlying network socket. Warning:
there is no guarantee that the FD is still valid by the time your code
receives this event.

ZMQ_EVENT_CONNECT_DELAYED
~~~~~~~~~~~~~~~~~~~~~~~~~
A connect request on the socket is pending. The event value is unspecified.

ZMQ_EVENT_CONNECT_RETRIED
~~~~~~~~~~~~~~~~~~~~~~~~~
A connect request failed, and is now being retried. The event value is the
reconnect interval in milliseconds. Note that the reconnect interval is
recalculated for each retry.

ZMQ_EVENT_LISTENING
~~~~~~~~~~~~~~~~~~~
The socket was successfully bound to a network interface. The event value
is the FD of the underlying network socket. Warning: there is no guarantee
that the FD is still valid by the time your code receives this event.

ZMQ_EVENT_BIND_FAILED
~~~~~~~~~~~~~~~~~~~~~
The socket could not bind to a given interface. The event value is the
errno generated by the system bind call.

ZMQ_EVENT_ACCEPTED
~~~~~~~~~~~~~~~~~~
The socket has accepted a connection from a remote peer. The event value is
the FD of the underlying network socket. Warning: there is no guarantee that
the FD is still valid by the time your code receives this event.

ZMQ_EVENT_ACCEPT_FAILED
~~~~~~~~~~~~~~~~~~~~~~~
The socket has rejected a connection from a remote peer. The event value is
the errno generated by the accept call.

ZMQ_EVENT_CLOSED
~~~~~~~~~~~~~~~~
The socket was closed. The event value is the FD of the (now closed) network
socket.

ZMQ_EVENT_CLOSE_FAILED
~~~~~~~~~~~~~~~~~~~~~~
The socket close failed. The event value is the errno returned by the system
call. Note that this event occurs only on IPC transports.

ZMQ_EVENT_DISCONNECTED
~~~~~~~~~~~~~~~~~~~~~~
The socket was disconnected unexpectedly. The event value is the FD of the
underlying network socket. Warning: this socket will be closed.

ZMQ_EVENT_MONITOR_STOPPED
~~~~~~~~~~~~~~~~~~~~~~~~~
Monitoring on this socket ended.

ZMQ_EVENT_HANDSHAKE_FAILED_NO_DETAIL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Unspecified error during handshake.
The event value is an errno.

ZMQ_EVENT_HANDSHAKE_SUCCEEDED
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ZMTP security mechanism handshake succeeded.
The event value is unspecified.

ZMQ_EVENT_HANDSHAKE_FAILED_PROTOCOL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ZMTP security mechanism handshake failed due to some mechanism protocol 
error, either between the ZMTP mechanism peers, or between the mechanism 
server and the ZAP handler. This indicates a configuration or implementation 
error in either peer resp. the ZAP handler.
The event value is one of the ZMQ_PROTOCOL_ERROR_* values:
ZMQ_PROTOCOL_ERROR_ZMTP_UNSPECIFIED
ZMQ_PROTOCOL_ERROR_ZMTP_UNEXPECTED_COMMAND
ZMQ_PROTOCOL_ERROR_ZMTP_INVALID_SEQUENCE
ZMQ_PROTOCOL_ERROR_ZMTP_KEY_EXCHANGE
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_UNSPECIFIED
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_MESSAGE
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_HELLO
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_INITIATE
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_ERROR
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_READY
ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_WELCOME
ZMQ_PROTOCOL_ERROR_ZMTP_INVALID_METADATA
ZMQ_PROTOCOL_ERROR_ZMTP_CRYPTOGRAPHIC
ZMQ_PROTOCOL_ERROR_ZMTP_MECHANISM_MISMATCH
ZMQ_PROTOCOL_ERROR_ZAP_UNSPECIFIED
ZMQ_PROTOCOL_ERROR_ZAP_MALFORMED_REPLY
ZMQ_PROTOCOL_ERROR_ZAP_BAD_REQUEST_ID
ZMQ_PROTOCOL_ERROR_ZAP_BAD_VERSION
ZMQ_PROTOCOL_ERROR_ZAP_INVALID_STATUS_CODE
ZMQ_PROTOCOL_ERROR_ZAP_INVALID_METADATA

ZMQ_EVENT_HANDSHAKE_FAILED_AUTH
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ZMTP security mechanism handshake failed due to an authentication failure.
The event value is the status code returned by the ZAP handler (i.e. 300, 
400 or 500).

----

Supported events (v2)
----------------

ZMQ_EVENT_PIPES_STATS
~~~~~~~~~~~~~~~~~~~~~
This event provides two values, the number of messages in each of the two
queues associated with the returned endpoint (respectively egress and ingress).
This event only triggers after calling the function
_zmq_socket_monitor_pipes_stats()_.
NOTE: this measurement is asynchronous, so by the time the message is received
the internal state might have already changed.
NOTE: when the monitored socket and the monitor are not used in a poll, the
event might not be delivered until an API has been called on the monitored
socket, like zmq_getsockopt for example (the option is irrelevant).
NOTE: in DRAFT state, not yet available in stable releases.



== RETURN VALUE
The _zmq_socket_monitor()_ and _zmq_socket_monitor_pipes_stats()_ functions
return a value of 0 or greater if successful. Otherwise they return `-1` and
set 'errno' to one of the values defined below.


ERRORS - _zmq_socket_monitor()_
-------------------------------
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.

*EPROTONOSUPPORT*::
The transport protocol of the monitor 'endpoint' is not supported. Monitor
sockets are required to use the inproc:// transport.

*EINVAL*::
The monitor 'endpoint' supplied does not exist or the specified socket 'type'
is not supported.


ERRORS - _zmq_socket_monitor_pipes_stats()_
-------------------------------------------
*ENOTSOCK*::
The 'socket' parameter was not a valid 0MQ socket.

*EINVAL*::
The socket did not have monitoring enabled.

*EAGAIN*::
The monitored socket did not have any connections to monitor yet.

== EXAMPLE
.Monitoring client and server sockets
----
//  Read one event off the monitor socket; return values and addresses
//  by reference, if not null, and event number by value. Returns -1
//  in case of error.

static uint64_t
get_monitor_event (void *monitor, uint64_t **value, char **local_address, char **remote_address)
{
    //  First frame in message contains event number
    zmq_msg_t msg;
    zmq_msg_init (&msg);
    if (zmq_msg_recv (&msg, monitor, 0) == -1)
        return -1;              //  Interrupted, presumably
    assert (zmq_msg_more (&msg));

    uint64_t event;
    memcpy (&event, zmq_msg_data (&msg), sizeof (event));
    zmq_msg_close (&msg);

    //  Second frame in message contains the number of values
    zmq_msg_init (&msg);
    if (zmq_msg_recv (&msg, monitor, 0) == -1)
        return -1;              //  Interrupted, presumably
    assert (zmq_msg_more (&msg));

    uint64_t value_count;
    memcpy (&value_count, zmq_msg_data (&msg), sizeof (value_count));
    zmq_msg_close (&msg);

    if (value) {
        *value = (uint64_t *) malloc (value_count * sizeof (uint64_t));
        assert (*value);
    }

    for (uint64_t i = 0; i < value_count; ++i) {
        //  Subsequent frames in message contain event values
        zmq_msg_init (&msg);
        if (zmq_msg_recv (&msg, monitor, 0) == -1)
            return -1;              //  Interrupted, presumably
        assert (zmq_msg_more (&msg));

        if (value && *value)
            memcpy (&(*value)[i], zmq_msg_data (&msg), sizeof (uint64_t));
        zmq_msg_close (&msg);
    }

    //  Second-to-last frame in message contains local address
    zmq_msg_init (&msg);
    if (zmq_msg_recv (&msg, monitor, 0) == -1)
        return -1;              //  Interrupted, presumably
    assert (zmq_msg_more (&msg));

    if (local_address_) {
        uint8_t *data = (uint8_t *) zmq_msg_data (&msg);
        size_t size = zmq_msg_size (&msg);
        *local_address_ = (char *) malloc (size + 1);
        memcpy (*local_address_, data, size);
        (*local_address_)[size] = 0;
    }
    zmq_msg_close (&msg);

    //  Last frame in message contains remote address
    zmq_msg_init (&msg);
    if (zmq_msg_recv (&msg, monitor, 0) == -1)
        return -1;              //  Interrupted, presumably
    assert (!zmq_msg_more (&msg));

    if (remote_address_) {
        uint8_t *data = (uint8_t *) zmq_msg_data (&msg);
        size_t size = zmq_msg_size (&msg);
        *remote_address_ = (char *) malloc (size + 1);
        memcpy (*remote_address_, data, size);
        (*remote_address_)[size] = 0;
    }
    zmq_msg_close (&msg);

    return event;
}

int main (void)
{
    void *ctx = zmq_ctx_new ();
    assert (ctx);

    //  We'll monitor these two sockets
    void *client = zmq_socket (ctx, ZMQ_DEALER);
    assert (client);
    void *server = zmq_socket (ctx, ZMQ_DEALER);
    assert (server);

    //  Socket monitoring only works over inproc://
    int rc = zmq_socket_monitor_versioned (client, "tcp://127.0.0.1:9999", 0, 2);
    assert (rc == -1);
    assert (zmq_errno () == EPROTONOSUPPORT);

    //  Monitor all events on client and server sockets
    rc = zmq_socket_monitor_versioned (client, "inproc://monitor-client", ZMQ_EVENT_ALL, 2);
    assert (rc == 0);
    rc = zmq_socket_monitor_versioned (server, "inproc://monitor-server", ZMQ_EVENT_ALL, 2);
    assert (rc == 0);

    //  Create two sockets for collecting monitor events
    void *client_mon = zmq_socket (ctx, ZMQ_PAIR);
    assert (client_mon);
    void *server_mon = zmq_socket (ctx, ZMQ_PAIR);
    assert (server_mon);

    //  Connect these to the inproc endpoints so they'll get events
    rc = zmq_connect (client_mon, "inproc://monitor-client");
    assert (rc == 0);
    rc = zmq_connect (server_mon, "inproc://monitor-server");
    assert (rc == 0);

    //  Now do a basic ping test
    rc = zmq_bind (server, "tcp://127.0.0.1:9998");
    assert (rc == 0);
    rc = zmq_connect (client, "tcp://127.0.0.1:9998");
    assert (rc == 0);
    bounce (client, server);

    //  Close client and server
    close_zero_linger (client);
    close_zero_linger (server);

    //  Now collect and check events from both sockets
    int event = get_monitor_event (client_mon, NULL, NULL);
    if (event == ZMQ_EVENT_CONNECT_DELAYED)
        event = get_monitor_event (client_mon, NULL, NULL);
    assert (event == ZMQ_EVENT_CONNECTED);
    event = get_monitor_event (client_mon, NULL, NULL);
    assert (event == ZMQ_EVENT_MONITOR_STOPPED);

    //  This is the flow of server events
    event = get_monitor_event (server_mon, NULL, NULL);
    assert (event == ZMQ_EVENT_LISTENING);
    event = get_monitor_event (server_mon, NULL, NULL);
    assert (event == ZMQ_EVENT_ACCEPTED);
    event = get_monitor_event (server_mon, NULL, NULL);
    assert (event == ZMQ_EVENT_CLOSED);
    event = get_monitor_event (server_mon, NULL, NULL);
    assert (event == ZMQ_EVENT_MONITOR_STOPPED);

    //  Close down the sockets
    close_zero_linger (client_mon);
    close_zero_linger (server_mon);
    zmq_ctx_term (ctx);

    return 0 ;
}
----


== SEE ALSO
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Strerror (`doc/zmq_strerror.adoc`)

= zmq_strerror(3)


== NAME
zmq_strerror - get 0MQ error message string


== SYNOPSIS
*const char *zmq_strerror (int 'errnum');*


== DESCRIPTION
The _zmq_strerror()_ function shall return a pointer to an error message string
corresponding to the error number specified by the 'errnum' argument. As 0MQ
defines additional error numbers over and above those defined by the operating
system, applications should use _zmq_strerror()_ in preference to the standard
_strerror()_ function.


== RETURN VALUE
The _zmq_strerror()_ function shall return a pointer to an error message
string.


== ERRORS
No errors are defined.


== EXAMPLE
.Displaying an error message when a 0MQ context cannot be initialised
----
void *ctx = zmq_init (1, 1, 0);
if (!ctx) {
    printf ("Error occurred during zmq_init(): %s\n", zmq_strerror (errno));
    abort ();
}
----


== SEE ALSO
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Tcp (`doc/zmq_tcp.adoc`)

= zmq_tcp(7)


== NAME
zmq_tcp - 0MQ unicast transport using TCP


== SYNOPSIS
TCP is an ubiquitous, reliable, unicast transport. When connecting distributed
applications over a network with 0MQ, using the TCP transport will likely be
your first choice.


== ADDRESSING
A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.

For the TCP transport, the transport is `tcp`, and the meaning of the
'address' part is defined below.


Assigning a local address to a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When assigning a local address to a socket using _zmq_bind()_ with the 'tcp'
transport, the 'endpoint' shall be interpreted as an 'interface' followed by a
colon and the TCP port number to use.

An 'interface' may be specified by either of the following:

* The wild-card `*`, meaning all available interfaces.
* The primary IPv4 or IPv6 address assigned to the interface, in its numeric
  representation.
* The non-portable interface name as defined by the operating system.

The TCP port number may be specified by:

* A numeric value, usually above 1024 on POSIX systems.
* The wild-card `*`, meaning a system-assigned ephemeral port.

When using ephemeral ports, the caller should retrieve the actual assigned
port using the ZMQ_LAST_ENDPOINT socket option. See xref:zmq_getsockopt.adoc[zmq_getsockopt]
for details.

Unbinding wild-card address from a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When wild-card `*` 'endpoint' was used in _zmq_bind()_, the caller should use
real 'endpoint' obtained from the ZMQ_LAST_ENDPOINT socket option to unbind 
this 'endpoint' from a socket using _zmq_unbind()_.

Connecting a socket
~~~~~~~~~~~~~~~~~~~
When connecting a socket to a peer address using _zmq_connect()_ with the 'tcp'
transport, the 'endpoint' shall be interpreted as a 'peer address' followed by
a colon and the TCP port number to use.
You can optionally specify a 'source_endpoint' which will be used as the source
address for your connection; tcp://'source_endpoint';'endpoint', see the
'interface' description above for details.

A 'peer address' may be specified by either of the following:

* The DNS name of the peer.
* The IPv4 or IPv6 address of the peer, in its numeric representation.

Note: A description of the ZeroMQ Message Transport Protocol (ZMTP) which is 
used by the TCP transport can be found at <http://rfc.zeromq.org/spec:23>


== HWM

For the TCP transport, the high water mark (HWM) mechanism works in conjunction
with the TCP socket buffers handled at OS level.
Depending on the OS and several other factors the size of such TCP buffers will
be different. Moreover TCP buffers provided by the OS will accommodate a varying
number of messages depending on the size of messages (unlike ZMQ HWM settings
the TCP socket buffers are measured in bytes and not messages).

This may result in apparently inexplicable behaviors: e.g., you may expect that
setting ZMQ_SNDHWM to 100 on a socket using TCP transport will have the effect
of blocking the transmission of the 101-th message if the receiver is slow.
This is very unlikely when using TCP transport since OS TCP buffers will typically
provide enough buffering to allow you sending much more than 100 messages.

Of course if the receiver is slow, transmitting on a TCP ZMQ socket will eventually trigger
the "mute state" of the socket; simply don't rely on the exact HWM value.

Obviously the same considerations apply for the receive HWM (see ZMQ_RCVHWM).



== EXAMPLES
.Assigning a local address to a socket
----
//  TCP port 5555 on all available interfaces
rc = zmq_bind(socket, "tcp://*:5555");
assert (rc == 0);
//  TCP port 5555 on the local loop-back interface on all platforms
rc = zmq_bind(socket, "tcp://127.0.0.1:5555");
assert (rc == 0);
//  TCP port 5555 on the first Ethernet network interface on Linux
rc = zmq_bind(socket, "tcp://eth0:5555");
assert (rc == 0);
----

.Connecting a socket
----
//  Connecting using an IP address
rc = zmq_connect(socket, "tcp://192.168.1.1:5555");
assert (rc == 0);
//  Connecting using a DNS name
rc = zmq_connect(socket, "tcp://server1:5555");
assert (rc == 0);
//  Connecting using a DNS name and bind to eth1
rc = zmq_connect(socket, "tcp://eth1:0;server1:5555");
assert (rc == 0);
//  Connecting using a IP address and bind to an IP address
rc = zmq_connect(socket, "tcp://192.168.1.17:5555;192.168.1.1:5555");
assert (rc == 0);
----


== SEE ALSO
* xref:zmq_bind.adoc[zmq_bind]
* xref:zmq_connect.adoc[zmq_connect]
* xref:zmq_pgm.adoc[zmq_pgm]
* xref:zmq_ipc.adoc[zmq_ipc]
* xref:zmq_inproc.adoc[zmq_inproc]
* xref:zmq_vmci.adoc[zmq_vmci]
* xref:zmq_vsock.adoc[zmq_vsock]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Timers (`doc/zmq_timers.adoc`)

= zmq_timers(3)


== NAME
zmq_timers - helper functions for cross-platform timers callbacks


== SYNOPSIS

*typedef void(zmq_timer_fn) (int 'timer_id', void *'arg');*

*void *zmq_timers_new (void);*

*int zmq_timers_destroy (void **'timers_p');*

*int zmq_timers_add (void *'timers', size_t 'interval', zmq_timer_fn 'handler', void *'arg');*

*int zmq_timers_cancel (void *'timers', int 'timer_id');*

*int zmq_timers_set_interval (void *'timers', int 'timer_id', size_t 'interval');*

*int zmq_timers_reset (void *'timers', int 'timer_id');*

*long zmq_timers_timeout (void *'timers');*

*int zmq_timers_execute (void *'timers');*


== DESCRIPTION
The _zmq_timers_*_ functions provide cross-platform access to timers callbacks.
Once a timer has been registered, it will repeat at the specified interval until
it gets manually cancelled. To run the callbacks, _zmq_timers_execute_ must be
ran.

_zmq_timers_new_ and _zmq_timers_destroy_ manage the lifetime of a timer
instance. _zmq_timers_new_ creates and returns a new timer instance, while
_zmq_timers_destroy_ destroys it. A pointer to a valid timer must be passed
as the _timers_p_ argument of _zmq_timers_destroy_. In particular,
_zmq_timers_destroy_ may not be called multiple times for the same timer
instance. _zmq_timers_destroy_ sets the passed pointer to NULL in case of a
successful execution.

_zmq_timers_add_ and _zmq_timers_cancel_ manage the timers registered.

_zmq_timers_add_ registers a new _timer_ with a given instance. _timers_ must
point to a valid _timers_ object. The _interval_ parameter specifies the
expiration of the timer in milliseconds. _handler_ and _arg_ specify the callback
that will be invoked on expiration and the optional parameter that will be passed
through. The callback must be a valid function implementing the _zmq_timer_fn_
prototype. An ID will be returned that can be used to modify or cancel the timer.

_zmq_timers_cancel_ will cancel the timer associated with _timer_id_ from the
instance _timers_.

_zmq_timers_set_interval_ will set the expiration of the timer associated with
_timer_id_ from the instance _timers_ to _interval_ milliseconds into the future.

_zmq_timers_reset_ will restart the timer associated with _timer_id_ from the
instance _timers_.

_zmq_timers_timeout_ will return the time left in milliseconds until the next
timer registered with _timers_ expires.

_zmq_timers_execute_ will run callbacks of all expired timers from the instance
_timers_.


== THREAD SAFETY
Like most other 0MQ objects, timers are not thread-safe. All operations must
be called from the same thread. Otherwise, behaviour is undefined.


== RETURN VALUE
_zmq_timers_new_ always returns a valid pointer to a poller.

All functions that return an int, return -1 in case of a failure. In that case,
zmq_errno() can be used to query the type of the error as described below.

_zmq_timers_timeout_ returns the time left in milliseconds until the next
timer registered with _timers_ expires, or -1 if there are no timers left.

All other functions return 0 in case of a successful execution.


== ERRORS
On _zmq_timers_destroy_, _zmq_poller_cancel_, _zmq_timers_set_interval_,
_zmq_timers_reset_, zmq_timers_timeout_, and _zmq_timers_execute_:
*EFAULT*::
_timers_ did not point to a valid timer. Note that passing an
invalid pointer (e.g. pointer to deallocated memory) may cause undefined
behaviour (e.g. an access violation).

On _zmq_timers_add_:
*EFAULT*::
_timers_ did not point to a valid timer or _handler_ did not point to a valid
function.

On _zmq_poller_cancel_, _zmq_timers_set_interval_ and zmq_timers_timeout_:
*EINVAL*::
_timer_id_ did not exist or was already cancelled.


== EXAMPLE
.Add one timer with a simple callback that changes a boolean.
----
    void handler (int timer_id_, void *arg_)
    {
        (void) timer_id_; //  Stop 'unused' compiler warnings
        *((bool *) arg_) = true;
    }

    ...

    void *timers = zmq_timers_new ();
    assert (timers);

    bool timer_invoked = false;

    const unsigned long full_timeout = 100;

    int timer_id =
      zmq_timers_add (timers, full_timeout, handler, &timer_invoked);
    assert (timer_id);

    //  Timer should not have been invoked yet
    int rc = zmq_timers_execute (timers);
    assert (rc == 0);

    //  Wait half the time and check again
    long timeout = zmq_timers_timeout (timers);
    assert (rc != -1);
    msleep (timeout / 2);
    rc = zmq_timers_execute (timers);
    assert (rc == 0);

    // Wait until the end
    rc = msleep (zmq_timers_timeout (timers));
    assert (rc == 0);

    // The handler will be executed
    rc = zmq_timers_execute (timers);
    assert (rc == 0);
    assert (timer_invoked);

    rc = zmq_timers_destroy (&timers);
    assert (rc == 0);
----


== SEE ALSO
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Tipc (`doc/zmq_tipc.adoc`)

= zmq_tipc(7)


== NAME
zmq_tipc - 0MQ unicast transport using TIPC


== SYNOPSIS
TIPC is a cluster IPC protocol with a location transparent addressing scheme.


== ADDRESSING
A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.

For the TIPC transport, the transport is `tipc`, and the meaning of the
'address' part is defined below.


Assigning a port name to a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When assigning a port name to a socket using _zmq_bind()_ with the 'tipc'
transport, the 'endpoint' is defined in the form:
{type, lower, upper}

* Type is the numerical (u32) ID of your service.
* Lower and Upper specify a range for your service.

Publishing the same service with overlapping lower/upper ID's will
cause connection requests to be distributed over these in a round-robin
manner.


Connecting a socket
~~~~~~~~~~~~~~~~~~~
When connecting a socket to a peer address using _zmq_connect()_ with the 'tipc'
transport, the 'endpoint' shall be interpreted as a service ID, followed by a 
comma and the instance ID.

The instance ID must be within the lower/upper range of a published port name
for the endpoint to be valid.

== EXAMPLES
.Assigning a local address to a socket
----
//  Publish TIPC service ID 5555
rc = zmq_bind(socket, "tipc://{5555,0,0}");
assert (rc == 0);
//  Publish TIPC service ID 5555 with a service range of 0-100
rc = zmq_bind(socket, "tipc://{5555,0,100}");
assert (rc == 0);
----

.Connecting a socket
----
//  Connect to service 5555 instance id 50
rc = zmq_connect(socket, "tipc://{5555,50}");
assert (rc == 0);
----


== SEE ALSO
* xref:zmq_bind.adoc[zmq_bind]
* xref:zmq_connect.adoc[zmq_connect]
* xref:zmq_tcp.adoc[zmq_tcp]
* xref:zmq_pgm.adoc[zmq_pgm]
* xref:zmq_ipc.adoc[zmq_ipc]
* xref:zmq_inproc.adoc[zmq_inproc]
* xref:zmq_vmci.adoc[zmq_vmci]
* xref:zmq_vsock.adoc[zmq_vsock]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Udp (`doc/zmq_udp.adoc`)

= zmq_udp(7)


== NAME
zmq_udp - 0MQ UDP multicast and unicast transport


== SYNOPSIS
UDP is unreliable protocol transport of data over IP networks.
UDP support both unicast and multicast communication.


== DESCRIPTION
UDP transport can only be used with the 'ZMQ_RADIO' and
'ZMQ_DISH' socket types.

== ADDRESSING
A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.

For the UDP transport, the transport is `udp`.
The meaning of the 'address' part is defined below.

Binding a socket
----------------
With 'udp' we can only bind the 'ZMQ_DISH' socket type.
When binding a socket using _zmq_bind()_ with the 'udp'
transport the 'endpoint' shall be interpreted as an 'interface' followed by a
colon and the UDP port number to use.

An 'interface' may be specified by either of the following:

* The wild-card `*`, meaning all available interfaces.
* The name of the network interface (i.e. eth0, lo, wlan0 etc...)
* The primary address assigned to the interface, in its numeric representation.
* Multicast address in its numeric representation the socket should join.

The UDP port number may be specified a numeric value, usually above
1024 on POSIX systems.

Connecting a socket
-------------------
With 'udp' we can only connect the 'ZMQ_RADIO' socket type.
When connecting a socket to a peer address using _zmq_connect()_ with the 'udp'
transport, the 'endpoint' shall be interpreted as a 'peer address' followed by
a colon and the UDP port number to use.

A 'peer address' may be specified by either of the following:

* The IPv4 or IPv6 address of the peer, in its numeric representation
  or using its hostname.
* Multicast address in its numeric representation.

== EXAMPLES
.Binding a socket
----
//  Unicast - UDP port 5555 on all available interfaces
rc = zmq_bind(dish, "udp://*:5555");
assert (rc == 0);
//  Unicast - UDP port 5555 on the local loop-back interface
rc = zmq_bind(dish, "udp://127.0.0.1:5555");
assert (rc == 0);
//  Unicast - UDP port 5555 on interface eth1
rc = zmq_bind(dish, "udp://eth1:5555");
assert (rc == 0);
//  Multicast - UDP port 5555 on a Multicast address
rc = zmq_bind(dish, "udp://239.0.0.1:5555");
assert (rc == 0);
//  Same as above but joining only on interface eth0
rc = zmq_bind(dish, "udp://eth0;239.0.0.1:5555");
assert (rc == 0);
//  Same as above using IPv6 multicast
rc = zmq_bind(dish, "udp://eth0;[ff02::1]:5555");
assert (rc == 0);
----


.Connecting a socket
----
//  Connecting using an Unicast IP address
rc = zmq_connect(radio, "udp://192.168.1.1:5555");
assert (rc == 0);
//  Connecting using a Multicast address
rc = zmq_connect(socket, "udp://239.0.0.1:5555);
assert (rc == 0);
//  Connecting using a Multicast address using local interface wlan0
rc = zmq_connect(socket, "udp://wlan0;239.0.0.1:5555);
assert (rc == 0);
//  Connecting to IPv6 multicast
rc = zmq_connect(socket, "udp://[ff02::1]:5555);
assert (rc == 0);
----


== SEE ALSO
* xref:zmq_connect.adoc[zmq_connect]
* xref:zmq_setsockopt.adoc[zmq_setsockopt]
* xref:zmq_tcp.adoc[zmq_tcp]
* xref:zmq_ipc.adoc[zmq_ipc]
* xref:zmq_inproc.adoc[zmq_inproc]
* xref:zmq_vmci.adoc[zmq_vmci]
* xref:zmq_vsock.adoc[zmq_vsock]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Unbind (`doc/zmq_unbind.adoc`)

= zmq_unbind(3)


== NAME
zmq_unbind - Stop accepting connections on a socket


== SYNOPSIS
int zmq_unbind (void '*socket', const char '*endpoint');


== DESCRIPTION
The _zmq_unbind()_ function shall unbind a socket specified
by the 'socket' argument from the endpoint specified by the 'endpoint'
argument. 

Additionally the incoming message queue associated with the endpoint will be
discarded. This means that after unbinding an endpoint it is possible to
received messages originating from that same endpoint if they were already
present in the incoming message queue before unbinding.

The 'endpoint' argument is as described in xref:zmq_bind.adoc[zmq_bind]

Unbinding wild-card address from a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When wild-card `*` 'endpoint' (described in xref:zmq_tcp.adoc[zmq_tcp],
xref:zmq_ipc.adoc[zmq_ipc], xref:zmq_udp.adoc[zmq_udp],
xref:zmq_vmci.adoc[zmq_vmci] and xref:zmq_vsock.adoc[zmq_vsock]) was used in
_zmq_bind()_, the caller should use real 'endpoint' obtained from the 
ZMQ_LAST_ENDPOINT socket option to unbind this 'endpoint' from a socket.

== RETURN VALUE
The _zmq_unbind()_ function shall return zero if successful. Otherwise it
shall return `-1` and set 'errno' to one of the values defined below.

== ERRORS
*EINVAL*::
The endpoint supplied is invalid.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*ENOENT*::
The endpoint supplied was not previously bound.


== EXAMPLES
.Unbind a subscriber socket from a TCP transport
----
/* Create a ZMQ_SUB socket */
void *socket = zmq_socket (context, ZMQ_SUB);
assert (socket);
/* Connect it to the host server001, port 5555 using a TCP transport */
rc = zmq_bind (socket, "tcp://127.0.0.1:5555");
assert (rc == 0);
/* Disconnect from the previously connected endpoint */
rc = zmq_unbind (socket, "tcp://127.0.0.1:5555");
assert (rc == 0);
----

.Unbind wild-card `*` binded socket
----
/* Create a ZMQ_SUB socket */
void *socket = zmq_socket (context, ZMQ_SUB);
assert (socket);
/* Bind it to the system-assigned ephemeral port using a TCP transport */
rc = zmq_bind (socket, "tcp://127.0.0.1:*");
assert (rc == 0);
/* Obtain real endpoint */
const size_t buf_size = 32;
char buf[buf_size];
rc = zmq_getsockopt (socket, ZMQ_LAST_ENDPOINT, buf, (size_t *)&buf_size);
assert (rc == 0);
/* Unbind socket by real endpoint */
rc = zmq_unbind (socket, buf);
assert (rc == 0);
----

== NOTE

Note that while the implementation is similar to _zmq_disconnect()_, the
semantics are different and the two functions should not be used
interchangeably. Bound sockets should be unbound, and connected sockets should
be disconnected.

== SEE ALSO
* xref:zmq_bind.adoc[zmq_bind]
* xref:zmq_socket.adoc[zmq_socket]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Version (`doc/zmq_version.adoc`)

= zmq_version(3)


== NAME
zmq_version - report 0MQ library version


== SYNOPSIS
*void zmq_version (int '*major', int '*minor', int '*patch');*


== DESCRIPTION
The _zmq_version()_ function shall fill in the integer variables pointed to by
the 'major', 'minor' and 'patch' arguments with the major, minor and patch level
components of the 0MQ library version.

This functionality is intended for applications or language bindings
dynamically linking to the 0MQ library that wish to determine the actual
version of the 0MQ library they are using.


== RETURN VALUE
There is no return value.


== ERRORS
No errors are defined.


== EXAMPLE
.Printing out the version of the 0MQ library
----
int major, minor, patch;
zmq_version (&major, &minor, &patch);
printf ("Current 0MQ version is %d.%d.%d\n", major, minor, patch);
----


== SEE ALSO
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Vmci (`doc/zmq_vmci.adoc`)

= zmq_vmci(7)


== NAME
zmq_vmci - 0MQ transport over virtual machine communications interface (VMCI) sockets


== SYNOPSIS
The VMCI transport passes messages between VMware virtual machines running on the same host,
between virtual machine and the host and within virtual machines (inter-process transport like ipc).

NOTE: Communication between a virtual machine and the host is not supported on Mac OS X 10.9 and above.


== ADDRESSING
A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.

For the VMCI transport, the transport is `vmci`, and the meaning of
the 'address' part is defined below.


Binding a socket
~~~~~~~~~~~~~~~~
When binding a 'socket' to a local address using _zmq_bind()_ with the 'vmci'
transport, the 'endpoint' shall be interpreted as an 'interface' followed by a
colon and the TCP port number to use.

An 'interface' may be specified by either of the following:

* The wild-card `*`, meaning all available interfaces.
* An integer returned by `VMCISock_GetLocalCID` or `@` (ZeroMQ will call VMCISock_GetLocalCID internally).

The port may be specified by:

* A numeric value, usually above 1024 on POSIX systems.
* The wild-card `*`, meaning a system-assigned ephemeral port.

Unbinding wild-card address from a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When wild-card `*` 'endpoint' was used in _zmq_bind()_, the caller should use
real 'endpoint' obtained from the ZMQ_LAST_ENDPOINT socket option to unbind
this 'endpoint' from a socket using _zmq_unbind()_.

Connecting a socket
~~~~~~~~~~~~~~~~~~~
When connecting a socket to a peer address using _zmq_connect()_ with the 'vmci'
transport, the 'endpoint' shall be interpreted as a 'peer address' followed by
a colon and the port number to use.

A 'peer address' must be a CID of the peer.


== EXAMPLES
.Assigning a local address to a socket
----
//  VMCI port 5555 on all available interfaces
rc = zmq_bind(socket, "vmci://*:5555");
assert (rc == 0);
//  VMCI port 5555 on the local loop-back interface on all platforms
cid = VMCISock_GetLocalCID();
sprintf(endpoint, "vmci://%d:5555", cid);
rc = zmq_bind(socket, endpoint);
assert (rc == 0);
----

.Connecting a socket
----
//  Connecting using a CID
sprintf(endpoint, "vmci://%d:5555", cid);
rc = zmq_connect(socket, endpoint);
assert (rc == 0);
----


== SEE ALSO
* xref:zmq_bind.adoc[zmq_bind]
* xref:zmq_connect.adoc[zmq_connect]
* xref:zmq_inproc.adoc[zmq_inproc]
* xref:zmq_tcp.adoc[zmq_tcp]
* xref:zmq_pgm.adoc[zmq_pgm]
* xref:zmq_vmci.adoc[zmq_vmci]
* xref:zmq_getsockopt.adoc[zmq_getsockopt]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Vsock (`doc/zmq_vsock.adoc`)

= zmq_vsock(7)


== NAME
zmq_vsock - 0MQ transport over Linux VSOCK (AF_VSOCK)


== SYNOPSIS
The AF_VSOCK address family facilitates communication between virtual machines and the host they are running on.
This address family is used by guest agents and hypervisor services that need a communications channel that is independent of virtual machine network configuration.

NOTE: AF_VSOCK is only supported on linux, <https://man7.org/linux/man-pages/man7/vsock.7.html>


== ADDRESSING
A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.

For the VSOCK transport, the transport is `vsock`, and the meaning of
the 'address' part is defined below.


Binding a socket
~~~~~~~~~~~~~~~~
When binding a 'socket' to a local address using _zmq_bind()_ with the 'vsock'
transport, the 'endpoint' shall be interpreted as an 'interface' followed by a
colon and the port number to use.

An 'interface' may be specified by either of the following:

* The wild-card `*`, meaning all available interfaces.
* An integer returned by `VMADDR_CID_LOCAL` or `@`.

The port may be specified by:

* A numeric value, usually above 1024 on POSIX systems.
* The wild-card `*`, meaning a system-assigned ephemeral port.

Unbinding wild-card address from a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When wild-card `*` 'endpoint' was used in _zmq_bind()_, the caller should use
real 'endpoint' obtained from the ZMQ_LAST_ENDPOINT socket option to unbind
this 'endpoint' from a socket using _zmq_unbind()_.

Connecting a socket
~~~~~~~~~~~~~~~~~~~
When connecting a socket to a peer address using _zmq_connect()_ with the 'vsock'
transport, the 'endpoint' shall be interpreted as a 'peer address' followed by
a colon and the port number to use.

A 'peer address' must be a CID of the peer.


== EXAMPLES
.Assigning a local address to a socket
----
//  VSOCK port 5555 on all available interfaces
rc = zmq_bind(socket, "vsock://*:5555");
assert (rc == 0);
//  VSOCK port 5555 on the local loop-back interface on all platforms
cid = VMADDR_CID_LOCAL;
sprintf(endpoint, "vsock://%d:5555", cid);
rc = zmq_bind(socket, endpoint);
assert (rc == 0);
----

.Connecting a socket
----
//  Connecting using a CID
sprintf(endpoint, "vsock://%d:5555", cid);
rc = zmq_connect(socket, endpoint);
assert (rc == 0);
----


== SEE ALSO
* xref:zmq_bind.adoc[zmq_bind]
* xref:zmq_connect.adoc[zmq_connect]
* xref:zmq_inproc.adoc[zmq_inproc]
* xref:zmq_tcp.adoc[zmq_tcp]
* xref:zmq_pgm.adoc[zmq_pgm]
* xref:zmq_vsock.adoc[zmq_vsock]
* xref:zmq_getsockopt.adoc[zmq_getsockopt]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Z85 Decode (`doc/zmq_z85_decode.adoc`)

= zmq_z85_decode(3)


== NAME
zmq_z85_decode - decode a binary key from Z85 printable text


== SYNOPSIS
*uint8_t *zmq_z85_decode (uint8_t *dest, const char *string);*


== DESCRIPTION
The _zmq_z85_decode()_ function shall decode 'string' into 'dest'.
The length of 'string' shall be divisible by 5. 'dest' must be large
enough for the decoded value (0.8 x strlen (string)). 

The encoding shall follow the ZMQ RFC 32 specification.


== RETURN VALUE
The _zmq_z85_decode()_ function shall return 'dest' if successful, else it
shall return NULL.


== EXAMPLE
.Decoding a CURVE key
----
const char decoded [] = "rq:rM>}U?@Lns47E1%kR.o@n%FcmmsL/@{H8]yf7";
uint8_t public_key [32];
zmq_z85_decode (public_key, decoded);
----


== SEE ALSO
* xref:zmq_z85_encode.adoc[zmq_z85_encode]
* xref:zmq_curve_keypair.adoc[zmq_curve_keypair]
* xref:zmq_curve_public.adoc[zmq_curve_public]
* xref:zmq_curve.adoc[zmq_curve]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

### Doc Zmq Z85 Encode (`doc/zmq_z85_encode.adoc`)

= zmq_z85_encode(3)


== NAME
zmq_z85_encode - encode a binary key as Z85 printable text


== SYNOPSIS
*char *zmq_z85_encode (char *dest, const uint8_t *data, size_t size);*


== DESCRIPTION
The _zmq_z85_encode()_ function shall encode the binary block specified 
by 'data' and 'size' into a string in 'dest'. The size of the binary block
must be divisible by 4. The 'dest' must have sufficient space for size * 1.25 
plus 1 for a null terminator. A 32-byte CURVE key is encoded as 40 ASCII 
characters plus a null terminator.

The encoding shall follow the ZMQ RFC 32 specification.


== RETURN VALUE
The _zmq_z85_encode()_ function shall return 'dest' if successful, else it
shall return NULL.


== EXAMPLE
.Encoding a CURVE key
----
#include <sodium.h>
uint8_t public_key [32];
uint8_t secret_key [32];
int rc = crypto_box_keypair (public_key, secret_key);
assert (rc == 0);
char encoded [41];
zmq_z85_encode (encoded, public_key, 32);
puts (encoded);
----


== SEE ALSO
* xref:zmq_z85_decode.adoc[zmq_z85_decode]
* xref:zmq_curve_keypair.adoc[zmq_curve_keypair]
* xref:zmq_curve_public.adoc[zmq_curve_public]
* xref:zmq_curve.adoc[zmq_curve]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.

---

--- METRICS ---
- Files Extracted: 80
- Estimated Token Budget: ~101315 tokens
- Canonical Reference: https://codewiki.google/github.com/zeromq/libzmq