Documentation rewrite

doc/Makefile.am

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

doc/asciidoc.conf

+[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[]

doc/zmq_bind.txt

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

doc/zmq_close.txt

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

doc/zmq_connect.txt

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

doc/zmq_epgm.txt

+zmq_pgm.txt
\ No newline at end of file

doc/zmq_flush.txt

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

doc/zmq_forwarder.txt

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

doc/zmq_init.txt

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

doc/zmq_inproc.txt

@@ -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.
+
+
+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'.
 
-----
-    inproc://my_endpoint
-    inproc://feeds/opra/cboe
-    inproc://feeds.opra.nasdaq
-    inproc://!&W#($)_@_123*((^^^
-----
+
+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>.

doc/zmq_ipc.txt

@@ -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.)
 
-----
-    ipc:///tmp/my_ipc_endpoint
-    ipc:///tmp/prices.ipc
-----
+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.
+
+
+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>.

doc/zmq_java.txt

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

doc/zmq_msg_close.txt

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

doc/zmq_msg_copy.txt

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

doc/zmq_msg_data.txt

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

doc/zmq_msg_init.txt

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

doc/zmq_msg_init_data.txt

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

doc/zmq_msg_init_size.txt

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

doc/zmq_msg_move.txt

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

doc/zmq_msg_size.txt

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

doc/zmq_pgm.txt

@@ -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.
-
-
-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:
+PGM (Pragmatic General Multicast) is a protocol for reliable multicast
+transport of data over IP networks.
 
-----
-    pgm://eth0;224.0.0.1:5555
-    pgm://lo;230.0.0.0:6666
-    pgm://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.
+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).
 
+The 'pgm' and 'epgm' transports can only be used with the 'ZMQ_PUB' and
+'ZMQ_SUB' socket types.
 
-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.
+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].
 
-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.
+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.
 
-Each packet thus looks like this:
 
-----
-+-----------+------------+------------------+--------
-| IP header | PGM header | offset (16 bits) | data .....
-+-----------+------------+------------------+--------
-----
+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.
 
-Following example shows how messages are arranged in subsequent packets:
 
-----
-+---------------+--------+-----------+-----------------------------+
-| PGM/IPheaders | 0x0000 |   message 1   |   message 2 (part 1)    |
-+---------------+--------+-----------+-----------------------------+
+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:
 
-+---------------+--------+-----------------------------------------+
-| PGM/IPheaders | 0xFFFF |           message 2 (part 2)            |
-+---------------+--------+-----------------------------------------+
+* The interface name as defined by the operating system.
+* The primary IPv4 address assigned to the interface, in it's numeric
+  representation.
 
-+---------------+--------+--------------------------+-----------+
-| PGM/IPheaders | 0x0008 | message 2 (last 8 bytes) | message 3 |
-+---------------+--------+--------------------------+-----------+
+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 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].
+
+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.
+
+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
+----
+/* 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>.

doc/zmq_poll.txt

@@ -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.
+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.
+
 *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 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()_.
 
-'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.
+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>.

doc/zmq_queue.txt

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

doc/zmq_recv.txt

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

doc/zmq_send.txt

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

doc/zmq_socket.txt

@@ -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.
-
-*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.
-
-*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.
-
-*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.
-
-*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.
-
-*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.
-
-*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.
-
-*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.
+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.
+
+The following _messaging patterns_ are defined:
+
+
+Peer to peer pattern
+~~~~~~~~~~~~~~~~~~~~
+The simplest messaging pattern, used for communicating between two peers.
+
+Socket type:: 'ZMQ_P2P'
+Compatible peer sockets:: 'ZMQ_P2P'
+
+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.
+
+
+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.
+
+Socket type:: 'ZMQ_PUB'
+Compatible peer sockets:: 'ZMQ_SUB'
+
+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>.

doc/zmq_streamer.txt

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

doc/zmq_strerror.txt

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

doc/zmq_tcp.txt

@@ -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:
 
-WIRE FORMAT
------------
-A message consists of a message length followed by message data.
-Size of message data MUST correspond to the message length.
+* 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.
 
-For messages of 0 to 254 octets, the length is represented by single octet. 
+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'.
 
-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.
+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.
 
-The protocol can be defined by this BNF grammar:
+A 'peer address' may be specified by either of the following:
 
-----
-    frame   = length data
-    length  = OCTET | escape 8*OCTET
-    escape  = %xFF
-    data    = *OCTET
-----
+* The DNS name of the peer.
+* The IPv4 address of the peer, in it's numeric representation.
 
-Binary layout of a message (up to 254 bytes long):
 
-----
+WIRE FORMAT
+-----------
+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:
+
+....
+    frame           = (message-length message-data)
+    message-length  = OCTET / (escape 8OCTET)
+    escape          = %xFF
+    message-data    = *OCTET
+....
+
+
+For messages of 0 to 254 octets in length, the message length is represented by
+a single octet:
+
+....
 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>.

doc/zmq_term.txt

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

doc/zmq_udp.txt

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

doc/zmq_version.txt

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