zmq(7)

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

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_term(3) +
+

These deprecated functions let you create and destroy contexts:

+Initialise ØMQ context +: +
+ zmq_init(3) +
+
+Terminate ØMQ context +: +
+ zmq_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 +initialization, 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_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_get(3) + zmq_msg_set(3) +
+
+Message manipulation +: +
+ zmq_msg_copy(3) + zmq_msg_move(3) +
+

Sockets

ØMQ sockets present an abstraction of a 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).

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

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)

Convert an armored key into a 32-byte binary key: + zmq_z85_decode(3)

Convert a 32-byte binary CURVE key to an armored text string: + 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).

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.

+zmq(7) Manual Page +

NAME