the rest of man3 man pages filled in

9 files changed, 249 insertions, 0 deletions

diff --git a/man/man3/zmq_msg_close.3 b/man/man3/zmq_msg_close.3
index ee9d009..6613360 100644
--- a/man/man3/zmq_msg_close.3
+++ b/man/man3/zmq_msg_close.3
@@ -4,9 +4,29 @@ 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
index 239203b..2f70400 100644
--- a/man/man3/zmq_msg_copy.3
+++ b/man/man3/zmq_msg_copy.3
@@ -4,9 +4,40 @@ 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
index 647e9e9..9876378 100644
--- a/man/man3/zmq_msg_data.3
+++ b/man/man3/zmq_msg_data.3
@@ -4,9 +4,24 @@ 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
index 8b18207..a531fc1 100644
--- a/man/man3/zmq_msg_init.3
+++ b/man/man3/zmq_msg_init.3
@@ -4,9 +4,30 @@ 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
index d00ed9c..a0b14c8 100644
--- a/man/man3/zmq_msg_init_data.3
+++ b/man/man3/zmq_msg_init_data.3
@@ -7,9 +7,42 @@ zmq_msg_init \- initialises 0MQ message from the given 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
index b1baa75..ce1ec94 100644
--- a/man/man3/zmq_msg_init_size.3
+++ b/man/man3/zmq_msg_init_size.3
@@ -4,9 +4,41 @@ 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
index 0daf2f7..810e105 100644
--- a/man/man3/zmq_msg_move.3
+++ b/man/man3/zmq_msg_move.3
@@ -4,9 +4,35 @@ 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
index d8bbc53..b51d582 100644
--- a/man/man3/zmq_msg_size.3
+++ b/man/man3/zmq_msg_size.3
@@ -4,9 +4,27 @@ 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
index d821e9f..5ce5055 100644
--- a/man/man3/zmq_poll.3
+++ b/man/man3/zmq_poll.3
@@ -4,9 +4,62 @@ 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>