zmq(7)

zmq(7) Manual Page

NAME

zmq - 0MQ lightweight messaging kernel

SYNOPSIS

#include <zmq.h>

cc [flags] files -lzmq [libraries]

DESCRIPTION

The ØMQ lightweight messaging kernel is a library which extends the standard socket interfaces with features traditionally provided by specialised messaging middleware products. ØMQ sockets provide an abstraction of asynchronous message queues, multiple messaging patterns, message filtering (subscriptions), seamless access to multiple transport protocols and more.

This documentation presents an overview of ØMQ concepts, describes how ØMQ abstracts standard sockets and provides a reference manual for the functions provided by the ØMQ library.

Context

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

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

Create a new ØMQ context

zmq_ctx_new(3)

Work with context properties

zmq_ctx_set(3) zmq_ctx_get(3)

Destroy a ØMQ context

zmq_ctx_shutdown(3) zmq_ctx_term(3)

Thread safety

A ØMQ 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 ØMQ 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 ØMQ directly and at the same time make use of any number of additional libraries or components which themselves make use of ØMQ as long as the above guidelines regarding thread safety are adhered to.

Messages

A ØMQ message is a discrete unit of data passed between applications or components of the same application. ØMQ messages have no internal structure and from the point of view of ØMQ itself they are considered to be opaque binary data.

The following functions are provided to work with messages:

Initialise a message

zmq_msg_init(3)
zmq_msg_init_size(3)
zmq_msg_init_buffer(3)
zmq_msg_init_data(3)

Sending and receiving a message

zmq_msg_send(3) zmq_msg_recv(3)

Release a message

zmq_msg_close(3)

Access message content

zmq_msg_data(3)
zmq_msg_size(3)
zmq_msg_more(3)

Work with message properties

zmq_msg_gets(3)
zmq_msg_get(3)
zmq_msg_set(3)

Message manipulation

zmq_msg_copy(3) zmq_msg_move(3)

Sockets

ØMQ sockets present an abstraction of an asynchronous message queue, with the exact queueing semantics depending on the socket type in use. See zmq_socket(3) for the socket types provided.

The following functions are provided to work with sockets:

Creating a socket

zmq_socket(3)

Closing a socket

zmq_close(3)

Manipulating socket options

zmq_getsockopt(3) zmq_setsockopt(3)

Establishing a message flow

zmq_bind(3) zmq_connect(3)

Sending and receiving messages

zmq_msg_send(3)
zmq_msg_recv(3)
zmq_send(3)
zmq_recv(3)
zmq_send_const(3)

Monitoring socket events

zmq_socket_monitor(3)

Input/output multiplexing

ØMQ provides a mechanism for applications to multiplex input/output events over a set containing both ØMQ sockets and standard sockets. This mechanism mirrors the standard poll() system call, and is described in detail in zmq_poll(3). This API is deprecated, however.

There is a new DRAFT API with multiple zmq_poller_* function, which is described in zmq_poller(3).

Transports

A ØMQ socket can use multiple different underlying transport mechanisms. Each transport mechanism is suited to a particular purpose and has its own advantages and drawbacks.

The following transport mechanisms are provided:

Unicast transport using TCP

zmq_tcp(7)

Reliable multicast transport using PGM

zmq_pgm(7)

Local inter-process communication transport

zmq_ipc(7)

Local in-process (inter-thread) communication transport

zmq_inproc(7)

Virtual Machine Communications Interface (VMC) transport

zmq_vmci(7)

Unreliable unicast and multicast using UDP

zmq_udp(7)

Proxies

ØMQ 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 zmq_proxy(3).

Security

A ØMQ socket can select a security mechanism. Both peers must use the same security mechanism.

The following security mechanisms are provided for IPC and TCP connections:

Null security

zmq_null(7)

Plain-text authentication using username and password

zmq_plain(7)

Elliptic curve authentication and encryption

zmq_curve(7)

Generate a CURVE keypair in armored text format

zmq_curve_keypair(3)

Derive a CURVE public key from a secret key: zmq_curve_public(3)

Converting keys to/from armoured text strings

zmq_z85_decode(3) zmq_z85_encode(3)

ERROR HANDLING

The ØMQ library functions handle errors using the standard conventions found on POSIX systems. Generally, this means that upon failure a ØMQ library function shall return either a NULL value (if returning a pointer) or a negative value (if returning an integer), and the actual error code shall be stored in the errno variable.

On non-POSIX systems some users may experience issues with retrieving the correct value of the errno variable. The zmq_errno() function is provided to assist in these cases; for details refer to zmq_errno(3).

The zmq_strerror() function is provided to translate ØMQ-specific error codes into error message strings; for details refer to zmq_strerror(3).

UTILITY

The following utility functions are provided:

Working with atomic counters

zmq_atomic_counter_new(3)
zmq_atomic_counter_set(3)
zmq_atomic_counter_inc(3)
zmq_atomic_counter_dec(3)
zmq_atomic_counter_value(3)
zmq_atomic_counter_destroy(3)

MISCELLANEOUS

The following miscellaneous functions are provided:

Report ØMQ library version

zmq_version(3)

LANGUAGE BINDINGS

The ØMQ library provides interfaces suitable for calling from programs in any language; this documentation documents those interfaces as they would be used by C programmers. The intent is that programmers using ØMQ from other languages shall refer to this documentation alongside any documentation provided by the vendor of their language binding.

Language bindings (C++, Python, PHP, Ruby, Java and more) are provided by members of the ØMQ community and pointers can be found on the ØMQ website.

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

RESOURCES

Main web site: http://www.zeromq.org/

Report bugs to the ØMQ development mailing list: <zeromq-dev@lists.zeromq.org>

COPYING

Free use of this software is granted under the terms of the GNU Lesser General Public License (LGPL). For details see the files COPYING and COPYING.LESSER included with the ØMQ distribution.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


zmq(7)
======

NAME
----
zmq - 0MQ lightweight messaging kernel

SYNOPSIS
--------
*#include <zmq.h>*

*cc* ['flags'] 'files' *-lzmq* ['libraries']

DESCRIPTION
-----------
The 0MQ lightweight messaging kernel is a library which extends the standard
socket interfaces with features traditionally provided by specialised
_messaging middleware_ products. 0MQ sockets provide an abstraction of
asynchronous _message queues_, multiple _messaging patterns_, message
filtering (_subscriptions_), seamless access to multiple _transport protocols_
and more.

This documentation presents an overview of 0MQ concepts, describes how 0MQ
abstracts standard sockets and provides a reference manual for the functions
provided by the 0MQ library.

Context
~~~~~~~
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::
    linkzmq:zmq_ctx_new[3]

Work with context properties::
    linkzmq:zmq_ctx_set[3]
    linkzmq:zmq_ctx_get[3]

Destroy a 0MQ context::
    linkzmq:zmq_ctx_shutdown[3]
    linkzmq:zmq_ctx_term[3]

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
~~~~~~~~
A 0MQ message is a discrete unit of data passed between applications or
components of the same application. 0MQ messages have no internal structure and
from the point of view of 0MQ itself they are considered to be opaque binary
data.

The following functions are provided to work with messages:

Initialise a message::
    linkzmq:zmq_msg_init[3]
    linkzmq:zmq_msg_init_size[3]
    linkzmq:zmq_msg_init_buffer[3]
    linkzmq:zmq_msg_init_data[3]

Sending and receiving a message::
    linkzmq:zmq_msg_send[3]
    linkzmq:zmq_msg_recv[3]

Release a message::
    linkzmq:zmq_msg_close[3]

Access message content::
    linkzmq:zmq_msg_data[3]
    linkzmq:zmq_msg_size[3]
    linkzmq:zmq_msg_more[3]

Work with message properties::
    linkzmq:zmq_msg_gets[3]
    linkzmq:zmq_msg_get[3]
    linkzmq:zmq_msg_set[3]

Message manipulation::
    linkzmq:zmq_msg_copy[3]
    linkzmq:zmq_msg_move[3]

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

The following functions are provided to work with sockets:

Creating a socket::
    linkzmq:zmq_socket[3]

Closing a socket::
    linkzmq:zmq_close[3]

Manipulating socket options::
    linkzmq:zmq_getsockopt[3]
    linkzmq:zmq_setsockopt[3]

Establishing a message flow::
    linkzmq:zmq_bind[3]
    linkzmq:zmq_connect[3]

Sending and receiving messages::
    linkzmq:zmq_msg_send[3]
    linkzmq:zmq_msg_recv[3]
    linkzmq:zmq_send[3]
    linkzmq:zmq_recv[3]
    linkzmq:zmq_send_const[3]

Monitoring socket events::
    linkzmq:zmq_socket_monitor[3]

.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
linkzmq:zmq_poll[3]. This API is deprecated, however.

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

Transports
~~~~~~~~~~
A 0MQ socket can use multiple different underlying transport mechanisms.
Each transport mechanism is suited to a particular purpose and has its own
advantages and drawbacks.

The following transport mechanisms are provided:

Unicast transport using TCP::
    linkzmq:zmq_tcp[7]

Reliable multicast transport using PGM::
    linkzmq:zmq_pgm[7]

Local inter-process communication transport::
    linkzmq:zmq_ipc[7]

Local in-process (inter-thread) communication transport::
    linkzmq:zmq_inproc[7]

Virtual Machine Communications Interface (VMC) transport::
    linkzmq:zmq_vmci[7]

Unreliable unicast and multicast using UDP::
    linkzmq:zmq_udp[7]

Proxies
~~~~~~~
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 linkzmq:zmq_proxy[3].

Security
~~~~~~~~
A 0MQ socket can select a security mechanism. Both peers must use the same
security mechanism.

The following security mechanisms are provided for IPC and TCP connections:

Null security::
    linkzmq:zmq_null[7]

Plain-text authentication using username and password::
    linkzmq:zmq_plain[7]

Elliptic curve authentication and encryption::
    linkzmq:zmq_curve[7]

Generate a CURVE keypair in armored text format::
    linkzmq:zmq_curve_keypair[3]

Derive a CURVE public key from a secret key:
    linkzmq:zmq_curve_public[3]

Converting keys to/from armoured text strings::
    linkzmq:zmq_z85_decode[3]
    linkzmq:zmq_z85_encode[3]

ERROR HANDLING
--------------
The 0MQ library functions handle errors using the standard conventions found on
POSIX systems. Generally, this means that upon failure a 0MQ library function
shall return either a NULL value (if returning a pointer) or a negative value
(if returning an integer), and the actual error code shall be stored in the
'errno' variable.

On non-POSIX systems some users may experience issues with retrieving the
correct value of the 'errno' variable. The _zmq_errno()_ function is provided
to assist in these cases; for details refer to linkzmq:zmq_errno[3].

The _zmq_strerror()_ function is provided to translate 0MQ-specific error codes
into error message strings; for details refer to linkzmq:zmq_strerror[3].

UTILITY
-------
The following utility functions are provided:

Working with atomic counters::
    linkzmq:zmq_atomic_counter_new[3]
    linkzmq:zmq_atomic_counter_set[3]
    linkzmq:zmq_atomic_counter_inc[3]
    linkzmq:zmq_atomic_counter_dec[3]
    linkzmq:zmq_atomic_counter_value[3]
    linkzmq:zmq_atomic_counter_destroy[3]

MISCELLANEOUS
-------------
The following miscellaneous functions are provided:

Report 0MQ library version::
    linkzmq:zmq_version[3]

LANGUAGE BINDINGS
-----------------
The 0MQ library provides interfaces suitable for calling from programs in any
language; this documentation documents those interfaces as they would be used
by C programmers. The intent is that programmers using 0MQ from other languages
shall refer to this documentation alongside any documentation provided by the
vendor of their language binding.

Language bindings ($$C++$$, Python, PHP, Ruby, Java and more) are provided by
members of the 0MQ community and pointers can be found on the 0MQ website.

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.

RESOURCES
---------
Main web site: <http://www.zeromq.org/>

Report bugs to the 0MQ development mailing list: <zeromq-dev@lists.zeromq.org>

COPYING
-------
Free use of this software is granted under the terms of the GNU Lesser General
Public License (LGPL). For details see the files `COPYING` and `COPYING.LESSER`
included with the 0MQ distribution.


zmq_atomic_counter_dec(3)

zmq_atomic_counter_dec(3) Manual Page

NAME

zmq_atomic_counter_dec - decrement an atomic counter

SYNOPSIS

int zmq_atomic_counter_dec (void *counter);

DESCRIPTION

The zmq_atomic_counter_dec function decrements an atomic counter in a threadsafe fashion. This function uses platform specific atomic operations.

RETURN VALUE

The zmq_atomic_counter_dec() function returns 1 if the counter is greater than zero after decrementing, or zero if the counter reached zero.

EXAMPLE

