Convert documentation to AsciiDoc

34 files changed, 2201 insertions, 0 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..07dfb02
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,41 @@
+MAN1 = zmq_forwarder.1 zmq_streamer.1 zmq_queue.1
+MAN3 = zmq_bind.3 zmq_close.3 zmq_connect.3 zmq_flush.3 zmq_init.3 \
+    zmq_msg_close.3 zmq_msg_copy.3 zmq_msg_data.3 zmq_msg_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
+MAN7 = zmq.7 zmq_tcp.7 zmq_udp.7 zmq_pgm.7 zmq_inproc.7 zmq_ipc.7 \
+    zmq_cpp.7 zmq_java.7 zmq_python.7
+MAN_DOC = $(MAN1) $(MAN3) $(MAN7)
+
+MAN_TXT = $(MAN1:%.1=%.txt)
+MAN_TXT += $(MAN3:%.3=%.txt)
+MAN_TXT += $(MAN7:%.7=%.txt)
+MAN_HTML = $(MAN_TXT:%.txt=%.html)
+
+if INSTALL_MAN
+dist_man_MANS = $(MAN_DOC)
+endif
+
+EXTRA_DIST = $(MAN_TXT)
+if BUILD_DOC
+EXTRA_DIST += $(MAN_HTML)
+endif
+
+MAINTAINERCLEANFILES = $(MAN_DOC) $(MAN_HTML)
+
+dist-hook : $(MAN_DOC) $(MAN_HTML)
+
+SUFFIXES=.html .txt .xml .1 .3 .7
+
+.txt.html:
+	asciidoc -d manpage -b xhtml11 -f asciidoc.conf $<
+.txt.xml:
+	asciidoc -d manpage -b docbook -f asciidoc.conf $<
+.xml.1:
+	xmlto man $<
+.xml.3:
+	xmlto man $<
+.xml.7:
+	xmlto man $<
+
diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf
new file mode 100644
index 0000000..d1dac78
--- /dev/null
+++ b/doc/asciidoc.conf
@@ -0,0 +1,34 @@
+[macros]
+(?su)[\\]?(?P<name>linkzmq):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
+
+ifdef::backend-docbook[]
+[linkzmq-inlinemacro]
+{0%{target}}
+{0#<citerefentry>}
+{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
+{0#</citerefentry>}
+endif::backend-docbook[]
+
+ifdef::backend-xhtml11[]
+[linkzmq-inlinemacro]
+<a href="{target}.html">{target}{0?({0})}</a>
+endif::backend-xhtml11[]
+
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">0MQ</refmiscinfo>
+<refmiscinfo class="version">2.0.0</refmiscinfo>
+<refmiscinfo class="manual">0MQ Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+  <refname>{manname}</refname>
+  <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
diff --git a/doc/zmq.txt b/doc/zmq.txt
new file mode 100644
index 0000000..0c911c3
--- /dev/null
+++ b/doc/zmq.txt
@@ -0,0 +1,175 @@
+zmq(7)
+======
+
+
+NAME
+----
+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.
+
+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.
+
+
+CONTEXT
+-------
+Each 0MQ socket lives within a specific context. Creating and destroying
+context is a counterpart of library initialisation/deinitialisation as used
+elsewhere. Ability to create multiple contexts saves the day when an application
+happens to link (indirectly and involuntarily) with several instances of 0MQ.
+
+Initialise 0MQ context::
+    linkzmq:zmq_init[3]
+
+Uninitialise 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.
+
+Initialise a message::
+    linkzmq:zmq_msg_init[3]
+    linkzmq:zmq_msg_size[3]
+    linkzmq:zmq_msg_data[3]
+
+Uninitialise a message::
+    linkzmq:zmq_msg_close[3]
+
+Access message content::
+    linkzmq:zmq_msg_data[3]
+    linkzmq:zmq_msg_size[3]
+
+Message manipulation::
+    linkzmq:zmq_msg_copy[3]
+    linkzmq:zmq_msg_move[3]
+
+
+SOCKETS
+-------
+0MQ sockets are very similar to POSIX sockets. See following manual pages to
+understand them in depth.
+
+Creating a socket::
+    linkzmq:zmq_socket[3]
+
+Closing a socket::
+    linkzmq:zmq_close[3]
+
+Setting socket options::
+    linkzmq:zmq_setsockopt[3]
+
+Establishing a message flow::
+    linkzmq:zmq_bind[3]
+    linkzmq:zmq_connect[3]
+
+Sending & 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.
+
+Poll for I/O events::
+    linkzmq:zmq_poll[3]
+
+
+ERROR HANDLING
+--------------
+0MQ defines couple of non-POSIX error codes. Use following functions to handle
+them neatly.
+
+Convert error code into human readable string::
+    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]
+
+
+DEVICES
+-------
+Aside of the messaging library (a.k.a. messaging kernel) 0MQ provides pre-built
+executables - devices - to serve as middle nodes in complex messaging
+topologies. For detailed description of individual devices check following
+manual pages:
+
+Forwarder device for PUB/SUB messaging::
+    linkzmq:zmq_forwarder[1]
+
+Streamer device for UPSTREAM/DOWNSTREAM messaging::
+    linkzmq:zmq_streamer[1]
+
+Forwarder device for REQ/REP messaging::
+    linkzmq:zmq_queue[1]
+
+
+LANGUAGES
+---------
+0MQ manual pages provide info on C API. To find out how the your
+favourite language API maps to C API and thus how to find relevant manual pages,
+see following articles:
+
+$$C++$$::
+    linkzmq:zmq_cpp[7]
+
+Java::
+    linkzmq:zmq_java[7]
+
+Python::
+    linkzmq:zmq_python[7]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_bind.txt b/doc/zmq_bind.txt
new file mode 100644
index 0000000..391238a
--- /dev/null
+++ b/doc/zmq_bind.txt
@@ -0,0 +1,67 @@
+zmq_bind(3)
+===========
+
+
+NAME
+----
+zmq_bind - binds the socket to the specified address
+
+
+SYNOPSIS
+--------
+'int zmq_bind (void *s, const char *addr);'
+
+
+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.
+
+Note that single socket can be bound (and connected) to
+arbitrary number of peers using different transport mechanisms.
+
+
+RETURN VALUE
+------------
+In case of success the function returns zero. Otherwise it returns -1 and
+sets 'errno' to the appropriate value.
+
+
+ERRORS
+------
+*EPROTONOSUPPORT*::
+unsupported protocol.
+*ENOCOMPATPROTO*::
+protocol is not compatible with the socket type.
+*EADDRINUSE*::
+the given address is already in use.
+*EADDRNOTAVAIL*::
+a nonexistent interface was requested or the requested address was not local.
+
+
+EXAMPLE
+-------
+----
+void *s = zmq_socket (context, ZMQ_PUB);
+assert (s);
+int rc = zmq_bind (s, "inproc://my_publisher");
+assert (rc == 0);
+rc = zmq_bind (s, "tcp://eth0:5555");
+assert (rc == 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_connect[3]
+linkzmq:zmq_socket[3]
+linkzmq:zmq[7]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_close.txt b/doc/zmq_close.txt
new file mode 100644
index 0000000..9964d36
--- /dev/null
+++ b/doc/zmq_close.txt
@@ -0,0 +1,52 @@
+zmq_close(3)
+============
+
+
+NAME
+----
+zmq_close - destroys 0MQ socket
+
+
+SYNOPSIS
+--------
+'int zmq_close (void *s);'
+
+
+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.
+
+
+RETURN VALUE
+------------
+In case of success the function returns zero. Otherwise it returns -1 and
+sets 'errno' to the appropriate value.
+
+
+ERRORS
+------
+No errors are defined.
+
+
+EXAMPLE
+-------
+----
+int rc = zmq_close (s);
+assert (rc == 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_socket[3]
+linkzmq:zmq_term[3]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_connect.txt b/doc/zmq_connect.txt
new file mode 100644
index 0000000..375873d
--- /dev/null
+++ b/doc/zmq_connect.txt
@@ -0,0 +1,63 @@
+zmq_connect(3)
+==============
+
+
+NAME
+----
+zmq_connect - connect the socket to the specified peer
+
+
+SYNOPSIS
+--------
+'int zmq_connect (void *s, const char *addr);'
+
+
+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.
+
+Note that single socket can be connected (and bound) to
+arbitrary number of peers using different transport mechanisms.
+
+
+RETURN VALUE
+------------
+In case of success the function returns zero. Otherwise it returns -1 and
+sets 'errno' to the appropriate value.
+
+
+ERRORS
+------
+*EPROTONOSUPPORT*::
+unsupported protocol.
+*ENOCOMPATPROTO*::
+protocol is not compatible with the socket type.
+
+
+EXAMPLE
+-------
+----
+void *s = zmq_socket (context, ZMQ_SUB);
+assert (s);
+int rc = zmq_connect (s, "inproc://my_publisher");
+assert (rc == 0);
+rc = zmq_connect (s, "tcp://server001:5555");
+assert (rc == 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_bind[3]
+linkzmq:zmq_socket[3]
+linkzmq:zmq[7]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_cpp.txt b/doc/zmq_cpp.txt
new file mode 100644
index 0000000..8b58f2d
--- /dev/null
+++ b/doc/zmq_cpp.txt
@@ -0,0 +1,89 @@
+zmq_cpp(7)
+==========
+
+
+NAME
+----
+zmq_cpp - interface between 0MQ and C++ applications
+
+
+SYNOPSIS
+--------
+This manual page explains how C++ API maps to underlying C API. To learn about
+individual functions and parameters check appropriate C API manual
+pages.
+
+For example, to understand 'zmq::socket_t::setsockopt' function check
+linkzmq:zmq_setsockopt[3].
+
+All 0MQ constants defined with C API are available with C++ API.
+
+
+zmq::context_t
+--------------
+This class encapsulates the functions dealing with initialisation and
+termination of 0MQ context. Constructor of the class invokes
+linkzmq:zmq_init[3] while destructor calls linkzmq:zmq_term[3].
+
+
+zmq::socket_t
+-------------
+This class encapsulates all the functions to deal with 0MQ sockets. Constructor
+calls linkzmq:zmq_socket[3], destructor calls linkzmq:zmq_close[3].  Other
+functions of the class are mapped to C functions with corresponding names.
+'zmq::socket_t::bind' calls linkzmq:zmq_bind[3] etc.
+
+
+zmq::message_t
+--------------
+This class encapsulates 'zmq_msg_t' structure and all the C functions that deal
+with 0MQ messages.  Constructors of the class invoke corresponding
+initialisation functions linkzmq:zmq_msg_init[3], linkzmq:zmq_msg_init_size[3]
+and linkzmq:zmq_msg_init_data[3], while destructor invokes
+linkzmq:zmq_msg_close[3] function.
+
+Remaining functions are mapped to C functions with corresponding names.
+For instance, 'zmq::message_t::copy' is mapped to linkzmq:zmq_msg_copy[3]
+etc.
+
+C++ provides an additional function not available with C API.
+'zmq::message_t::rebuild' is equivalent to calling linkzmq:zmq_close[3]
+followed by linkzmq:zmq_msg_init[3], linkzmq:zmq_msg_init_size[3] or
+linkzmq:zmq_msg_init_data[3].  It provides a way to reuse existing
+'zmq::message_t' instances to store different message content.
+
+
+zmq::error_t
+------------
+All the errors reported using 'errno' mechanism in C API are automatically
+converted to exceptions in C++ API.  'zmq::error_t' is derived from
+'std::exception' and uses linkzmq:zmq_strerror[3] function to convert the error
+code to human-readable string.
+
+
+zmq::poll
+---------
+'zmq::poll' function is a namespaced equivalent of raw C linkzmq:zmq_poll[3]
+function.
+
+
+EXAMPLE
+-------
+----
+zmq::context_t ctx (1, 1);
+zmq::socket_t s (ctx, ZMQ_PUB);
+s.connect ("tcp://192.168.0.115:5555");
+zmq::message_t msg (100);
+memset (msg.data (), 0, 100);
+s.send (msg);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq[7]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_flush.txt b/doc/zmq_flush.txt
new file mode 100644
index 0000000..3a2cd37
--- /dev/null
+++ b/doc/zmq_flush.txt
@@ -0,0 +1,59 @@
+zmq_flush(3)
+============
+
+
+NAME
+----
+zmq_flush - flushes pre-sent messages to the socket
+
+
+SYNOPSIS
+--------
+'int zmq_flush (void *s);'
+
+
+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.
+
+
+RETURN VALUE
+------------
+In case of success the function returns zero. Otherwise it returns -1 and
+sets 'errno' to the appropriate value.
+
+
+ERRORS
+------
+*ENOTSUP*::
+function isn't supported by particular 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);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_send[3]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_forwarder.txt b/doc/zmq_forwarder.txt
new file mode 100644
index 0000000..17d938b
--- /dev/null
+++ b/doc/zmq_forwarder.txt
@@ -0,0 +1,32 @@
+zmq_forwarder(1)
+================
+
+
+NAME
+----
+zmq_forwarder - forwards the stream of PUB/SUB messages
+
+
+SYNOPSIS
+--------
+*
+
+
+DESCRIPTION
+-----------
+*
+
+
+OPTIONS
+-------
+*
+
+
+SEE ALSO
+--------
+*
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_init.txt b/doc/zmq_init.txt
new file mode 100644
index 0000000..6683d27
--- /dev/null
+++ b/doc/zmq_init.txt
@@ -0,0 +1,61 @@
+zmq_init(3)
+===========
+
+
+NAME
+----
+zmq_init - initialises 0MQ context
+
+
+SYNOPSIS
+--------
+'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 '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.
+
+
+RETURN VALUE
+------------
+Function returns context handle is successful. Otherwise it returns NULL and
+sets errno to one of the values 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);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_term[3]
+linkzmq:zmq_socket[3]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_inproc.txt b/doc/zmq_inproc.txt
new file mode 100644
index 0000000..7861201
--- /dev/null
+++ b/doc/zmq_inproc.txt
@@ -0,0 +1,50 @@
+zmq_inproc(7)
+=============
+
+
+NAME
+----
+zmq_inproc - 0MQ transport to pass messages between threads
+
+
+SYNOPSIS
+--------
+In-process transport is optimised for passing messages between threads in the
+same process.
+
+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.
+
+
+CONNECTION STRING
+-----------------
+Connection string for inproc transport is "inproc://" followed by an arbitrary
+string. There are no restrictions on the string format:
+
+----
+    inproc://my_endpoint
+    inproc://feeds/opra/cboe
+    inproc://feeds.opra.nasdaq
+    inproc://!&W#($)_@_123*((^^^
+----
+
+
+WIRE FORMAT
+-----------
+In-process transport transfers messages via memory thus there is no need for a
+wire format specification.
+
+
+SEE ALSO
+--------
+linkzmq:zmq_ipc[7]
+linkzmq:zmq_tcp[7]
+linkzmq:zmq_udp[7]
+linkzmq:zmq_pgm[7]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_ipc.txt b/doc/zmq_ipc.txt
new file mode 100644
index 0000000..c3980f6
--- /dev/null
+++ b/doc/zmq_ipc.txt
@@ -0,0 +1,44 @@
+zmq_ipc(7)
+==========
+
+
+NAME
+----
+zmq_ipc - 0MQ transport to pass messages between processes
+
+
+SYNOPSIS
+--------
+Inter-process transport is optimised for passing messages between processes on
+the same physical machine.
+
+
+CONNECTION STRING
+-----------------
+Connection string for inproc 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
+----
+
+
+WIRE FORMAT
+-----------
+IPC transport doesn't transfer messages across the network thus there is no need
+for a wire format specification.
+
+
+SEE ALSO
+--------
+linkzmq:zmq_inproc[7]
+linkzmq:zmq_tcp[7]
+linkzmq:zmq_udp[7]
+linkzmq:zmq_pgm[7]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_java.txt b/doc/zmq_java.txt
new file mode 100644
index 0000000..c49e589
--- /dev/null
+++ b/doc/zmq_java.txt
@@ -0,0 +1,27 @@
+zmq_java(7)
+===========
+
+
+NAME
+----
+zmq_java - interface between 0MQ and Java applications
+
+
+SYNOPSIS
+--------
+*
+
+
+DESCRIPTION
+-----------
+*
+
+
+SEE ALSO
+--------
+*
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_msg_close.txt b/doc/zmq_msg_close.txt
new file mode 100644
index 0000000..1b043a2
--- /dev/null
+++ b/doc/zmq_msg_close.txt
@@ -0,0 +1,53 @@
+zmq_msg_close(3)
+================
+
+
+NAME
+----
+zmq_msg_close - destroys 0MQ message
+
+
+SYNOPSIS
+--------
+'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.
+
+
+RETURN VALUE
+------------
+In case of success the function returns zero. Otherwise it returns -1 and sets
+'errno' to the appropriate value.
+
+
+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]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_msg_copy.txt b/doc/zmq_msg_copy.txt
new file mode 100644
index 0000000..b31897a
--- /dev/null
+++ b/doc/zmq_msg_copy.txt
@@ -0,0 +1,60 @@
+zmq_msg_copy(3)
+===============
+
+
+NAME
+----
+zmq_msg_copy - copies content of a message to another message
+
+
+SYNOPSIS
+--------
+'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.
+
+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'.
+
+
+RETURN VALUE
+------------
+In case of success the function returns zero. Otherwise it returns -1 and
+sets 'errno' to the appropriate value.
+
+
+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]
+linkzmq:zmq_msg_init[3]
+linkzmq:zmq_msg_init_size[3]
+linkzmq:zmq_msg_init_data[3]
+linkzmq:zmq_msg_close[3]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_msg_data.txt b/doc/zmq_msg_data.txt
new file mode 100644
index 0000000..45a99b1
--- /dev/null
+++ b/doc/zmq_msg_data.txt
@@ -0,0 +1,50 @@
+zmq_msg_data(3)
+===============
+
+
+NAME
+----
+zmq_msg_data - retrieves pointer to the message content
+
+
+SYNOPSIS
+--------
+'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.
+
+
+RETURN VALUE
+------------
+Pointer to the message data.
+
+
+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_init[3]
+linkzmq:zmq_msg_init_size[3]
+linkzmq:zmq_msg_init_data[3]
+linkzmq:zmq_msg_close[3]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_msg_init.txt b/doc/zmq_msg_init.txt
new file mode 100644
index 0000000..b080c18
--- /dev/null
+++ b/doc/zmq_msg_init.txt
@@ -0,0 +1,54 @@
+zmq_msg_init(3)
+===============
+
+
+NAME
+----
+zmq_msg_init - initialises empty 0MQ message
+
+
+SYNOPSIS
+--------
+'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.
+
+
+RETURN VALUE
+------------
+In case of success the function returns zero. Otherwise it returns -1 and
+sets 'errno' to the appropriate value.
+
+
+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);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_msg_close[3]
+linkzmq:zmq_msg_init_size[3]
+linkzmq:zmq_msg_init_data[3]
+linkzmq:zmq_msg_data[3]
+linkzmq:zmq_msg_size[3]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_msg_init_data.txt b/doc/zmq_msg_init_data.txt
new file mode 100644
index 0000000..1ae6ce2
--- /dev/null
+++ b/doc/zmq_msg_init_data.txt
@@ -0,0 +1,67 @@
+zmq_msg_init_data(3)
+====================
+
+
+NAME
+----
+zmq_msg_init_data - initialises 0MQ message from the given data
+
+
+SYNOPSIS
+--------
+'typedef void (zmq_free_fn) (void *data, void *hint);'
+'int zmq_msg_init_data (zmq_msg_t *msg, void *data, size_t size, zmq_free_fn *ffn, void *hint);'
+
+
+DESCRIPTION
+-----------
+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.
+
+
+RETURN VALUE
+------------
+In case of success the function returns zero. Otherwise it returns -1 and
+sets 'errno' to the appropriate value.
+
+
+ERRORS
+------
+No errors are defined.
+
+
+EXAMPLE
+-------
+----
+void my_free (void *data, void *hint) {free (data);}
+
+        ...
+
+void *data = malloc (6);
+assert (data);
+memcpy (data, "ABCDEF", 6);
+zmq_msg_t msg;
+rc = zmq_msg_init_data (&msg, data, 6, my_free, NULL);
+assert (rc == 0);
+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_data[3]
+linkzmq:zmq_msg_size[3]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_msg_init_size.txt b/doc/zmq_msg_init_size.txt
new file mode 100644
index 0000000..9f09ade
--- /dev/null
+++ b/doc/zmq_msg_init_size.txt
@@ -0,0 +1,61 @@
+zmq_msg_init_size(3)
+====================
+
+
+NAME
+----
+zmq_msg_init_size - initialises 0MQ message of a specified size
+
+
+SYNOPSIS
+--------
+'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.
+
+
+RETURN VALUE
+------------
+In case of success the function returns zero. Otherwise it returns -1 and
+sets 'errno' to the appropriate value.
+
+
+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);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_msg_close[3]
+linkzmq:zmq_msg_init[3]
+linkzmq:zmq_msg_init_data[3]
+linkzmq:zmq_msg_data[3]
+linkzmq:zmq_msg_size[3]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_msg_move.txt b/doc/zmq_msg_move.txt
new file mode 100644
index 0000000..d8ce667
--- /dev/null
+++ b/doc/zmq_msg_move.txt
@@ -0,0 +1,55 @@
+zmq_msg_move(3)
+===============
+
+
+NAME
+----
+zmq_msg_move - moves content of a message to another message
+
+
+SYNOPSIS
+--------
+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.
+
+
+RETURN VALUE
+------------
+In case of success the function returns zero. Otherwise it returns -1 and
+sets 'errno' to the appropriate value.
+
+
+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]
+linkzmq:zmq_msg_init[3]
+linkzmq:zmq_msg_init_size[3]
+linkzmq:zmq_msg_init_data[3]
+linkzmq:zmq_msg_close[3]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_msg_size.txt b/doc/zmq_msg_size.txt
new file mode 100644
index 0000000..6d24243
--- /dev/null
+++ b/doc/zmq_msg_size.txt
@@ -0,0 +1,53 @@
+zmq_msg_size(3)
+===============
+
+
+NAME
+----
+zmq_msg_size - retrieves size of the message content
+
+
+SYNOPSIS
+--------
+'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.
+
+
+RETURN VALUE
+------------
+Size of the message data (bytes).
+
+
+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_init[3]
+linkzmq:zmq_msg_init_size[3]
+linkzmq:zmq_msg_init_data[3]
+linkzmq:zmq_msg_close[3]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_pgm.txt b/doc/zmq_pgm.txt
new file mode 100644
index 0000000..d0e2622
--- /dev/null
+++ b/doc/zmq_pgm.txt
@@ -0,0 +1,106 @@
+zmq_pgm(7)
+==========
+
+
+NAME
+----
+zmq_pgm - 0MQ PGM reliable multicast transport
+
+
+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://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.
+
+
+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.
+
+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.
+
+Each packet thus looks like this:
+
+----
++-----------+------------+------------------+--------
+| 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 |
++---------------+--------+--------------------------+-----------+
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_udp[7]
+linkzmq:zmq_tcp[7]
+linkzmq:zmq_ipc[7]
+linkzmq:zmq_inproc[7]
+linkzmq:zmq_setsockopt[3]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_poll.txt b/doc/zmq_poll.txt
new file mode 100644
index 0000000..8e386bc
--- /dev/null
+++ b/doc/zmq_poll.txt
@@ -0,0 +1,85 @@
+zmq_poll(3)
+===========
+
+
+NAME
+----
+zmq_poll - polls for events on a set of 0MQ and POSIX sockets
+
+
+SYNOPSIS
+--------
+'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:
+
+----
+typedef struct
+{
+    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.
+
+*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.
+
+'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.
+
+
+RETURN VALUE
+------------
+Function returns number of items signaled or -1 in the case of error.
+
+
+ERRORS
+------
+*EFAULT*::
+there's a 0MQ socket in the pollset belonging to a different application thread.
+*ENOTSUP*::
+0MQ context was initialised without ZMQ_POLL flag. I/O multiplexing is disabled.
+
+
+EXAMPLE
+-------
+----
+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);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_socket[3]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_python.txt b/doc/zmq_python.txt
new file mode 100644
index 0000000..7ad19a3
--- /dev/null
+++ b/doc/zmq_python.txt
@@ -0,0 +1,27 @@
+zmq_python(7)
+=============
+
+
+NAME
+----
+zmq_python - interface between 0MQ and Python applications
+
+
+SYNOPSIS
+--------
+*
+
+
+DESCRIPTION
+-----------
+*
+
+
+SEE ALSO
+--------
+*
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_queue.txt b/doc/zmq_queue.txt
new file mode 100644
index 0000000..7f31ff9
--- /dev/null
+++ b/doc/zmq_queue.txt
@@ -0,0 +1,32 @@
+zmq_queue(1)
+============
+
+
+NAME
+----
+zmq_queue - forwards REQ/REP messages
+
+
+SYNOPSIS
+--------
+*
+
+
+DESCRIPTION
+-----------
+*
+
+
+OPTIONS
+-------
+*
+
+
+SEE ALSO
+--------
+*
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_recv.txt b/doc/zmq_recv.txt
new file mode 100644
index 0000000..0365d23
--- /dev/null
+++ b/doc/zmq_recv.txt
@@ -0,0 +1,66 @@
+zmq_recv(3)
+===========
+
+
+NAME
+----
+zmq_recv - retrieves a message from the socket
+
+
+SYNOPSIS
+--------
+'int zmq_recv (void *s, 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.
+
+*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.
+
+
+RETURN VALUE
+------------
+In case of success the function returns zero. Otherwise it returns -1 and
+sets 'errno' to the appropriate value.
+
+
+ERRORS
+------
+*EAGAIN*::
+it's a non-blocking receive and there's no message available at the moment.
+*ENOTSUP*::
+function isn't supported by particular 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).
+
+
+EXAMPLE
+-------
+----
+zmq_msg_t msg;
+int rc = zmq_msg_init (&msg);
+assert (rc == 0);
+rc = zmq_recv (s, &msg, 0);
+assert (rc == 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_send[3]
+linkzmq:zmq_msg_init[3]
+linkzmq:zmq_msg_data[3]
+linkzmq:zmq_msg_size[3]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_send.txt b/doc/zmq_send.txt
new file mode 100644
index 0000000..f6a35c5
--- /dev/null
+++ b/doc/zmq_send.txt
@@ -0,0 +1,77 @@
+zmq_send(3)
+===========
+
+
+NAME
+----
+zmq_send - sends a message
+
+
+SYNOPSIS
+--------
+'int zmq_send (void *s, zmq_msg_t *msg, int flags);'
+
+
+DESCRIPTION
+-----------
+Send the message 'msg' to the socket 's'.  'flags' argument can be combination
+the flags described 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.
+
+*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.
+
+
+RETURN VALUE
+------------
+In case of success the function returns zero. Otherwise it returns -1 and
+sets 'errno' to the appropriate value.
+
+
+ERRORS
+------
+*EAGAIN*::
+it's a non-blocking send and message cannot be sent at the moment.
+*ENOTSUP*::
+function isn't supported by particular 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).
+
+
+EXAMPLE
+-------
+----
+zmq_msg_t msg;
+int rc = zmq_msg_init_size (&msg, 6);
+assert (rc == 0);
+memset (zmq_msg_data (&msg), 'A', 6);
+rc = zmq_send (s, &msg, 0);
+assert (rc == 0);
+----
+
+
+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]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt
new file mode 100644
index 0000000..549a2de
--- /dev/null
+++ b/doc/zmq_setsockopt.txt
@@ -0,0 +1,155 @@
+zmq_setsockopt(3)
+=================
+
+
+NAME
+----
+
+zmq_setsockopt - sets a specified option on a 0MQ socket
+
+
+SYNOPSIS
+--------
+'int zmq_setsockopt (void *s, int option, const void *optval, size_t optvallen);'
+
+
+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.
+
+*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
+
+*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_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
+
+*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.
++
+Type: string  Unit: N/A  Default: NULL
+
+*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: string  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: string  Unit: N/A  Default: N/A
+
+*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
+
+*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_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
+
+*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
+
+
+RETURN VALUE
+------------
+In case of success the function returns zero. Otherwise it returns -1 and
+sets 'errno' to the appropriate value.
+
+
+ERRORS
+------
+*EINVAL*::
+unknown option, a value with incorrect length or invalid value.
+
+
+EXAMPLE
+-------
+----
+int rc = zmq_setsockopt (s, ZMQ_SUBSCRIBE, "", 0);
+assert (rc == 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_socket[3]
+linkzmq:zmq[7]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt
new file mode 100644
index 0000000..6cfc726
--- /dev/null
+++ b/doc/zmq_socket.txt
@@ -0,0 +1,126 @@
+zmq_socket(3)
+=============
+
+
+NAME
+----
+zmq_socket - creates 0MQ socket
+
+
+SYNOPSIS
+--------
+'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 postfix 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.
+
+
+RETURN VALUE
+------------
+Function returns socket handle is successful. Otherwise it returns NULL and
+sets errno to one of the values below.
+
+
+ERRORS
+------
+*EINVAL*::
+    invalid socket type.
+
+*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);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_init[3]
+linkzmq:zmq_setsockopt[3]
+linkzmq:zmq_bind[3]
+linkzmq:zmq_connect[3]
+linkzmq:zmq_send[3]
+linkzmq:zmq_flush[3]
+linkzmq:zmq_recv[3]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_streamer.txt b/doc/zmq_streamer.txt
new file mode 100644
index 0000000..d0df514
--- /dev/null
+++ b/doc/zmq_streamer.txt
@@ -0,0 +1,32 @@
+zmq_streamer(1)
+===============
+
+
+NAME
+----
+zmq_streamer - forwards the stream of UPSTREAM/DOWNSTREAM messages
+
+
+SYNOPSIS
+--------
+*
+
+
+DESCRIPTION
+-----------
+*
+
+
+OPTIONS
+-------
+*
+
+
+SEE ALSO
+--------
+*
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_strerror.txt b/doc/zmq_strerror.txt
new file mode 100644
index 0000000..2bdf762
--- /dev/null
+++ b/doc/zmq_strerror.txt
@@ -0,0 +1,50 @@
+zmq_strerror(3)
+===============
+
+
+NAME
+----
+zmq_strerror - returns string describing the error number
+
+
+SYNOPSIS
+--------
+'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.
+
+
+RETURN VALUE
+------------
+Returns string describing the error number.
+
+
+ERRORS
+------
+No errors are defined.
+
+
+EXAMPLE
+-------
+----
+void *ctx = zmq_init (1, 1, 0);
+if (!ctx) {
+    printf ("error occured during zmq_init: %s\\n", zmq_strerror (errno));
+    abort ();
+}
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq[7]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_tcp.txt b/doc/zmq_tcp.txt
new file mode 100644
index 0000000..98f1219
--- /dev/null
+++ b/doc/zmq_tcp.txt
@@ -0,0 +1,93 @@
+zmq_tcp(7)
+==========
+
+
+NAME
+----
+zmq_tcp - 0MQ unicast TCP transport over the network
+
+
+SYNOPSIS
+--------
+TCP is an ubiquitous unicast transport. When connecting distributed
+applications, you will mostly use TCP transport.
+
+
+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):
+
+----
+    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.
+
+
+WIRE FORMAT
+-----------
+A message consists of a message length followed by message data.
+Size of message data MUST correspond to the message length.
+
+For messages of 0 to 254 octets, the length is represented by single 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:
+
+----
+    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
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+| Message size  |                Message body               ... |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+| Message body ...
++-+-+-+-+-+-+- ...
+----
+
+Binary layout of a larger message:
+
+----
+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
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|     0xff      |                Message size               ... |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                        Message size                       ... |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|  Message size |                Message body               ... |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|  Message body ...
++-+-+-+-+-+-+-+ ...
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_udp[7]
+linkzmq:zmq_pgm[7]
+linkzmq:zmq_ipc[7]
+linkzmq:zmq_inproc[7]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
+
diff --git a/doc/zmq_term.txt b/doc/zmq_term.txt
new file mode 100644
index 0000000..451c1ac
--- /dev/null
+++ b/doc/zmq_term.txt
@@ -0,0 +1,49 @@
+zmq_term(3)
+===========
+
+
+NAME
+----
+zmq_term - terminates 0MQ context
+
+
+SYNOPSIS
+--------
+'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.
+
+
+RETURN VALUE
+------------
+Function returns zero is successful. Otherwise it returns -1 and sets errno to
+one of the values below.
+
+
+ERRORS
+------
+No errors are defined.
+
+
+EXAMPLE
+-------
+----
+int rc = zmq_term (context);
+assert (rc == 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_init[3]
+linkzmq:zmq_close[3]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_udp.txt b/doc/zmq_udp.txt
new file mode 100644
index 0000000..ecc6bdf
--- /dev/null
+++ b/doc/zmq_udp.txt
@@ -0,0 +1,56 @@
+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>
+