3party/libzmq
0
0
Fork 0
mirror of https://github.com/zeromq/libzmq.git synced 2024-12-27 07:31:03 +08:00
Code Issues Projects Releases Wiki Activity

Documentation rewrite

Browse Source
This commit is contained in:
Martin Lucina 2010-03-09 18:47:31 +01:00
parent d790940fd0
commit 1aee86408d
34 changed files with 1286 additions and 962 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/Makefile.am
View File

@ -4,8 +4,8 @@ MAN3 = zmq_bind.3 zmq_close.3 zmq_connect.3 zmq_flush.3 zmq_init.3 \
zmq_msg_init_data.3 zmq_msg_init_size.3 zmq_msg_move.3 zmq_msg_size.3 \
zmq_poll.3 zmq_recv.3 zmq_send.3 zmq_setsockopt.3 zmq_socket.3 \
zmq_strerror.3 zmq_term.3 zmq_version.3
MAN7 = zmq.7 zmq_tcp.7 zmq_udp.7 zmq_pgm.7 zmq_inproc.7 zmq_ipc.7 \
zmq_cpp.7 zmq_java.7
MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_epgm.7 zmq_inproc.7 zmq_ipc.7 \
zmq_cpp.7
MAN_DOC = $(MAN1) $(MAN3) $(MAN7)
MAN_TXT = $(MAN1:%.1=%.txt)

8
doc/asciidoc.conf
View File

@ -1,3 +1,6 @@
[paradef-default]
literal-style=template="literalparagraph"
[macros]
(?su)[\\]?(?P<name>linkzmq):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
@ -32,3 +35,8 @@ template::[header-declarations]
</refnamediv>
endif::backend-docbook[]
endif::doctype-manpage[]
[replacements]
ifdef::backend-xhtml11[]
0MQ=ØMQ
endif::backend-xhtml11[]

247
doc/zmq.txt
View File

@ -9,59 +9,69 @@ zmq - 0MQ lightweight messaging kernel
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.
*#include <zmq.h>*
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.
*cc* ['flags'] 'files' *-lzmq* ['libraries']
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.
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
~~~~~~~
Before using any 0MQ library functions the caller must initialise a 0MQ
'context' using _zmq_init()_. The following functions are provided to handle
initialisation and termination of a 'context':
Initialise 0MQ context::
linkzmq:zmq_init[3]
Uninitialise 0MQ context::
Terminate 0MQ context::
linkzmq:zmq_term[3]
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.
Thread safety
^^^^^^^^^^^^^
A 0MQ 'context' is thread safe and may be shared among as many application
threads as the application has requested using the _app_threads_ parameter to
_zmq_init()_, without any additional locking required on the part of the
caller. Each 0MQ socket belonging to a particular 'context' may only be used
by *the thread that created it* using _zmq_socket()_.
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 BLOBs.
The following functions are provided to work with messages:
Initialise a message::
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_size[3]
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_data[3]
Uninitialise a message::
Release a message::
linkzmq:zmq_msg_close[3]
Access message content::
@ -73,10 +83,21 @@ Message manipulation::
linkzmq:zmq_msg_move[3]
SOCKETS
-------
0MQ sockets are very similar to POSIX sockets. See following manual pages to
understand them in depth.
Sockets
~~~~~~~
Standard sockets present a _synchronous_ interface to either connection-mode
reliable byte streams (SOCK_STREAM), or connection-less unreliable datagrams
(SOCK_DGRAM). In comparison, 0MQ sockets present an abstraction of a
asynchronous _message queue_, with the exact queueing semantics depending on
the socket type (_messaging pattern_) in use. See linkzmq:zmq_socket[3] for the
_messaging patterns_ provided.
0MQ sockets being _asynchronous_ means that the timings of the physical
connection setup and teardown, reconnect and effective delivery are organized
by 0MQ itself, and that messages may be _queued_ in the event that a peer is
unavailable to receive them.
The following functions are provided to work with sockets:
Creating a socket::
linkzmq:zmq_socket[3]
@ -91,82 +112,108 @@ Establishing a message flow::
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
Sending & receiving messages::
Sending and receiving messages::
linkzmq:zmq_send[3]
linkzmq:zmq_flush[3]
linkzmq:zmq_recv[3]
MULTIPLEXING
------------
0MQ allows you to handle multiple sockets (0MQ as well as standard POSIX)
in an asynchronous manner.
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].
Poll for I/O events::
linkzmq:zmq_poll[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]
Devices
~~~~~~~
Apart from the 0MQ library the 0MQ distribution includes 'devices' which are
building blocks intended to serve as intermediate nodes in complex messaging
topologies.
The following devices are provided:
Forwarder device for request-response messaging::
linkzmq:zmq_queue[1]
Forwarder device for publish-subscribe messaging::
linkzmq:zmq_forwarder[1]
Streamer device for parallelized pipeline messaging::
linkzmq:zmq_streamer[1]
ERROR HANDLING
--------------
0MQ defines couple of non-POSIX error codes. Use following functions to handle
them neatly.
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.
Convert error code into human readable string::
linkzmq:zmq_strerror[3]
A _zmq_strerror()_ function is provided to translate 0MQ-specific error codes
into error message strings. For further details refer to
linkzmq:zmq_strerror[3].
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::
linkzmq:zmq_tcp[7]
UDP reliable multicast transport::
linkzmq:zmq_udp[7]
PGM reliable multicast transport::
linkzmq:zmq_pgm[7]
Inter-process transport::
linkzmq:zmq_ipc[7]
In-process (inter-thread) transport::
linkzmq:zmq_inproc[7]
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.
DEVICES
C++ language binding
~~~~~~~~~~~~~~~~~~~~
The 0MQ distribution includes a $$C++$$ language binding, which is documented
separately in linkzmq:zmq_cpp[7].
Other language bindings
~~~~~~~~~~~~~~~~~~~~~~~
Other language bindings (Python, Ruby, Java and more) are provided by members
of the 0MQ community and pointers can be found on the 0MQ website.
AUTHORS
-------
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::
linkzmq:zmq_forwarder[1]
Streamer device for UPSTREAM/DOWNSTREAM messaging::
linkzmq:zmq_streamer[1]
Forwarder device for REQ/REP messaging::
linkzmq:zmq_queue[1]
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
LANGUAGES
RESOURCES
---------
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:
Main web site: <http://www.zeromq.org/>
$$C++$$::
linkzmq:zmq_cpp[7]
Java::
linkzmq:zmq_java[7]
Report bugs to the 0MQ development mailing list: <zeromq-dev@lists.zeromq.org>
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
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.

60
doc/zmq_bind.txt
View File

@ -4,53 +4,66 @@ zmq_bind(3)
NAME
----
zmq_bind - binds the socket to the specified address
zmq_bind - assign a local address to a socket
SYNOPSIS
--------
'int zmq_bind (void *s, const char *addr);'
*int zmq_bind (void '*socket', const char '*address');*
DESCRIPTION
-----------
The function binds socket 's' to a particular transport. Actual semantics of the
command depend on the underlying transport mechanism, however, in cases where
peers connect in an asymmetric manner, 'zmq_bind' should be called first,
'zmq_connect' afterwards. Actual formats of 'addr' parameter are defined by
individual transports. For a list of supported transports have a look at
linkzmq:zmq[7] manual page.
The _zmq_bind()_ function shall assign a local address specified by the
'address' argument to the socket referenced by the 'socket' argument.
Note that single socket can be bound (and connected) to
arbitrary number of peers using different transport mechanisms.
The 'address' argument is a string consisting of two parts as follows:
'transport'://'endpoint'. The 'transport' part specifies the underlying
transport protocol to use. The meaning of the 'endpoint' part is specific to
the underlying transport protocol selected.
The following transports are defined:
'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
'pgm', 'udp':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[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]
A single socket may have an arbitrary number of local addresses assigned to it
using _zmq_bind()_, while also being connected to an arbitrary number of peer
addresses using _zmq_connect()_.
RETURN VALUE
------------
In case of success the function returns zero. Otherwise it returns -1 and
sets 'errno' to the appropriate value.
The _zmq_bind()_ function shall return zero if successful. Otherwise it shall
return -1 and set 'errno' to one of the values defined below.
ERRORS
------
*EPROTONOSUPPORT*::
unsupported protocol.
The requested 'transport' protocol is not supported.
*ENOCOMPATPROTO*::
protocol is not compatible with the socket type.
The requested 'transport' protocol is not compatible with the socket type.
*EADDRINUSE*::
the given address is already in use.
The given 'address' is already in use.
*EADDRNOTAVAIL*::
a nonexistent interface was requested or the requested address was not local.
A nonexistent interface was requested or the requested 'address' was not local.
EXAMPLE
-------
.Binding a publisher socket to an in-process and a TCP transport
----
void *s = zmq_socket (context, ZMQ_PUB);
assert (s);
int rc = zmq_bind (s, "inproc://my_publisher");
/* Create a ZMQ_PUB socket */
void *socket = zmq_socket (context, ZMQ_PUB);
assert (socket);
/* Bind it to a in-process transport with the endpoint 'my_publisher' */
int rc = zmq_bind (socket, "inproc://my_publisher");
assert (rc == 0);
rc = zmq_bind (s, "tcp://eth0:5555");
/* Bind it to a TCP transport on port 5555 of the 'eth0' interface */
rc = zmq_bind (socket, "tcp://eth0:5555");
assert (rc == 0);
----
@ -62,6 +75,7 @@ linkzmq:zmq_socket[3]
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