Test code for atomic counters
void *counter = zmq_atomic_counter_new ();
assert (zmq_atomic_counter_value (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 1);
assert (zmq_atomic_counter_inc (counter) == 2);
assert (zmq_atomic_counter_value (counter) == 3);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_set (counter, 2);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_destroy (&counter);
return 0;

SEE ALSO

zmq_atomic_counter_new(3)
zmq_atomic_counter_set(3)
zmq_atomic_counter_inc(3)
zmq_atomic_counter_value(3)
zmq_atomic_counter_destroy(3)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-08-30 22:42:36 BST


zmq_atomic_counter_dec(3)
=========================

NAME
----
zmq_atomic_counter_dec - decrement an atomic counter

SYNOPSIS
--------
*int zmq_atomic_counter_dec (void *counter);*

DESCRIPTION
-----------
The _zmq_atomic_counter_dec_ function decrements an atomic counter in
a threadsafe fashion. This function uses platform specific atomic
operations.

RETURN VALUE
------------
The _zmq_atomic_counter_dec()_ function returns 1 if the counter is
greater than zero after decrementing, or zero if the counter reached
zero.

EXAMPLE
-------
.Test code for atomic counters
----
void *counter = zmq_atomic_counter_new ();
assert (zmq_atomic_counter_value (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 1);
assert (zmq_atomic_counter_inc (counter) == 2);
assert (zmq_atomic_counter_value (counter) == 3);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_set (counter, 2);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_destroy (&counter);
return 0;
----

SEE ALSO
--------
linkzmq:zmq_atomic_counter_new[3]
linkzmq:zmq_atomic_counter_set[3]
linkzmq:zmq_atomic_counter_inc[3]
linkzmq:zmq_atomic_counter_value[3]
linkzmq:zmq_atomic_counter_destroy[3]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_atomic_counter_destroy(3)

zmq_atomic_counter_destroy(3) Manual Page

NAME

zmq_atomic_counter_destroy - destroy an atomic counter

SYNOPSIS

void zmq_atomic_counter_destroy (void **counter_p);

DESCRIPTION

The zmq_atomic_counter_destroy function destroys an atomic counter and nullifies its reference. Pass the address of an atomic counter (void **) rather than the counter itself. You must destroy all counters that you create, to avoid memory leakage. This function uses platform specific atomic operations.

RETURN VALUE

The zmq_atomic_counter_destroy() function has no return value.

EXAMPLE

Test code for atomic counters
void *counter = zmq_atomic_counter_new ();
assert (zmq_atomic_counter_value (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 1);
assert (zmq_atomic_counter_inc (counter) == 2);
assert (zmq_atomic_counter_value (counter) == 3);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_set (counter, 2);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_destroy (&counter);
return 0;

SEE ALSO

zmq_atomic_counter_new(3)
zmq_atomic_counter_set(3)
zmq_atomic_counter_inc(3)
zmq_atomic_counter_dec(3)
zmq_atomic_counter_value(3)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-08-30 22:42:36 BST


zmq_atomic_counter_destroy(3)
=============================

NAME
----
zmq_atomic_counter_destroy - destroy an atomic counter

SYNOPSIS
--------
*void zmq_atomic_counter_destroy (void **counter_p);*

DESCRIPTION
-----------
The _zmq_atomic_counter_destroy_ function destroys an atomic counter and
nullifies its reference. Pass the address of an atomic counter (void **)
rather than the counter itself. You must destroy all counters that you
create, to avoid memory leakage. This function uses platform specific
atomic operations.

RETURN VALUE
------------
The _zmq_atomic_counter_destroy()_ function has no return value.

EXAMPLE
-------
.Test code for atomic counters
----
void *counter = zmq_atomic_counter_new ();
assert (zmq_atomic_counter_value (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 1);
assert (zmq_atomic_counter_inc (counter) == 2);
assert (zmq_atomic_counter_value (counter) == 3);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_set (counter, 2);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_destroy (&counter);
return 0;
----

SEE ALSO
--------
linkzmq:zmq_atomic_counter_new[3]
linkzmq:zmq_atomic_counter_set[3]
linkzmq:zmq_atomic_counter_inc[3]
linkzmq:zmq_atomic_counter_dec[3]
linkzmq:zmq_atomic_counter_value[3]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_atomic_counter_inc(3)

zmq_atomic_counter_inc(3) Manual Page

NAME

zmq_atomic_counter_inc - increment an atomic counter

SYNOPSIS

int zmq_atomic_counter_inc (void *counter);

DESCRIPTION

The zmq_atomic_counter_inc function increments an atomic counter in a threadsafe fashion. This function uses platform specific atomic operations.

RETURN VALUE

The zmq_atomic_counter_inc() function returns the old value of the counter, before incrementing.

EXAMPLE

Test code for atomic counters
void *counter = zmq_atomic_counter_new ();
assert (zmq_atomic_counter_value (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 1);
assert (zmq_atomic_counter_inc (counter) == 2);
assert (zmq_atomic_counter_value (counter) == 3);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_set (counter, 2);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_destroy (&counter);
return 0;

SEE ALSO

zmq_atomic_counter_new(3)
zmq_atomic_counter_set(3)
zmq_atomic_counter_dec(3)
zmq_atomic_counter_value(3)
zmq_atomic_counter_destroy(3)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-08-30 22:42:36 BST


zmq_atomic_counter_inc(3)
=========================

NAME
----
zmq_atomic_counter_inc - increment an atomic counter

SYNOPSIS
--------
*int zmq_atomic_counter_inc (void *counter);*

DESCRIPTION
-----------
The _zmq_atomic_counter_inc_ function increments an atomic counter in a
threadsafe fashion. This function uses platform specific atomic
operations.

RETURN VALUE
------------
The _zmq_atomic_counter_inc()_ function returns the old value of the
counter, before incrementing.

EXAMPLE
-------
.Test code for atomic counters
----
void *counter = zmq_atomic_counter_new ();
assert (zmq_atomic_counter_value (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 1);
assert (zmq_atomic_counter_inc (counter) == 2);
assert (zmq_atomic_counter_value (counter) == 3);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_set (counter, 2);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_destroy (&counter);
return 0;
----

SEE ALSO
--------
linkzmq:zmq_atomic_counter_new[3]
linkzmq:zmq_atomic_counter_set[3]
linkzmq:zmq_atomic_counter_dec[3]
linkzmq:zmq_atomic_counter_value[3]
linkzmq:zmq_atomic_counter_destroy[3]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_atomic_counter_new(3)

zmq_atomic_counter_new(3) Manual Page

NAME

zmq_atomic_counter_new - create a new atomic counter

SYNOPSIS

void *zmq_atomic_counter_new (void);

DESCRIPTION

The zmq_atomic_counter_new function creates a new atomic counter. You can use this in multithreaded applications to do, for example, reference counting of shared objects. The atomic counter is at least 32 bits large. This function uses platform specific atomic operations.

RETURN VALUE

The zmq_atomic_counter_new() function returns the new atomic counter if successful. Otherwise it returns NULL.

EXAMPLE

Test code for atomic counters
void *counter = zmq_atomic_counter_new ();
assert (zmq_atomic_counter_value (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 1);
assert (zmq_atomic_counter_inc (counter) == 2);
assert (zmq_atomic_counter_value (counter) == 3);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_set (counter, 2);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_destroy (&counter);
return 0;

SEE ALSO

zmq_atomic_counter_set(3)
zmq_atomic_counter_inc(3)
zmq_atomic_counter_dec(3)
zmq_atomic_counter_value(3)
zmq_atomic_counter_destroy(3)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-08-30 22:42:36 BST


zmq_atomic_counter_new(3)
=========================

NAME
----
zmq_atomic_counter_new - create a new atomic counter

SYNOPSIS
--------
*void *zmq_atomic_counter_new (void);*

DESCRIPTION
-----------
The _zmq_atomic_counter_new_ function creates a new atomic counter. You
can use this in multithreaded applications to do, for example, reference
counting of shared objects. The atomic counter is at least 32 bits large.
This function uses platform specific atomic operations.

RETURN VALUE
------------
The _zmq_atomic_counter_new()_ function returns the new atomic counter
if successful. Otherwise it returns NULL.

EXAMPLE
-------
.Test code for atomic counters
----
void *counter = zmq_atomic_counter_new ();
assert (zmq_atomic_counter_value (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 1);
assert (zmq_atomic_counter_inc (counter) == 2);
assert (zmq_atomic_counter_value (counter) == 3);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_set (counter, 2);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_destroy (&counter);
return 0;
----

SEE ALSO
--------
linkzmq:zmq_atomic_counter_set[3]
linkzmq:zmq_atomic_counter_inc[3]
linkzmq:zmq_atomic_counter_dec[3]
linkzmq:zmq_atomic_counter_value[3]
linkzmq:zmq_atomic_counter_destroy[3]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_atomic_counter_set(3)

zmq_atomic_counter_set(3) Manual Page

NAME

zmq_atomic_counter_set - set atomic counter to new value

SYNOPSIS

void zmq_atomic_counter_set (void *counter, int value);

DESCRIPTION

The zmq_atomic_counter_set function sets the counter to a new value, in a threadsafe fashion. The largest value that is guaranteed to work across all platforms is 2^31-1. This function uses platform specific atomic operations.

RETURN VALUE

The zmq_atomic_counter_set() function has no return value.

EXAMPLE

Test code for atomic counters
void *counter = zmq_atomic_counter_new ();
assert (zmq_atomic_counter_value (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 1);
assert (zmq_atomic_counter_inc (counter) == 2);
assert (zmq_atomic_counter_value (counter) == 3);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_set (counter, 2);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_destroy (&counter);
return 0;

SEE ALSO

zmq_atomic_counter_new(3)
zmq_atomic_counter_inc(3)
zmq_atomic_counter_dec(3)
zmq_atomic_counter_value(3)
zmq_atomic_counter_destroy(3)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-08-30 22:42:36 BST


zmq_atomic_counter_set(3)
=========================

NAME
----
zmq_atomic_counter_set - set atomic counter to new value

SYNOPSIS
--------
*void zmq_atomic_counter_set (void *counter, int value);*

DESCRIPTION
-----------
The _zmq_atomic_counter_set_ function sets the counter to a new value,
in a threadsafe fashion. The largest value that is guaranteed to work
across all platforms is 2^31-1. This function uses platform specific
atomic operations.

RETURN VALUE
------------
The _zmq_atomic_counter_set()_ function has no return value.

EXAMPLE
-------
.Test code for atomic counters
----
void *counter = zmq_atomic_counter_new ();
assert (zmq_atomic_counter_value (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 1);
assert (zmq_atomic_counter_inc (counter) == 2);
assert (zmq_atomic_counter_value (counter) == 3);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_set (counter, 2);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_destroy (&counter);
return 0;
----

SEE ALSO
--------
linkzmq:zmq_atomic_counter_new[3]
linkzmq:zmq_atomic_counter_inc[3]
linkzmq:zmq_atomic_counter_dec[3]
linkzmq:zmq_atomic_counter_value[3]
linkzmq:zmq_atomic_counter_destroy[3]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_atomic_counter_value(3)

zmq_atomic_counter_value(3) Manual Page

NAME

zmq_atomic_counter_value - return value of atomic counter

SYNOPSIS

int zmq_atomic_counter_value (void *counter);

DESCRIPTION

The zmq_atomic_counter_value function returns the value of an atomic counter created by zmq_atomic_counter_new(). This function uses platform specific atomic operations.

RETURN VALUE

The zmq_atomic_counter_value() function returns the value of the atomic counter. If counter does not point to an atomic counter created by zmq_atomic_counter_new(), the behaviour is undefined.

EXAMPLE

Test code for atomic counters
void *counter = zmq_atomic_counter_new ();
assert (zmq_atomic_counter_value (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 1);
assert (zmq_atomic_counter_inc (counter) == 2);
assert (zmq_atomic_counter_value (counter) == 3);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_set (counter, 2);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_destroy (&counter);
return 0;

SEE ALSO

zmq_atomic_counter_new(3)
zmq_atomic_counter_set(3)
zmq_atomic_counter_inc(3)
zmq_atomic_counter_dec(3)
zmq_atomic_counter_destroy(3)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-09-06 11:47:31 BST


zmq_atomic_counter_value(3)
===========================

NAME
----
zmq_atomic_counter_value - return value of atomic counter

SYNOPSIS
--------
*int zmq_atomic_counter_value (void *counter);*

DESCRIPTION
-----------
The _zmq_atomic_counter_value_ function returns the value of an atomic
counter created by _zmq_atomic_counter_new()_. This function uses platform
specific atomic operations.

RETURN VALUE
------------
The _zmq_atomic_counter_value()_ function returns the value of the
atomic counter. If _counter_ does not point to an atomic counter created by
_zmq_atomic_counter_new()_, the behaviour is undefined.

EXAMPLE
-------
.Test code for atomic counters
----
void *counter = zmq_atomic_counter_new ();
assert (zmq_atomic_counter_value (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 0);
assert (zmq_atomic_counter_inc (counter) == 1);
assert (zmq_atomic_counter_inc (counter) == 2);
assert (zmq_atomic_counter_value (counter) == 3);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_set (counter, 2);
assert (zmq_atomic_counter_dec (counter) == 1);
assert (zmq_atomic_counter_dec (counter) == 0);
zmq_atomic_counter_destroy (&counter);
return 0;
----

SEE ALSO
--------
linkzmq:zmq_atomic_counter_new[3]
linkzmq:zmq_atomic_counter_set[3]
linkzmq:zmq_atomic_counter_inc[3]
linkzmq:zmq_atomic_counter_dec[3]
linkzmq:zmq_atomic_counter_destroy[3]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_bind(3)

zmq_bind(3) Manual Page

NAME

zmq_bind - accept incoming connections on a socket

SYNOPSIS

int zmq_bind (void *socket, const char *endpoint);

DESCRIPTION

The zmq_bind() function binds the socket to a local endpoint and then accepts incoming connections on that endpoint.

The 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 bind to.

ØMQ provides the the following transports:

tcp

unicast transport using TCP, see zmq_tcp(7)

ipc

local inter-process communication transport, see zmq_ipc(7)

inproc

local in-process (inter-thread) communication transport, see zmq_inproc(7)

pgm, epgm

reliable multicast transport using PGM, see zmq_pgm(7)

vmci

virtual machine communications interface (VMCI), see zmq_vmci(7)

udp

unreliable unicast and multicast using UDP, see zmq_udp(7)

Every ØMQ socket type except ZMQ_PAIR and ZMQ_CHANNEL supports one-to-many and many-to-one semantics. The precise semantics depend on the socket type and are defined in zmq_socket(3).

The ipc, tcp, vmci and udp transports accept wildcard addresses: see zmq_ipc(7), zmq_tcp(7), zmq_vmci(7) and zmq_udp(7) for details.

Note
 the address syntax may be different for zmq_bind() and zmq_connect() especially for the tcp, pgm and epgm transports.
Note
 following a zmq_bind(), the socket enters a mute state unless or until at least one incoming or outgoing connection is made, at which point the socket enters a ready state. In the mute state, the socket blocks or drops messages according to the socket type, as defined in zmq_socket(3). By contrast, following a libzmq:zmq_connect[3], the socket enters the ready state.

RETURN VALUE

The zmq_bind() function returns zero if successful. Otherwise it returns -1 and sets errno to one of the values defined below.

ERRORS

EINVAL

The endpoint supplied is invalid.

EPROTONOSUPPORT

The requested transport protocol is not supported.

ENOCOMPATPROTO

The requested transport protocol is not compatible with the socket type.

EADDRINUSE

The requested address is already in use.

EADDRNOTAVAIL

The requested address was not local.

ENODEV

The requested address specifies a nonexistent interface.

ETERM

The ØMQ context associated with the specified socket was terminated.

ENOTSOCK

The provided socket was invalid.

EMTHREAD

No I/O thread is available to accomplish the task.

EXAMPLE

Binding a publisher socket to an in-process and a TCP transport
/* Create a ZMQ_PUB socket */
void *socket = zmq_socket (context, ZMQ_PUB);
assert (socket);
/* Bind it to a in-process transport with the address 'my_publisher' */
int rc = zmq_bind (socket, "inproc://my_publisher");
assert (rc == 0);
/* Bind it to a TCP transport on port 5555 of the 'eth0' interface */
rc = zmq_bind (socket, "tcp://eth0:5555");
assert (rc == 0);

SEE ALSO

zmq_connect(3)
zmq_socket(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


zmq_bind(3)
===========

NAME
----
zmq_bind - accept incoming connections on a socket

SYNOPSIS
--------
*int zmq_bind (void '*socket', const char '*endpoint');*

DESCRIPTION
-----------
The _zmq_bind()_ function binds the 'socket' to a local 'endpoint' and then
accepts incoming connections on that endpoint.

The '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 bind to.

0MQ provides the the following transports:

'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7]
'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7]
'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7]
'vmci':: virtual machine communications interface (VMCI), see linkzmq:zmq_vmci[7]
'udp':: unreliable unicast and multicast using UDP, see linkzmq:zmq_udp[7]

Every 0MQ socket type except 'ZMQ_PAIR' and 'ZMQ_CHANNEL' supports one-to-many and many-to-one
semantics. The precise semantics depend on the socket type and are defined in
linkzmq:zmq_socket[3].

The 'ipc', 'tcp', 'vmci' and 'udp' transports accept wildcard addresses: see
linkzmq:zmq_ipc[7], linkzmq:zmq_tcp[7], linkzmq:zmq_vmci[7] and
linkzmq:zmq_udp[7] for details.

NOTE: the address syntax may be different for _zmq_bind()_ and _zmq_connect()_
especially for the 'tcp', 'pgm' and 'epgm' transports.

NOTE: following a _zmq_bind()_, the socket enters a 'mute' state unless or
until at least one incoming or outgoing connection is made, at which point
the socket enters a 'ready' state. In the mute state, the socket blocks or
drops messages according to the socket type, as defined in linkzmq:zmq_socket[3].
By contrast, following a libzmq:zmq_connect[3], the socket enters the 'ready' state.

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

ERRORS
------
*EINVAL*::
The endpoint supplied is invalid.
*EPROTONOSUPPORT*::
The requested 'transport' protocol is not supported.
*ENOCOMPATPROTO*::
The requested 'transport' protocol is not compatible with the socket type.
*EADDRINUSE*::
The requested 'address' is already in use.
*EADDRNOTAVAIL*::
The requested 'address' was not local.
*ENODEV*::
The requested 'address' specifies a nonexistent interface.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*EMTHREAD*::
No I/O thread is available to accomplish the task.

EXAMPLE
-------
.Binding a publisher socket to an in-process and a TCP transport
----
/* Create a ZMQ_PUB socket */
void *socket = zmq_socket (context, ZMQ_PUB);
assert (socket);
/* Bind it to a in-process transport with the address 'my_publisher' */
int rc = zmq_bind (socket, "inproc://my_publisher");
assert (rc == 0);
/* Bind it to a TCP transport on port 5555 of the 'eth0' interface */
rc = zmq_bind (socket, "tcp://eth0:5555");
assert (rc == 0);
----

SEE ALSO
--------
linkzmq:zmq_connect[3]
linkzmq:zmq_socket[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_close(3)

zmq_close(3) Manual Page

NAME

zmq_close - close 0MQ socket

SYNOPSIS

int zmq_close (void *socket);

DESCRIPTION

The zmq_close() function shall destroy the socket referenced by the socket argument. Any outstanding messages physically received from the network but not yet received by the application with zmq_recv() shall be discarded. The behaviour for discarding messages sent by the application with zmq_send() but not yet physically transferred to the network depends on the value of the ZMQ_LINGER socket option for the specified socket.

zmq_close() must be called exactly once for each socket. If it is never called, zmq_ctx_term() will block forever. If it is called multiple times for the same socket or if socket does not point to a socket, the behaviour is undefined.

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 zmq_setsockopt(3) and zmq_ctx_term(3).
Note
 This API will complete asynchronously, so not everything will be deallocated after it returns. See above for details about linger.

RETURN VALUE

The zmq_close() function shall return zero if successful. Otherwise it shall return -1 and set errno to one of the values defined below.

ERRORS

ENOTSOCK

The provided socket was NULL.

SEE ALSO

zmq_socket(3)
zmq_ctx_term(3)
zmq_setsockopt(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-09-06 11:47:31 BST


zmq_close(3)
============

NAME
----
zmq_close - close 0MQ socket

SYNOPSIS
--------
*int zmq_close (void '*socket');*

DESCRIPTION
-----------
The _zmq_close()_ function shall destroy the socket referenced by the 'socket'
argument. Any outstanding messages physically received from the network but not
yet received by the application with _zmq_recv()_ shall be discarded. The
behaviour for discarding messages sent by the application with _zmq_send()_ but
not yet physically transferred to the network depends on the value of the
_ZMQ_LINGER_ socket option for the specified 'socket'.

_zmq_close()_ must be called exactly once for each socket. If it is never called,
_zmq_ctx_term()_ will block forever. If it is called multiple times for the same
socket or if 'socket' does not point to a socket, the behaviour is undefined.

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 linkzmq:zmq_setsockopt[3] and linkzmq:zmq_ctx_term[3].

NOTE: This API will complete asynchronously, so not everything will be deallocated
after it returns. See above for details about linger.

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

ERRORS
------
*ENOTSOCK*::
The provided 'socket' was NULL.

SEE ALSO
--------
linkzmq:zmq_socket[3]
linkzmq:zmq_ctx_term[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_connect(3)

zmq_connect(3) Manual Page

NAME

zmq_connect - create outgoing connection from socket

SYNOPSIS

int zmq_connect (void *socket, const char *endpoint);

DESCRIPTION

The zmq_connect() function connects the socket to an endpoint and then accepts incoming connections on that endpoint.

The 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.

ØMQ provides the the following transports:

tcp

unicast transport using TCP, see zmq_tcp(7)

ipc

local inter-process communication transport, see zmq_ipc(7)

inproc

local in-process (inter-thread) communication transport, see zmq_inproc(7)

pgm, epgm

reliable multicast transport using PGM, see zmq_pgm(7)

vmci

virtual machine communications interface (VMCI), see zmq_vmci(7)

udp

unreliable unicast and multicast using UDP, see zmq_udp(7)

Every ØMQ socket type except ZMQ_PAIR and ZMQ_CHANNEL supports one-to-many and many-to-one semantics. The precise semantics depend on the socket type and are defined in zmq_socket(3).

Note
 for most transports and socket types the connection is not performed immediately but as needed by ØMQ. Thus a successful call to zmq_connect() does not mean that the connection was or could actually be established. Because of this, for most transports and socket types the order in which a server socket is bound and a client socket is connected to it does not matter. The ZMQ_PAIR and ZMQ_CHANNEL sockets are an exception, as they do not automatically reconnect to endpoints.
Note
 following a zmq_connect(), for socket types except for ZMQ_ROUTER, the socket enters its normal ready state. By contrast, following a zmq_bind() alone, the socket enters a mute state in which the socket blocks or drops messages according to the socket type, as defined in zmq_socket(3). A ZMQ_ROUTER socket enters its normal ready state for a specific peer only when handshaking is complete for that peer, which may take an arbitrary time.
Note
 for some socket types, multiple connections to the same endpoint don’t really make sense (see https://github.com/zeromq/libzmq/issues/788). For those socket types, any attempt to connect to an already connected endpoint is silently ignored (i.e., returns zero). This behavior applies to ZMQ_DEALER, ZMQ_SUB, ZMQ_PUB, and ZMQ_REQ socket types.

RETURN VALUE

The zmq_connect() function returns zero if successful. Otherwise it returns -1 and sets errno to one of the values defined below.

ERRORS

EINVAL

The endpoint supplied is invalid.

EPROTONOSUPPORT

The requested transport protocol is not supported.

ENOCOMPATPROTO

The requested transport protocol is not compatible with the socket type.

ETERM

The ØMQ context associated with the specified socket was terminated.

ENOTSOCK

The provided socket was invalid.

EMTHREAD

No I/O thread is available to accomplish the task.

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 an in-process transport with the address 'my_publisher' */
int rc = zmq_connect (socket, "inproc://my_publisher");
assert (rc == 0);
/* Connect it to the host server001, port 5555 using a TCP transport */
rc = zmq_connect (socket, "tcp://server001:5555");
assert (rc == 0);

SEE ALSO

zmq_bind(3)
zmq_socket(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


zmq_connect(3)
==============

NAME
----
zmq_connect - create outgoing connection from socket

SYNOPSIS
--------
*int zmq_connect (void '*socket', const char '*endpoint');*

DESCRIPTION
-----------
The _zmq_connect()_ function connects the 'socket' to an 'endpoint' and then
accepts incoming connections on that endpoint.

The '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.

0MQ provides the the following transports:

'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7]
'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7]
'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7]
'vmci':: virtual machine communications interface (VMCI), see linkzmq:zmq_vmci[7]
'udp':: unreliable unicast and multicast using UDP, see linkzmq:zmq_udp[7]

Every 0MQ socket type except 'ZMQ_PAIR' and 'ZMQ_CHANNEL' supports one-to-many and many-to-one
semantics. The precise semantics depend on the socket type and are defined in
linkzmq:zmq_socket[3].

NOTE: for most transports and socket types the connection is not performed
immediately but as needed by 0MQ. Thus a successful call to _zmq_connect()_
does not mean that the connection was or could actually be established.
Because of this, for most transports and socket types the order in which
a 'server' socket is bound and a 'client' socket is connected to it does not
matter. The _ZMQ_PAIR_ and _ZMQ_CHANNEL_ sockets are an exception, as they do not automatically
reconnect to endpoints.

NOTE: following a _zmq_connect()_, for socket types except for ZMQ_ROUTER,
the socket enters its normal 'ready' state. By contrast, following a
_zmq_bind()_ alone, the socket enters a 'mute' state in which the socket
blocks or drops messages according to the socket type, as defined in
linkzmq:zmq_socket[3]. A ZMQ_ROUTER socket enters its normal 'ready' state
for a specific peer only when handshaking is complete for that peer, which
may take an arbitrary time.

NOTE: for some socket types, multiple connections to the same endpoint
don't really make sense
(see https://github.com/zeromq/libzmq/issues/788).
For those socket types, any attempt to connect to an already connected endpoint
is silently ignored (i.e., returns zero).  This behavior applies to ZMQ_DEALER,
ZMQ_SUB, ZMQ_PUB, and ZMQ_REQ socket types.

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

ERRORS
------
*EINVAL*::
The endpoint supplied is invalid.
*EPROTONOSUPPORT*::
The requested 'transport' protocol is not supported.
*ENOCOMPATPROTO*::
The requested 'transport' protocol is not compatible with the socket type.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*EMTHREAD*::
No I/O thread is available to accomplish the task.

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 an in-process transport with the address 'my_publisher' */
int rc = zmq_connect (socket, "inproc://my_publisher");
assert (rc == 0);
/* Connect it to the host server001, port 5555 using a TCP transport */
rc = zmq_connect (socket, "tcp://server001:5555");
assert (rc == 0);
----

SEE ALSO
--------
linkzmq:zmq_bind[3]
linkzmq:zmq_socket[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_connect_peer(3)

zmq_connect_peer(3) Manual Page

NAME

zmq_connect_peer - create outgoing connection from socket and return the connection routing id in thread-safe and atomic way.

SYNOPSIS

uint32_t zmq_connect_peer (void *socket, const char *endpoint);

DESCRIPTION

The zmq_connect_peer() function connects a ZMQ_PEER socket to an endpoint and then returns the endpoint routing_id.

The 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.

The function is supported only on the ZMQ_PEER socket type and would return 0 with errno set to ENOTSUP otherwise.

The zmq_connect_peer() support the following transports:

tcp

unicast transport using TCP, see zmq_tcp(7)

ipc

local inter-process communication transport, see zmq_ipc(7)

inproc

local in-process (inter-thread) communication transport, see zmq_inproc(7)

ws

unicast transport using WebSockets, see zmq_ws(7)

wss

unicast transport using WebSockets over TLS, see zmq_wss(7)

RETURN VALUE

The zmq_connect_peer() function returns the peer routing_id if successful. Otherwise it returns 0 and sets errno to one of the values defined below.

ERRORS

EINVAL

The endpoint supplied is invalid.

EPROTONOSUPPORT

The requested transport protocol is not supported with ZMQ_PEER.

ENOCOMPATPROTO

The requested transport protocol is not compatible with the socket type.

ETERM

The ØMQ context associated with the specified socket was terminated.

ENOTSOCK

The provided socket was invalid.

EMTHREAD

No I/O thread is available to accomplish the task.

ENOTSUP

The socket is not of type ZMQ_PEER.

EFAULT

The ZMQ_IMMEDIATE option is set on the socket.

EXAMPLE

Connecting a peer socket to a TCP transport and sending a message
/* Create a ZMQ_SUB socket */
void *socket = zmq_socket (context, ZMQ_PEER);
assert (socket);
/* Connect it to the host server001, port 5555 using a TCP transport */
uint32_t routing_id = zmq_connect (socket, "tcp://server001:5555");
assert (routing_id == 0);
/* Sending a message to the peer  */
zmq_msg_t msg;
int rc = zmq_msg_init_data (&msg, "HELLO", 5, NULL, NULL);
assert (rc == 0);
rc = zmq_msg_set_routing_id (&msg, routing_id);
assert (rc == 0);
rc = zmq_msg_send (&msg, socket, 0);
assert (rc == 5);
rc = zmq_msg_close (&msg);
assert (rc == 0);

SEE ALSO

zmq_connect(3)
zmq_bind(3)
zmq_socket(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


zmq_connect_peer(3)
===================

NAME
----
zmq_connect_peer - create outgoing connection from socket and return the connection routing id in thread-safe and atomic way.

SYNOPSIS
--------
*uint32_t zmq_connect_peer (void '*socket', const char '*endpoint');*

DESCRIPTION
-----------
The _zmq_connect_peer()_ function connects a 'ZMQ_PEER' socket to an 'endpoint' and then returns the endpoint 'routing_id'.

The '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.

The function is supported only on the 'ZMQ_PEER' socket type and would return `0` with 'errno' set to 'ENOTSUP' otherwise.

The _zmq_connect_peer()_ support the following transports:

'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7]
'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7]
'ws':: unicast transport using WebSockets, see linkzmq:zmq_ws[7]
'wss':: unicast transport using WebSockets over TLS, see linkzmq:zmq_wss[7]

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

ERRORS
------
*EINVAL*::
The endpoint supplied is invalid.
*EPROTONOSUPPORT*::
The requested 'transport' protocol is not supported with 'ZMQ_PEER'.
*ENOCOMPATPROTO*::
The requested 'transport' protocol is not compatible with the socket type.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*EMTHREAD*::
No I/O thread is available to accomplish the task.
*ENOTSUP*::
The socket is not of type 'ZMQ_PEER'.
*EFAULT*::
The 'ZMQ_IMMEDIATE' option is set on the socket.

EXAMPLE
-------
.Connecting a peer socket to a TCP transport and sending a message
----
/* Create a ZMQ_SUB socket */
void *socket = zmq_socket (context, ZMQ_PEER);
assert (socket);
/* Connect it to the host server001, port 5555 using a TCP transport */
uint32_t routing_id = zmq_connect (socket, "tcp://server001:5555");
assert (routing_id == 0);
/* Sending a message to the peer  */
zmq_msg_t msg;
int rc = zmq_msg_init_data (&msg, "HELLO", 5, NULL, NULL);
assert (rc == 0);
rc = zmq_msg_set_routing_id (&msg, routing_id);
assert (rc == 0);
rc = zmq_msg_send (&msg, socket, 0);
assert (rc == 5);
rc = zmq_msg_close (&msg);
assert (rc == 0);
----

SEE ALSO
--------
linkzmq:zmq_connect[3]
linkzmq:zmq_bind[3]
linkzmq:zmq_socket[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_ctx_get(3)

zmq_ctx_get(3) Manual Page

NAME

zmq_ctx_get - get context options

SYNOPSIS

int zmq_ctx_get (void *context, int option_name);

DESCRIPTION

The zmq_ctx_get() function shall return the option specified by the option_name argument.

The zmq_ctx_get() function accepts the following option names:

ZMQ_IO_THREADS: Get number of I/O threads

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

ZMQ_MAX_SOCKETS: Get maximum number of sockets

The ZMQ_MAX_SOCKETS argument returns the maximum number of sockets allowed for this context.

ZMQ_MAX_MSGSZ: Get maximum message size

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_ZERO_COPY_RECV argument return whether message decoder uses a zero copy strategy when receiving messages. Default value is 1. NOTE: in DRAFT state, not yet available in stable releases.

ZMQ_SOCKET_LIMIT: Get largest configurable number of sockets

The ZMQ_SOCKET_LIMIT argument returns the largest number of sockets that zmq_ctx_set(3) 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_SCHED_POLICY argument returns the scheduling policy for internal context’s thread pool.

ZMQ_THREAD_NAME_PREFIX: Get name prefix 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

zmq_ctx_set(3) zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


zmq_ctx_get(3)
==============

NAME
----

zmq_ctx_get - get context options

SYNOPSIS
--------
*int zmq_ctx_get (void '*context', int 'option_name');*

DESCRIPTION
-----------
The _zmq_ctx_get()_ function shall return the option specified by the
'option_name' argument.

The _zmq_ctx_get()_ function accepts the following option names:

ZMQ_IO_THREADS: Get number of I/O threads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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_SOCKETS' argument returns the maximum number of sockets
allowed for this context.

ZMQ_MAX_MSGSZ: Get maximum message size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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_ZERO_COPY_RECV' argument return whether message decoder uses a zero copy
strategy when receiving messages. Default value is 1.
NOTE: in DRAFT state, not yet available in stable releases.

ZMQ_SOCKET_LIMIT: Get largest configurable number of sockets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_SOCKET_LIMIT' argument returns the largest number of sockets that
linkzmq:zmq_ctx_set[3] 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_SCHED_POLICY' argument returns the scheduling policy for
internal context's thread pool.

ZMQ_THREAD_NAME_PREFIX: Get name prefix 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
--------
linkzmq:zmq_ctx_set[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_ctx_new(3)

zmq_ctx_new(3) Manual Page

NAME

zmq_ctx_new - create new 0MQ context

SYNOPSIS

void *zmq_ctx_new ();

DESCRIPTION

The zmq_ctx_new() function creates a new ØMQ context.

This function replaces the deprecated function zmq_init(3).

Thread safety

A ØMQ 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.

RETURN VALUE

The zmq_ctx_new() function shall return an opaque handle to the newly created context if successful. Otherwise it shall return NULL and set errno to one of the values defined below.

ERRORS

EMFILE

The limit on the total number of open files has been reached and it wasn’t possible to create a new context.

EMFILE

The limit on the total number of open files in system has been reached and it wasn’t possible to create a new context.

SEE ALSO

zmq(7)
zmq_ctx_set(3)
zmq_ctx_get(3)
zmq_ctx_term(3)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


zmq_ctx_new(3)
==============

NAME
----
zmq_ctx_new - create new 0MQ context

SYNOPSIS
--------
*void *zmq_ctx_new ();*

DESCRIPTION
-----------
The _zmq_ctx_new()_ function creates a new 0MQ 'context'.

This function replaces the deprecated function linkzmq:zmq_init[3].

.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.

RETURN VALUE
------------
The _zmq_ctx_new()_ function shall return an opaque handle to the newly created
'context' if successful. Otherwise it shall return NULL and set 'errno' to one
of the values defined below.

ERRORS
------
*EMFILE*::
The limit on the total number of open files has been reached and it
wasn't possible to create a new context.
*EMFILE*::
The limit on the total number of open files in system has been reached
and it wasn't possible to create a new context.

SEE ALSO
--------
linkzmq:zmq[7]
linkzmq:zmq_ctx_set[3]
linkzmq:zmq_ctx_get[3]
linkzmq:zmq_ctx_term[3]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_ctx_set(3)

zmq_ctx_set(3) Manual Page

NAME

zmq_ctx_set - set context options

SYNOPSIS

int zmq_ctx_set (void *context, int option_name, int option_value);

DESCRIPTION

The zmq_ctx_set() function shall set the option specified by the option_name argument to the value of the option_value argument.

The zmq_ctx_set() function accepts the following options:

ZMQ_BLOCKY: Fix blocky behavior

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.

Default value

true (old behavior)

ZMQ_IO_THREADS: Set number of I/O threads

The ZMQ_IO_THREADS argument specifies the size of the ØMQ thread pool to handle I/O operations. If your application is using only the inproc transport for messaging you may set this to zero, otherwise set it to at least one. This option only applies before creating any sockets on the context.

Default value

1

ZMQ_THREAD_SCHED_POLICY: Set scheduling policy for 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.

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 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.

Default value

-1

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

The ZMQ_THREAD_AFFINITY_CPU_ADD argument adds 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.

Default value

-1

ZMQ_THREAD_AFFINITY_CPU_REMOVE: Remove 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.

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.

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 zmq_ctx_get(3) using the ZMQ_MAX_MSGSZ option.

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 zmq_ctx_get(3) using the ZMQ_ZERO_COPY_RECV option. NOTE: in DRAFT state, not yet available in stable releases.

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 zmq_ctx_get(3) using the ZMQ_SOCKET_LIMIT option.

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.

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

zmq_ctx_get(3) zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


zmq_ctx_set(3)
==============

NAME
----

zmq_ctx_set - set context options

SYNOPSIS
--------
*int zmq_ctx_set (void '*context', int 'option_name', int 'option_value');*

DESCRIPTION
-----------
The _zmq_ctx_set()_ function shall set the option specified by the
'option_name' argument to the value of the 'option_value' argument.

The _zmq_ctx_set()_ function accepts the following options:

ZMQ_BLOCKY: Fix blocky behavior
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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_IO_THREADS' argument specifies the size of the 0MQ thread pool to
handle I/O operations. If your application is using only the 'inproc'
transport for messaging you may set this to zero, otherwise set it to at
least one. This option only applies before creating any sockets on the
context.

[horizontal]
Default value:: 1

ZMQ_THREAD_SCHED_POLICY: Set scheduling policy for 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
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_ADD' argument adds 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_AFFINITY_CPU_REMOVE: Remove 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 linkzmq:zmq_ctx_get[3] 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
linkzmq:zmq_ctx_get[3] 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
linkzmq:zmq_ctx_get[3] 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
--------
linkzmq:zmq_ctx_get[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_ctx_shutdown(3)

zmq_ctx_shutdown(3) Manual Page

NAME

zmq_ctx_shutdown - shutdown a 0MQ context

SYNOPSIS

int zmq_ctx_shutdown (void *context);

DESCRIPTION

The zmq_ctx_shutdown() function shall shutdown the ØMQ 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 zmq_ctx_term(3) 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

zmq(7)
zmq_init(3)
zmq_ctx_term(3)
zmq_close(3)
zmq_setsockopt(3)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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 linkzmq:zmq_ctx_term[3]
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
--------
linkzmq:zmq[7]
linkzmq:zmq_init[3]
linkzmq:zmq_ctx_term[3]
linkzmq:zmq_close[3]
linkzmq:zmq_setsockopt[3]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_ctx_term(3)

zmq_ctx_term(3) Manual Page

NAME

zmq_ctx_term - terminate a 0MQ context

SYNOPSIS

int zmq_ctx_term (void *context);

DESCRIPTION

The zmq_ctx_term() function shall destroy the ØMQ 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 zmq_setsockopt(3).

This function replaces the deprecated functions zmq_term(3) and zmq_ctx_destroy(3).

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

zmq(7)
zmq_init(3)
zmq_close(3)
zmq_setsockopt(3)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-08-30 22:42:36 BST


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 linkzmq:zmq_setsockopt[3].

This function replaces the deprecated functions linkzmq:zmq_term[3] and
linkzmq:zmq_ctx_destroy[3].

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
--------
linkzmq:zmq[7]
linkzmq:zmq_init[3]
linkzmq:zmq_close[3]
linkzmq:zmq_setsockopt[3]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_curve(7)

zmq_curve(7) Manual Page

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

zmq_z85_encode(3)
zmq_z85_decode(3)
zmq_setsockopt(3)
zmq_null(7)
zmq_plain(7)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2017-05-16 22:07:05 BST


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
--------
linkzmq:zmq_z85_encode[3]
linkzmq:zmq_z85_decode[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_null[7]
linkzmq:zmq_plain[7]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_curve_keypair(3)

zmq_curve_keypair(3) Manual Page

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 zmq_z85_encode(3).

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

zmq_z85_decode(3)
zmq_z85_encode(3)
zmq_curve(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-08-30 22:42:36 BST


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 linkzmq:zmq_z85_encode[3].

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
--------
linkzmq:zmq_z85_decode[3]
linkzmq:zmq_z85_encode[3]
linkzmq:zmq_curve[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_curve_public(3)

zmq_curve_public(3) Manual Page

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 zmq_z85_encode(3).

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

zmq_z85_decode(3)
zmq_z85_encode(3)
zmq_curve_keypair(3)
zmq_curve(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-08-30 22:42:36 BST


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 linkzmq:zmq_z85_encode[3].

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
--------
linkzmq:zmq_z85_decode[3]
linkzmq:zmq_z85_encode[3]
linkzmq:zmq_curve_keypair[3]
linkzmq:zmq_curve[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_disconnect(3)

zmq_disconnect(3) Manual Page

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 longuer 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 zmq_connect(3)

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 zmq_setsockopt(3) and zmq_ctx_term(3).

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 ØMQ 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

zmq_connect(3)
zmq_socket(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-09-06 11:47:31 BST


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 longuer 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 linkzmq:zmq_connect[3]

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 linkzmq:zmq_setsockopt[3] and linkzmq:zmq_ctx_term[3].

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
--------
linkzmq:zmq_connect[3]
linkzmq:zmq_socket[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_errno(3)

zmq_errno(3) Manual Page

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 ØMQ 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

zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2017-05-16 22:07:05 BST


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
--------
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_getsockopt(3)

zmq_getsockopt(3) Manual Page

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 ØMQ 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 ØMQ 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 ØMQ 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 zmq_init(3) for details on allocating the number of I/O threads for a specific context.

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.

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.

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.

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.

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.

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.

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.

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 ØMQ 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.
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.

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.

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.

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.

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).

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).

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.

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.

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.

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.

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.

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().

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 zmq_close(3), and further affects the termination of the socket’s context with zmq_ctx_term(3). The following outlines the different behaviours:

  • The default value of -1 specifies an infinite linger period. Pending messages shall not be discarded after a call to zmq_close(); attempting to terminate the socket’s context with zmq_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.

    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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 ØMQ 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, ØMQ shall take appropriate action such as blocking or dropping sent messages. Refer to the individual socket descriptions in zmq_socket(3) for details on the exact action taken for each socket type.

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 zmq_send(3) and zmq_recv(3) for a detailed description of multi-part messages.

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.

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 ØMQ 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 ØMQ to prevent reconnection storms in topologies with a large number of peers per socket.
Option value type | int
Option value unit | milliseconds
Default value | 100
Applicable socket types | all, only for connection-oriented transports

ZMQ_RECONNECT_IVL_MAX: Retrieve maximum reconnection interval

The ZMQ_RECONNECT_IVL_MAX option shall retrieve the maximum reconnection interval for the specified socket. This is the maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled untill ZMQ_RECONNECT_IVL_MAX is reached. This allows for exponential backoff strategy. Default value means no exponential backoff is performed and reconnect interval calculations are only based on ZMQ_RECONNECT_IVL.

Note
 Values less than ZMQ_RECONNECT_IVL will be ignored.
Option value type | int
Option value unit | milliseconds
Default value | 0 (only use ZMQ_RECONNECT_IVL)
Applicable socket types | all, only for connection-oriented transport

ZMQ_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 ØMQ receives the ECONNREFUSED return code from the connect. This indicates that there is no code bound to the specified endpoint.

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.

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 ØMQ infrastructure.

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.

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 ØMQ 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, ØMQ shall take appropriate action such as blocking or dropping sent messages. Refer to the individual socket descriptions in zmq_socket(3) for details on the exact action taken for each socket type.

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.

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.

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.

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.

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.

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.

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.

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 zmq_socket(3) for which sockets are thread-safe.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.
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.
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.
Option value type | int
Option value unit | messages
Default value | 8192
Applicable socket types | All, when using TCP, IPC, PGM or 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 ØMQ 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

zmq_setsockopt(3)
zmq_socket(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-16 14:15:51 GMT


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 linkzmq:zmq_init[3] for details on allocating the number of I/O
threads for a specific _context_.

[horizontal]
Option value type:: uint64_t
Option value unit:: N/A (bitmap)
Default value:: 0
Applicable socket types:: N/A

ZMQ_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
linkzmq:zmq_close[3], and further affects the termination of the socket's
context with linkzmq:zmq_ctx_term[3]. The following outlines the different
behaviours:

* The default value of '-1' specifies an infinite linger period. Pending
  messages shall not be discarded after a call to _zmq_close()_; attempting to
  terminate the socket's context with _zmq_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 linkzmq:zmq_socket[3] for details on the exact action taken for each socket
type.

[horizontal]
Option value type:: int
Option value unit:: messages
Default value:: 1000
Applicable socket types:: all

ZMQ_RCVMORE: More message data parts to follow
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_RCVMORE' option shall return True (1) if the message part last
received from the 'socket' was a data part with more parts to follow. If there
are no data parts to follow, this option shall return False (0).

Refer to linkzmq:zmq_send[3] and linkzmq:zmq_recv[3] for a detailed description
of multi-part messages.

[horizontal]
Option value type:: int
Option value unit:: boolean
Default value:: N/A
Applicable socket types:: all

ZMQ_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 maximum reconnection interval
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_RECONNECT_IVL_MAX' option shall retrieve the maximum reconnection
interval for the specified 'socket'.  This is the maximum period 0MQ shall wait
between attempts to reconnect. On each reconnect attempt, the previous interval
shall be doubled untill ZMQ_RECONNECT_IVL_MAX is reached. This allows for
exponential backoff strategy. Default value means no exponential backoff is
performed and reconnect interval calculations are only based on
ZMQ_RECONNECT_IVL.

NOTE:  Values less than ZMQ_RECONNECT_IVL will be ignored.

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

ZMQ_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 linkzmq:zmq_socket[3] for details on the exact action taken for each socket
type.

[horizontal]
Option value type:: int
Option value unit:: messages
Default value:: 1000
Applicable socket types:: all

ZMQ_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 linkzmq:zmq_socket[3] 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.

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

ERRORS
------
*EINVAL*::
The requested option _option_name_ is unknown, or the requested _option_len_ or
_option_value_ is invalid, or the size of the buffer pointed to by
_option_value_, as specified by _option_len_, is insufficient for storing the
option value.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*EINTR*::
The operation was interrupted by delivery of a signal.

EXAMPLE
-------
.Retrieving the high water mark for outgoing messages
----
/* Retrieve high water mark into sndhwm */
int sndhwm;
size_t sndhwm_size = sizeof (sndhwm);
rc = zmq_getsockopt (socket, ZMQ_SNDHWM, &sndhwm, &sndhwm_size);
assert (rc == 0);
----

SEE ALSO
--------
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_socket[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_gssapi(7)

zmq_gssapi(7) Manual Page

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

zmq_setsockopt(3)
zmq_null(7)
zmq_curve(7)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-09-06 11:47:31 BST


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
--------
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_null[7]
linkzmq:zmq_curve[7]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_has(3)

zmq_has(3) Manual Page

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 ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-09-06 11:47:31 BST


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 <http://www.zeromq.org/docs:contributing>.


zmq_inproc(7)

zmq_inproc(7) Manual Page

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 ØMQ context.

Note
 No I/O threads are involved in passing messages using the inproc transport. Therefore, if you are using a ØMQ context for in-process messaging only you can initialise the context with zero I/O threads. See zmq_init(3) for details.

ADDRESSING

A ØMQ 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 ØMQ 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 ØMQ 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

zmq_bind(3)
zmq_connect(3)
zmq_ipc(7)
zmq_tcp(7)
zmq_pgm(7)
zmq_vmci(7)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-08-30 22:42:36 BST


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
linkzmq:zmq_init[3] 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
--------
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_ipc[7]
linkzmq:zmq_tcp[7]
linkzmq:zmq_pgm[7]
linkzmq:zmq_vmci[7]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_ipc(7)

zmq_ipc(7) Manual Page

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 ØMQ 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 zmq_getsockopt(3) 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

zmq_bind(3)
zmq_connect(3)
zmq_inproc(7)
zmq_tcp(7)
zmq_pgm(7)
zmq_vmci(7)
zmq_getsockopt(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-08-30 22:42:36 BST


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 linkzmq:zmq_getsockopt[3] 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
--------
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_inproc[7]
linkzmq:zmq_tcp[7]
linkzmq:zmq_pgm[7]
linkzmq:zmq_vmci[7]
linkzmq:zmq_getsockopt[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_msg_close(3)

zmq_msg_close(3) Manual Page

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 ØMQ 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 ØMQ 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

zmq_msg_init(3)
zmq_msg_init_size(3)
zmq_msg_init_buffer(3)
zmq_msg_init_data(3)
zmq_msg_data(3)
zmq_msg_size(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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
--------
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_buffer[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_msg_copy(3)

zmq_msg_copy(3) Manual Page

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

zmq_msg_move(3)
zmq_msg_init(3)
zmq_msg_init_size(3)
zmq_msg_init_buffer(3)
zmq_msg_init_data(3)
zmq_msg_close(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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
--------
linkzmq:zmq_msg_move[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_buffer[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_msg_data(3)

zmq_msg_data(3) Manual Page

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

zmq_msg_size(3)
zmq_msg_init(3)
zmq_msg_init_size(3)
zmq_msg_init_buffer(3)
zmq_msg_init_data(3)
zmq_msg_close(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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
--------
linkzmq:zmq_msg_size[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_buffer[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_msg_get(3)

zmq_msg_get(3) Manual Page

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

zmq_msg_set(3)
zmq_msg_init(3)
zmq_msg_close(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-08-30 22:42:36 BST


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
--------
linkzmq:zmq_msg_set[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_msg_gets(3)

zmq_msg_gets(3) Manual Page

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 zmq_setsockopt(3) 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

zmq(7) zmq_setsockopt(3)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-09-06 11:47:31 BST


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 linkzmq:zmq_setsockopt[3] 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
--------
linkzmq:zmq[7]
linkzmq:zmq_setsockopt[3]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_msg_init(3)

zmq_msg_init(3) Manual Page

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

zmq_msg_init_size(3)
zmq_msg_init_buffer(3)
zmq_msg_init_data(3)
zmq_msg_close(3)
zmq_msg_data(3)
zmq_msg_size(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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
--------
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_buffer[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_msg_init_buffer(3)

zmq_msg_init_buffer(3) Manual Page

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

zmq_msg_init_data(3)
zmq_msg_init_size(3)
zmq_msg_init(3)
zmq_msg_close(3)
zmq_msg_data(3)
zmq_msg_size(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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
--------
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_msg_init_data(3)

zmq_msg_init_data(3) Manual Page

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 ØMQ 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 ØMQ, 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

zmq_msg_init_size(3)
zmq_msg_init_buffer(3)
zmq_msg_init(3)
zmq_msg_close(3)
zmq_msg_data(3)
zmq_msg_size(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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
--------
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_buffer[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_msg_init_size(3)

zmq_msg_init_size(3) Manual Page

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

zmq_msg_init_data(3)
zmq_msg_init_buffer(3)
zmq_msg_init(3)
zmq_msg_close(3)
zmq_msg_data(3)
zmq_msg_size(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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
--------
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_init_buffer[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_msg_more(3)

zmq_msg_more(3) Manual Page

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

zmq_msg_get(3)
zmq_msg_set(3)
zmq_msg_init(3)
zmq_msg_close(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2017-05-16 22:07:05 BST


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
--------
linkzmq:zmq_msg_get[3]
linkzmq:zmq_msg_set[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_msg_move(3)

zmq_msg_move(3) Manual Page

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

zmq_msg_copy(3)
zmq_msg_init(3)
zmq_msg_init_size(3)
zmq_msg_init_buffer(3)
zmq_msg_init_data(3)
zmq_msg_close(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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
--------
linkzmq:zmq_msg_copy[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_buffer[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_msg_recv(3)

zmq_msg_recv(3) Manual Page

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 zmq_recvmsg(3), 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 ØMQ message is composed of 1 or more message parts. Each message part is an independent zmq_msg_t in its own right. ØMQ 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 zmq_getsockopt(3) 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 zmq_setsockopt(3)) 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 zmq_socket(3) for more information.

ETERM

The ØMQ 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

zmq_recv(3)
zmq_send(3)
zmq_msg_send(3)
zmq_getsockopt(3)
zmq_setsockopt(3)
zmq_socket(7)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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 linkzmq:zmq_recvmsg[3], 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_
linkzmq:zmq_getsockopt[3] 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 linkzmq:zmq_setsockopt[3])
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 linkzmq:zmq_socket[3] 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
--------
linkzmq:zmq_recv[3]
linkzmq:zmq_send[3]
linkzmq:zmq_msg_send[3]
linkzmq:zmq_getsockopt[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_socket[7]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_msg_routing_id(3)

zmq_msg_routing_id(3) Manual Page

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

zmq_msg_set_routing_id(3)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-08-30 22:42:36 BST


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
--------
linkzmq:zmq_msg_set_routing_id[3]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_msg_send(3)

zmq_msg_send(3) Manual Page

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 zmq_sendmsg(3), 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 ØMQ 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 ØMQ message is composed of 1 or more message parts. Each message part is an independent zmq_msg_t in its own right. ØMQ 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 zmq_socket(3) for more information.

ETERM

The ØMQ 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

zmq_recv(3)
zmq_send(3)
zmq_msg_recv(3)
zmq_socket(7)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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 linkzmq:zmq_sendmsg[3], 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 linkzmq:zmq_socket[3] 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
--------
linkzmq:zmq_recv[3]
linkzmq:zmq_send[3]
linkzmq:zmq_msg_recv[3]
linkzmq:zmq_socket[7]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_msg_set(3)

zmq_msg_set(3) Manual Page

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 ØMQ 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

zmq_msg_get(3) zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2017-05-16 22:07:05 BST


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
--------
linkzmq:zmq_msg_get[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_msg_set_routing_id(3)

zmq_msg_set_routing_id(3) Manual Page

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

zmq_msg_routing_id(3) zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-08-30 22:42:36 BST


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
--------
linkzmq:zmq_msg_routing_id[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_msg_size(3)

zmq_msg_size(3) Manual Page

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

zmq_msg_data(3)
zmq_msg_init(3)
zmq_msg_init_size(3)
zmq_msg_init_buffer(3)
zmq_msg_init_data(3)
zmq_msg_close(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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
--------
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_buffer[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_null(7)

zmq_null(7) Manual Page

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

zmq_plain(7)
zmq_curve(7)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2017-05-16 22:07:05 BST


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
--------
linkzmq:zmq_plain[7]
linkzmq:zmq_curve[7]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_pgm(7)

zmq_pgm(7) Manual Page

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

ØMQ 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 zmq_setsockopt(3).

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 ØMQ 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 ØMQ as a single continuous stream of data where ØMQ messages are not necessarily aligned with PGM datagram boundaries and a single ØMQ message may span several PGM datagrams. This stream of data consists of ØMQ messages encapsulated in frames as described in zmq_tcp(7).

PGM datagram payload

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

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 ØMQ 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 relevent ZMQ socket options that are documented in zmq_setsockopt(3):

  • 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

zmq_connect(3)
zmq_setsockopt(3)
zmq_tcp(7)
zmq_ipc(7)
zmq_inproc(7)
zmq_vmci(7)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-09-06 11:47:31 BST


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
linkzmq:zmq_setsockopt[3].

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
linkzmq:zmq_tcp[7].

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 relevent ZMQ socket
options that are documented in linkzmq:zmq_setsockopt[3]:

* 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
--------
linkzmq:zmq_connect[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_tcp[7]
linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7]
linkzmq:zmq_vmci[7]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_plain(7)

zmq_plain(7) Manual Page

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

zmq_setsockopt(3)
zmq_null(7)
zmq_curve(7)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2017-05-16 22:07:05 BST


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
--------
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_null[7]
linkzmq:zmq_curve[7]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_poll(3)

zmq_poll(3) Manual Page

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:

typedef struct
{
    void *socket;
    int fd;
    short events;
    short revents;
} zmq_pollitem_t;

For each zmq_pollitem_t item, zmq_poll() shall examine either the ØMQ 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 ØMQ 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 ØMQ 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 ØMQ 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 ØMQ sockets this flag has no effect if set in events, and shall never be returned in revents by zmq_poll().

ZMQ_POLLPRI

For ØMQ 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 informations. 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 thead-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 ØMQ 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 ØMQ 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

zmq_socket(3)
zmq_send(3)
zmq_recv(3)
zmq(7)

Your operating system documentation for the poll() system call.

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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';
    int '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 informations.
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 thead-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
--------
linkzmq:zmq_socket[3]
linkzmq:zmq_send[3]
linkzmq:zmq_recv[3]
linkzmq:zmq[7]

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 <http://www.zeromq.org/docs:contributing>.


zmq_poller(3)

zmq_poller(3) Manual Page

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 ØMQ sockets registered with a poller.

zmq_poller_add registers a new socket with a given poller. Both poller and socket must point to valid ØMQ 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 descriptiors registered with a poller. On Windows, these functions can only be used with WinSock sockets.

In the following, ØMQ 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:

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 ØMQ 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 ØMQ 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 ØMQ 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 ØMQ 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 informations. 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 ØMQ 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 ØMQ 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 ØMQ socket and a standard socket.
void *poller = zmq_poller_new ();

zmq_poller_event_t events [2];
/* 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);
/* Poll for events indefinitely */
int rc = zmq_poller_wait_all (poller, events, 2, -1);
assert (rc >= 0);
/* Returned events will be stored in 'events' */
zmq_poller_destroy (poller);

SEE ALSO

zmq_socket(3)
zmq_send(3)
zmq_recv(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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 descriptiors
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 informations.
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 ();

zmq_poller_event_t events [2];
/* 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);
/* Poll for events indefinitely */
int rc = zmq_poller_wait_all (poller, events, 2, -1);
assert (rc >= 0);
/* Returned events will be stored in 'events' */
zmq_poller_destroy (poller);
----

SEE ALSO
--------
linkzmq:zmq_socket[3]
linkzmq:zmq_send[3]
linkzmq:zmq_recv[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_proxy(3)

zmq_proxy(3) Manual Page

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 ØMQ 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 zmq_socket(3) 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 ØMQ 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

zmq_bind(3)
zmq_connect(3)
zmq_socket(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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 linkzmq:zmq_socket[3] 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
--------
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_socket[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_proxy_steerable(3)

zmq_proxy_steerable(3) Manual Page

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 starts the built-in ØMQ proxy in the current application thread, as zmq_proxy() do. Please, refer to this function for the general description and usage. We describe here only the additional control flow provided by the socket passed as the fourth argument "control".

If the control socket is not NULL, the proxy supports control flow. If PAUSE is received on this socket, the proxy suspends its activities. If RESUME is received, it goes on. If TERMINATE is received, it terminates smoothly. If STATISTICS is received, the proxy will reply on the control socket sending a multipart message with 8 frames, each with an unsigned integer 64-bit wide that provide in the following order: - number of messages received by the frontend socket - number of bytes received by the frontend socket - number of messages sent out the frontend socket - number of bytes sent out the frontend socket - number of messages received by the backend socket - number of bytes received by the backend socket - number of messages sent out the backend socket - number of bytes sent out the backend socket

At start, the proxy runs normally as if zmq_proxy was used.

If the control socket is NULL, the function behave exactly as if zmq_proxy(3) had been called.

Refer to zmq_socket(3) for a description of the available socket types. Refer to zmq_proxy(3) for a description of the zmq_proxy.

EXAMPLE USAGE

cf zmq_proxy

RETURN VALUE

The zmq_proxy_steerable() function returns 0 if TERMINATE is sent to its control socket. Otherwise, it returns -1 and errno set to ETERM or EINTR (the ØMQ 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, backend and control sockets
void *frontend = zmq_socket (context, ZMQ_ROUTER);
assert (frontend);
void *backend = zmq_socket (context, ZMQ_DEALER);
assert (backend);
void *control = zmq_socket (context, ZMQ_SUB);
assert (control);

//  Bind sockets to TCP ports
assert (zmq_bind (frontend, "tcp://*:5555") == 0);
assert (zmq_bind (backend, "tcp://*:5556") == 0);
assert (zmq_connect (control, "tcp://*:5557") == 0);

// Subscribe to the control socket since we have chosen SUB here
assert (zmq_setsockopt (control, ZMQ_SUBSCRIBE, "", 0));

//  Start the queue proxy, which runs until ETERM or "TERMINATE"
//  received on the control socket
zmq_proxy_steerable (frontend, backend, NULL, control);
Set up a controller in another node, process or whatever
void *control = zmq_socket (context, ZMQ_PUB);
assert (control);
assert (zmq_bind (control, "tcp://*:5557") == 0);

// pause the proxy
assert (zmq_send (control, "PAUSE", 5, 0) == 0);

// resume the proxy
assert (zmq_send (control, "RESUME", 6, 0) == 0);

// terminate the proxy
assert (zmq_send (control, "TERMINATE", 9, 0) == 0);

// check statistics
assert (zmq_send (control, "STATISTICS", 10, 0) == 0);
zmq_msg_t stats_msg;

while (1) {
    assert (zmq_msg_init (&stats_msg) == 0);
    assert (zmq_recvmsg (control, &stats_msg, 0) == sizeof (uint64_t));
    assert (rc == sizeof (uint64_t));
    printf ("Stat: %lu\n", *(unsigned long int *)zmq_msg_data (&stats_msg));
    if (!zmq_msg_get (&stats_msg, ZMQ_MORE))
        break;
    assert (zmq_msg_close (&stats_msg) == 0);
}
assert (zmq_msg_close (&stats_msg) == 0);
---

SEE ALSO

zmq_proxy(3)
zmq_bind(3)
zmq_connect(3)
zmq_socket(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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 starts the built-in 0MQ proxy in the
current application thread, as _zmq_proxy()_ do. Please, refer to this function
for the general description and usage. We describe here only the additional
control flow provided by the socket passed as the fourth argument "control".

If the control socket is not NULL, the proxy supports control flow. If
'PAUSE' is received on this socket, the proxy suspends its activities. If
'RESUME' is received, it goes on. If 'TERMINATE' is received, it terminates
smoothly. If 'STATISTICS' is received, the proxy will reply on the control socket
sending a multipart message with 8 frames, each with an unsigned integer 64-bit
wide that provide in the following order:
 - number of messages received by the frontend socket
 - number of bytes received by the frontend socket
 - number of messages sent out the frontend socket
 - number of bytes sent out the frontend socket
 - number of messages received by the backend socket
 - number of bytes received by the backend socket
 - number of messages sent out the backend socket
 - number of bytes sent out the backend socket

At start, the proxy runs normally as if zmq_proxy was used.

If the control socket is NULL, the function behave exactly as if linkzmq:zmq_proxy[3]
had been called.

Refer to linkzmq:zmq_socket[3] for a description of the available socket types.
Refer to linkzmq:zmq_proxy[3] for a description of the zmq_proxy.

EXAMPLE USAGE
-------------
cf zmq_proxy

RETURN VALUE
------------
The _zmq_proxy_steerable()_ function returns 0 if TERMINATE is sent to 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
-------
.Creating a shared queue proxy
----
//  Create frontend, backend and control sockets
void *frontend = zmq_socket (context, ZMQ_ROUTER);
assert (frontend);
void *backend = zmq_socket (context, ZMQ_DEALER);
assert (backend);
void *control = zmq_socket (context, ZMQ_SUB);
assert (control);

//  Bind sockets to TCP ports
assert (zmq_bind (frontend, "tcp://*:5555") == 0);
assert (zmq_bind (backend, "tcp://*:5556") == 0);
assert (zmq_connect (control, "tcp://*:5557") == 0);

// Subscribe to the control socket since we have chosen SUB here
assert (zmq_setsockopt (control, ZMQ_SUBSCRIBE, "", 0));

//  Start the queue proxy, which runs until ETERM or "TERMINATE"
//  received on the control socket
zmq_proxy_steerable (frontend, backend, NULL, control);
----
.Set up a controller in another node, process or whatever
----
void *control = zmq_socket (context, ZMQ_PUB);
assert (control);
assert (zmq_bind (control, "tcp://*:5557") == 0);

// pause the proxy
assert (zmq_send (control, "PAUSE", 5, 0) == 0);

// resume the proxy
assert (zmq_send (control, "RESUME", 6, 0) == 0);

// terminate the proxy
assert (zmq_send (control, "TERMINATE", 9, 0) == 0);

// check statistics
assert (zmq_send (control, "STATISTICS", 10, 0) == 0);
zmq_msg_t stats_msg;

while (1) {
    assert (zmq_msg_init (&stats_msg) == 0);
    assert (zmq_recvmsg (control, &stats_msg, 0) == sizeof (uint64_t));
    assert (rc == sizeof (uint64_t));
    printf ("Stat: %lu\n", *(unsigned long int *)zmq_msg_data (&stats_msg));
    if (!zmq_msg_get (&stats_msg, ZMQ_MORE))
        break;
    assert (zmq_msg_close (&stats_msg) == 0);
}
assert (zmq_msg_close (&stats_msg) == 0);
---

SEE ALSO
--------
linkzmq:zmq_proxy[3]
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_socket[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_recv(3)

zmq_recv(3) Manual Page

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 ØMQ message is composed of 1 or more message parts. ØMQ 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 zmq_getsockopt(3) 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 zmq_setsockopt(3)) 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 zmq_socket(3) for more information.

ETERM

The ØMQ 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

zmq_send(3)
zmq_getsockopt(3)
zmq_setsockopt(3)
zmq_socket(7)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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_
linkzmq:zmq_getsockopt[3] 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 linkzmq:zmq_setsockopt[3])
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 linkzmq:zmq_socket[3] 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
--------
linkzmq:zmq_send[3]
linkzmq:zmq_getsockopt[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_socket[7]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_recvmsg(3)

zmq_recvmsg(3) Manual Page

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 ØMQ message is composed of 1 or more message parts. Each message part is an independent zmq_msg_t in its own right. ØMQ 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 zmq_getsockopt(3) 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 zmq_setsockopt(3)) 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 zmq_socket(3) for more information.

ETERM

The ØMQ 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

zmq_recv(3)
zmq_send(3)
zmq_getsockopt(3)
zmq_setsockopt(3)
zmq_socket(7)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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_
linkzmq:zmq_getsockopt[3] 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 linkzmq:zmq_setsockopt[3])
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 linkzmq:zmq_socket[3] 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
--------
linkzmq:zmq_recv[3]
linkzmq:zmq_send[3]
linkzmq:zmq_getsockopt[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_socket[7]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_send(3)

zmq_send(3) Manual Page

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 ØMQ has assumed responsibility for the message.

Multi-part messages

A ØMQ message is composed of 1 or more message parts. ØMQ 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 zmq_socket(3) for more information.

ETERM

The ØMQ 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

zmq_send_const(3)
zmq_recv(3)
zmq_socket(7)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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 linkzmq:zmq_socket[3] 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
--------
linkzmq:zmq_send_const[3]
linkzmq:zmq_recv[3]
linkzmq:zmq_socket[7]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_send_const(3)

zmq_send_const(3) Manual Page

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 ØMQ has assumed responsibility for the message.

Multi-part messages

A ØMQ message is composed of 1 or more message parts. ØMQ 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 zmq_socket(3) for more information.

ETERM

The ØMQ 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

zmq_send(3)
zmq_recv(3)
zmq_socket(7)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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 linkzmq:zmq_socket[3] 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
--------
linkzmq:zmq_send[3]
linkzmq:zmq_recv[3]
linkzmq:zmq_socket[7]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_sendmsg(3)

zmq_sendmsg(3) Manual Page

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 ØMQ has assumed responsibility for the message.
Note
 this API method is deprecated in favor of zmq_msg_send(3).

Multi-part messages

A ØMQ message is composed of 1 or more message parts. Each message part is an independent zmq_msg_t in its own right. ØMQ 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 zmq_socket(3) for more information.

ETERM

The ØMQ 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

zmq_recv(3)
zmq_socket(7)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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 linkzmq:zmq_socket[3] 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
--------
linkzmq:zmq_recv[3]
linkzmq:zmq_socket[7]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_setsockopt(3)

zmq_setsockopt(3) Manual Page

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 ØMQ 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 ØMQ 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 ØMQ 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 zmq_init(3) for details on allocating the number of I/O threads for a specific context.

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.

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.
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_RID: Assign the next outbound connection id

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

The ZMQ_CONNECT_ROUTING_ID option sets the peer id of the peer connected via the next zmq_connect() call, such that that connection is immediately ready for data transfer with the given routing id. This option applies only to the first subsequent call to zmq_connect(), zmq_connect() calls thereafter use the default connection behaviour.

Typical use is to set this socket option ahead of each zmq_connect() call. Each connection MUST be assigned a unique routing id. Assigning a routing id that is already in use is not allowed.

Useful when connecting ROUTER to ROUTER, or STREAM to STREAM, as it allows for immediate sending to peers. Outbound routing id framing requirements for ROUTER and STREAM sockets apply.

The routing id must be from 1 to 255 bytes long and MAY NOT start with a zero byte (such routing ids are reserved for internal use by the ØMQ infrastructure).

Option value type | binary data
Option value unit | N/A
Default value | NULL
Applicable socket types | ZMQ_ROUTER, ZMQ_STREAM

ZMQ_CONFLATE: Keep only last message

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 zmq_getsockopt(3) with ZMQ_EVENTS to trigger the conflation of the messages.
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 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.

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

ZMQ_CURVE_PUBLICKEY: Set CURVE public key

Sets the socket’s long term public key. You must set this on CURVE client sockets, see zmq_curve(7). 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 zmq_curve_keypair(3). To derive the public key from a secret key, use zmq_curve_public(3).

Note
 an option value size of 40 is supported for backwards compatibility, though is deprecated.
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

Sets the socket’s long term secret key. You must set this on both CURVE client and server sockets, see zmq_curve(7). 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. To generate a public/secret key pair, use zmq_curve_keypair(3). To derive the public key from a secret key, use zmq_curve_public(3).

Note
 an option value size of 40 is supported for backwards compatibility, though is deprecated.
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_SERVER: Set CURVE server role

Defines whether the socket will act as server for CURVE security, see zmq_curve(7). 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.

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

Sets the socket’s long term server key. You must set this on CURVE client sockets, see zmq_curve(7). 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. This key must have been generated together with the server’s secret key. To generate a public/secret key pair, use zmq_curve_keypair(3).

Note
 an option value size of 40 is supported for backwards compatibility, though is deprecated.
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_DISCONNECT_MSG: set a disconnect message that the socket will generate when accepted peer disconnect

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.

Option value type | binary data
Option value unit | N/A
Default value | NULL
Applicable socket types | ZMQ_ROUTER, ZMQ_SERVER and ZMQ_PEER

ZMQ_GSSAPI_PLAINTEXT: Disable GSSAPI encryption

Defines whether communications on the socket will be encrypted, see zmq_gssapi(7). A value of 1 means that communications will be plaintext. A value of 0 means communications will be encrypted.

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

Sets the name of the principal for whom GSSAPI credentials should be acquired.

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

ZMQ_GSSAPI_SERVER: Set GSSAPI server role

Defines whether the socket will act as server for GSSAPI security, see zmq_gssapi(7). A value of 1 means the socket will act as GSSAPI server. A value of 0 means the socket will act as GSSAPI client.

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 of the principal of the GSSAPI server to which a GSSAPI client intends to connect.

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

ZMQ_GSSAPI_SERVICE_PRINCIPAL_NAMETYPE: Set name type of 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).

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).

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.

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

When set, the socket will automatically send an hello message when a new connection is made or accepted. You may set this on DEALER, ROUTER, CLIENT, SERVER and PEER sockets. The combination with ZMQ_HEARTBEAT_IVL is powerful and simplify protocols, as now heartbeat and sending the hello message can be left out of protocols and be handled by zeromq.

Option value type | binary data
Option value unit | N/A
Default value | NULL
Applicable socket types | ZMQ_ROUTER, ZMQ_DEALER, ZMQ_CLIENT, ZMQ_SERVER and ZMQ_PEER

ZMQ_HEARTBEAT_IVL: Set interval between sending ZMTP heartbeats

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.

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.

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.

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.

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.

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.

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 zmq_disconnect(3) or closed with zmq_close(3), and further affects the termination of the socket’s context with zmq_ctx_term(3). 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.

    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.

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 specfied 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 restrited 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 (zmq_z85_encode(3)).

Note
 in DRAFT state, not yet available in stable releases.
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.

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 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.

Option value type | int
Option value unit | bytes
Default value | 1500
Applicable socket types | all, when using multicast transports

ZMQ_PLAIN_PASSWORD: Set PLAIN security password

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 zmq_plain(7). If you set this to a null value, the security mechanism used for connections shall be NULL, see zmq_null(3).

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 zmq_plain(7). 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.

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

Sets the username 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 zmq_plain(7). If you set this to a null value, the security mechanism used for connections shall be NULL, see zmq_null(3).

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

ZMQ_USE_FD: Set the pre-allocated socket file descriptor

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.
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)

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

When set to 1, the socket will automatically send an empty message when a new connection is made or accepted. You may set this on REQ, DEALER, or ROUTER sockets connected to a ROUTER socket. The application must filter such empty messages. The ZMQ_PROBE_ROUTER option in effect provides the ROUTER application with an event signaling the arrival of a new peer.

Note
 do not set this option on a socket that talks to any other socket types: the results are undefined.
Option value type | int
Option value unit | 0, 1
Default value | 0
Applicable socket types | ZMQ_ROUTER, ZMQ_DEALER, ZMQ_REQ

ZMQ_RATE: Set multicast data rate

The ZMQ_RATE option shall set the maximum send or receive data rate for multicast transports such as zmq_pgm(7) using the specified socket.

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_RCVBUF option shall set the underlying kernel receive buffer size for the socket to the specified size in bytes. A value of -1 means leave the OS default unchanged. For details refer to your operating system documentation for the SO_RCVBUF socket option.

Option value type | int
Option value unit | bytes
Default value | -1
Applicable socket types | all

ZMQ_RCVHWM: Set high water mark for inbound messages

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 ØMQ 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, ØMQ shall take appropriate action such as blocking or dropping sent messages. Refer to the individual socket descriptions in zmq_socket(3) for details on the exact action taken for each socket type.

Note
 ØMQ 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 zmq_tcp(7).
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

Sets the timeout for receive 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.

Option value type | int
Option value unit | milliseconds
Default value | -1 (infinite)
Applicable socket types | all

ZMQ_RECONNECT_IVL: Set reconnection interval

The ZMQ_RECONNECT_IVL option shall set the initial reconnection interval for the specified socket. The reconnection interval is the period ØMQ 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 ØMQ to prevent reconnection storms in topologies with a large number of peers per socket.
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 maximum reconnection interval

The ZMQ_RECONNECT_IVL_MAX option shall set the maximum reconnection interval for the specified socket. This is the maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled untill ZMQ_RECONNECT_IVL_MAX is reached. This allows for exponential backoff strategy. Default value means no exponential backoff is performed and reconnect interval calculations are only based on ZMQ_RECONNECT_IVL.

Note
 Values less than ZMQ_RECONNECT_IVL will be ignored.
Option value type | int
Option value unit | milliseconds
Default value | 0 (only use ZMQ_RECONNECT_IVL)
Applicable socket types | all, only for connection-oriented transports

ZMQ_RECONNECT_STOP: Set condition where reconnection will stop

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 ØMQ 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 ØMQ handshake fails. This can be used to detect and/or prevent errant connection attempts to non-ØMQ 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.
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.
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.

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

By default, a REQ socket does not allow initiating a new request with zmq_send(3) until the reply to the previous one has been received. When set to 1, sending another message is allowed and previous replies will be discarded if any. The request-reply state machine is reset and a new request is sent to the next available peer.

If set to 1, also enable ZMQ_REQ_CORRELATE to ensure correct matching of requests and replies. Otherwise a late reply to an aborted request can be reported as the reply to the superseding request.

Option value type | int
Option value unit | 0, 1
Default value | 0
Applicable socket types | ZMQ_REQ

ZMQ_ROUTER_HANDOVER: handle duplicate client routing ids on ROUTER sockets

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.

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.

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 ØMQ framing. This lets ØMQ applications talk to non-ØMQ 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.
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 ØMQ 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.

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.

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 ØMQ 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, ØMQ shall take appropriate action such as blocking or dropping sent messages. Refer to the individual socket descriptions in zmq_socket(3) for details on the exact action taken for each socket type.

Note
 ØMQ 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 zmq_tcp(7).
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.

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).

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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. If enabled, the socket passes all subscribe messages to the caller. If disabled, only the first subscription to each filter will be passed. The default is 0 (disabled).

Option value type | int
Option value unit | 0, 1
Default value | 0
Applicable socket types | ZMQ_XPUB

ZMQ_XPUB_VERBOSER: pass duplicate subscribe and unsubscribe 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).

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.

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.
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.

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 a welcome message the will be recieved by subscriber when connecting. Subscriber must subscribe to the Welcome message before connecting. Welcome message will also be sent on reconnecting. For welcome message to work well user must poll on incoming subscription messages on the XPUB socket and handle them.

Use NULL and length of zero to disable welcome message.

Option value type | binary data
Option value unit | N/A
Default value | NULL
Applicable socket types | ZMQ_XPUB

ZMQ_ONLY_FIRST_SUBSCRIBE: Process only first subscribe/unsubscribe in a multipart message

If set, only the first part of the multipart message is processed as a subscribe/unsubscribe message. The rest are forwarded as user data regardless of message contents.

It not set (default), subscribe/unsubscribe messages in a multipart message are processed as such regardless of their number and order.

Option value type | int
Option value unit | boolean
Default value | 0 (false)
Applicable socket types | ZMQ_XSUB, ZMQ_XPUB

ZMQ_ZAP_DOMAIN: Set RFC 27 authentication domain

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.

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

The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.

Option value type | int
Option value unit | 0, 1
Default value | 0
Applicable socket types | all, when using ZAP

ZMQ_TCP_ACCEPT_FILTER: Assign filters to allow new TCP connections

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.
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 GID filters call zmq_setsockopt(socket, ZMQ_IPC_FILTER_GID, NULL, 0).

Note
 GID 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.
Option value type | gid_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_PID: Assign process 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.
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.
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.

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.

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.

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.

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.

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.

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.
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.
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.
Option value type | int
Option value unit | messages
Default value | 8192
Applicable socket types | All, when using TCP, IPC, PGM or 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 ØMQ 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

zmq_getsockopt(3)
zmq_socket(3)
zmq_plain(7)
zmq_curve(7)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-16 15:41:38 GMT


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 linkzmq:zmq_init[3] for details on allocating the number of I/O
threads for a specific _context_.

[horizontal]
Option value type:: uint64_t
Option value unit:: N/A (bitmap)
Default value:: 0
Applicable socket types:: N/A

ZMQ_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_CONNECT_RID: Assign the next outbound connection id
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_CONNECT_ROUTING_ID' option sets the peer id of the peer connected
via the next zmq_connect() call, such that that connection is immediately ready for
data transfer with the given routing id.  This option applies only to the first
subsequent call to zmq_connect(), zmq_connect() calls thereafter use the default
connection behaviour.

Typical use is to set this socket option ahead of each zmq_connect() call.
Each connection MUST be assigned a unique routing id. Assigning a
routing id that is already in use is not allowed.

Useful when connecting ROUTER to ROUTER, or STREAM to STREAM, as it
allows for immediate sending to peers. Outbound routing id framing requirements
for ROUTER and STREAM sockets apply.

The routing id must be from 1 to 255 bytes long and MAY NOT start with
a zero byte (such routing ids are reserved for internal use by the 0MQ
infrastructure).

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

ZMQ_CONFLATE: Keep only last message
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 linkzmq:zmq_getsockopt[3] 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 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: Set CURVE public key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the socket's long term public key. You must set this on CURVE client
sockets, see linkzmq:zmq_curve[7]. 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
linkzmq:zmq_curve_keypair[3]. To derive the public key from a secret key,
use linkzmq:zmq_curve_public[3].

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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the socket's long term secret key. You must set this on both CURVE
client and server sockets, see linkzmq:zmq_curve[7]. 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. To generate a public/secret
key pair, use linkzmq:zmq_curve_keypair[3]. To derive the public key from
a secret key, use linkzmq:zmq_curve_public[3].

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_SERVER: Set CURVE server role
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Defines whether the socket will act as server for CURVE security, see
linkzmq:zmq_curve[7]. 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the socket's long term server key. You must set this on CURVE client
sockets, see linkzmq:zmq_curve[7]. 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. This key must have been generated together with
the server's secret key. To generate a public/secret key pair, use
linkzmq:zmq_curve_keypair[3].

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_DISCONNECT_MSG: set a disconnect message that the socket will generate when accepted peer disconnect
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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_GSSAPI_PLAINTEXT: Disable GSSAPI encryption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Defines whether communications on the socket will be encrypted, see
linkzmq:zmq_gssapi[7]. 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the name of the principal for whom GSSAPI credentials should be acquired.

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

ZMQ_GSSAPI_SERVER: Set GSSAPI server role
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Defines whether the socket will act as server for GSSAPI security, see
linkzmq:zmq_gssapi[7]. 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 of the principal of the GSSAPI server to which a GSSAPI client
intends to connect.

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

ZMQ_GSSAPI_SERVICE_PRINCIPAL_NAMETYPE: Set name type of 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When set, the socket will automatically send an hello message when a new connection is made or accepted.
You may set this on DEALER, ROUTER, CLIENT, SERVER and PEER sockets.
The combination with ZMQ_HEARTBEAT_IVL is powerful and simplify protocols,
as now heartbeat and sending the hello message can be left out of protocols and be handled by zeromq.

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

ZMQ_HEARTBEAT_IVL: Set interval between sending ZMTP heartbeats
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
linkzmq:zmq_disconnect[3] or closed with linkzmq:zmq_close[3], and further
affects the termination of the socket's context with linkzmq:zmq_ctx_term[3].
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
specfied 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 restrited 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 (linkzmq:zmq_z85_encode[3]).

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 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: Set PLAIN security password
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 linkzmq:zmq_plain[7]. If you set this to a null value, the security
mechanism used for connections shall be NULL, see linkzmq:zmq_null[3].

[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
linkzmq:zmq_plain[7]. 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the username 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 linkzmq:zmq_plain[7]. If you set this to a null value, the security
mechanism used for connections shall be NULL, see linkzmq:zmq_null[3].

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

ZMQ_USE_FD: Set the pre-allocated socket file descriptor
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When set to 1, the socket will automatically send an empty message when a
new connection is made or accepted. You may set this on REQ, DEALER, or
ROUTER sockets connected to a ROUTER socket. The application must filter
such empty messages. The ZMQ_PROBE_ROUTER option in effect provides the
ROUTER application with an event signaling the arrival of a new peer.

NOTE: do not set this option on a socket that talks to any other socket
types: the results are undefined.

[horizontal]
Option value type:: int
Option value unit:: 0, 1
Default value:: 0
Applicable socket types:: ZMQ_ROUTER, ZMQ_DEALER, ZMQ_REQ

ZMQ_RATE: Set multicast data rate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_RATE' option shall set the maximum send or receive data rate for
multicast transports such as linkzmq:zmq_pgm[7] 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_RCVBUF' option shall set the underlying kernel receive buffer size for
the 'socket' to the specified size in bytes.  A value of -1 means leave the
OS default unchanged. 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:: -1
Applicable socket types:: all

ZMQ_RCVHWM: Set high water mark for inbound messages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 linkzmq:zmq_socket[3] 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 linkzmq:zmq_tcp[7].

[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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the timeout for receive 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: Set reconnection interval
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 maximum reconnection interval
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_RECONNECT_IVL_MAX' option shall set the maximum reconnection interval
for the specified 'socket'.  This is the maximum period 0MQ shall wait between
attempts to reconnect. On each reconnect attempt, the previous interval shall be
doubled untill ZMQ_RECONNECT_IVL_MAX is reached. This allows for exponential
backoff strategy. Default value means no exponential backoff is performed and
reconnect interval calculations are only based on ZMQ_RECONNECT_IVL.

NOTE:  Values less than ZMQ_RECONNECT_IVL will be ignored.

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

ZMQ_RECONNECT_STOP: Set condition where reconnection will stop
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, a REQ socket does not allow initiating a new request with
_zmq_send(3)_ until the reply to the previous one has been received.
When set to 1, sending another message is allowed and previous replies will
be discarded if any. The request-reply state machine is reset and a new
request is sent to the next available peer.

If set to 1, also enable ZMQ_REQ_CORRELATE to ensure correct matching of
requests and replies. Otherwise a late reply to an aborted request can be
reported as the reply to the superseding request.

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

ZMQ_ROUTER_HANDOVER: handle duplicate client routing ids on ROUTER sockets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 linkzmq:zmq_socket[3] 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 linkzmq:zmq_tcp[7].

[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_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: 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. If enabled,
the socket passes all subscribe messages to the caller. If disabled,
only the first subscription to 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_VERBOSER: pass duplicate subscribe and unsubscribe 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 a welcome message the will be recieved by subscriber when connecting.
Subscriber must subscribe to the Welcome message before connecting.
Welcome message will also be sent on reconnecting.
For welcome message to work well user must poll on incoming subscription messages on the XPUB socket and handle them.

Use NULL and length of zero to disable welcome message.

[horizontal]
Option value type:: binary data
Option value unit:: N/A
Default value:: NULL
Applicable socket types:: ZMQ_XPUB

ZMQ_ONLY_FIRST_SUBSCRIBE: Process only first subscribe/unsubscribe in a multipart message
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If set, only the first part of the multipart message is processed as
a subscribe/unsubscribe message. The rest are forwarded as user data
regardless of message contents.

It not set (default), subscribe/unsubscribe messages in a multipart message
are processed as such regardless of their number and order.

[horizontal]
Option value type:: int
Option value unit:: boolean
Default value:: 0 (false)
Applicable socket types:: ZMQ_XSUB, ZMQ_XPUB

ZMQ_ZAP_DOMAIN: Set RFC 27 authentication domain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must
always be set. Older versions of libzmq did not follow the spec and allowed
an empty domain to be set.
This option can be used to enabled or disable the stricter, backward
incompatible behaviour. For now it is disabled by default, but in a future
version it will be enabled by default.

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

ZMQ_TCP_ACCEPT_FILTER: Assign filters to allow new TCP connections
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 GID filters call zmq_setsockopt(socket,
ZMQ_IPC_FILTER_GID, NULL, 0).

NOTE: GID 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:: gid_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_PID: Assign process 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.

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
--------
linkzmq:zmq_getsockopt[3]
linkzmq:zmq_socket[3]
linkzmq:zmq_plain[7]
linkzmq:zmq_curve[7]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_socket(3)

zmq_socket(3) Manual Page

NAME

zmq_socket - create 0MQ socket

SYNOPSIS

void *zmq_socket (void *context, int type);

DESCRIPTION

The zmq_socket() function shall create a ØMQ 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 zmq_connect(3), or at least one endpoint must be created for accepting incoming connections with zmq_bind(3).

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, ØMQ 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, ØMQ sockets transfer discrete messages.

ØMQ 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 ØMQ 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, ØMQ 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

ØMQ 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 ØMQ, 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, zmq_send(3) 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, zmq_send(3) 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 zmq_msg_recv(3). 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.
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 zmq_msg_routing_id(3). To send a message to a given ZMQ_CLIENT peer the application must set the peer’s routing_id on the message, using zmq_msg_set_routing_id(3).

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.
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 zmq_msg_set_group(3). Messages are distributed to all members of a group. The zmq_recv(3) 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.
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 zmq_join(3) to join a group. To get the group the message belong to call zmq_msg_group(3). 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.
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 zmq_recv(3) 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.

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 zmq_setsockopt(3) to specify which messages to subscribe to. The zmq_send() function is not implemented for this socket type.

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.

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.

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 zmq_send(3) 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.

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.

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 linkzmq:zmq_send[3] 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 zmq_send(3) 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 zmq_inproc(7), 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 zmq_inproc(7) transport and do not implement functionality such as auto-reconnection.
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 zmq_connect_peer(3).

Each received message has a routing_id that is a 32-bit unsigned integer. The application can fetch this with zmq_msg_routing_id(3).

To send a message to a given ZMQ_PEER peer the application must set the peer’s routing_id on the message, using zmq_msg_set_routing_id(3).

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.
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 linkzmq:zmq_send[3] 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 linkzmq:zmq_inproc[7],
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 linkzmq:zmq_inproc[7] 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-ØMQ 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.

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.

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.

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 zmq_send(3) 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.

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.

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 ØMQ 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

zmq_init(3)
zmq_setsockopt(3)
zmq_bind(3)
zmq_connect(3)
zmq_send(3)
zmq_recv(3)
zmq_inproc(7)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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 linkzmq:zmq_connect[3], or at least one
endpoint must be created for accepting incoming connections with
linkzmq:zmq_bind[3].

.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, linkzmq:zmq_send[3]
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,
linkzmq:zmq_send[3] 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 linkzmq:zmq_msg_recv[3]. 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 linkzmq:zmq_msg_routing_id[3]. To send
a message to a given 'ZMQ_CLIENT' peer the application must set the peer's
'routing_id' on the message, using linkzmq:zmq_msg_set_routing_id[3].

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 linkzmq:zmq_msg_set_group[3].
Messages are distributed to all members of a group.
The linkzmq:zmq_recv[3] 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 linkzmq:zmq_join[3] to
join a group.
To get the group the message belong to call linkzmq:zmq_msg_group[3].
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 linkzmq:zmq_recv[3] 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 linkzmq:zmq_setsockopt[3] 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 linkzmq:zmq_send[3] 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 linkzmq:zmq_send[3] 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 linkzmq:zmq_send[3] 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 linkzmq:zmq_inproc[7],
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 linkzmq:zmq_inproc[7] 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 linkzmq:zmq_connect_peer[3].

Each received message has a 'routing_id' that is a 32-bit unsigned integer.
The application can fetch this with linkzmq:zmq_msg_routing_id[3].

To send a message to a given 'ZMQ_PEER' peer the application must set the peer's
'routing_id' on the message, using linkzmq:zmq_msg_set_routing_id[3].

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 linkzmq:zmq_send[3] 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 linkzmq:zmq_inproc[7],
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 linkzmq:zmq_inproc[7] 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
linkzmq:zmq_send[3] 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
--------
linkzmq:zmq_init[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_send[3]
linkzmq:zmq_recv[3]
linkzmq:zmq_inproc[7]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_socket_monitor(3)

zmq_socket_monitor(3) Manual Page

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 zmq_socket_monitor_versioned(3), 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 ØMQ 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

zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-09-06 11:47:31 BST


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 linkzmq:zmq_socket_monitor_versioned[3],
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
--------
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_socket_monitor_versioned(3)

zmq_socket_monitor_versioned(3) Manual Page

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 zmq_socket_monitor(3).

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_PIPE_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 ØMQ 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 ØMQ 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);

    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_ + i)
            memcpy (value_ + i, zmq_msg_data (&msg), sizeof (*value_));
        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

zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-09-06 11:47:31 BST


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 linkzmq:zmq_socket_monitor[3].

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_PIPE_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);

    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_ + i)
            memcpy (value_ + i, zmq_msg_data (&msg), sizeof (*value_));
        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
--------
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_strerror(3)

zmq_strerror(3) Manual Page

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 ØMQ 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 ØMQ 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

zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2017-05-16 22:07:05 BST


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
--------
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_tcp(7)

zmq_tcp(7) Manual Page

NAME

zmq_tcp - 0MQ unicast transport using TCP

SYNOPSIS

TCP is an ubiquitous, reliable, unicast transport. When connecting distributed applications over a network with ØMQ, using the TCP transport will likely be your first choice.

ADDRESSING

A ØMQ 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 zmq_getsockopt(3) 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:15

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 accomodate 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

zmq_bind(3)
zmq_connect(3)
zmq_pgm(7)
zmq_ipc(7)
zmq_inproc(7)
zmq_vmci(7)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-09-06 11:47:31 BST


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 linkzmq:zmq_getsockopt[3]
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:15>

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 accomodate 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
--------
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_pgm[7]
linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7]
linkzmq:zmq_vmci[7]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_timers(3)

zmq_timers(3) Manual Page

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 ØMQ 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);
    assert (timer_invoked);

    rc = zmq_timers_destroy (&timers);
    assert (rc == 0);

SEE ALSO

zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-09-06 11:47:31 BST


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);
    assert (timer_invoked);

    rc = zmq_timers_destroy (&timers);
    assert (rc == 0);
----

SEE ALSO
--------
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_tipc(7)

zmq_tipc(7) Manual Page

NAME

zmq_tipc - 0MQ unicast transport using TIPC

SYNOPSIS

TIPC is a cluster IPC protocol with a location transparent addressing scheme.

ADDRESSING

A ØMQ 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

zmq_bind(3)
zmq_connect(3)
zmq_tcp(7)
zmq_pgm(7)
zmq_ipc(7)
zmq_inproc(7)
zmq_vmci(7)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-08-30 22:42:36 BST


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
--------
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_tcp[7]
linkzmq:zmq_pgm[7]
linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7]
linkzmq:zmq_vmci[7]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_udp(7)

zmq_udp(7) Manual Page

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 ØMQ 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

zmq_connect(3)
zmq_setsockopt(3)
zmq_tcp(7)
zmq_ipc(7)
zmq_inproc(7)
zmq_vmci(7)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-09-06 11:47:31 BST


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
--------
linkzmq:zmq_connect[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_tcp[7]
linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7]
linkzmq:zmq_vmci[7]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_unbind(3)

zmq_unbind(3) Manual Page

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.

Addionally 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 zmq_bind(3)

Unbinding wild-card address from a socket

When wild-card * endpoint (described in zmq_tcp(7), zmq_ipc(7), zmq_udp(7) and zmq_vmci(7)) 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 ØMQ 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

zmq_bind(3)
zmq_socket(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2021-01-03 21:46:01 GMT


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.

Addionally 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 linkzmq:zmq_bind[3]

Unbinding wild-card address from a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When wild-card `*` 'endpoint' (described in linkzmq:zmq_tcp[7],
linkzmq:zmq_ipc[7], linkzmq:zmq_udp[7] and linkzmq:zmq_vmci[7]) 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
--------
linkzmq:zmq_bind[3]
linkzmq:zmq_socket[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_version(3)

zmq_version(3) Manual Page

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 ØMQ library version.

This functionality is intended for applications or language bindings dynamically linking to the ØMQ library that wish to determine the actual version of the ØMQ library they are using.

RETURN VALUE

There is no return value.

ERRORS

No errors are defined.

EXAMPLE

Printing out the version of the ØMQ library
int major, minor, patch;
zmq_version (&major, &minor, &patch);
printf ("Current 0MQ version is %d.%d.%d\n", major, minor, patch);

SEE ALSO

zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2017-05-16 22:07:05 BST


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
--------
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_vmci(7)

zmq_vmci(7) Manual Page

NAME

zmq_vmci - 0MQ transport over virtual machine communicatios 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 ØMQ 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

zmq_bind(3)
zmq_connect(3)
zmq_inproc(7)
zmq_tcp(7)
zmq_pgm(7)
zmq_vmci(7)
zmq_getsockopt(3)
zmq(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-08-30 22:42:36 BST


zmq_vmci(7)
===========

NAME
----
zmq_vmci - 0MQ transport over virtual machine communicatios 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
--------
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_inproc[7]
linkzmq:zmq_tcp[7]
linkzmq:zmq_pgm[7]
linkzmq:zmq_vmci[7]
linkzmq:zmq_getsockopt[3]
linkzmq:zmq[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_z85_decode(3)

zmq_z85_decode(3) Manual Page

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

zmq_z85_decode(3)
zmq_curve_keypair(3)
zmq_curve_public(3)
zmq_curve(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-08-30 22:42:36 BST


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
--------
linkzmq:zmq_z85_decode[3]
linkzmq:zmq_curve_keypair[3]
linkzmq:zmq_curve_public[3]
linkzmq:zmq_curve[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.


zmq_z85_encode(3)

zmq_z85_encode(3) Manual Page

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

zmq_z85_decode(3)
zmq_curve_keypair(3)
zmq_curve_public(3)
zmq_curve(7)

AUTHORS

This page was written by the ØMQ community. To make a change please read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

ØMQ 4.3.4
Last updated 2020-08-30 22:42:36 BST


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
--------
linkzmq:zmq_z85_decode[3]
linkzmq:zmq_curve_keypair[3]
linkzmq:zmq_curve_public[3]
linkzmq:zmq_curve[7]

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.