diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/Makefile.am | 19 | ||||
| -rw-r--r-- | man/convert2pdf.sh | 66 | ||||
| -rw-r--r-- | man/man1/zmq_forwarder.1 | 11 | ||||
| -rw-r--r-- | man/man3/zmq_bind.3 | 48 | ||||
| -rw-r--r-- | man/man3/zmq_close.3 | 27 | ||||
| -rw-r--r-- | man/man3/zmq_connect.3 | 47 | ||||
| -rw-r--r-- | man/man3/zmq_flush.3 | 37 | ||||
| -rw-r--r-- | man/man3/zmq_init.3 | 39 | ||||
| -rw-r--r-- | man/man3/zmq_msg_close.3 | 32 | ||||
| -rw-r--r-- | man/man3/zmq_msg_copy.3 | 43 | ||||
| -rw-r--r-- | man/man3/zmq_msg_data.3 | 27 | ||||
| -rw-r--r-- | man/man3/zmq_msg_init.3 | 33 | ||||
| -rw-r--r-- | man/man3/zmq_msg_init_data.3 | 48 | ||||
| -rw-r--r-- | man/man3/zmq_msg_init_size.3 | 44 | ||||
| -rw-r--r-- | man/man3/zmq_msg_move.3 | 38 | ||||
| -rw-r--r-- | man/man3/zmq_msg_size.3 | 30 | ||||
| -rw-r--r-- | man/man3/zmq_poll.3 | 65 | ||||
| -rw-r--r-- | man/man3/zmq_recv.3 | 52 | ||||
| -rw-r--r-- | man/man3/zmq_send.3 | 64 | ||||
| -rw-r--r-- | man/man3/zmq_setsockopt.3 | 115 | ||||
| -rw-r--r-- | man/man3/zmq_socket.3 | 77 | ||||
| -rw-r--r-- | man/man3/zmq_strerror.3 | 27 | ||||
| -rw-r--r-- | man/man3/zmq_term.3 | 25 | ||||
| -rw-r--r-- | man/man7/zmq.7 | 9 |
24 files changed, 1023 insertions, 0 deletions
diff --git a/man/Makefile.am b/man/Makefile.am new file mode 100644 index 0000000..4f8c05a --- /dev/null +++ b/man/Makefile.am @@ -0,0 +1,19 @@ +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_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: + -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..85bc22c --- /dev/null +++ b/man/convert2pdf.sh @@ -0,0 +1,66 @@ +#!/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 <http://www.gnu.org/licenses/>. + +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 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 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/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 <sustrik at fastmq dot com> + + 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> 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 <sustrik at fastmq dot com> + |