37
doc/zmq_close.txt
View File

@ -4,28 +4,29 @@ zmq_close(3)
NAME
----
zmq_close - destroys 0MQ socket
zmq_close - close 0MQ socket
SYNOPSIS
--------
'int zmq_close (void *s);'
*int zmq_close (void '*socket');*
DESCRIPTION
-----------
Destroys 0MQ socket (one created using
'zmq_socket' function). All sockets have to be properly closed before the
application terminates, otherwise memory leaks will occur. Note that any
outbound messages that haven't been psuhed to the network yet and any inbound
messages that haven't been received by the application yet will be dropped on
the socket shutdown.
The _zmq_close()_ function shall destroy the socket referenced by the 'socket'
argument. All active connections on the socket shall be terminated and
resources associated with the socket shall be released. Any outstanding
messages sent with _zmq_send()_ but not yet physically sent to the network
shall be dropped. Likewise, any outstanding messages physically received from
the network but not yet received by the application with _zmq_recv()_ shall
also be dropped.
RETURN VALUE
------------
In case of success the function returns zero. Otherwise it returns -1 and
sets 'errno' to the appropriate 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
@ -33,20 +34,14 @@ ERRORS
No errors are defined.
EXAMPLE
-------
----
int rc = zmq_close (s);
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_socket[3]
linkzmq:zmq_term[3]
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

60
doc/zmq_connect.txt
View File

@ -4,49 +4,66 @@ zmq_connect(3)
NAME
----
zmq_connect - connect the socket to the specified peer
zmq_connect - connect a socket to a peer address
SYNOPSIS
--------
'int zmq_connect (void *s, const char *addr);'
*int zmq_connect (void '*socket', const char '*address');*
DESCRIPTION
-----------
The function connect socket 's' to the peer identified by 'addr'. Actual
semantics of the command depend on the underlying transport mechanism,
however, in cases where peers connect in an asymmetric manner, 'zmq_bind'
should be called first, 'zmq_connect' afterwards. Formats of the 'addr'
parameter are defined by individual transports. For a list of supported
transports have a look at linkzmq:zmq[7] manual page.
The _zmq_connect()_ function shall connect the socket referenced by the
'socket' argument to a peer address specified by the 'address' argument.
Note that single socket can be connected (and bound) to
arbitrary number of peers using different transport mechanisms.
The 'address' argument is a string consisting of two parts as follows:
'transport'`://`'endpoint'. The 'transport' part specifies the underlying
transport protocol to use. The meaning of the 'endpoint' part is specific to
the underlying transport protocol selected.
The following transports are defined:
'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
'pgm', 'udp':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[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]
A single socket may be connected to an arbitrary number of peer addresses using
_zmq_connect()_, while also having an arbitrary number of local addresses
assigned to it using _zmq_bind()_.
NOTE: The connection will not be performed immediately but as needed by 0MQ.
Thus a successful invocation of _zmq_connect()_ does not indicate that a
physical connection was or can actually be established.
RETURN VALUE
------------
In case of success the function returns zero. Otherwise it returns -1 and
sets 'errno' to the appropriate value.
The _zmq_connect()_ function shall return zero if successful. Otherwise it
shall return -1 and set 'errno' to one of the values defined below.
ERRORS
------
*EPROTONOSUPPORT*::
unsupported protocol.
The requested 'transport' protocol is not supported.
*ENOCOMPATPROTO*::
protocol is not compatible with the socket type.
The requested 'transport' protocol is not compatible with the socket type.
EXAMPLE
-------
.Connecting a subscriber socket to an in-process and a TCP transport
----
void *s = zmq_socket (context, ZMQ_SUB);
assert (s);
int rc = zmq_connect (s, "inproc://my_publisher");
/* Create a ZMQ_SUB socket */
void *socket = zmq_socket (context, ZMQ_SUB);
assert (socket);
/* Connect it to an in-process transport with the endpoint 'my_publisher' */
int rc = zmq_connect (socket, "inproc://my_publisher");
assert (rc == 0);
rc = zmq_connect (s, "tcp://server001:5555");
/* Connect it to the host server001, port 5555 using a TCP transport */
rc = zmq_connect (socket, "tcp://server001:5555");
assert (rc == 0);
----
@ -58,6 +75,7 @@ linkzmq:zmq_socket[3]
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

1
doc/zmq_epgm.txt Symbolic link
View File

@ -0,0 +1 @@
zmq_pgm.txt

48
doc/zmq_flush.txt
View File

@ -4,56 +4,52 @@ zmq_flush(3)
NAME
----
zmq_flush - flushes pre-sent messages to the socket
zmq_flush - flush messages queued on a socket
SYNOPSIS
--------
'int zmq_flush (void *s);'
*int zmq_flush (void '*socket');*
DESCRIPTION
-----------
Flushes all the pre-sent messages - i.e. those that have been sent with
ZMQ_NOFLUSH flag - to the socket. This functionality improves performance in
cases where several messages are sent during a single business operation.
It should not be used as a transaction - ACID properties are not guaranteed.
Note that calling 'zmq_send' without ZMQ_NOFLUSH flag automatically flushes all
previously pre-sent messages.
The _zmq_flush()_ function shall flush messages previously queued on the socket
referenced by the 'socket' argument. The _zmq_flush()_ function only affects
messages that have been queued on the _message queue_ associated with 'socket'
using the 'ZMQ_NOFLUSH' flag to the _zmq_send()_ function. If no such messages
exist, the function has no effect.
CAUTION: A successful invocation of _zmq_flush()_ does not indicate that the
flushed messages have been transmitted to the network, or even that such a
transmission has been initiated by 0MQ. This function exists merely as a way
for the application programmer to supply a hint to the 0MQ infrastructure that
the queued messages *may* be flushed as a single batch.
RETURN VALUE
------------
In case of success the function returns zero. Otherwise it returns -1 and
sets 'errno' to the appropriate value.
The _zmq_flush()_ function shall return zero if successful. Otherwise it shall
return -1 and set 'errno' to one of the values defined below.
ERRORS
------
*ENOTSUP*::
function isn't supported by particular socket type.
The _zmq_flush()_ operation is not supported by this socket type.
*EFSM*::
function cannot be called at the moment, because socket is not in the
approprite state.
EXAMPLE
-------
----
rc = zmq_send (s, &msg1, ZMQ_NOFLUSH);
assert (rc == 0);
rc = zmq_send (s, &msg2, ZMQ_NOFLUSH);
assert (rc == 0);
rc = zmq_flush (s);
assert (rc == 0);
----
The _zmq_flush()_ operation cannot be performed on this socket at the moment
due to the socket not being in the appropriate state.
SEE ALSO
--------
linkzmq:zmq_send[3]
linkzmq:zmq_socket[3]
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

17
doc/zmq_forwarder.txt
View File

@ -4,29 +4,30 @@ zmq_forwarder(1)
NAME
----
zmq_forwarder - forwards the stream of PUB/SUB messages
zmq_forwarder - forwarding device for publish-subscribe messaging
SYNOPSIS
--------
*
To be written.
DESCRIPTION
-----------
*
To be written.
OPTIONS
-------
*
To be written.
SEE ALSO
--------
*
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

52
doc/zmq_init.txt
View File

