From 55b64a02e7f3b1ce9e512240a9f9a337ead3b54c Mon Sep 17 00:00:00 2001 From: Martin Sustrik Date: Sun, 22 Nov 2009 08:47:06 +0100 Subject: man pages - initial (dummy) version --- man/Makefile.am | 16 ++++++++++++++++ man/convert2pdf.sh | 48 +++++++++++++++++++++++++++++++++++++++++++++++ man/man1/zmq_forwarder.1 | 11 +++++++++++ man/man3/zmq_bind.3 | 12 ++++++++++++ man/man3/zmq_close.3 | 12 ++++++++++++ man/man3/zmq_connect.3 | 12 ++++++++++++ man/man3/zmq_flush.3 | 12 ++++++++++++ man/man3/zmq_init.3 | 12 ++++++++++++ man/man3/zmq_poll.3 | 12 ++++++++++++ man/man3/zmq_recv.3 | 12 ++++++++++++ man/man3/zmq_send.3 | 12 ++++++++++++ man/man3/zmq_setsockopt.3 | 12 ++++++++++++ man/man3/zmq_socket.3 | 12 ++++++++++++ man/man3/zmq_term.3 | 12 ++++++++++++ man/man7/zmq.7 | 9 +++++++++ 15 files changed, 216 insertions(+) create mode 100644 man/Makefile.am create mode 100644 man/convert2pdf.sh create mode 100644 man/man1/zmq_forwarder.1 create mode 100644 man/man3/zmq_bind.3 create mode 100644 man/man3/zmq_close.3 create mode 100644 man/man3/zmq_connect.3 create mode 100644 man/man3/zmq_flush.3 create mode 100644 man/man3/zmq_init.3 create mode 100644 man/man3/zmq_poll.3 create mode 100644 man/man3/zmq_recv.3 create mode 100644 man/man3/zmq_send.3 create mode 100644 man/man3/zmq_setsockopt.3 create mode 100644 man/man3/zmq_socket.3 create mode 100644 man/man3/zmq_term.3 create mode 100644 man/man7/zmq.7 (limited to 'man') diff --git a/man/Makefile.am b/man/Makefile.am new file mode 100644 index 0000000..84e0e47 --- /dev/null +++ b/man/Makefile.am @@ -0,0 +1,16 @@ +dist_man_MANS = man1/zmq_forwarder.1 man3/zmq_init.3 man3/zmq_term.3 \ + man3/zmq_socket.3 man3/zmq_close.3 man3/zmq_setsockopt.3 man3/zmq_bind.3 \ + man3/zmq_connect.3 man3/zmq_send.3 man3/zmq_flush.3 man3/zmq_recv.3 \ + man3/zmq_poll.3 man7/zmq.7 + +distclean-local: + -rm *.pdf + -rm man1/*.ps + -rm man3/*.ps + -rm man7/*.ps + +dist-hook: + ./convert2pdf.sh + $(mkdir_p) $(top_distdir)/doc + cp $(top_srcdir)/man/*.pdf $(top_distdir)/doc + diff --git a/man/convert2pdf.sh b/man/convert2pdf.sh new file mode 100644 index 0000000..6a7029f --- /dev/null +++ b/man/convert2pdf.sh @@ -0,0 +1,48 @@ +#!/bin/sh +# +# Copyright (c) 2007-2009 FastMQ Inc. +# +# This file is part of 0MQ. +# +# 0MQ is free software; you can redistribute it and/or modify it under +# the terms of the Lesser GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# 0MQ is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# Lesser GNU General Public License for more details. +# +# You should have received a copy of the Lesser GNU General Public License +# along with this program. If not, see . + +groff -man -Tps man1/zmq_forwarder.1 > man1/zmq_forwarder.1.ps +ps2pdf man1/zmq_forwarder.1.ps zmq_forwarder.pdf + +groff -man -Tps man3/zmq_init.3 > man3/zmq_init.3.ps +ps2pdf man3/zmq_init.3.ps zmq_init.pdf +groff -man -Tps man3/zmq_term.3 > man3/zmq_term.3.ps +ps2pdf man3/zmq_term.3.ps zmq_term.pdf +groff -man -Tps man3/zmq_socket.3 > man3/zmq_socket.3.ps +ps2pdf man3/zmq_socket.3.ps zmq_socket.pdf +groff -man -Tps man3/zmq_close.3 > man3/zmq_close.3.ps +ps2pdf man3/zmq_close.3.ps zmq_close.pdf +groff -man -Tps man3/zmq_setsockopt.3 > man3/zmq_setsockopt.3.ps +ps2pdf man3/zmq_setsockopt.3.ps zmq_setsockopt.pdf +groff -man -Tps man3/zmq_bind.3 > man3/zmq_bind.3.ps +ps2pdf man3/zmq_bind.3.ps zmq_bind.pdf +groff -man -Tps man3/zmq_connect.3 > man3/zmq_connect.3.ps +ps2pdf man3/zmq_connect.3.ps zmq_connect.pdf +groff -man -Tps man3/zmq_send.3 > man3/zmq_send.3.ps +ps2pdf man3/zmq_send.3.ps zmq_send.pdf +groff -man -Tps man3/zmq_flush.3 > man3/zmq_flush.3.ps +ps2pdf man3/zmq_flush.3.ps zmq_flush.pdf +groff -man -Tps man3/zmq_recv.3 > man3/zmq_recv.3.ps +ps2pdf man3/zmq_recv.3.ps zmq_recv.pdf +groff -man -Tps man3/zmq_poll.3 > man3/zmq_poll.3.ps +ps2pdf man3/zmq_poll.3.ps zmq_poll.pdf + +groff -man -Tps man7/zmq.7 > man7/zmq.7.ps +ps2pdf man7/zmq.7.ps zmq.pdf + diff --git a/man/man1/zmq_forwarder.1 b/man/man1/zmq_forwarder.1 new file mode 100644 index 0000000..63a0b6b --- /dev/null +++ b/man/man1/zmq_forwarder.1 @@ -0,0 +1,11 @@ +.TH zmq_forwarder 1 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals" +.SH NAME +zmq_forwarder \- forwards the stream of PUB/SUB messages +.SH SYNOPSIS +.SH DESCRIPTION +.SH OPTIONS +.SH "SEE ALSO" +.SH AUTHOR +Martin Sustrik + + diff --git a/man/man3/zmq_bind.3 b/man/man3/zmq_bind.3 new file mode 100644 index 0000000..70f1df7 --- /dev/null +++ b/man/man3/zmq_bind.3 @@ -0,0 +1,12 @@ +.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 +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik diff --git a/man/man3/zmq_close.3 b/man/man3/zmq_close.3 new file mode 100644 index 0000000..c04f97a --- /dev/null +++ b/man/man3/zmq_close.3 @@ -0,0 +1,12 @@ +.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 +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik diff --git a/man/man3/zmq_connect.3 b/man/man3/zmq_connect.3 new file mode 100644 index 0000000..c68101c --- /dev/null +++ b/man/man3/zmq_connect.3 @@ -0,0 +1,12 @@ +.TH zmq_connect 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals" +.SH NAME +zmq_connect \- connects the socket to the specified address +.SH SYNOPSIS +.B int zmq_connect (void *s, const char *addr); +.SH DESCRIPTION +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik diff --git a/man/man3/zmq_flush.3 b/man/man3/zmq_flush.3 new file mode 100644 index 0000000..f84c561 --- /dev/null +++ b/man/man3/zmq_flush.3 @@ -0,0 +1,12 @@ +.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 +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik diff --git a/man/man3/zmq_init.3 b/man/man3/zmq_init.3 new file mode 100644 index 0000000..04f04ef --- /dev/null +++ b/man/man3/zmq_init.3 @@ -0,0 +1,12 @@ +.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 +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik diff --git a/man/man3/zmq_poll.3 b/man/man3/zmq_poll.3 new file mode 100644 index 0000000..d821e9f --- /dev/null +++ b/man/man3/zmq_poll.3 @@ -0,0 +1,12 @@ +.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 +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik diff --git a/man/man3/zmq_recv.3 b/man/man3/zmq_recv.3 new file mode 100644 index 0000000..8308f79 --- /dev/null +++ b/man/man3/zmq_recv.3 @@ -0,0 +1,12 @@ +.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 +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik diff --git a/man/man3/zmq_send.3 b/man/man3/zmq_send.3 new file mode 100644 index 0000000..ff6e429 --- /dev/null +++ b/man/man3/zmq_send.3 @@ -0,0 +1,12 @@ +.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 +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik diff --git a/man/man3/zmq_setsockopt.3 b/man/man3/zmq_setsockopt.3 new file mode 100644 index 0000000..da528cf --- /dev/null +++ b/man/man3/zmq_setsockopt.3 @@ -0,0 +1,12 @@ +.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 +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik diff --git a/man/man3/zmq_socket.3 b/man/man3/zmq_socket.3 new file mode 100644 index 0000000..f404b6b --- /dev/null +++ b/man/man3/zmq_socket.3 @@ -0,0 +1,12 @@ +.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 +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik diff --git a/man/man3/zmq_term.3 b/man/man3/zmq_term.3 new file mode 100644 index 0000000..afd3273 --- /dev/null +++ b/man/man3/zmq_term.3 @@ -0,0 +1,12 @@ +.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 +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik diff --git a/man/man7/zmq.7 b/man/man7/zmq.7 new file mode 100644 index 0000000..02257a7 --- /dev/null +++ b/man/man7/zmq.7 @@ -0,0 +1,9 @@ +.TH zmq 7 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals" +.SH NAME +0MQ \- a lightweight messaging kernel +.SH SYNOPSIS +.SH DESCRIPTION +.SH "SEE ALSO" +.SH AUTHOR +Martin Sustrik + -- cgit v1.2.3 From ed5563f75285197aa0cdbe8a0dc6f80c5bb1f89c Mon Sep 17 00:00:00 2001 From: Martin Sustrik Date: Sun, 22 Nov 2009 10:25:53 +0100 Subject: man pages (dummy) added for zmq_msg_* functions --- man/Makefile.am | 5 ++++- man/convert2pdf.sh | 16 ++++++++++++++++ man/man3/zmq_msg_close.3 | 12 ++++++++++++ man/man3/zmq_msg_copy.3 | 12 ++++++++++++ man/man3/zmq_msg_data.3 | 12 ++++++++++++ man/man3/zmq_msg_init.3 | 12 ++++++++++++ man/man3/zmq_msg_init_data.3 | 15 +++++++++++++++ man/man3/zmq_msg_init_size.3 | 12 ++++++++++++ man/man3/zmq_msg_move.3 | 12 ++++++++++++ man/man3/zmq_msg_size.3 | 12 ++++++++++++ 10 files changed, 119 insertions(+), 1 deletion(-) create mode 100644 man/man3/zmq_msg_close.3 create mode 100644 man/man3/zmq_msg_copy.3 create mode 100644 man/man3/zmq_msg_data.3 create mode 100644 man/man3/zmq_msg_init.3 create mode 100644 man/man3/zmq_msg_init_data.3 create mode 100644 man/man3/zmq_msg_init_size.3 create mode 100644 man/man3/zmq_msg_move.3 create mode 100644 man/man3/zmq_msg_size.3 (limited to 'man') diff --git a/man/Makefile.am b/man/Makefile.am index 84e0e47..9477351 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -1,7 +1,10 @@ dist_man_MANS = man1/zmq_forwarder.1 man3/zmq_init.3 man3/zmq_term.3 \ man3/zmq_socket.3 man3/zmq_close.3 man3/zmq_setsockopt.3 man3/zmq_bind.3 \ man3/zmq_connect.3 man3/zmq_send.3 man3/zmq_flush.3 man3/zmq_recv.3 \ - man3/zmq_poll.3 man7/zmq.7 + 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 distclean-local: -rm *.pdf diff --git a/man/convert2pdf.sh b/man/convert2pdf.sh index 6a7029f..f47854a 100644 --- a/man/convert2pdf.sh +++ b/man/convert2pdf.sh @@ -42,6 +42,22 @@ groff -man -Tps man3/zmq_recv.3 > man3/zmq_recv.3.ps ps2pdf man3/zmq_recv.3.ps zmq_recv.pdf groff -man -Tps man3/zmq_poll.3 > man3/zmq_poll.3.ps ps2pdf man3/zmq_poll.3.ps zmq_poll.pdf +groff -man -Tps man3/zmq_msg_init.3 > man3/zmq_msg_init.3.ps +ps2pdf man3/zmq_msg_init.3.ps zmq_msg_init.pdf +groff -man -Tps man3/zmq_msg_init_size.3 > man3/zmq_msg_init_size.3.ps +ps2pdf man3/zmq_msg_init_size.3.ps zmq_msg_init_size.pdf +groff -man -Tps man3/zmq_msg_init_data.3 > man3/zmq_msg_init_data.3.ps +ps2pdf man3/zmq_msg_init_data.3.ps zmq_msg_init_data.pdf +groff -man -Tps man3/zmq_msg_close.3 > man3/zmq_msg_close.3.ps +ps2pdf man3/zmq_msg_close.3.ps zmq_msg_close.pdf +groff -man -Tps man3/zmq_msg_move.3 > man3/zmq_msg_move.3.ps +ps2pdf man3/zmq_msg_move.3.ps zmq_msg_move.pdf +groff -man -Tps man3/zmq_msg_copy.3 > man3/zmq_msg_copy.3.ps +ps2pdf man3/zmq_msg_copy.3.ps zmq_msg_copy.pdf +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 man7/zmq.7 > man7/zmq.7.ps ps2pdf man7/zmq.7.ps zmq.pdf diff --git a/man/man3/zmq_msg_close.3 b/man/man3/zmq_msg_close.3 new file mode 100644 index 0000000..ee9d009 --- /dev/null +++ b/man/man3/zmq_msg_close.3 @@ -0,0 +1,12 @@ +.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 +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik diff --git a/man/man3/zmq_msg_copy.3 b/man/man3/zmq_msg_copy.3 new file mode 100644 index 0000000..239203b --- /dev/null +++ b/man/man3/zmq_msg_copy.3 @@ -0,0 +1,12 @@ +.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 +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik diff --git a/man/man3/zmq_msg_data.3 b/man/man3/zmq_msg_data.3 new file mode 100644 index 0000000..647e9e9 --- /dev/null +++ b/man/man3/zmq_msg_data.3 @@ -0,0 +1,12 @@ +.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 +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik diff --git a/man/man3/zmq_msg_init.3 b/man/man3/zmq_msg_init.3 new file mode 100644 index 0000000..8b18207 --- /dev/null +++ b/man/man3/zmq_msg_init.3 @@ -0,0 +1,12 @@ +.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 +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik diff --git a/man/man3/zmq_msg_init_data.3 b/man/man3/zmq_msg_init_data.3 new file mode 100644 index 0000000..d00ed9c --- /dev/null +++ b/man/man3/zmq_msg_init_data.3 @@ -0,0 +1,15 @@ +.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 +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik diff --git a/man/man3/zmq_msg_init_size.3 b/man/man3/zmq_msg_init_size.3 new file mode 100644 index 0000000..b1baa75 --- /dev/null +++ b/man/man3/zmq_msg_init_size.3 @@ -0,0 +1,12 @@ +.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 +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik diff --git a/man/man3/zmq_msg_move.3 b/man/man3/zmq_msg_move.3 new file mode 100644 index 0000000..0daf2f7 --- /dev/null +++ b/man/man3/zmq_msg_move.3 @@ -0,0 +1,12 @@ +.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 +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik diff --git a/man/man3/zmq_msg_size.3 b/man/man3/zmq_msg_size.3 new file mode 100644 index 0000000..d8bbc53 --- /dev/null +++ b/man/man3/zmq_msg_size.3 @@ -0,0 +1,12 @@ +.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 +.SH RETURN VALUE +.SH ERRORS +.SH EXAMPLE +.SH SEE ALSO +.SH AUTHOR +Martin Sustrik -- cgit v1.2.3 From 6602cce9af93539df8f1c43235e7e7130a3df60d Mon Sep 17 00:00:00 2001 From: Martin Sustrik 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 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 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 -- cgit v1.2.3 From e90ada0d044636201c57786307a49a52f9cf7643 Mon Sep 17 00:00:00 2001 From: Martin Sustrik Date: Sun, 22 Nov 2009 16:51:21 +0100 Subject: more man pages filled in --- man/man3/zmq_bind.3 | 36 ++++++++++++++++ man/man3/zmq_close.3 | 15 +++++++ man/man3/zmq_connect.3 | 37 ++++++++++++++++- man/man3/zmq_flush.3 | 25 +++++++++++ man/man3/zmq_init.3 | 3 +- man/man3/zmq_recv.3 | 40 ++++++++++++++++++ man/man3/zmq_send.3 | 52 +++++++++++++++++++++++ man/man3/zmq_setsockopt.3 | 103 ++++++++++++++++++++++++++++++++++++++++++++++ man/man3/zmq_socket.3 | 56 +++++++++++++++++++++++++ man/man3/zmq_term.3 | 2 + 10 files changed, 367 insertions(+), 2 deletions(-) (limited to 'man') 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 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 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 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 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 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 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 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 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 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 -- cgit v1.2.3 From 5cd98bc575517ea72c435770a5313711484f7d34 Mon Sep 17 00:00:00 2001 From: Martin Sustrik Date: Mon, 23 Nov 2009 09:22:25 +0100 Subject: the rest of man3 man pages filled in --- man/man3/zmq_msg_close.3 | 20 +++++++++++++++++ man/man3/zmq_msg_copy.3 | 31 ++++++++++++++++++++++++++ man/man3/zmq_msg_data.3 | 15 +++++++++++++ man/man3/zmq_msg_init.3 | 21 ++++++++++++++++++ man/man3/zmq_msg_init_data.3 | 33 +++++++++++++++++++++++++++ man/man3/zmq_msg_init_size.3 | 32 ++++++++++++++++++++++++++ man/man3/zmq_msg_move.3 | 26 ++++++++++++++++++++++ man/man3/zmq_msg_size.3 | 18 +++++++++++++++ man/man3/zmq_poll.3 | 53 ++++++++++++++++++++++++++++++++++++++++++++ 9 files changed, 249 insertions(+) (limited to 'man') 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 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 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 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 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 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 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 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 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 -- cgit v1.2.3 From c98fd6bc3f2a49d7cb0b820a07354168c98f60b7 Mon Sep 17 00:00:00 2001 From: Martin Sustrik Date: Tue, 24 Nov 2009 11:23:10 +0100 Subject: ZMQII-25: Implement streamed request/reply --- man/man3/zmq_socket.3 | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'man') diff --git a/man/man3/zmq_socket.3 b/man/man3/zmq_socket.3 index 8b819b5..a73bba5 100644 --- a/man/man3/zmq_socket.3 +++ b/man/man3/zmq_socket.3 @@ -37,6 +37,15 @@ 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. -- cgit v1.2.3 From 19ce7c0e77f703ed2ec3b54685ddf4a6f2329ffe Mon Sep 17 00:00:00 2001 From: Martin Sustrik Date: Thu, 26 Nov 2009 12:41:50 +0100 Subject: zmq_msg_data.3 referenced twice in Makefile.am - fixed --- man/Makefile.am | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'man') diff --git a/man/Makefile.am b/man/Makefile.am index 2efb80d..4f8c05a 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -2,8 +2,8 @@ dist_man_MANS = man1/zmq_forwarder.1 man3/zmq_init.3 man3/zmq_term.3 \ man3/zmq_socket.3 man3/zmq_close.3 man3/zmq_setsockopt.3 man3/zmq_bind.3 \ man3/zmq_connect.3 man3/zmq_send.3 man3/zmq_flush.3 man3/zmq_recv.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 \ + 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 \ man3/zmq_strerror.3 man7/zmq.7 distclean-local: -- cgit v1.2.3