From 6602cce9af93539df8f1c43235e7e7130a3df60d Mon Sep 17 00:00:00 2001
From: Martin Sustrik <sustrik@fastmq.commkdir>
Date: Sun, 22 Nov 2009 12:05:11 +0100
Subject: zmq_init, zmq_term & zmq_strerror man pages added

---
 man/Makefile.am         |  2 +-
 man/convert2pdf.sh      |  2 ++
 man/man3/zmq_init.3     | 26 ++++++++++++++++++++++++++
 man/man3/zmq_strerror.3 | 27 +++++++++++++++++++++++++++
 man/man3/zmq_term.3     | 11 +++++++++++
 5 files changed, 67 insertions(+), 1 deletion(-)
 create mode 100644 man/man3/zmq_strerror.3

(limited to 'man')

diff --git a/man/Makefile.am b/man/Makefile.am
index 9477351..2efb80d 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -4,7 +4,7 @@ dist_man_MANS = man1/zmq_forwarder.1 man3/zmq_init.3 man3/zmq_term.3 \
     man3/zmq_poll.3 man3/zmq_msg_init.3 man3/zmq_msg_init_size.3 \
     man3/zmq_msg_data.3 man3/zmq_msg_close.3 man3/zmq_msg_move.3 \
     man3/zmq_msg_copy.3 man3/zmq_msg_data.3 man3/zmq_msg_size.3 \
-    man7/zmq.7
+    man3/zmq_strerror.3 man7/zmq.7
 
 distclean-local:
 		-rm  *.pdf
diff --git a/man/convert2pdf.sh b/man/convert2pdf.sh
index f47854a..85bc22c 100644
--- a/man/convert2pdf.sh
+++ b/man/convert2pdf.sh
@@ -58,6 +58,8 @@ groff -man -Tps man3/zmq_msg_data.3 > man3/zmq_msg_data.3.ps
 ps2pdf man3/zmq_msg_data.3.ps zmq_msg_data.pdf
 groff -man -Tps man3/zmq_msg_size.3 > man3/zmq_msg_size.3.ps
 ps2pdf man3/zmq_msg_size.3.ps zmq_msg_size.pdf
+groff -man -Tps man3/zmq_strerror.3 > man3/zmq_strerror.3.ps
+ps2pdf man3/zmq_strerror.3.ps zmq_strerror.pdf
 
 groff -man -Tps man7/zmq.7 > man7/zmq.7.ps
 ps2pdf man7/zmq.7.ps zmq.pdf
diff --git a/man/man3/zmq_init.3 b/man/man3/zmq_init.3
index 04f04ef..1e48fd7 100644
--- a/man/man3/zmq_init.3
+++ b/man/man3/zmq_init.3
@@ -4,9 +4,35 @@ 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)
 .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
index afd3273..14d9da9 100644
--- a/man/man3/zmq_term.3
+++ b/man/man3/zmq_term.3
@@ -4,9 +4,20 @@ 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
 .SH AUTHOR
 Martin Sustrik <sustrik at 250bpm dot com>
-- 
cgit v1.2.3