@ -4,58 +4,56 @@ zmq_init(3)
NAME
----
zmq_init - initialises 0MQ context
zmq_init - initialise 0MQ context
SYNOPSIS
--------
'void *zmq_init (int app_threads, int io_threads, int flags);'
*void *zmq_init (int 'app_threads', int 'io_threads', int 'flags');*
DESCRIPTION
-----------
Initialises 0MQ context. 'app_threads' specifies maximal number of application
threads that can own open sockets at the same time. At least one application
thread should be defined. 'io_threads' specifies the size of thread pool to
handle I/O operations. The value shouldn't be negative. Zero can be used in
case only in-process messaging is going to be used, i.e. there will be no I/O
traffic.
The _zmq_init()_ function initialises a 0MQ 'context' with 'app_threads'
application threads and 'io_threads' I/O threads.
The 'app_threads' argument specifies the maximum number of application threads
that will be using 0MQ sockets in this 'context'. As a guide, set this to the
number of threads in your application.
The 'io_threads' argument specifies the size of the 0MQ thread pool to handle
I/O operations. If your application is using 'inproc' messaging exclusively you
may set this to zero, otherwise set it to at least one.
The 'flags' argument is a combination of the flags defined below:
*ZMQ_POLL*::
flag specifying that the sockets within this context should be pollable
(see linkzmq:zmq_poll[3]). Pollable sockets may add a little latency to the
message transfer when compared to non-pollable sockets.
Specifies that sockets within this 'context' should support multiplexing using
_zmq_poll()_. Enabling this functionality may add a small amount of latency to
message transfers compared to leaving it disabled.
RETURN VALUE
------------
Function returns context handle is successful. Otherwise it returns NULL and
sets errno to one of the values below.
The _zmq_init()_ function shall return an opaque handle to the initialised
'context' if successful. Otherwise it shall return NULL and set 'errno' to one
of the values defined below.
ERRORS
------
*EINVAL*::
there's less than one application thread allocated, or number of I/O
threads is negative.
EXAMPLE
-------
----
void *ctx = zmq_init (1, 1, ZMQ_POLL);
assert (ctx);
----
The number of 'app_threads' requested is less than one, or the number of
'io_threads' requested is negative.
SEE ALSO
--------
linkzmq:zmq[7]
linkzmq:zmq_term[3]
linkzmq:zmq_socket[3]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

85
doc/zmq_inproc.txt
View File

@ -4,47 +4,86 @@ zmq_inproc(7)
NAME
----
zmq_inproc - 0MQ transport to pass messages between threads
zmq_inproc - 0MQ local in-process (inter-thread) communication transport
SYNOPSIS
--------
In-process transport is optimised for passing messages between threads in the
same process.
The in-process transport passes messages via memory directly between threads
sharing a single 0MQ 'context'.
Messages are passed directly from one application thread to
another application thread. There are no intervening I/O threads involved.
Thus, if you are using 0MQ for in-process messaging only, you can initialise
the library (linkzmq:zmq_init[3]) with zero I/O worker threads.
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.
CONNECTION STRING
-----------------
Connection string for inproc transport is "inproc://" followed by an arbitrary
string. There are no restrictions on the string format:
ADDRESSING
----------
A 0MQ address string consists of two parts as follows:
'transport'`://`'endpoint'. The 'transport' part specifies the underlying
transport protocol to use, and for the in-process transport shall be set to
`inproc`. The meaning of the 'endpoint' part for the in-process transport is
defined below.
----
inproc://my_endpoint
inproc://feeds/opra/cboe
inproc://feeds.opra.nasdaq
inproc://!&W#($)_@_123*((^^^
----
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. The 'name' must have been previously
created by assigning it to at least one 'socket' within the same 0MQ 'context'
as the 'socket' being connected.
WIRE FORMAT
-----------
In-process transport transfers messages via memory thus there is no need for a
wire format specification.
Not applicable.
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_udp[7]
linkzmq:zmq_pgm[7]
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

72
doc/zmq_ipc.txt
View File

@ -4,41 +4,77 @@ zmq_ipc(7)
NAME
----
zmq_ipc - 0MQ transport to pass messages between processes
zmq_ipc - 0MQ local inter-process communication transport
SYNOPSIS
--------
Inter-process transport is optimised for passing messages between processes on
the same physical machine.
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.
CONNECTION STRING
-----------------
Connection string for inter-process transport is "ipc://" followed by a file
name. The file will be used as placeholder for a message endpoint. (UNIX domain
sockets associate a file with the listening socket in a similar way.)
ADDRESSING
----------
A 0MQ address string consists of two parts as follows:
'transport'`://`'endpoint'. The 'transport' part specifies the underlying
transport protocol to use, and for the inter-process transport shall be set to
`ipc`. The meaning of the 'endpoint' part for the inter-process transport is
defined below.
----
ipc:///tmp/my_ipc_endpoint
ipc:///tmp/prices.ipc
----
Assigning a local address to a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When assigning a local address to a 'socket' 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'.
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()_.
WIRE FORMAT
-----------
IPC transport doesn't transfer messages across the network thus there is no need
for a wire format specification.
Not applicable.
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_udp[7]
linkzmq:zmq_pgm[7]
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

27
doc/zmq_java.txt
View File

@ -1,27 +0,0 @@
zmq_java(7)
===========
NAME
----
zmq_java - interface between 0MQ and Java applications
SYNOPSIS
--------
*
DESCRIPTION
-----------
*
SEE ALSO
--------
*
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>

43
doc/zmq_msg_close.txt
View File

@ -4,25 +4,33 @@ zmq_msg_close(3)
NAME
----
zmq_msg_close - destroys 0MQ message
zmq_msg_close - release 0MQ message
SYNOPSIS
--------
'int zmq_msg_close (zmq_msg_t *msg);'
*int zmq_msg_close (zmq_msg_t '*msg');*
DESCRIPTION
-----------
Deallocates message 'msg' including any associated buffers (unless the buffer
is shared with another message). Not calling this function can result in
memory leaks.
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.
CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.
RETURN VALUE
------------
In case of success the function returns zero. Otherwise it returns -1 and sets
'errno' to the appropriate 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
@ -30,24 +38,17 @@ ERRORS
No errors are defined.
EXAMPLE
-------
----
zmq_msg_t msg;
rc = zmq_msg_init_size (&msg, 1000000);
assert (rc = 0);
rc = zmq_msg_close (&msg);
assert (rc = 0);
----
SEE ALSO
--------
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3]
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

46
doc/zmq_msg_copy.txt
View File

@ -4,30 +4,35 @@ zmq_msg_copy(3)
NAME
----
zmq_msg_copy - copies content of a message to another message
zmq_msg_copy - copy content of a message to another message
SYNOPSIS
--------
'int zmq_msg_copy (zmq_msg_t *dest, zmq_msg_t *src);'
*int zmq_msg_copy (zmq_msg_t '*dest', zmq_msg_t '*src');*
DESCRIPTION
-----------
Copy the 'src' message to 'dest'. The original content of
'dest' is orderly deallocated.
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.
CAUTION: The implementation may choose not to physically copy the data, rather
to share the buffer between two messages. Thus avoid modifying message data
after the message was copied. Doing so can modify multiple message instances.
If what you need is actual hard copy, allocate new message using
'zmq_msg_size' and copy the data using 'memcpy'.
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, allocate a new message using _zmq_msg_init_size()_ and
copy the message content using _memcpy()_.
CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.
RETURN VALUE
------------
In case of success the function returns zero. Otherwise it returns -1 and
sets 'errno' to the appropriate 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
@ -35,17 +40,6 @@ ERRORS
No errors are defined.
EXAMPLE
-------
----
zmq_msg_t dest;
rc = zmq_msg_init (&dest);
assert (rc == 0);
rc = zmq_msg_copy (&dest, &src);
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_msg_move[3]
@ -53,8 +47,10 @@ linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

32
doc/zmq_msg_data.txt
View File

@ -4,23 +4,27 @@ zmq_msg_data(3)
NAME
----
zmq_msg_data - retrieves pointer to the message content
zmq_msg_data - retrieve pointer to message content
SYNOPSIS
--------
'void *zmq_msg_data (zmq_msg_t *msg);'
*void *zmq_msg_data (zmq_msg_t '*msg');*
DESCRIPTION
-----------
Returns pointer to message data. Always use this function to access the data,
never use 'zmq_msg_t' members directly.
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
------------
Pointer to the message data.
Upon successful completion, _zmq_msg_data()_ shall return a pointer to the
message content.
ERRORS
@ -28,23 +32,17 @@ ERRORS
No errors are defined.
EXAMPLE
-------
----
zmq_msg_t msg;
rc = zmq_msg_init_size (&msg, 100);
memset (zmq_msg_data (&msg), 0, 100);
----
SEE ALSO
--------
linkzmq:zmq_msg_size[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

29
doc/zmq_msg_init.txt
View File

@ -4,24 +4,28 @@ zmq_msg_init(3)
NAME
----
zmq_msg_init - initialises empty 0MQ message
zmq_msg_init - initialise empty 0MQ message
SYNOPSIS
--------
'int zmq_msg_init (zmq_msg_t *msg);'
*int zmq_msg_init (zmq_msg_t '*msg');*
DESCRIPTION
-----------
Initialises 0MQ message zero bytes long. The function is most useful
to initialise a 'zmq_msg_t' structure before receiving a message.
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_recv()_.
CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
_zmq_msg_ family of functions.
RETURN VALUE
------------
In case of success the function returns zero. Otherwise it returns -1 and
sets 'errno' to the appropriate value.
The _zmq_msg_init()_ function shall return zero if successful. Otherwise it
shall return -1 and set 'errno' to one of the values defined below.
ERRORS
@ -31,24 +35,27 @@ No errors are defined.
EXAMPLE
-------
.Receiving a message from a socket
----
zmq_msg_t msg;
rc = zmq_msg_init (&msg);
assert (rc == 0);
rc = zmq_recv (s, &msg, 0);
rc = zmq_recv (socket, &msg, 0);
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_msg_close[3]
linkzmq:zmq_msg_init_size[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]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

51
doc/zmq_msg_init_data.txt
View File

@ -4,30 +4,35 @@ zmq_msg_init_data(3)
NAME
----
zmq_msg_init_data - initialises 0MQ message from the given data
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);'
*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
-----------
Initialise a message from a supplied buffer. Message isn't copied,
instead 0MQ infrastructure takes ownership of the buffer located at address
'data', 'size' bytes long. Deallocation function ('ffn') will be called once
the data are not needed anymore. When using a static constant buffer, 'ffn' may
be NULL to prevent subsequent deallocation. If needed, additional 'hint' can be
passed to the initialisation function. It's an opaque pointer that will be
later on passed to 'ffn' as a second argument.
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.
RETURN VALUE
------------
In case of success the function returns zero. Otherwise it returns -1 and
sets 'errno' to the appropriate 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
@ -37,10 +42,14 @@ No errors are defined.
EXAMPLE
-------
.Initialising a message from a supplied buffer
----
void my_free (void *data, void *hint) {free (data);}
void my_free (void *data, void *hint)
{
free (data);
}
...
/* ... */
void *data = malloc (6);
assert (data);
@ -48,20 +57,20 @@ memcpy (data, "ABCDEF", 6);
zmq_msg_t msg;
rc = zmq_msg_init_data (&msg, data, 6, my_free, NULL);
assert (rc == 0);
rc = zmq_send (s, &msg, 0);
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_msg_close[3]
linkzmq:zmq_msg_init[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]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

