more man pages filled in

10 files changed, 367 insertions, 2 deletions

diff --git a/man/man3/zmq_bind.3 b/man/man3/zmq_bind.3
index 70f1df7..069b966 100644
--- a/man/man3/zmq_bind.3
+++ b/man/man3/zmq_bind.3
@@ -4,9 +4,45 @@ 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
index c04f97a..cc49635 100644
--- a/man/man3/zmq_close.3
+++ b/man/man3/zmq_close.3
@@ -4,9 +4,24 @@ 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
index c68101c..8f09e20 100644
--- a/man/man3/zmq_connect.3
+++ b/man/man3/zmq_connect.3
@@ -1,12 +1,47 @@
 .TH zmq_connect 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
 .SH NAME
-zmq_connect \- connects the socket to the specified address
+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
index f84c561..194cf6c 100644
--- a/man/man3/zmq_flush.3
+++ b/man/man3/zmq_flush.3
@@ -4,9 +4,34 @@ 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
index 1e48fd7..317dbba 100644
--- a/man/man3/zmq_init.3
+++ b/man/man3/zmq_init.3
@@ -25,7 +25,7 @@ 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
+there's less than one application thread allocated, or number of I/O threads
 is negative.
 .SH EXAMPLE
 .nf
@@ -34,5 +34,6 @@ 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_recv.3 b/man/man3/zmq_recv.3
index 8308f79..d3cf2fd 100644
--- a/man/man3/zmq_recv.3
+++ b/man/man3/zmq_recv.3
@@ -4,9 +4,49 @@ 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
index ff6e429..0ebbd0c 100644
--- a/man/man3/zmq_send.3
+++ b/man/man3/zmq_send.3
@@ -4,9 +4,61 @@ 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
index da528cf..a79f879 100644
--- a/man/man3/zmq_setsockopt.3
+++ b/man/man3/zmq_setsockopt.3
@@ -4,9 +4,112 @@ 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
index f404b6b..8b819b5 100644
--- a/man/man3/zmq_socket.3
+++ b/man/man3/zmq_socket.3
@@ -4,9 +4,65 @@ 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.
+
 .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_term.3 b/man/man3/zmq_term.3
index 14d9da9..8d822b6 100644
--- a/man/man3/zmq_term.3
+++ b/man/man3/zmq_term.3
@@ -19,5 +19,7 @@ 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>