libzmq/man/man7/zmq.7

.TH zmq 7 "" "(c)2007-2010 iMatix Corporation" "0MQ User Manuals"
.SH NAME
0MQ \- a lightweight messaging kernel
.SH SYNOPSIS

0MQ is an extension of POSIX sockets. It is a library that augments standard
networking sockets by special capabilities that you can otherwise get only
by using specialised "messaging middleware" products, such as automated
handling of connections and disconnections, delivery of a message to multiple
destinations, load balancing messages, sophisticated message filtering etc.

0MQ is designed to be extremely fast. Expected end-to-end latencies for
messages passed over a LAN are in tens of microseconds. Expected
throughputs are to be measured in millions of messages per second.

0MQ is designed to be very thin. It requires no more than couple of
pages in resident memory and is thus well suited for any environment ranging
from small embedded devices, routers and cell phones to enterprise-scale
data centers.

0MQ runs on a wide range of operating systems and supports variety of processor
microarchitectures.

0MQ is accessible from a large set of programming languages.

0MQ is fully open sourced LGPL-licensed software.

.SH CONTEXT
Each 0MQ socket lives within a specific context. Creating and destroying
context is a counterpart of library initialisation/deinitialisation as used
elsewhere. Ability to create multiple contexts saves the day when an application
happens to link (indirectly and involuntarily) with several instances of 0MQ.

Initialise 0MQ context:
.BR zmq_init(3)

Uninitialise 0MQ context:
.BR zmq_term(3)

.SH MESSAGES
Message is a discrete unit of data passed between applications or components
of the same application. 0MQ message has no internal structure, it is an opaque
BLOB. When writing data to or reading data from the message, you are free to
use any of the many serialisation libraries available. Alternatively, you can
use your own serialisation code. The latter option is especially useful when
migrating legacy applications to 0MQ - there's no need to break existing
message formats.

Initialise a message:
.BR zmq_msg_init(3)
.BR zmq_msg_size(3)
.BR zmq_msg_data(3)

Uninitialise a message:
.BR zmq_msg_close(3)

Access message content:
.BR zmq_msg_data(3)
.BR zmq_msg_size(3)

Message manipulation:
.BR zmq_msg_copy(3)
.BR zmq_msg_move(3)

.SH SOCKETS
0MQ sockets are very similar to POSIX sockets. See following manual pages to
understand them in depth.

Creating a socket:
.BR zmq_socket(3)

Closing a socket:
.BR zmq_close(3)

Setting socket options:
.BR zmq_setsockopt(3)

Establishing a message flow:
.BR zmq_bind(3)
.BR zmq_connect(3)

Sending & receiving messages:
.BR zmq_send(3)
.BR zmq_flush(3)
.BR zmq_recv(3)

.SH MULTIPLEXING
0MQ allows you to handle multiple sockets (0MQ as well as standard POSIX)
in an asynchronous manner.

Poll for I/O events:
.BR zmq_poll(3)

.SH ERROR HANDLING
0MQ defines couple of non-POSIX error codes. Use following functions to handle
them neatly.

Convert error code into human readable string:
.BR zmq_strerror(3)

.SH TRANSPORTS
0MQ allows for using different underlying transport mechanisms (even multiple
at once). Each transport mechanism has its own advantages and drawbacks. For
detailed description of individual mechanisms check following manual pages:

TCP/IP transport:
.BR zmq_tcp(7)

UDP reliable multicast transport:
.BR zmq_udp(7)

PGM reliable multicast transport:
.BR zmq_pgm(7)

Inter-process transport:
.BR zmq_ipc (7)

In-process (inter-thread) transport:
.BR zmq_inproc(7)

.SH DEVICES
Aside of the messaging library (a.k.a. messaging kernel) 0MQ provides pre-built
executables - devices - to serve as middle nodes in complex messaging
topologies. For detailed description of individual devices check following
manual pages:

Forwarder device for PUB/SUB messaging:
.BR zmq_forwarder(1)

Streamer device for UPSTREAM/DOWNSTREAM messaging:
.BR zmq_streamer(1)
.SH LANGUAGES
0MQ manual pages provide info on C API. To find out how the your
favourite language API maps to C API and thus how to find relevant manual pages,
see following articles:

C++:
.BR zmq_cpp(7)

Common Lisp:
.BR zmq_cl(7)

Python:
.BR zmq_python(7)

Ruby:
.BR zmq_ruby(7)

.SH AUTHOR
Martin Sustrik <sustrik at 250bpm dot com>