51
doc/zmq_msg_init_size.txt
View File

@ -4,58 +4,51 @@ zmq_msg_init_size(3)
NAME
----
zmq_msg_init_size - initialises 0MQ message of a specified size
zmq_msg_init_size - initialise 0MQ message of a specified size
SYNOPSIS
--------
'int zmq_msg_init_size (zmq_msg_t *msg, size_t size);'
*int zmq_msg_init_size (zmq_msg_t '*msg', size_t 'size');*
DESCRIPTION
-----------
Initialises 0MQ message 'size' bytes long. The implementation chooses whether
it is more efficient to store message content on the stack (small messages) or
on the heap (large messages). Therefore, never access message data directly
via 'zmq_msg_t' members, rather use 'zmq_msg_data' and 'zmq_msg_size' functions
to get message data and size. Note that the message data are not nullified to
avoid the associated performance impact. Thus you should expect your message to
contain bogus data after this call.
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.
RETURN VALUE
------------
In case of success the function returns zero. Otherwise it returns -1 and
sets 'errno' to the appropriate 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*::
memory to hold the message cannot be allocated.
EXAMPLE
-------
----
zmq_msg_t msg;
rc = zmq_msg_init_size (&msg, 6);
assert (rc == 0);
memcpy (zmq_msg_data (&msg), "ABCDEF", 6);
rc = zmq_send (s, &msg, 0);
assert (rc == 0);
----
Insufficient storage space is available.
SEE ALSO
--------
linkzmq:zmq_msg_close[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3]
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

38
doc/zmq_msg_move.txt
View File

@ -4,25 +4,30 @@ zmq_msg_move(3)
NAME
----
zmq_msg_move - moves content of a message to another message
zmq_msg_move - move content of a message to another message
SYNOPSIS
--------
int zmq_msg_move (zmq_msg_t *dest, zmq_msg_t *src);
*int zmq_msg_move (zmq_msg_t '*dest', zmq_msg_t '*src');*
DESCRIPTION
-----------
Move the content of the message from 'src' to 'dest'. The content isn't
copied, just moved. 'src' becomes an empty message after the call. Original
content of 'dest' message is deallocated.
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
------------
In case of success the function returns zero. Otherwise it returns -1 and
sets 'errno' to the appropriate 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
@ -30,17 +35,6 @@ ERRORS
No errors are defined.
EXAMPLE
-------
----
zmq_msg_t dest;
rc = zmq_msg_init (&dest);
assert (rc == 0);
rc = zmq_msg_move (&dest, &src);
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_msg_copy[3]
@ -48,8 +42,10 @@ linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

35
doc/zmq_msg_size.txt
View File

@ -4,23 +4,27 @@ zmq_msg_size(3)
NAME
----
zmq_msg_size - retrieves size of the message content
zmq_msg_size - retrieve message content size in bytes
SYNOPSIS
--------
'size_t zmq_msg_size (zmq_msg_t *msg);'
*size_t zmq_msg_size (zmq_msg_t '*msg');*
DESCRIPTION
-----------
Returns size of the message data. Always use this function to get the size,
never use 'zmq_msg_t' members directly.
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
------------
Size of the message data (bytes).
Upon successful completion, _zmq_msg_data()_ shall return the size of the
message content in bytes.
ERRORS
@ -28,26 +32,17 @@ ERRORS
No errors are defined.
EXAMPLE
-------
----
zmq_msg_t msg;
rc = zmq_msg_init (&msg);
assert (rc == 0);
rc = zmq_recv (s, &msg, 0);
assert (rc == 0);
size_t msg_size = zmq_msg_size (&msg);
----
SEE ALSO
--------
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_close[3]
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

172
doc/zmq_pgm.txt
View File

