Merge branch 'master' of git@github.com:sustrik/zeromq2

20 files changed, 918 insertions, 0 deletions

diff --git a/man/man3/zmq_bind.3 b/man/man3/zmq_bind.3
new file mode 100644
index 0000000..069b966
--- /dev/null
+++ b/man/man3/zmq_bind.3
@@ -0,0 +1,48 @@
+.TH zmq_bind 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_bind \- binds the socket to the specified address
+.SH SYNOPSIS
+.B int zmq_bind (void *s, const char *addr);
+.SH DESCRIPTION
+The function binds socket
+.IR s to a particular transport. Actual semantics of the 
+command depend on the underlying transport mechanism, however, in cases where
+peers connect in an asymetric manner,
+.IR zmq_bind
+should be called first,
+.IR zmq_connect
+afterwards. For actual formats of
+.IR addr
+parameter for different types of transport have a look at
+.IR zmq(7) .
+Note that single socket can be bound (and connected) to
+arbitrary number of peers using different transport mechanisms.
+.SH RETURN VALUE
+In case of success the function returns zero. Otherwise it returns -1 and
+sets
+.IR errno
+to the appropriate value.
+.SH ERRORS
+.IP "\fBEPROTONOSUPPORT\fP"
+unsupported protocol.
+.IP "\fBENOCOMPATPROTO\fP"
+protocol is not compatible with the socket type.
+.IP "\fBEADDRINUSE\fP"
+the given address is already in use.
+.IP "\fBEADDRNOTAVAIL\fP"
+a nonexistent interface was requested or the requested address was not local.
+.SH EXAMPLE
+.nf
+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);
+.fi
+.SH SEE ALSO
+.BR zmq_connect (3)
+.BR zmq_socket (3)
+.BR zmq (7)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_close.3 b/man/man3/zmq_close.3
new file mode 100644
index 0000000..cc49635
--- /dev/null
+++ b/man/man3/zmq_close.3
@@ -0,0 +1,27 @@
+.TH zmq_close 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_close \- destroys 0MQ socket
+.SH SYNOPSIS
+.B int zmq_close (void *s);
+.SH DESCRIPTION
+Destroys 0MQ socket (one created using
+.IR zmq_socket
+function). All sockets have to be properly closed before the application
+terminates, otherwise memory leaks will occur.
+.SH RETURN VALUE
+In case of success the function returns zero. Otherwise it returns -1 and
+sets
+.IR errno
+to the appropriate value.
+.SH ERRORS
+No errors are defined.
+.SH EXAMPLE
+.nf
+int rc = zmq_close (s);
+assert (rc == 0);
+.fi
+.SH SEE ALSO
+.BR zmq_socket (3)
+.BR zmq_term (3)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_connect.3 b/man/man3/zmq_connect.3
new file mode 100644
index 0000000..8f09e20
--- /dev/null
+++ b/man/man3/zmq_connect.3
@@ -0,0 +1,47 @@
+.TH zmq_connect 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_connect \- connect the socket to the specified peer
+.SH SYNOPSIS
+.B int zmq_connect (void *s, const char *addr);
+.SH DESCRIPTION
+The function connect socket
+.IR s to the peer identified by
+.IR addr .
+Actual semantics of the  command depend on the underlying transport mechanism,
+however, in cases where peers connect in an asymetric manner,
+.IR zmq_bind
+should be called first,
+.IR zmq_connect
+afterwards. For actual formats of
+.IR addr
+parameter for different types of transport have a look at
+.IR zmq(7) .
+Note that single socket can be connected (and bound) to
+arbitrary number of peers using different transport mechanisms.
+.SH RETURN VALUE
+In case of success the function returns zero. Otherwise it returns -1 and
+sets
+.IR errno
+to the appropriate value.
+.SH ERRORS
+.IP "\fBEPROTONOSUPPORT\fP"
+unsupported protocol.
+.IP "\fBENOCOMPATPROTO\fP"
+protocol is not compatible with the socket type.
+.IP "\fBECONNREFUSED\fP"
+no-one listening on the remote address.
+.SH EXAMPLE
+.nf
+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);
+.fi
+.SH SEE ALSO
+.BR zmq_bind (3)
+.BR zmq_socket (3)
+.BR zmq (7)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_flush.3 b/man/man3/zmq_flush.3
new file mode 100644
index 0000000..194cf6c
--- /dev/null
+++ b/man/man3/zmq_flush.3
@@ -0,0 +1,37 @@
+.TH zmq_flush 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_flush \- flushes pre-sent messages to the socket
+.SH SYNOPSIS
+.B int zmq_flush (void *s);
+.SH 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
+.IR zmq_send
+without ZMQ_NOFLUSH flag automatically flushes all previously pre-sent messages.
+.SH RETURN VALUE
+In case of success the function returns zero. Otherwise it returns -1 and
+sets
+.IR errno
+to the appropriate value.
+.SH ERRORS
+.IP "\fBENOTSUP\fP"
+function isn't supported by particular socket type.
+.IP "\fBEFSM\fP"
+function cannot be called at the moment, because socket is not in the
+approprite state.
+.SH EXAMPLE
+.nf
+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);
+.fi
+.SH SEE ALSO
+.BR zmq_send (3)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_init.3 b/man/man3/zmq_init.3
new file mode 100644
index 0000000..317dbba
--- /dev/null
+++ b/man/man3/zmq_init.3
@@ -0,0 +1,39 @@
+.TH zmq_init 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_init \- initialises 0MQ context
+.SH SYNOPSIS
+.B void *zmq_init (int app_threads, int io_threads, int flags);
+.SH DESCRIPTION
+Initialises 0MQ context. 
+.IR 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.
+.IR 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.
+'flags' argument is a combination of the flags defined below:
+
+.IP "\fBZMQ_POLL\fP"
+flag specifying that the sockets within this context should be pollable (see
+.IR zmq_poll
+). Pollable sockets may add a little latency to the message transfer when
+compared to non-pollable sockets.
+
+.SH RETURN VALUE
+Function returns context handle is successful. Otherwise it returns NULL and
+sets errno to one of the values below.
+.SH ERRORS
+.IP "\fBEINVAL\fP"
+there's less than one application thread allocated, or number of I/O threads
+is negative.
+.SH EXAMPLE
+.nf
+void *ctx = zmq_init (1, 1, ZMQ_POLL);
+assert (ctx);
+.fi
+.SH SEE ALSO
+.BR zmq_term (3)
+.BR zmq_socket (3)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_msg_close.3 b/man/man3/zmq_msg_close.3
new file mode 100644
index 0000000..6613360
--- /dev/null
+++ b/man/man3/zmq_msg_close.3
@@ -0,0 +1,32 @@
+.TH zmq_msg_close 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_msg_close \- destroys 0MQ message
+.SH SYNOPSIS
+.B int zmq_msg_close (zmq_msg_t *msg);
+.SH DESCRIPTION
+Deallocates message
+.IR msg
+including any associated buffers (unless the buffer is
+shared with another message). Not calling this function can result in
+memory leaks.
+.SH RETURN VALUE
+In case of success the function returns zero. Otherwise it returns -1 and
+sets
+.IR errno
+to the appropriate value.
+.SH ERRORS
+No errors are defined.
+.SH EXAMPLE
+.nf
+zmq_msg_t msg;
+rc = zmq_msg_init_size (&msg, 1000000);
+assert (rc = 0);
+rc = zmq_msg_close (&msg);
+assert (rc = 0);
+.fi
+.SH SEE ALSO
+.BR zmq_msg_init (3)
+.BR zmq_msg_init_size (3)
+.BR zmq_msg_init_data (3)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_msg_copy.3 b/man/man3/zmq_msg_copy.3
new file mode 100644
index 0000000..2f70400
--- /dev/null
+++ b/man/man3/zmq_msg_copy.3
@@ -0,0 +1,43 @@
+.TH zmq_msg_copy 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_msg_copy \- copies content of a message to another message
+.SH SYNOPSIS
+.B int zmq_msg_copy (zmq_msg_t *dest, zmq_msg_t *src);
+.SH DESCRIPTION
+Copy the
+.IR src
+message to
+.IR dest .
+The original content of
+.IR 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
+.IR zmq_msg_size
+and copy the data using
+.IR memcpy .
+.SH RETURN VALUE
+In case of success the function returns zero. Otherwise it returns -1 and
+sets
+.IR errno
+to the appropriate value.
+.SH ERRORS
+No errors are defined.
+.SH EXAMPLE
+.nf
+zmq_msg_t dest;
+rc = zmq_msg_init (&dest);
+assert (rc == 0);
+rc = zmq_msg_copy (&dest, &src);
+assert (rc == 0);
+.fi
+.SH SEE ALSO
+.BR zmq_msg_move (3)
+.BR zmq_msg_init (3)
+.BR zmq_msg_init_size (3)
+.BR zmq_msg_init_data (3)
+.BR zmq_msg_close (3)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_msg_data.3 b/man/man3/zmq_msg_data.3
new file mode 100644
index 0000000..9876378
--- /dev/null
+++ b/man/man3/zmq_msg_data.3
@@ -0,0 +1,27 @@
+.TH zmq_msg_data 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_msg_data \- retrieves pointer to the message content
+.SH SYNOPSIS
+.B void *zmq_msg_data (zmq_msg_t *msg);
+.SH DESCRIPTION
+Returns pointer to message data. Always use this function to access the data,
+never use
+.IR zmq_msg_t
+members directly.
+.SH RETURN VALUE
+Pointer to the message data.
+.SH ERRORS
+No errors are defined.
+.SH EXAMPLE
+.nf
+zmq_msg_t msg;
+rc = zmq_msg_init_size (&msg, 100);
+memset (zmq_msg_data (&msg), 0, 100);
+.fi
+.SH SEE ALSO
+.BR zmq_msg_init (3)
+.BR zmq_msg_init_size (3)
+.BR zmq_msg_init_data (3)
+.BR zmq_msg_close (3)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_msg_init.3 b/man/man3/zmq_msg_init.3
new file mode 100644
index 0000000..a531fc1
--- /dev/null
+++ b/man/man3/zmq_msg_init.3
@@ -0,0 +1,33 @@
+.TH zmq_msg_init 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_msg_init \- initialises empty 0MQ message
+.SH SYNOPSIS
+.B int zmq_msg_init (zmq_msg_t *msg);
+.SH DESCRIPTION
+Initialises 0MQ message zero bytes long. The function is most useful
+to initialise a
+.IR zmq_msg_t
+structure before receiving a message.
+.SH RETURN VALUE
+In case of success the function returns zero. Otherwise it returns -1 and
+sets
+.IR errno
+to the appropriate value.
+.SH ERRORS
+No errors are defined.
+.SH EXAMPLE
+.nf
+zmq_msg_t msg;
+rc = zmq_msg_init (&msg);
+assert (rc == 0);
+rc = zmq_recv (s, &msg, 0);
+assert (rc == 0);
+.fi
+.SH SEE ALSO
+.BR zmq_msg_close (3)
+.BR zmq_msg_init_size (3)
+.BR zmq_msg_init_data (3)
+.BR zmq_msg_data (3)
+.BR zmq_msg_size (3)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_msg_init_data.3 b/man/man3/zmq_msg_init_data.3
new file mode 100644
index 0000000..a0b14c8
--- /dev/null
+++ b/man/man3/zmq_msg_init_data.3
@@ -0,0 +1,48 @@
+.TH zmq_msg_init_data 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_msg_init \- initialises 0MQ message from the given data
+.SH SYNOPSIS
+.nf
+.B typedef void (zmq_free_fn) (void *data);
+.B int zmq_msg_init_data (zmq_msg_t *msg, void *data, size_t size, zmq_free_fn *ffn);
+.fi
+.SH DESCRIPTION
+Initialise a message from a supplied buffer. Message isn't copied,
+instead 0MQ infrastructure takes ownership of the buffer located at address
+.IR data ,
+.IR size
+bytes long. 
+Deallocation function (
+.IR ffn
+) will be called once the data are not needed anymore. Note that deallocation
+function prototype is designed so that it complies with standard C
+.IR free
+function. When using a static constant buffer,
+.IR ffn
+may be NULL to prevent subsequent deallocation.
+.SH RETURN VALUE
+In case of success the function returns zero. Otherwise it returns -1 and
+sets
+.IR errno
+to the appropriate value.
+.SH ERRORS
+No errors are defined.
+.SH EXAMPLE
+.nf
+void *data = malloc (6);
+assert (data);
+memcpy (data, "ABCDEF", 6);
+zmq_msg_t msg;
+rc = zmq_msg_init_data (&msg, data, 6, free);
+assert (rc == 0);
+rc = zmq_send (s, &msg, 0);
+assert (rc == 0);
+.fi
+.SH SEE ALSO
+.BR zmq_msg_close (3)
+.BR zmq_msg_init (3)
+.BR zmq_msg_init_size (3)
+.BR zmq_msg_data (3)
+.BR zmq_msg_size (3)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_msg_init_size.3 b/man/man3/zmq_msg_init_size.3
new file mode 100644
index 0000000..ce1ec94
--- /dev/null
+++ b/man/man3/zmq_msg_init_size.3
@@ -0,0 +1,44 @@
+.TH zmq_msg_init_size 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_msg_init \- initialises 0MQ message of a specified size
+.SH SYNOPSIS
+.B int zmq_msg_init_size (zmq_msg_t *msg, size_t size);
+.SH DESCRIPTION
+Initialises 0MQ message
+.IR 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
+.IR zmq_msg_t
+members, rather use
+.IR zmq_msg_data
+and
+.IR 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.
+.SH RETURN VALUE
+In case of success the function returns zero. Otherwise it returns -1 and
+sets
+.IR errno
+to the appropriate value.
+.SH ERRORS
+.IP "\fBENOMEM\fP"
+memory to hold the message cannot be allocated.
+.SH EXAMPLE
+.nf
+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);
+.fi
+.SH SEE ALSO
+.BR zmq_msg_close (3)
+.BR zmq_msg_init (3)
+.BR zmq_msg_init_data (3)
+.BR zmq_msg_data (3)
+.BR zmq_msg_size (3)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_msg_move.3 b/man/man3/zmq_msg_move.3
new file mode 100644
index 0000000..810e105
--- /dev/null
+++ b/man/man3/zmq_msg_move.3
@@ -0,0 +1,38 @@
+.TH zmq_msg_move 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_msg_move \- moves content of a message to another message
+.SH SYNOPSIS
+.B int zmq_msg_move (zmq_msg_t *dest, zmq_msg_t *src);
+.SH DESCRIPTION
+Move the content of the message from
+.IR src
+to
+.IR dest .
+The content isn't copied, just moved.
+.IR src
+becomes an empty message after the call. Original content of
+.IR dest
+message is deallocated.
+.SH RETURN VALUE
+In case of success the function returns zero. Otherwise it returns -1 and
+sets
+.IR errno
+to the appropriate value.
+.SH ERRORS
+No errors are defined.
+.SH EXAMPLE
+.nf
+zmq_msg_t dest;
+rc = zmq_msg_init (&dest);
+assert (rc == 0);
+rc = zmq_msg_move (&dest, &src);
+assert (rc == 0);
+.fi
+.SH SEE ALSO
+.BR zmq_msg_copy (3)
+.BR zmq_msg_init (3)
+.BR zmq_msg_init_size (3)
+.BR zmq_msg_init_data (3)
+.BR zmq_msg_close (3)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_msg_size.3 b/man/man3/zmq_msg_size.3
new file mode 100644
index 0000000..b51d582
--- /dev/null
+++ b/man/man3/zmq_msg_size.3
@@ -0,0 +1,30 @@
+.TH zmq_msg_size 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_msg_size \- retrieves size of the message content
+.SH SYNOPSIS
+.B size_t zmq_msg_size (zmq_msg_t *msg);
+.SH DESCRIPTION
+Returns size of the message data. Always use this function to get the size,
+never use
+.IR zmq_msg_t
+members directly.
+.SH RETURN VALUE
+Size of the message data (bytes).
+.SH ERRORS
+No errors are defined.
+.SH EXAMPLE
+.nf
+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);
+.fi
+.SH SEE ALSO
+.BR zmq_msg_init (3)
+.BR zmq_msg_init_size (3)
+.BR zmq_msg_init_data (3)
+.BR zmq_msg_close (3)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_poll.3 b/man/man3/zmq_poll.3
new file mode 100644
index 0000000..5ce5055
--- /dev/null
+++ b/man/man3/zmq_poll.3
@@ -0,0 +1,65 @@
+.TH zmq_poll 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_poll \- polls for events on a set of 0MQ and POSIX sockets
+.SH SYNOPSIS
+.B int zmq_poll (zmq_pollitem_t *items, int nitems);
+.SH DESCRIPTION
+Waits for the events specified by 
+.IR items
+parameter. Number of items in the array is determined by
+.IR nitems
+argument. Each item in the array looks like this:
+
+.nf
+typedef struct
+{
+    void *socket;
+    int fd;
+    short events;
+    short revents;
+} zmq_pollitem_t;
+.fi
+
+0MQ socket to poll on is specified by
+.IR socket .
+In case you want to poll on standard POSIX socket, set
+.IR socket
+to NULL and fill the POSIX file descriptor to
+.IR fd .
+.IR events
+specifies which events to wait for. It's a combination of the values below.
+Once the call exits,
+.IR revent
+will be filled with events that have actually occured on the socket. The field
+will contain a combination of the following values.
+
+.IP "\fBZMQ_POLLIN\fP"
+poll for incoming messages.
+.IP "\fBZMQ_POLLOUT\fP"
+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.
+
+.SH RETURN VALUE
+Function returns number of items signaled or -1 in the case of error.
+.SH ERRORS
+.IP "\fBEFAULT\fP"
+there's a 0MQ socket in the pollset belonging to a different application thread.
+.IP "\fBENOTSUP\fP"
+0MQ context was initialised without ZMQ_POLL flag. I/O multiplexing is disabled.
+.SH EXAMPLE
+.nf
+zmq_pollitem_t items [2];
+items [0].socket = s;
+items [0].events = POLLIN;
+items [1].socket = NULL;
+items [1].fd = my_fd;
+items [1].events = POLLIN;
+
+int rc = zmq_poll (items, 2);
+assert (rc != -1);
+.fi
+.SH SEE ALSO
+.BR zmq_socket (3)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_recv.3 b/man/man3/zmq_recv.3
new file mode 100644
index 0000000..d3cf2fd
--- /dev/null
+++ b/man/man3/zmq_recv.3
@@ -0,0 +1,52 @@
+.TH zmq_recv 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_recv \- retrieves a message from the socket
+.SH SYNOPSIS
+.B int zmq_recv (void *s, zmq_msg_t *msg, int flags);
+.SH DESCRIPTION
+Receive a message from the socket
+.IR s ,
+store it in
+.IR msg .
+Any content previously in
+.IR msg
+will be properly deallocated.
+.IR flags
+argument can be combination of the flags described below.
+
+.IP "\fBZMQ_NOBLOCK\fP"
+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
+.IR errno
+set to EAGAIN.
+
+.SH RETURN VALUE
+In case of success the function returns zero. Otherwise it returns -1 and
+sets
+.IR errno
+to the appropriate value.
+.SH ERRORS
+.IP "\fBEAGAIN\fP"
+it's a non-blocking receive and there's no message available at the moment.
+.IP "\fBENOTSUP\fP"
+function isn't supported by particular socket type.
+.IP "\fBEFSM\fP"
+function cannot be called at the moment, because socket is not in the
+approprite state. This error may occur with sockets that switch between
+several states (e.g. ZMQ_REQ).
+.SH EXAMPLE
+.nf
+zmq_msg_t msg;
+int rc = zmq_msg_init (&msg);
+assert (rc == 0);
+rc = zmq_recv (s, &msg, 0);
+assert (rc == 0);
+.fi
+.SH SEE ALSO
+.BR zmq_send (3)
+.BR zmq_msg_init (3)
+.BR zmq_msg_data (3)
+.BR zmq_msg_size (3)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_send.3 b/man/man3/zmq_send.3
new file mode 100644
index 0000000..0ebbd0c
--- /dev/null
+++ b/man/man3/zmq_send.3
@@ -0,0 +1,64 @@
+.TH zmq_send 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_send \- sends a message
+.SH SYNOPSIS
+.B int zmq_send (void *s, zmq_msg_t *msg, int flags);
+.SH DESCRIPTION
+Send the message
+.IR msg
+to the socket
+.IR s .
+.IR flags
+argument can be combination the flags described below.
+
+.IP "\fBZMQ_NOBLOCK\fP"
+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
+.IR errno
+set to EAGAIN.
+
+.IP "\fBZMQ_NOFLUSH\fP"
+The flag specifies that
+.IR zmq_send
+should not flush the message downstream immediately. Instead, it should batch
+ZMQ_NOFLUSH messages and send them downstream only once
+.IR 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.
+
+.SH RETURN VALUE
+In case of success the function returns zero. Otherwise it returns -1 and
+sets
+.IR errno
+to the appropriate value.
+.SH ERRORS
+.IP "\fBEAGAIN\fP"
+it's a non-blocking send and message cannot be sent at the moment.
+.IP "\fBENOTSUP\fP"
+function isn't supported by particular socket type.
+.IP "\fBEFSM\fP"
+function cannot be called at the moment, because socket is not in the
+approprite state. This error may occur with sockets that switch between
+several states (e.g. ZMQ_REQ).
+.SH EXAMPLE
+.nf
+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);
+.fi
+.SH SEE ALSO
+.BR zmq_flush (3)
+.BR zmq_recv (3)
+.BR zmq_msg_init (3)
+.BR zmq_msg_init_size (3)
+.BR zmq_msg_init_data (3)
+.BR zmq_msg_data (3)
+.BR zmq_msg_size (3)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_setsockopt.3 b/man/man3/zmq_setsockopt.3
new file mode 100644
index 0000000..a79f879
--- /dev/null
+++ b/man/man3/zmq_setsockopt.3
@@ -0,0 +1,115 @@
+.TH zmq_setsockopt 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_setsockopt \- sets a specified option on a 0MQ socket
+.SH SYNOPSIS
+.B int zmq_setsockopt (void *s, int option, const void *optval, size_t optvallen); 
+.SH DESCRIPTION
+Sets an option on the socket.
+.IR option
+argument specifies the option from the list below.
+.IR optval
+is a pointer to the value to set,
+.IR optvallen
+is the size of the value in bytes.
+
+.IP "\fBZMQ_HWM\fP"
+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: bytes  Default: 0
+
+.IP "\fBZMQ_LWM\fP"
+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 till the size of the pipe decreases to low watermark.
+At that point normal state is resumed.
+Type: int64_t  Unit: bytes  Default: 0
+
+.IP "\fBZMQ_SWAP\fP"
+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
+
+.IP "\fBZMQ_AFFINITY\fP"
+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
+
+.IP "\fBZMQ_IDENTITY\fP"
+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
+
+.IP "\fBZMQ_SUBSCRIBE\fP"
+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 ("*"), messages with
+specific topic ("x.y.z") and/or messages with specific topic prefix
+("x.y.*"). Topic is one-byte-size-prefixed string located at
+the very beginning of the message. 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
+
+.IP "\fBZMQ_UNSUBSCRIBE\fP"
+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
+
+.IP "\fBZMQ_RATE\fP"
+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
+
+.IP "\fBZMQ_RECOVERY_IVL\fP"
+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 
+
+.IP "\fBZMQ_MCAST_LOOP\fP"
+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
+
+.SH RETURN VALUE
+In case of success the function returns zero. Otherwise it returns -1 and
+sets
+.IR errno
+to the appropriate value.
+.SH ERRORS
+.IP "\fBEINVAL\fP"
+unknown option, a value with incorrect length or invalid value.
+.SH EXAMPLE
+.nf
+int rc = zmq_setsockopt (s, ZMQ_SUBSCRIBE, "*", 1);
+assert (rc == 0);
+.fi
+.SH SEE ALSO
+.BR zmq_socket (3)
+.BR zmq (7)
+
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_socket.3 b/man/man3/zmq_socket.3
new file mode 100644
index 0000000..a73bba5
--- /dev/null
+++ b/man/man3/zmq_socket.3
@@ -0,0 +1,77 @@
+.TH zmq_socket 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_socket \- creates 0MQ socket
+.SH SYNOPSIS
+.B void *zmq_socket (void *context, int type);
+.SH DESCRIPTION
+Open a socket within the specified
+.IR context .
+To create a context, use
+.IR zmq_init
+function.
+.IR 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.
+
+.IP "\fBZMQ_P2P\fP"
+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.
+
+.IP "\fBZMQ_PUB\fP"
+Socket to distribute data. Recv fuction is not implemented for this socket
+type. Messages are distributed in fanout fashion to all the peers.
+
+.IP "\fBZMQ_SUB\fP"
+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.
+
+.IP "\fBZMQ_REQ\fP"
+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.
+
+.IP "\fBZMQ_REP\fP"
+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.
+
+.IP "\fBZMQ_UPSTREAM\fP"
+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. 
+
+.IP "\fBZMQ_DOWNSTREAM\fP"
+Socket to send messages down stream. Messages are load-balanced among all the
+connected peers. Send function is not implemented for this socket type. 
+
+.SH RETURN VALUE
+Function returns socket handle is successful. Otherwise it returns NULL and
+sets errno to one of the values below.
+.SH ERRORS
+.IP "\fBEINVAL\fP"
+invalid socket type.
+.IP "\fBEMTHREAD\fP"
+the number of application threads allowed to own 0MQ sockets was exceeded. See
+.IR app_threads
+parameter to
+.IR zmq_init
+function.
+.SH EXAMPLE
+.nf
+void *s = zmq_socket (context, ZMQ_PUB);
+assert (s);
+int rc = zmq_bind (s, "tcp://192.168.0.1:5555");
+assert (rc == 0);
+.fi
+.SH SEE ALSO
+.BR zmq_init (3)
+.BR zmq_setsockopt (3)
+.BR zmq_bind (3)
+.BR zmq_connect (3)
+.BR zmq_send (3)
+.BR zmq_flush (3)
+.BR zmq_recv (3)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_strerror.3 b/man/man3/zmq_strerror.3
new file mode 100644
index 0000000..343c3ed
--- /dev/null
+++ b/man/man3/zmq_strerror.3
@@ -0,0 +1,27 @@
+.TH zmq_strerror 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_strerror \- returns string describing the error number
+.SH SYNOPSIS
+.B const char *zmq_strerror (int errnum);
+.SH DESCRIPTION
+As 0MQ defines few additional (non-POSIX) error codes, standard
+.IR strerror
+isn't capable of translating those errors into human readable strings. Instead,
+.IR zmq_strerror
+should be used.
+.SH RETURN VALUE
+Returns string describing the error number.
+.SH ERRORS
+No errors are defined.
+.SH EXAMPLE
+.nf
+void *ctx = zmq_init (1, 1, 0);
+if (!ctx) {
+    printf ("error occured during zmq_init: %s\\n", zmq_strerror (errno));
+    abort ();
+}
+.fi
+.SH SEE ALSO
+.BR zmq (7)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/man/man3/zmq_term.3 b/man/man3/zmq_term.3
new file mode 100644
index 0000000..8d822b6
--- /dev/null
+++ b/man/man3/zmq_term.3
@@ -0,0 +1,25 @@
+.TH zmq_term 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
+.SH NAME
+zmq_init \- terminates 0MQ context
+.SH SYNOPSIS
+.B int zmq_term (void *context);
+.SH DESCRIPTION
+Destroys 0MQ context. However, if there are still any sockets open within
+the context,
+.IR zmq_term
+succeeds but shutdown of the context is delayed till the last socket is closed.
+.SH RETURN VALUE
+Function returns zero is successful. Otherwise it returns -1 and
+sets errno to one of the values below.
+.SH ERRORS
+No errors are defined.
+.SH EXAMPLE
+.nf
+int rc = zmq_term (context);
+assert (rc == 0);
+.fi
+.SH SEE ALSO
+.BR zmq_init (3)
+.BR zmq_close (3)
+.SH AUTHOR
+Martin Sustrik <sustrik at 250bpm dot com>