@ -4,103 +4,125 @@ zmq_pgm(7)
NAME
----
zmq_pgm - 0MQ PGM reliable multicast transport
zmq_pgm - 0MQ reliable multicast transport using PGM
SYNOPSIS
--------
PGM is a protocol for reliable multicast (RFC3208). 0MQ's PGM transport allows
you to deliver messages to multiple destinations sending the data over
the network once only. It makes sense to use PGM transport if the data,
delivered to each destination separately, would seriously load or even overload
the network.
PGM sending is rate limited rather than controlled by receivers. Thus, to get
optimal performance you should set ZMQ_RATE and ZMQ_RECOVERY_IVL socket options
prior to using PGM transport. Also note that passing multicast packets via
loopback interface has negative effect on the overall performance of the system.
Thus, if not needed, you should turn multicast loopback off using ZMQ_MCAST_LOOP
socket option.
PGM transport can be used only with ZMQ_PUB and ZMQ_SUB sockets.
CAUTION: PGM protocol runs directly on top of IP protocol and thus needs to
open raw IP socket. On some operating systems this operation requires special
privileges. On Linux, for example, you would need to either run your application
as root or set adequate capabilities for your executable. Alternative approach
is to use UDP transport, linkzmq:zmq_udp[7], that stacks PGM on top of UDP and
thus needs no special privileges.
PGM (Pragmatic General Multicast) is a protocol for reliable multicast
transport of data over IP networks.
CONNECTION STRING
-----------------
Connection string for PGM transport is "pgm://" followed by an IP address
of the NIC to use, semicolon, IP address of the multicast group, colon and
port number. IP address of the NIC can be either its numeric representation
or the name of the NIC as reported by operating system. IP address of the
multicast group should be specified in the numeric representation. For example:
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" where PGM datagrams are encapsulated inside
UDP datagrams (the 'epgm' transport).
----
pgm://eth0;224.0.0.1:5555
pgm://lo;230.0.0.0:6666
pgm://192.168.0.111;224.0.0.1:5555
----
The 'pgm' and 'epgm' transports can only be used with the 'ZMQ_PUB' and
'ZMQ_SUB' socket types.
NOTE: NIC names are not standardised by POSIX. They tend to be rather arbitrary
and platform dependent. Say, "eth0" on Linux would correspond to "en0" on OSX
and "e1000g" on Solaris. On Windows platform, as there are no short NIC names
available, you have to use numeric IP addresses instead.
Further, PGM sockets are rate limited by default and incur a performance
penalty when used over a loopback interface. For details, refer to the
'ZMQ_RATE', 'ZMQ_RECOVERY_IVL' and 'ZMQ_MCAST_LOOP' 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 address string consists of two parts as follows:
'transport'`://`'endpoint'. The 'transport' part specifies the underlying
transport protocol to use. For the standard PGM protocol, 'transport' shall be
set to `pgm`. For the "Encapsulated PGM" protocol 'transport' shall be set to
`epgm`. The meaning of the 'endpoint' part for both the 'pgm' and 'epgm'
transport 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 it's 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'.
A 'multicast address' is specified by an IPv4 multicast address in it's numeric
representation.
WIRE FORMAT
-----------
Consecutive PGM packets are interpreted as a single continuous stream of data.
The data is then split into messages using the wire format described in
linkzmq:zmq_tcp[7]. Thus, messages are not aligned with packet boundaries and
each message can start at an arbitrary position within the packet and span
several packets.
Consecutive PGM datagrams are interpreted by 0MQ as a single continous 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].
Given this wire format, it would be impossible for late joining consumers to
identify message boundaries. To solve this problem, each PGM packet payload
starts with 16-bit unsigned integer in network byte order which specifies the
offset of the first message in the packet. If there's no beginning of a message
in the packet (it's a packet transferring inner part of a larger message)
the value of the initial integer is 0xFFFF.
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.
Each packet thus looks like this:
A single PGM datagram as used by 0MQ can thus be defined by the following ABNF
grammar:
....
datagram = message / intermediate
message = (frame-offset *data 1*frame) <1>
intermediate = (escape 1*data)
frame-offset = 2OCTET
escape = %xFF %xFF
data = 1*OCTET
....
<1> 'frame' as defined in linkzmq:zmq_tcp[7].
EXAMPLE
-------
.Connecting a socket
----
+-----------+------------+------------------+--------
| IP header | PGM header | offset (16 bits) | data .....
+-----------+------------+------------------+--------
----
Following example shows how messages are arranged in subsequent packets:
----
+---------------+--------+-----------+-----------------------------+
| PGM/IPheaders | 0x0000 | message 1 | message 2 (part 1) |
+---------------+--------+-----------+-----------------------------+
+---------------+--------+-----------------------------------------+
| PGM/IPheaders | 0xFFFF | message 2 (part 2) |
+---------------+--------+-----------------------------------------+
+---------------+--------+--------------------------+-----------+
| PGM/IPheaders | 0x0008 | message 2 (last 8 bytes) | message 3 |
+---------------+--------+--------------------------+-----------+
/* 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_udp[7]
linkzmq:zmq_connect[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_tcp[7]
linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

124
doc/zmq_poll.txt
View File

@ -4,83 +4,127 @@ zmq_poll(3)
NAME
----
zmq_poll - polls for events on a set of 0MQ and POSIX sockets
zmq_poll - input/output multiplexing
SYNOPSIS
--------
'int zmq_poll (zmq_pollitem_t *items, int nitems, long timeout);'
*int zmq_poll (zmq_pollitem_t '*items', int 'nitems', long 'timeout');*
DESCRIPTION
-----------
Waits for the events specified by 'items' parameter. Number of items in the
array is determined by 'nitems' argument. Each item in the array looks like
this:
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;
void '*socket';
int 'fd';
short 'events';
short 'revents';
} zmq_pollitem_t;
----
0MQ socket to poll on is specified by 'socket'. In case you want to poll on
standard POSIX socket, set 'socket' to NULL and fill the POSIX file descriptor
to 'fd'. 'events' specifies which events to wait for. It's a combination of
the values below. Once the call exits, 'revents' will be filled with events
that have actually occured on the socket. The field will contain a combination
of the values below.
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 occured by setting the
bit corresponding to the event condition in the 'revents' member.
If none of the requested events have occured on any *zmq_pollitem_t* item,
_zmq_poll()_ shall wait up to 'timeout' microseconds 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 wait
indefinitely for requested events to occur.
The 'events' and 'revents' members of *zmq_pollitem_t* are bitmasks constructed
by OR'ing a combination of the following event flags:
*ZMQ_POLLIN*::
poll for incoming messages.
*ZMQ_POLLOUT*::
wait while message can be set socket. Poll will return if a message of at least
one byte can be written to the socket. However, there is no guarantee that
arbitrarily large message can be sent.
For 0MQ sockets, at least one message may be dequeued from the underlying
_message queue_ associated with '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.
'timeout' argument specifies an upper limit on the time for which 'zmq_poll'
will block, in microseconds. Specifying a negative value in timeout means an
infinite timeout.
*ZMQ_POLLOUT*::
For 0MQ sockets, at least one message may be queued on the underlying
_message queue_ associated with '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()_.
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.
RETURN VALUE
------------
Function returns number of items signaled, 0 in the case of timeout or -1
in the case of error.
Upon successful completion, the _zmq_poll()_ function shall return the number
of *zmq_pollitem_t* structures with events signaled in 'revents' or 0 if the
'timeout' period has expired and no events have been signaled. Upon failure,
_zmq_poll()_ shall return -1 and set 'errno' to one of the values defined
below.
ERRORS
------
*EFAULT*::
there's a 0MQ socket in the pollset belonging to a different application thread.
At least one of the members of the 'items' array refers to a 'socket' belonging
to a different application thread.
*ENOTSUP*::
0MQ context was initialised without ZMQ_POLL flag. I/O multiplexing is disabled.
At least one of the members of the 'items' array refers to a 'socket' whose
associated 0MQ 'context' was initialised without the 'ZMQ_POLL' flag.
EXAMPLE
-------
.Polling idenfinitely for input events on both a 0MQ socket and a standard socket.
----
zmq_pollitem_t items [2];
items [0].socket = s;
items [0].events = ZMQ_POLLIN;
items [1].socket = NULL;
items [1].fd = my_fd;
items [1].events = ZMQ_POLLIN;
int rc = zmq_poll (items, 2);
assert (rc != -1);
/* 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.
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

17
doc/zmq_queue.txt
View File

@ -4,29 +4,30 @@ zmq_queue(1)
NAME
----
zmq_queue - forwards REQ/REP messages
zmq_queue - forwarding device for request-reply messaging
SYNOPSIS
--------
*
To be written.
DESCRIPTION
-----------
*
To be written.
OPTIONS
-------
*
To be written.
SEE ALSO
--------
*
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

53
doc/zmq_recv.txt
View File

@ -4,51 +4,60 @@ zmq_recv(3)
NAME
----
zmq_recv - retrieves a message from the socket
zmq_recv - receive a message from a socket
SYNOPSIS
--------
'int zmq_recv (void *s, zmq_msg_t *msg, int flags);'
*int zmq_recv (void '*socket', zmq_msg_t '*msg', int 'flags');*
DESCRIPTION
-----------
Receive a message from the socket 's', store it in
'msg' . Any content previously in 'msg' will be properly deallocated. 'flags'
argument can be combination of the flags described below.
The _zmq_recv()_ function shall dequeue a message from the underlying _message
queue_ associated with 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 messages
available to be dequeued from the underlying _message queue_ associated with
'socket' the _zmq_recv()_ function shall block until the request can be
satisfied. The 'flags' argument is a combination of the flags defined below:
*ZMQ_NOBLOCK*::
The flag specifies that the operation should be performed in
non-blocking mode. I.e. if it cannot be processed immediately,
error should be returned with 'errno' set to EAGAIN.
Specifies that the operation should be performed in non-blocking mode. If there
are no messages available to be dequeued from the underlying _message queue_
associated with 'socket', the _zmq_recv()_ function shall fail with 'errno' set
to EAGAIN.
RETURN VALUE
------------
In case of success the function returns zero. Otherwise it returns -1 and
sets 'errno' to the appropriate value.
The _zmq_recv()_ function shall return zero if successful. Otherwise it shall
return -1 and set 'errno' to one of the values defined below.
ERRORS
------
*EAGAIN*::
it's a non-blocking receive and there's no message available at the moment.
Non-blocking mode was requested and no messages are available at the moment.
*ENOTSUP*::
function isn't supported by particular socket type.
The _zmq_recv()_ operation is not supported by this socket type.
*EFSM*::
function cannot be called at the moment, because socket is not in the
appropriate state. This error may occur with sockets that switch between
several states (e.g. ZMQ_REQ).
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.
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);
rc = zmq_recv (s, &msg, 0);
/* Block until a message is available to be dequeued from socket */
rc = zmq_recv (socket, &msg, 0);
assert (rc == 0);
----
@ -56,11 +65,11 @@ assert (rc == 0);
SEE ALSO
--------
linkzmq:zmq_send[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3]
linkzmq:zmq_socket[7]
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

66
doc/zmq_send.txt
View File

@ -4,59 +4,69 @@ zmq_send(3)
NAME
----
zmq_send - sends a message
zmq_send - send a message on a socket
SYNOPSIS
--------
'int zmq_send (void *s, zmq_msg_t *msg, int flags);'
*int zmq_send (void '*socket', zmq_msg_t '*msg', int 'flags');*
DESCRIPTION
-----------
Send the message 'msg' to the socket 's'. 'flags' argument can be combination
the flags described below.
The _zmq_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_NOBLOCK*::
The flag specifies that the operation should be performed in non-blocking mode.
I.e. if it cannot be processed immediately, error should be returned with
'errno' set to EAGAIN.
Specifies that the operation should be performed in non-blocking mode. If the
message cannot be queued on the underlying _message queue_ associated with
'socket', the _zmq_send()_ function shall fail with 'errno' set to EAGAIN.
*ZMQ_NOFLUSH*::
The flag specifies that 'zmq_send' should not flush the message downstream
immediately. Instead, it should batch ZMQ_NOFLUSH messages and send them
downstream only once 'zmq_flush' is invoked. This is an optimisation for cases
where several messages are sent in a single business transaction. However, the
effect is measurable only in extremely high-perf scenarios (million messages a
second or so). If that's not your case, use standard flushing send instead.
Specifies that the _zmq_send()_ function should not flush the underlying
_message queue_ associated with 'socket' to the network automatically.
Instead, it should batch all messages queued with the 'ZMQ_NOFLUSH' flag and
only flush the _message queue_ once either a message without the 'ZMQ_NOFLUSH'
flag is queued, or manually on invocation of the _zmq_flush()_ function.
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 _message queue_ associated with the socket and 0MQ has assumed
responsibility for the message.
RETURN VALUE
------------
In case of success the function returns zero. Otherwise it returns -1 and
sets 'errno' to the appropriate value.
The _zmq_send()_ function shall return zero if successful. Otherwise it shall
return -1 and set 'errno' to one of the values defined below.
ERRORS
------
*EAGAIN*::
it's a non-blocking send and message cannot be sent at the moment.
Non-blocking mode was requested and the message cannot be queued at the moment.
*ENOTSUP*::
function isn't supported by particular socket type.
The _zmq_send()_ operation is not supported by this socket type.
*EFSM*::
function cannot be called at the moment, because socket is not in the
appropriate state. This error may occur with sockets that switch between
several states (e.g. ZMQ_REQ).
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.
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);
rc = zmq_send (s, &msg, 0);
/* Send the message to the socket */
rc = zmq_send (socket, &msg, 0);
assert (rc == 0);
----
@ -65,13 +75,11 @@ SEE ALSO
--------
linkzmq:zmq_flush[3]
linkzmq:zmq_recv[3]
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_init_size[3]
linkzmq:zmq_msg_init_data[3]
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3]
linkzmq:zmq_socket[7]
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

324
doc/zmq_setsockopt.txt
View File

@ -5,144 +5,255 @@ zmq_setsockopt(3)
NAME
----
zmq_setsockopt - sets a specified option on a 0MQ socket
zmq_setsockopt - set 0MQ socket options
SYNOPSIS
--------
'int zmq_setsockopt (void *s, int option, const void *optval, size_t optvallen);'
*int zmq_setsockopt (void '*socket', int 'option_name', const void '*option_value', size_t 'option_len');*
DESCRIPTION
-----------
Sets an option on the socket. 'option' argument specifies the option from the
list below. 'optval' is a pointer to the value to set, 'optvallen' is the size
of the value in bytes.
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.
*ZMQ_HWM*::
High watermark for the message pipes associated with the socket. The water
mark cannot be exceeded. If the messages don't fit into the pipe emergency
mechanisms of the particular socket type are used (block, drop etc.) If HWM
is set to zero, there are no limits for the content of the pipe.
+
Type: int64_t Unit: messages Default: 0
The following options are defined:
*ZMQ_LWM*::
Low watermark makes sense only if high watermark is defined (i.e. is non-zero).
When the emergency state is reached when messages overflow the pipe, the
emergency lasts at most till the size of the pipe decreases to low watermark.
Normal state is resumed at that point.
+
Type: int64_t Unit: messages Default: 0
*ZMQ_SWAP*::
Swap allows the pipe to exceed high watermark. However, the data are written
to the disk rather than held in the memory. Until high watermark is
exceeded there is no disk activity involved though. The value of the option
defines maximal size of the swap file.
+
Type: int64_t Unit: bytes Default: 0
ZMQ_HWM: Set high water mark
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_HWM' option shall set the high water mark for the _message queue_
associated with the socket. The high water mark is a hard limit on the number
of outstanding messages in the queue; if this limit has been reached the socket
shall enter an "emergency" state and depending on the socket type, 0MQ shall
take appropriate action such as blocking or dropping new messages entering the
queue.
*ZMQ_AFFINITY*::
Affinity defines which threads in the thread pool will be used to handle
newly created sockets. This way you can dedicate some of the threads (CPUs)
to a specific work. Value of 0 means no affinity. Work is distributed
fairly among the threads in the thread pool. For non-zero values, the lowest
bit corresponds to the thread 1, second lowest bit to the thread 2 etc.
Thus, value of 3 means that from now on newly created sockets will handle
I/O activity exclusively using threads no. 1 and 2.
+
Type: int64_t Unit: N/A (bitmap) Default: 0
The default 'ZMQ_HWM' value of zero means "no limit".
*ZMQ_IDENTITY*::
Identity of the socket. Identity is important when restarting applications.
If the socket has no identity, each run of the application is completely
separated from other runs. However, with identity application reconnects to
existing infrastructure left by the previous run. Thus it may receive
messages that were sent in the meantime, it shares pipe limits with the
previous run etc. Identity should be at least one byte and at most 255 bytes
long. Identities starting with binary zero are reserver for use by 0MQ
infrastructure.
+
Type: BLOB Unit: N/A Default: NULL
Option value type:: int64_t
Option value unit:: messages
Default value:: 0
Applicable socket types:: all
*ZMQ_SUBSCRIBE*::
Applicable only to ZMQ_SUB socket type. It establishes new message filter.
When ZMQ_SUB socket is created all the incoming messages are filtered out.
This option allows you to subscribe for all messages (""), or messages
beginning with specific prefix (e.g. "animals.mammals.dogs."). Multiple
filters can be attached to a single 'sub' socket. In that case message passes
if it matches at least one of the filters.
+
Type: BLOB Unit: N/A Default: N/A
*ZMQ_UNSUBSCRIBE*::
Applicable only to ZMQ_SUB socket type. Removes existing message filter.
The filter specified must match the string passed to ZMQ_SUBSCRIBE options
exactly. If there were several instances of the same filter created,
this options removes only one of them, leaving the rest in place
and functional.
+
Type: BLOB Unit: N/A Default: N/A
ZMQ_LWM: Set low water mark
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_LWM' option shall set the low water mark for the _message queue_
associated with the socket. This option only makes sense when used in
conjunction with the 'ZMQ_HWM' option. A socket which has reached it's high
water mark remains in the "emergency" state until the number of outstanding
messages in it's associated message queue falls below the low water mark, at
which point normal message processing is resumed.
*ZMQ_RATE*::
This option applies only to sending side of multicast transports (pgm & udp).
It specifies maximal outgoing data rate that an individual sender socket
can send.
+
Type: uint64_t Unit: kilobits/second Default: 100
Option value type:: int64_t
Option value unit:: messages
Default value:: 0
Applicable socket types:: all
*ZMQ_RECOVERY_IVL*::
This option applies only to multicast transports (pgm & udp). It specifies
how long can the receiver socket survive when the sender is inaccessible.
Keep in mind that large recovery intervals at high data rates result in
very large recovery buffers, meaning that you can easily overload your box
by setting say 1 minute recovery interval at 1Gb/s rate (requires
7GB in-memory buffer).
+
Type: uint64_t Unit: seconds Default: 10
*ZMQ_MCAST_LOOP*::
This option applies only to multicast transports (pgm & udp). Value of 1
means that the mutlicast packets can be received on the box they were sent
from. Setting the value to 0 disables the loopback functionality which
can have negative impact on the performance. If possible, disable
the loopback in production environments.
+
Type: uint64_t Unit: N/A (boolean value) Default: 1
ZMQ_SWAP: Set disk offload size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_SWAP' option shall set the disk offload (swap) size for the _message
queue_ associated with the socket. A socket which has 'ZMQ_SWAP' set to a
non-zero value may exceed it's high water mark; in this case outstanding
messages shall be offloaded to storage on disk rather than held in memory.
*ZMQ_SNDBUF*::
Sets the underlying kernel transmit buffer size to the specified size. See
'SO_SNDBUF' POSIX socket option. Value of zero means leaving the OS default
unchanged.
+
Type: uint64_t Unit: bytes Default: 0
The value of 'ZMQ_SWAP' defines the maximum size of the swap space in bytes.
*ZMQ_RCVBUF*::
Sets the underlying kernel receive buffer size to the specified size. See
'SO_RCVBUF' POSIX socket option. Value of zero means leaving the OS default
unchanged.
+
Type: uint64_t Unit: bytes Default: 0
Option value type:: int64_t
Option value unit:: bytes
Default value:: 0
Applicable socket types:: all
ZMQ_AFFINITY: Set I/O thread affinity
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_AFFINITY' option shall set the I/O thread affinity for connections
created by subsequent _zmq_connect()_ or _zmq_bind()_ calls on the specified
'socket'.
sockets. 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_.
Option value type:: int64_t
Option value unit:: N/A (bitmap)
Default value:: 0
Applicable socket types:: N/A
ZMQ_IDENTITY: Set socket identity
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_IDENTITY' option shall set the identity of the socket. Socket identity
determines if existing 0MQ infastructure (_message queues_, _forwarding
devices_) shall be identified with a specific application and persist across
multiple runs of the application.
If the socket has no identity, each run of an application is completely
separate from other runs. However, with identity set the socket shall re-use
any existing 0MQ infrastructure configured by the previous run(s). Thus the
application may receive messages that were sent in the meantime, _message
queue_ limits shall be shared with previous run(s) and so on.
Identity should be at least one byte and at most 255 bytes long. Identities
starting with binary zero are reserved for use by 0MQ infrastructure.
Option value type:: BLOB
Option value unit:: N/A
Default value:: NULL
Applicable socket types:: all
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. Mutiple 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:: BLOB
Option value unit:: N/A
Default value:: N/A
Applicable socket types:: ZMQ_SUB
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:: BLOB
Option value unit:: N/A
Default value:: N/A
Applicable socket types:: ZMQ_SUB
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] and linkzmq:zmq_udp[7] using
the specified 'socket'.
Option value type:: uint64_t
Option value unit:: kilobits per second
Default value:: 100
Applicable socket types:: all, when using multicast transports
ZMQ_RECOVERY_IVL: Set multicast recovery interval
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_RECOVERY_IVL' option shall set the recovery interval for multicast
transports such as linkzmq:zmq_pgm[7] and linkzmq:zmq_udp[7] using the
specified 'socket'. The recovery interval determines the maximum time in
seconds that a receiver can be absent from a multicast group before
unrecoverable data loss will occur.
CAUTION: Excersize 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:: uint64_t
Option value unit:: seconds
Default value:: 10
Applicable socket types:: all, when using multicast transports
ZMQ_MCAST_LOOP: Control multicast loopback
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_MCAST_LOOP' option shall control whether data sent via multicast
transports can also be received by the sending host via loopback. A value of
zero disables the loopback functionality, while the default value of 1 enables
the loopback functionality. Leaving multicast loopback enabled when it is not
required can have a negative impact on performance. Where possible, disable
'ZMQ_MCAST_LOOP' in production environments.
Option value type:: uint64_t
Option value unit:: boolean
Default value:: 1
Applicable socket types:: all, when using multicast transports
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 zero means leave the
OS default unchanged. For details please refer to your operating system
documentation for the 'SO_SNDBUF' socket option.
Option value type:: uint64_t
Option value unit:: bytes
Default value:: 0
Applicable socket types:: all
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 zero means leave the OS
default unchanged. For details refer to your operating system documentation for
the 'SO_RCVBUF' socket option.
Option value type:: uint64_t
Option value unit:: bytes
Default value:: 0
Applicable socket types:: all
RETURN VALUE
------------
In case of success the function returns zero. Otherwise it returns -1 and
sets 'errno' to the appropriate 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*::
unknown option, a value with incorrect length or invalid value.
The requested option _option_name_ is unknown, or the requested _option_len_ or
_option_value_ is invalid.
EXAMPLE
-------
.Subscribing to messages on a 'ZMQ_SUB' socket
----
int rc = zmq_setsockopt (s, ZMQ_SUBSCRIBE, "", 0);
/* 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
----
/* Incoming connections on TCP port 5555 shall be handled by I/O thread 1 */
rc = zmq_setsockopt (socket, ZMQ_AFFINITY, 1, sizeof (int64_t));
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 */
rc = zmq_setsockopt (socket, ZMQ_AFFINITY, 2, sizeof (int64_t));
assert (rc);
rc = zmq_bind (socket, "tcp://lo:5555");
assert (rc);
----
@ -152,6 +263,7 @@ linkzmq:zmq_socket[3]
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

166
doc/zmq_socket.txt
View File

@ -4,110 +4,117 @@ zmq_socket(3)
NAME
----
zmq_socket - creates 0MQ socket
zmq_socket - create 0MQ socket
SYNOPSIS
--------
'void *zmq_socket (void *context, int type);'
*void *zmq_socket (void '*context', int 'type');*
DESCRIPTION
-----------
Open a socket within the specified 'context'. To create a context, use
'zmq_init' function. 'type' argument can be one of the values defined below.
Note that each socket is owned by exactly one thread (the one that it was
created from) and should not be used from any other thread.
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 _messaging pattern_, which determines the semantics of
communication over the socket.
*ZMQ_P2P*::
Socket to communicate with a single peer. Allows for only a single connect
or a single bind. There's no message routing or message filtering involved.
+
Compatible peer sockets: ZMQ_P2P.
The following _messaging patterns_ are defined:
*ZMQ_PUB*::
Socket to distribute data. Recv function is not implemented for this socket
type. Messages are distributed in fanout fashion to all the peers.
+
Compatible peer sockets: ZMQ_SUB.
*ZMQ_SUB*::
Socket to subscribe for data. Send function is not implemented for this socket
type. Initially, socket is subscribed for no messages. Use ZMQ_SUBSCRIBE option
to specify which messages to subscribe for.
+
Compatible peer sockets: ZMQ_PUB.
Peer to peer pattern
~~~~~~~~~~~~~~~~~~~~
The simplest messaging pattern, used for communicating between two peers.
*ZMQ_REQ*::
Socket to send requests and receive replies. Requests are load-balanced among
all the peers. This socket type allows only an alternated sequence of send's
and recv's.
+
Compatible peer sockets: ZMQ_REP, ZMQ_XREP.
Socket type:: 'ZMQ_P2P'
Compatible peer sockets:: 'ZMQ_P2P'
*ZMQ_REP*::
Socket to receive requests and send replies. This socket type allows only an
alternated sequence of recv's and send's. Each send is routed to the peer that
issued the last received request.
+
Compatible peer sockets: ZMQ_REQ, ZMQ_XREQ.
A socket of type 'ZMQ_P2P' 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_P2P' socket.
*ZMQ_XREQ*::
Special socket type to be used in request/reply middleboxes such as
linkzmq:zmq_queue[7]. Requests forwarded using this socket type should be
tagged by a proper prefix identifying the original requester. Replies received
by this socket are tagged with a proper prefix that can be use to route the
reply back to the original requester.
+
Compatible peer sockets: ZMQ_REP, ZMQ_XREP.
*ZMQ_XREP*::
Special socket type to be used in request/reply middleboxes such as
linkzmq:zmq_queue[7]. Requests received using this socket are already properly
tagged with prefix identifying the original requester. When sending a reply via
XREP socket the message should be tagged with a prefix from a corresponding
request.
+
Compatible peer sockets: ZMQ_REQ, ZMQ_XREQ.
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 fanout fashion.
*ZMQ_UPSTREAM*::
Socket to receive messages from up the stream. Messages are fair-queued from
among all the connected peers. Send function is not implemented for this socket
type.
+
Compatible peer sockets: ZMQ_DOWNSTREAM.
Socket type:: 'ZMQ_PUB'
Compatible peer sockets:: 'ZMQ_SUB'
*ZMQ_DOWNSTREAM*::
Socket to send messages down stream. Messages are load-balanced among all the
connected peers. Recv function is not implemented for this socket type.
+
Compatible peer sockets: ZMQ_UPSTREAM.
A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data.
Messages sent are distributed in a fanout fashion to all connected peers.
The _zmq_recv()_ function is not implemented for this socket type.
Socket type:: 'ZMQ_SUB'
Compatible peer sockets:: 'ZMQ_PUB'
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()_ to specify
which messages to subscribe to. The _zmq_send()_ function is not implemented
for this socket type.
Request-reply pattern
~~~~~~~~~~~~~~~~~~~~~
The request-reply pattern is used for sending requests from a _client_ to a
_service_, and receiving subsequent replies to each request sent.
Socket type:: 'ZMQ_REQ'
Compatible peer sockets:: 'ZMQ_REP'
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 load-balanced among all connected _services_.
Socket type:: 'ZMQ_REP'
Compatible peer sockets:: 'ZMQ_REQ'
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
reply is routed to the _client_ that issued the last received request.
Parallelized pipeline pattern
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The parallelized pipeline pattern is used for distributing work between
_components_ of a pipeline. Work travels down the pipeline and at each stage
can be processed by any number of _components_ in parallel.
Socket type:: 'ZMQ_UPSTREAM'
Compatible peer sockets:: 'ZMQ_DOWNSTREAM'
A socket of type 'ZMQ_UPSTREAM' is used by a _component_ of a pipeline to
receive messages from upstream stages of the pipeline. Messages are fair-queued
from among all connected upstream _components_. The _zmq_send()_ function is
not implemented for this socket type.
Socket type:: 'ZMQ_DOWNSTREAM'
Compatible peer sockets:: 'ZMQ_UPSTREAM'
A socket of type 'ZMQ_DOWNSTREAM' is used by a _component_ of a pipeline to
send messages to downstream stages of the pipeline. The _zmq_recv()_ function
is not implemented for this socket type.
RETURN VALUE
------------
Function returns socket handle is successful. Otherwise it returns NULL and
sets errno to one of the values below.
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*::
invalid socket type.
The requested socket 'type' is invalid.
*EMTHREAD*::
the number of application threads allowed to own 0MQ sockets was exceeded.
See 'app_threads' parameter to 'zmq_init' function.
EXAMPLE
-------
----
void *s = zmq_socket (context, ZMQ_PUB);
assert (s);
int rc = zmq_bind (s, "tcp://192.168.0.1:5555");
assert (rc == 0);
----
The number of application threads using sockets within this 'context' has been
exceeded. See the 'app_threads' parameter of the _zmq_init()_ function.
SEE ALSO
@ -121,6 +128,7 @@ linkzmq:zmq_flush[3]
linkzmq:zmq_recv[3]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

17
doc/zmq_streamer.txt
View File

@ -4,29 +4,30 @@ zmq_streamer(1)
NAME
----
zmq_streamer - forwards the stream of UPSTREAM/DOWNSTREAM messages
zmq_streamer - streamer device for parallelized pipeline messaging
SYNOPSIS
--------
*
To be written.
DESCRIPTION
-----------
*
To be written.
OPTIONS
-------
*
To be written.
SEE ALSO
--------
*
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

25
doc/zmq_strerror.txt
View File

@ -4,24 +4,27 @@ zmq_strerror(3)
NAME
----
zmq_strerror - returns string describing the error number
zmq_strerror - get 0MQ error message string
SYNOPSIS
--------
'const char *zmq_strerror (int errnum);'
*const char *zmq_strerror (int 'errnum');*
DESCRIPTION
-----------
As 0MQ defines few additional (non-POSIX) error codes, standard
'strerror' isn't capable of translating those errors into human readable
strings. Instead, 'zmq_strerror' should be used.
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
------------
Returns string describing the error number.
The _zmq_strerror()_ function shall return a pointer to an error message
string.
ERRORS
@ -31,10 +34,11 @@ 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 occured during zmq_init: %s\\n", zmq_strerror (errno));
printf ("Error occurred during zmq_init(): %s\n", zmq_strerror (errno));
abort ();
}
----
@ -45,6 +49,7 @@ SEE ALSO
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

129
doc/zmq_tcp.txt
View File

@ -4,55 +4,72 @@ zmq_tcp(7)
NAME
----
zmq_tcp - 0MQ unicast TCP transport over the network
zmq_tcp - 0MQ unicast transport using TCP
SYNOPSIS
--------
TCP is an ubiquitous unicast transport. When connecting distributed
applications, you will mostly use TCP transport.
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.
CONNECTION STRING
-----------------
Connection string for TCP transport is "tcp://" followed by an IP address,
colon and port number. IP address can be either its numeric representation,
a NIC name or a hostname (resolved by DNS):
ADDRESSING
----------
A 0MQ address string consists of two parts as follows:
'transport'`://`'endpoint'. The 'transport' part specifies the underlying
transport protocol to use, and for the TCP transport shall be set to `tcp`.
The meaning of the 'endpoint' part for the TCP transport is defined below.
----
tcp://192.168.0.111:5555
tcp://myserver001:80
tcp://lo:32768
----
Note that NIC names are not standardised by POSIX. They tend to be rather
arbitrary and platform dependent. Say, "eth0" on Linux would correspond to "en0"
on OSX and "e1000g" on Solaris. On Windows platform, as there are no short NIC
names available, you have to use numeric IP addresses instead.
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 interface name as defined by the operating system.
* The primary IPv4 address assigned to the interface, in it's numeric representation.
* The wildcard `*`, meaning that the interface address is unspecified.
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'.
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.
A 'peer address' may be specified by either of the following:
* The DNS name of the peer.
* The IPv4 address of the peer, in it's numeric representation.
WIRE FORMAT
-----------
A message consists of a message length followed by message data.
Size of message data MUST correspond to the message length.
0MQ messages are transmitted over TCP in frames consisting of the message
length followed by the message data. The size of the message data MUST
correspond to the message length. A single 'frame' can be defined by the
following ABNF grammar:
For messages of 0 to 254 octets, the length is represented by single octet.
....
frame = (message-length message-data)
message-length = OCTET / (escape 8OCTET)
escape = %xFF
message-data = *OCTET
....
For messages of 255 or more octets the length is represented by a single octet
%xFF followed by a 64-bit unsigned integer length in network byte order.
The protocol can be defined by this BNF grammar:
For messages of 0 to 254 octets in length, the message length is represented by
a single octet:
----
frame = length data
length = OCTET | escape 8*OCTET
escape = %xFF
data = *OCTET
----
Binary layout of a message (up to 254 bytes long):
----
....
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
@ -60,11 +77,13 @@ Binary layout of a message (up to 254 bytes long):
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message body ...
+-+-+-+-+-+-+- ...
----
....
Binary layout of a larger message:
For messages of 255 or more octets in length, the message length is represented
by a single octet with the value `255` followed by the message length
represented as a 64-bit unsigned integer in network byte order:
----
....
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
@ -76,18 +95,46 @@ Binary layout of a larger message:
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message body ...
+-+-+-+-+-+-+-+ ...
....
EXAMPLES
--------
.Assigning a local address to a socket
----
/* TCP port 5555 on the local loopback 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);
/* TCP port 5555 with an unspecified interface */
rc = zmq_bind(socket, "tcp://*: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);
----
SEE ALSO
--------
linkzmq:zmq_udp[7]
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_pgm[7]
linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7]
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

33
doc/zmq_term.txt
View File

@ -4,25 +4,27 @@ zmq_term(3)
NAME
----
zmq_term - terminates 0MQ context
zmq_term - terminate 0MQ context
SYNOPSIS
--------
'int zmq_term (void *context);'
*int zmq_term (void '*context');*
DESCRIPTION
-----------
Destroys 0MQ context. However, if there are still any sockets open within
the context, 'zmq_term' succeeds but shutdown of the context is delayed till
the last socket is closed.
The _zmq_term()_ function terminates the 0MQ context 'context'.
If there are still sockets open within 'context' at the time _zmq_term()_ is
called the call will succeed but the actual shutdown of 'context' will be
delayed until the last socket within it is closed.
RETURN VALUE
------------
Function returns zero is successful. Otherwise it returns -1 and sets errno to
one of the values below.
The _zmq_term()_ function shall return zero if successful. Otherwise it shall
return -1 and set 'errno' to one of the values defined below.
ERRORS
@ -30,20 +32,13 @@ ERRORS
No errors are defined.
EXAMPLE
-------
----
int rc = zmq_term (context);
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq[7]
linkzmq:zmq_init[3]
linkzmq:zmq_close[3]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.

56
doc/zmq_udp.txt
View File

@ -1,56 +0,0 @@
zmq_udp(7)
==========
NAME
----
zmq_udp - 0MQ reliable multicast transport using UDP
SYNOPSIS
--------
UDP transport is exactly the same as PGM transport except that PGM packets
are encapsulated in UDP packets. Rationale for this transport is that user-space
implementation of PGM requires right to create raw sockets (PGM is located
directly on top of IP layer in the networking stack), which is often not
available. UDP encapsulation solves this problem, however, it adds some overhead
related to creating and transferring UDP packet headers.
CONNECTION STRING
-----------------
Connection string for UDP transport is "udp://" followed by an IP address
of the NIC to use, semicolon, IP address of the multicast group, colon and
port number. IP address of the NIC can be either its numeric representation
or the name of the NIC as reported by operating system. IP address of the
multicast group should be specified in the numeric representation. For example:
----
udp://eth0;224.0.0.1:5555
udp://lo;230.0.0.0:6666
udp://192.168.0.111;224.0.0.1:5555
----
NOTE: NIC names are not standardised by POSIX. They tend to be rather
arbitrary and platform dependent. Say, "eth0" on Linux would correspond to "en0"
on OSX and "e1000g" on Solaris. On Windows platform, as there are no short NIC
names available, you have to use numeric IP addresses instead.
WIRE FORMAT
-----------
Same as with PGM transport except for UDP packet headers.
SEE ALSO
--------
linkzmq:zmq_pgm[7]
linkzmq:zmq_tcp[7]
linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>

23
doc/zmq_version.txt
View File

@ -4,19 +4,24 @@ zmq_version(3)
NAME
----
zmq_version - reports 0MQ version
zmq_version - report 0MQ library version
SYNOPSIS
--------
'void zmq_version (int *major, int *minor, int *patch);'
*void zmq_version (int '*major', int '*minor', int '*patch');*
DESCRIPTION
-----------
Returns current version of 0MQ. The functionality is useful for applications
linking with 0MQ dynamically to make sure the right version of 0MQ is installed
on the system.
The _zmq_version()_ function shall fill in the integer variables pointed to by
the 'major', 'minor' and 'patch' arguments with the major, minor and patchlevel
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
------------
@ -30,6 +35,7 @@ No errors are defined.
EXAMPLE
-------
.Printing out the version of the 0MQ library
----
int major, minor, patch;
zmq_version (&major, &minor, &patch);
@ -41,6 +47,7 @@ SEE ALSO
--------
linkzmq:zmq[7]
AUTHOR
------
Martin Sustrik <sustrik at 250bpm dot com>
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.