From 8e61b98c5e2943b149c825310b24e714a6127072 Mon Sep 17 00:00:00 2001 From: Martin Lucina Date: Mon, 23 Jan 2012 08:53:41 +0100 Subject: Imported Upstream version 2.1.4 --- doc/Makefile.am | 6 +- doc/Makefile.in | 9 +- doc/zmq.7 | 6 +- doc/zmq.html | 846 ++++++++++++++++++++++ doc/zmq_bind.3 | 6 +- doc/zmq_bind.html | 746 +++++++++++++++++++ doc/zmq_close.3 | 6 +- doc/zmq_close.html | 645 +++++++++++++++++ doc/zmq_connect.3 | 6 +- doc/zmq_connect.html | 732 +++++++++++++++++++ doc/zmq_cpp.7 | 6 +- doc/zmq_cpp.html | 765 ++++++++++++++++++++ doc/zmq_device.3 | 6 +- doc/zmq_device.html | 736 +++++++++++++++++++ doc/zmq_epgm.7 | 6 +- doc/zmq_epgm.html | 745 +++++++++++++++++++ doc/zmq_errno.3 | 6 +- doc/zmq_errno.html | 634 ++++++++++++++++ doc/zmq_getsockopt.3 | 6 +- doc/zmq_getsockopt.html | 1713 ++++++++++++++++++++++++++++++++++++++++++++ doc/zmq_init.3 | 6 +- doc/zmq_init.html | 635 ++++++++++++++++ doc/zmq_inproc.7 | 6 +- doc/zmq_inproc.html | 669 +++++++++++++++++ doc/zmq_ipc.7 | 6 +- doc/zmq_ipc.html | 662 +++++++++++++++++ doc/zmq_msg_close.3 | 6 +- doc/zmq_msg_close.html | 638 +++++++++++++++++ doc/zmq_msg_copy.3 | 6 +- doc/zmq_msg_copy.html | 647 +++++++++++++++++ doc/zmq_msg_data.3 | 6 +- doc/zmq_msg_data.html | 633 ++++++++++++++++ doc/zmq_msg_init.3 | 6 +- doc/zmq_msg_init.html | 656 +++++++++++++++++ doc/zmq_msg_init_data.3 | 6 +- doc/zmq_msg_init_data.html | 669 +++++++++++++++++ doc/zmq_msg_init_size.3 | 6 +- doc/zmq_msg_init_size.html | 656 +++++++++++++++++ doc/zmq_msg_move.3 | 6 +- doc/zmq_msg_move.html | 636 ++++++++++++++++ doc/zmq_msg_size.3 | 6 +- doc/zmq_msg_size.html | 633 ++++++++++++++++ doc/zmq_pgm.7 | 6 +- doc/zmq_pgm.html | 745 +++++++++++++++++++ doc/zmq_poll.3 | 6 +- doc/zmq_poll.html | 755 +++++++++++++++++++ doc/zmq_recv.3 | 6 +- doc/zmq_recv.html | 738 +++++++++++++++++++ doc/zmq_send.3 | 6 +- doc/zmq_send.html | 744 +++++++++++++++++++ doc/zmq_setsockopt.3 | 6 +- doc/zmq_setsockopt.html | 1603 +++++++++++++++++++++++++++++++++++++++++ doc/zmq_socket.3 | 6 +- doc/zmq_socket.html | 1416 ++++++++++++++++++++++++++++++++++++ doc/zmq_strerror.3 | 6 +- doc/zmq_strerror.html | 634 ++++++++++++++++ doc/zmq_tcp.7 | 6 +- doc/zmq_tcp.html | 755 +++++++++++++++++++ doc/zmq_term.3 | 6 +- doc/zmq_term.html | 672 +++++++++++++++++ doc/zmq_version.3 | 6 +- doc/zmq_version.html | 632 ++++++++++++++++ 62 files changed, 23492 insertions(+), 93 deletions(-) create mode 100644 doc/zmq.html create mode 100644 doc/zmq_bind.html create mode 100644 doc/zmq_close.html create mode 100644 doc/zmq_connect.html create mode 100644 doc/zmq_cpp.html create mode 100644 doc/zmq_device.html create mode 100644 doc/zmq_epgm.html create mode 100644 doc/zmq_errno.html create mode 100644 doc/zmq_getsockopt.html create mode 100644 doc/zmq_init.html create mode 100644 doc/zmq_inproc.html create mode 100644 doc/zmq_ipc.html create mode 100644 doc/zmq_msg_close.html create mode 100644 doc/zmq_msg_copy.html create mode 100644 doc/zmq_msg_data.html create mode 100644 doc/zmq_msg_init.html create mode 100644 doc/zmq_msg_init_data.html create mode 100644 doc/zmq_msg_init_size.html create mode 100644 doc/zmq_msg_move.html create mode 100644 doc/zmq_msg_size.html create mode 100644 doc/zmq_pgm.html create mode 100644 doc/zmq_poll.html create mode 100644 doc/zmq_recv.html create mode 100644 doc/zmq_send.html create mode 100644 doc/zmq_setsockopt.html create mode 100644 doc/zmq_socket.html create mode 100644 doc/zmq_strerror.html create mode 100644 doc/zmq_tcp.html create mode 100644 doc/zmq_term.html create mode 100644 doc/zmq_version.html (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am index d00014d..7408f10 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -11,6 +11,7 @@ MAN_DOC = $(MAN1) $(MAN3) $(MAN7) MAN_TXT = $(MAN1:%.1=%.txt) MAN_TXT += $(MAN3:%.3=%.txt) MAN_TXT += $(MAN7:%.7=%.txt) +MAN_HTML = $(MAN_TXT:%.txt=%.html) if INSTALL_MAN dist_man_MANS = $(MAN_DOC) @@ -26,8 +27,11 @@ MAINTAINERCLEANFILES = $(MAN_DOC) $(MAN_HTML) dist-hook : $(MAN_DOC) $(MAN_HTML) if BUILD_DOC -SUFFIXES=.txt .xml .1 .3 .7 +SUFFIXES=.html .txt .xml .1 .3 .7 +.txt.html: + $(AM_V_GEN)$(ASCIIDOC) -d manpage -b xhtml11 -f asciidoc.conf \ + -azmq_version=@PACKAGE_VERSION@ $< .txt.xml: $(AM_V_GEN)$(ASCIIDOC) -d manpage -b docbook -f asciidoc.conf \ -azmq_version=@PACKAGE_VERSION@ $< diff --git a/doc/Makefile.in b/doc/Makefile.in index 0d71c0e..35bf698 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -203,6 +203,7 @@ oldincludedir = @oldincludedir@ pdfdir = @pdfdir@ pgm_basename = @pgm_basename@ pgm_srcdir = @pgm_srcdir@ +pgm_subdir = @pgm_subdir@ prefix = @prefix@ program_transform_name = @program_transform_name@ psdir = @psdir@ @@ -227,14 +228,15 @@ MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_epgm.7 zmq_inproc.7 zmq_ipc.7 \ MAN_DOC = $(MAN1) $(MAN3) $(MAN7) MAN_TXT = $(MAN1:%.1=%.txt) $(MAN3:%.3=%.txt) $(MAN7:%.7=%.txt) +MAN_HTML = $(MAN_TXT:%.txt=%.html) @INSTALL_MAN_TRUE@dist_man_MANS = $(MAN_DOC) EXTRA_DIST = asciidoc.conf $(MAN_TXT) $(am__append_1) MAINTAINERCLEANFILES = $(MAN_DOC) $(MAN_HTML) -@BUILD_DOC_TRUE@SUFFIXES = .txt .xml .1 .3 .7 +@BUILD_DOC_TRUE@SUFFIXES = .html .txt .xml .1 .3 .7 all: all-am .SUFFIXES: -.SUFFIXES: .txt .xml .1 .3 .7 +.SUFFIXES: .html .txt .xml .1 .3 .7 $(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps) @for dep in $?; do \ case '$(am__configure_deps)' in \ @@ -519,6 +521,9 @@ uninstall-man: uninstall-man3 uninstall-man7 dist-hook : $(MAN_DOC) $(MAN_HTML) +@BUILD_DOC_TRUE@.txt.html: +@BUILD_DOC_TRUE@ $(AM_V_GEN)$(ASCIIDOC) -d manpage -b xhtml11 -f asciidoc.conf \ +@BUILD_DOC_TRUE@ -azmq_version=@PACKAGE_VERSION@ $< @BUILD_DOC_TRUE@.txt.xml: @BUILD_DOC_TRUE@ $(AM_V_GEN)$(ASCIIDOC) -d manpage -b docbook -f asciidoc.conf \ @BUILD_DOC_TRUE@ -azmq_version=@PACKAGE_VERSION@ $< diff --git a/doc/zmq.7 b/doc/zmq.7 index 61345fb..d7fa3be 100644 --- a/doc/zmq.7 +++ b/doc/zmq.7 @@ -2,12 +2,12 @@ .\" Title: zmq .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ" "7" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ" "7" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq.html b/doc/zmq.html new file mode 100644 index 0000000..b35c57e --- /dev/null +++ b/doc/zmq.html @@ -0,0 +1,846 @@ + + + + + +zmq(7) + + + + + +
+

SYNOPSIS

+
+

#include <zmq.h>

+

cc [flags] files -lzmq [libraries]

+
+

DESCRIPTION

+
+

The ØMQ lightweight messaging kernel is a library which extends the standard +socket interfaces with features traditionally provided by specialised +messaging middleware products. ØMQ sockets provide an abstraction of +asynchronous message queues, multiple messaging patterns, message +filtering (subscriptions), seamless access to multiple transport protocols +and more.

+

This documentation presents an overview of ØMQ concepts, describes how ØMQ +abstracts standard sockets and provides a reference manual for the functions +provided by the ØMQ library.

+

Context

+

Before using any ØMQ library functions the caller must initialise a ØMQ +context using zmq_init(). The following functions are provided to handle +initialisation and termination of a context:

+
+
+Initialise ØMQ context +
+
+

+ zmq_init(3) +

+
+
+Terminate ØMQ context +
+
+

+ zmq_term(3) +

+
+
+

Thread safety

+

A ØMQ context is thread safe and may be shared among as many application +threads as necessary, without any additional locking required on the part of +the caller.

+

Individual ØMQ sockets are not thread safe except in the case where full +memory barriers are issued when migrating a socket from one thread to another. +In practice this means applications can create a socket in one thread with +zmq_socket() and then pass it to a newly created thread as part of thread +initialization, for example via a structure passed as an argument to +pthread_create().

+

Multiple contexts

+

Multiple contexts may coexist within a single application. Thus, an +application can use ØMQ directly and at the same time make use of any number of +additional libraries or components which themselves make use of ØMQ as long as +the above guidelines regarding thread safety are adhered to.

+

Messages

+

A ØMQ message is a discrete unit of data passed between applications or +components of the same application. ØMQ messages have no internal structure and +from the point of view of ØMQ itself they are considered to be opaque binary +data.

+

The following functions are provided to work with messages:

+
+
+Initialise a message +
+
+

+ zmq_msg_init(3) + zmq_msg_init_size(3) + zmq_msg_init_data(3) +

+
+
+Release a message +
+
+

+ zmq_msg_close(3) +

+
+
+Access message content +
+
+

+ zmq_msg_data(3) + zmq_msg_size(3) +

+
+
+Message manipulation +
+
+

+ zmq_msg_copy(3) + zmq_msg_move(3) +

+
+
+

Sockets

+

ØMQ sockets present an abstraction of a asynchronous message queue, with the +exact queueing semantics depending on the socket type in use. See +zmq_socket(3) for the socket types provided.

+

The following functions are provided to work with sockets:

+
+
+Creating a socket +
+
+

+ zmq_socket(3) +

+
+
+Closing a socket +
+
+

+ zmq_close(3) +

+
+
+Manipulating socket options +
+
+

+ zmq_getsockopt(3) + zmq_setsockopt(3) +

+
+
+Establishing a message flow +
+
+

+ zmq_bind(3) + zmq_connect(3) +

+
+
+Sending and receiving messages +
+
+

+ zmq_send(3) + zmq_recv(3) +

+
+
+
Input/output multiplexing

ØMQ provides a mechanism for applications to multiplex input/output events over +a set containing both ØMQ sockets and standard sockets. This mechanism mirrors +the standard poll() system call, and is described in detail in +zmq_poll(3).

+

Transports

+

A ØMQ socket can use multiple different underlying transport mechanisms. +Each transport mechanism is suited to a particular purpose and has its own +advantages and drawbacks.

+

The following transport mechanisms are provided:

+
+
+Unicast transport using TCP +
+
+

+ zmq_tcp(7) +

+
+
+Reliable multicast transport using PGM +
+
+

+ zmq_pgm(7) +

+
+
+Local inter-process communication transport +
+
+

+ zmq_ipc(7) +

+
+
+Local in-process (inter-thread) communication transport +
+
+

+ zmq_inproc(7) +

+
+
+

Devices

+

ØMQ provides devices, which are building blocks that act as intermediate +nodes in complex messaging topologies. Devices can act as brokers that other +nodes connect to, proxies that connect through to other nodes, or any mix of +these two models.

+

You can start a device in an application thread, see zmq_device(3).

+
+

ERROR HANDLING

+
+

The ØMQ library functions handle errors using the standard conventions found on +POSIX systems. Generally, this means that upon failure a ØMQ library function +shall return either a NULL value (if returning a pointer) or a negative value +(if returning an integer), and the actual error code shall be stored in the +errno variable.

+

On non-POSIX systems some users may experience issues with retrieving the +correct value of the errno variable. The zmq_errno() function is provided +to assist in these cases; for details refer to zmq_errno(3).

+

The zmq_strerror() function is provided to translate ØMQ-specific error codes +into error message strings; for details refer to zmq_strerror(3).

+
+

MISCELLANEOUS

+
+

The following miscellaneous functions are provided:

+
+
+Report ØMQ library version +
+
+

+ zmq_version(3) +

+
+
+
+

LANGUAGE BINDINGS

+
+

The ØMQ library provides interfaces suitable for calling from programs in any +language; this documentation documents those interfaces as they would be used +by C programmers. The intent is that programmers using ØMQ from other languages +shall refer to this documentation alongside any documentation provided by the +vendor of their language binding.

+

C++ language binding

+

The ØMQ distribution includes a C++ language binding, which is documented +separately in zmq_cpp(7).

+

Other language bindings

+

Other language bindings (Python, Ruby, Java and more) are provided by members +of the ØMQ community and pointers can be found on the ØMQ website.

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+

RESOURCES

+
+

Main web site: http://www.zeromq.org/

+

Report bugs to the ØMQ development mailing list: <zeromq-dev@lists.zeromq.org>

+
+

COPYING

+
+

Free use of this software is granted under the terms of the GNU Lesser General +Public License (LGPL). For details see the files COPYING and COPYING.LESSER +included with the ØMQ distribution.

+
+
+
+ + + diff --git a/doc/zmq_bind.3 b/doc/zmq_bind.3 index f4a637a..9ff1109 100644 --- a/doc/zmq_bind.3 +++ b/doc/zmq_bind.3 @@ -2,12 +2,12 @@ .\" Title: zmq_bind .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_BIND" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_BIND" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_bind.html b/doc/zmq_bind.html new file mode 100644 index 0000000..11b8762 --- /dev/null +++ b/doc/zmq_bind.html @@ -0,0 +1,746 @@ + + + + + +zmq_bind(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_bind (void *socket, const char *endpoint);

+
+

DESCRIPTION

+
+

The zmq_bind() function shall create an endpoint for accepting connections +and bind it to the socket referenced by the socket argument.

+

The endpoint argument is a string consisting of two parts as follows: +transport://address. The transport part specifies the underlying +transport protocol to use. The meaning of the address part is specific to +the underlying transport protocol selected.

+

The following transports are defined:

+
+
+inproc +
+
+

+local in-process (inter-thread) communication transport, see zmq_inproc(7) +

+
+
+ipc +
+
+

+local inter-process communication transport, see zmq_ipc(7) +

+
+
+tcp +
+
+

+unicast transport using TCP, see zmq_tcp(7) +

+
+
+pgm, epgm +
+
+

+reliable multicast transport using PGM, see zmq_pgm(7) +

+
+
+

With the exception of ZMQ_PAIR sockets, a single socket may be connected to +multiple endpoints using zmq_connect(), while simultaneously accepting +incoming connections from multiple endpoints bound to the socket using +zmq_bind(). Refer to zmq_socket(3) for a description of the exact +semantics involved when connecting or binding a socket to multiple endpoints.

+
+

RETURN VALUE

+
+

The zmq_bind() function shall return zero if successful. Otherwise it shall +return -1 and set errno to one of the values defined below.

+
+

ERRORS

+
+
+
+EPROTONOSUPPORT +
+
+

+The requested transport protocol is not supported. +

+
+
+ENOCOMPATPROTO +
+
+

+The requested transport protocol is not compatible with the socket type. +

+
+
+EADDRINUSE +
+
+

+The requested address is already in use. +

+
+
+EADDRNOTAVAIL +
+
+

+The requested address was not local. +

+
+
+ENODEV +
+
+

+The requested address specifies a nonexistent interface. +

+
+
+ETERM +
+
+

+The ØMQ context associated with the specified socket was terminated. +

+
+
+EFAULT +
+
+

+The provided socket was not valid (NULL). +

+
+
+EMTHREAD +
+
+

+No I/O thread is available to accomplish the task. +

+
+
+
+

EXAMPLE

+
+
+
Binding a publisher socket to an in-process and a TCP transport
+
+
/* Create a ZMQ_PUB socket */
+void *socket = zmq_socket (context, ZMQ_PUB);
+assert (socket);
+/* Bind it to a in-process transport with the address 'my_publisher' */
+int rc = zmq_bind (socket, "inproc://my_publisher");
+assert (rc == 0);
+/* Bind it to a TCP transport on port 5555 of the 'eth0' interface */
+rc = zmq_bind (socket, "tcp://eth0:5555");
+assert (rc == 0);
+
+
+

SEE ALSO

+
+

zmq_connect(3) +zmq_socket(3) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_close.3 b/doc/zmq_close.3 index 231ae96..520f0ac 100644 --- a/doc/zmq_close.3 +++ b/doc/zmq_close.3 @@ -2,12 +2,12 @@ .\" Title: zmq_close .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_CLOSE" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_CLOSE" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_close.html b/doc/zmq_close.html new file mode 100644 index 0000000..cc13445 --- /dev/null +++ b/doc/zmq_close.html @@ -0,0 +1,645 @@ + + + + + +zmq_close(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_close (void *socket);

+
+

DESCRIPTION

+
+

The zmq_close() function shall destroy the socket referenced by the socket +argument. Any outstanding messages physically received from the network but not +yet received by the application with zmq_recv() shall be discarded. The +behaviour for discarding messages sent by the application with zmq_send() but +not yet physically transferred to the network depends on the value of the +ZMQ_LINGER socket option for the specified socket.

+
+ + + +
+
Note
+		The default setting of ZMQ_LINGER does not discard unsent messages; +this behaviour may cause the application to block when calling zmq_term(). +For details refer to zmq_setsockopt(3) and zmq_term(3).
+
+
+

RETURN VALUE

+
+

The zmq_close() function shall return zero if successful. Otherwise it shall +return -1 and set errno to one of the values defined below.

+
+

ERRORS

+
+
+
+EFAULT +
+
+

+The provided socket was not valid (NULL). +

+
+
+
+

SEE ALSO

+
+

zmq_socket(3) +zmq_term(3) +zmq_setsockopt(3) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_connect.3 b/doc/zmq_connect.3 index 5305f76..06435e8 100644 --- a/doc/zmq_connect.3 +++ b/doc/zmq_connect.3 @@ -2,12 +2,12 @@ .\" Title: zmq_connect .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_CONNECT" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_CONNECT" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_connect.html b/doc/zmq_connect.html new file mode 100644 index 0000000..daa8fa0 --- /dev/null +++ b/doc/zmq_connect.html @@ -0,0 +1,732 @@ + + + + + +zmq_connect(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_connect (void *socket, const char *endpoint);

+
+

DESCRIPTION

+
+

The zmq_connect() function shall connect the socket referenced by the +socket argument to the endpoint specified by the endpoint argument.

+

The endpoint argument is a string consisting of two parts as follows: +transport://address. The transport part specifies the underlying +transport protocol to use. The meaning of the address part is specific to +the underlying transport protocol selected.

+

The following transports are defined:

+
+
+inproc +
+
+

+local in-process (inter-thread) communication transport, see zmq_inproc(7) +

+
+
+ipc +
+
+

+local inter-process communication transport, see zmq_ipc(7) +

+
+
+tcp +
+
+

+unicast transport using TCP, see zmq_tcp(7) +

+
+
+pgm, epgm +
+
+

+reliable multicast transport using PGM, see zmq_pgm(7) +

+
+
+

With the exception of ZMQ_PAIR sockets, a single socket may be connected to +multiple endpoints using zmq_connect(), while simultaneously accepting +incoming connections from multiple endpoints bound to the socket using +zmq_bind(). Refer to zmq_socket(3) for a description of the exact +semantics involved when connecting or binding a socket to multiple endpoints.

+
+ + + +
+
Note
+		The connection will not be performed immediately but as needed by ØMQ. +Thus a successful invocation of zmq_connect() does not indicate that a +physical connection was or can actually be established.
+
+
+

RETURN VALUE

+
+

The zmq_connect() function shall return zero if successful. Otherwise it +shall return -1 and set errno to one of the values defined below.

+
+

ERRORS

+
+
+
+EPROTONOSUPPORT +
+
+

+The requested transport protocol is not supported. +

+
+
+ENOCOMPATPROTO +
+
+

+The requested transport protocol is not compatible with the socket type. +

+
+
+ETERM +
+
+

+The ØMQ context associated with the specified socket was terminated. +

+
+
+EFAULT +
+
+

+The provided socket was not valid (NULL). +

+
+
+EMTHREAD +
+
+

+No I/O thread is available to accomplish the task. +

+
+
+
+

EXAMPLE

+
+
+
Connecting a subscriber socket to an in-process and a TCP transport
+
+
/* Create a ZMQ_SUB socket */
+void *socket = zmq_socket (context, ZMQ_SUB);
+assert (socket);
+/* Connect it to an in-process transport with the address 'my_publisher' */
+int rc = zmq_connect (socket, "inproc://my_publisher");
+assert (rc == 0);
+/* Connect it to the host server001, port 5555 using a TCP transport */
+rc = zmq_connect (socket, "tcp://server001:5555");
+assert (rc == 0);
+
+
+

SEE ALSO

+
+

zmq_bind(3) +zmq_socket(3) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_cpp.7 b/doc/zmq_cpp.7 index 2b0494e..c61797e 100644 --- a/doc/zmq_cpp.7 +++ b/doc/zmq_cpp.7 @@ -2,12 +2,12 @@ .\" Title: zmq_cpp .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_CPP" "7" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_CPP" "7" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_cpp.html b/doc/zmq_cpp.html new file mode 100644 index 0000000..31aea45 --- /dev/null +++ b/doc/zmq_cpp.html @@ -0,0 +1,765 @@ + + + + + +zmq_cpp(7) + + + + + +
+

SYNOPSIS

+
+

#include <zmq.hpp>

+

c++ [flags] files -lzmq [libraries]

+
+

DESCRIPTION

+
+

This manual page describes how the ØMQ C++ language binding maps to the +underlying ØMQ C library functions.

+

All ØMQ constants defined by zmq.h are also available to the C++ language +binding.

+

The following classes are provided in the zmq namespace:

+

Context

+

The context_t class encapsulates functionality dealing with the +initialisation and termination of a ØMQ context.

+

Constructor

+
+
context_t::context_t(int io_threads)
+
+
+

Maps to the zmq_init() function, as described in zmq_init(3).

+

Destructor

+
+
context_t::~context_t(void)
+
+
+

Maps to the zmq_term() function, as described in zmq_term(3).

+

Methods

+

None.

+

Socket

+

The socket_t class encapsulates a ØMQ socket.

+

Constructor

+
+
socket_t::socket_t(context_t &context, int type)
+
+
+

Maps to the zmq_socket() function, as described in zmq_socket(3).

+

Destructor

+
+
socket_t::~socket_t(void)
+
+
+

Calls the zmq_close() function, as described in zmq_close(3).

+

Methods

+
+
void socket_t::getsockopt(int option_name, void *option_value, size_t +*option_len)
+
+
+

Maps to the zmq_getsockopt() function, as described in +zmq_getsockopt(3).

+
+
void socket_t::setsockopt(int option_name, const void *option_value, size_t +option_len)
+
+
+

Maps to the zmq_setsockopt() function, as described in +zmq_setsockopt(3).

+
+
void socket_t::bind(const char *endpoint)
+
+
+

Maps to the zmq_bind() function, as described in zmq_bind(3).

+
+
void socket_t::connect(const char *endpoint)
+
+
+

Maps to the zmq_connect() function, as described in zmq_connect(3).

+
+
bool socket_t::send(message_t &msg, int flags = 0)
+
+
+

Maps to the zmq_send() function, as described in zmq_send(3). +Returns true if message is successfully sent, false if it is not.

+
+
bool socket_t::recv(message_t *msg, int flags = 0)
+
+
+

Maps to the zmq_recv() function, as described in zmq_recv(3). +Returns true if message is successfully received, false if it is not.

+

Message

+

The zmq::message_t class encapsulates the zmq_msg_t structure and +functions to construct, destruct and manipulate ØMQ messages.

+

Constructor

+
+
message_t::message_t(void) +message_t::message_t(size_t size) +message_t::message_t(void *data, size_t size, free_fn *ffn)
+
+
+

These map to the zmq_msg_init(), zmq_msg_init_size() and +zmq_msg_init_data() functions, described in zmq_msg_init(3), +zmq_msg_init_size(3) and zmq_msg_init_data(3) respectively.

+

Destructor

+
+
message_t::~message_t(void)
+
+
+

Calls the zmq_msg_close() function, as described in zmq_msg_close(3).

+

Methods

+
+
void *message_t::data (void)
+
+
+

Maps to the zmq_msg_data() function, as described in zmq_msg_data(3).

+
+
size_t message_t::size (void)
+
+
+

Maps to the zmq_msg_size() function, as described in zmq_msg_size(3).

+
+
void message_t::copy (message_t *src)
+
+
+

Maps to the zmq_msg_copy() function, as described in zmq_msg_copy(3).

+
+
void message_t::move (message_t *src)
+
+
+

Maps to the zmq_msg_move() function, as described in zmq_msg_move(3).

+
+
message_t::rebuild(void) +message_t::rebuild(size_t size) +message_t::rebuild(void *data, size_t size, free_fn *ffn)
+
+
+

Equivalent to calling the zmq_msg_close() function followed by the +corresponding zmq_msg_init() function.

+

Input/output multiplexing

+
+
int poll (zmq_pollitem_t *items, int nitems, long timeout = -1)
+
+
+

The poll() function is a namespaced equivalent of the zmq_poll() function, +as described in zmq_poll(3).

+
+ + + +
+
Note
+		To obtain a ØMQ socket for use in a zmq_pollitem_t structure, you +should cast an instance of the socket_t class to (void *).
+
+
+

ERROR HANDLING

+
+

All errors reported by the underlying ØMQ C library functions are automatically +converted to exceptions by the C++ language binding. The zmq::error_t class +is derived from the std::exception class and uses the zmq_strerror() +function to convert the error code to human-readable string.

+
+

EXAMPLE

+
+
+
+
zmq::context_t ctx (1);
+zmq::socket_t s (ctx, ZMQ_PUB);
+s.connect ("tcp://192.168.0.115:5555");
+zmq::message_t msg (100);
+memset (msg.data (), 0, 100);
+s.send (msg);
+
+
+

SEE ALSO

+
+

zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_device.3 b/doc/zmq_device.3 index e19c800..329360d 100644 --- a/doc/zmq_device.3 +++ b/doc/zmq_device.3 @@ -2,12 +2,12 @@ .\" Title: zmq_device .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_DEVICE" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_DEVICE" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_device.html b/doc/zmq_device.html new file mode 100644 index 0000000..21a2fbc --- /dev/null +++ b/doc/zmq_device.html @@ -0,0 +1,736 @@ + + + + + +zmq_device(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_device (int device, const void *frontend, const void *backend);

+
+

DESCRIPTION

+
+

The zmq_device() function starts a built-in ØMQ device. The device argument +is one of:

+
+
+ZMQ_QUEUE +
+
+

+ starts a queue device +

+
+
+ZMQ_FORWARDER +
+
+

+ starts a forwarder device +

+
+
+ZMQ_STREAMER +
+
+

+ starts a streamer device +

+
+
+

The device connects a frontend socket to a backend socket. Conceptually, data +flows from frontend to backend. Depending on the socket types, replies may flow +in the opposite direction.

+

Before calling zmq_device() you must set any socket options, and connect or +bind both frontend and backend sockets. The two conventional device models are:

+
+
+proxy +
+
+

+ bind frontend socket to an endpoint, and connect backend socket to + downstream components. A proxy device model does not require changes to + the downstream topology but that topology is static (any changes require + reconfiguring the device). +

+
+
+broker +
+
+

+ bind frontend socket to one endpoint and bind backend socket to a second + endpoint. Downstream components must now connect into the device. A broker + device model allows a dynamic downstream topology (components can come and + go at any time). +

+
+
+

zmq_device() runs in the current thread and returns only if/when the current +context is closed.

+
+

QUEUE DEVICE

+
+

ZMQ_QUEUE creates a shared queue that collects requests from a set of clients, +and distributes these fairly among a set of services. Requests are fair-queued +from frontend connections and load-balanced between backend connections. +Replies automatically return to the client that made the original request.

+

This device is part of the request-reply pattern. The frontend speaks to +clients and the backend speaks to services. You should use ZMQ_QUEUE with a +ZMQ_XREP socket for the frontend and a ZMQ_XREQ socket for the backend. +Other combinations are not documented.

+

Refer to zmq_socket(3) for a description of these socket types.

+
+

FORWARDER DEVICE

+
+

ZMQ_FORWARDER collects messages from a set of publishers and forwards these to +a set of subscribers. You will generally use this to bridge networks, e.g. read +on TCP unicast and forward on multicast.

+

This device is part of the publish-subscribe pattern. The frontend speaks to +publishers and the backend speaks to subscribers. You should use +ZMQ_FORWARDER with a ZMQ_SUB socket for the frontend and a ZMQ_PUB socket +for the backend. Other combinations are not documented.

+

Refer to zmq_socket(3) for a description of these socket types.

+
+

STREAMER DEVICE

+
+

ZMQ_STREAMER collects tasks from a set of pushers and forwards these to a set +of pullers. You will generally use this to bridge networks. Messages are +fair-queued from pushers and load-balanced to pullers.

+

This device is part of the pipeline pattern. The frontend speaks to pushers +and the backend speaks to pullers. You should use ZMQ_STREAMER with a +ZMQ_PULL socket for the frontend and a ZMQ_PUSH socket for the backend. +Other combinations are not documented.

+

Refer to zmq_socket(3) for a description of these socket types.

+
+

RETURN VALUE

+
+

The zmq_device() function always returns -1 and errno set to ETERM (the +ØMQ context associated with either of the specified sockets was terminated).

+
+

EXAMPLE

+
+
+
Creating a queue broker
+
+
//  Create frontend and backend sockets
+void *frontend = zmq_socket (context, ZMQ_XREP);
+assert (backend);
+void *backend = zmq_socket (context, ZMQ_XREQ);
+assert (frontend);
+//  Bind both sockets to TCP ports
+assert (zmq_bind (frontend, "tcp://*:5555") == 0);
+assert (zmq_bind (backend, "tcp://*:5556") == 0);
+//  Start a queue device
+zmq_device (ZMQ_QUEUE, frontend, backend);
+
+
+

SEE ALSO

+
+

zmq_bind(3) +zmq_connect(3) +zmq_socket(3) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Pieter Hintjens <ph@imatix.com>

+
+

RESOURCES

+
+

Main web site: http://www.zeromq.org/

+

Report bugs to the ØMQ development mailing list: <zeromq-dev@lists.zeromq.org>

+
+

COPYING

+
+

Free use of this software is granted under the terms of the GNU Lesser General +Public License (LGPL). For details see the files COPYING and COPYING.LESSER +included with the ØMQ distribution.

+
+
+
+ + + diff --git a/doc/zmq_epgm.7 b/doc/zmq_epgm.7 index 06cc456..1559950 100644 --- a/doc/zmq_epgm.7 +++ b/doc/zmq_epgm.7 @@ -2,12 +2,12 @@ .\" Title: zmq_pgm .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_PGM" "7" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_PGM" "7" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_epgm.html b/doc/zmq_epgm.html new file mode 100644 index 0000000..5506fa1 --- /dev/null +++ b/doc/zmq_epgm.html @@ -0,0 +1,745 @@ + + + + + +zmq_pgm(7) + + + + + +
+

SYNOPSIS

+
+

PGM (Pragmatic General Multicast) is a protocol for reliable multicast +transport of data over IP networks.

+
+

DESCRIPTION

+
+

ØMQ implements two variants of PGM, the standard protocol where PGM datagrams +are layered directly on top of IP datagrams as defined by RFC 3208 (the pgm +transport) and "Encapsulated PGM" where PGM datagrams are encapsulated inside +UDP datagrams (the epgm transport).

+

The pgm and epgm transports can only be used with the ZMQ_PUB and +ZMQ_SUB socket types.

+

Further, PGM sockets are rate limited by default and incur a performance +penalty when used over a loop-back interface. For details, refer to the +ZMQ_RATE, ZMQ_RECOVERY_IVL and ZMQ_MCAST_LOOP options documented in +zmq_setsockopt(3).

+
+ + + +
+
Caution
+		The pgm transport implementation requires access to raw IP sockets. +Additional privileges may be required on some operating systems for this +operation. Applications not requiring direct interoperability with other PGM +implementations are encouraged to use the epgm transport instead which does +not require any special privileges.
+
+
+

ADDRESSING

+
+

A ØMQ address string consists of two parts as follows: +transport://endpoint. The transport part specifies the underlying +transport protocol to use. For the standard PGM protocol, transport shall be +set to pgm. For the "Encapsulated PGM" protocol transport shall be set to +epgm. The meaning of the endpoint part for both the pgm and epgm +transport is defined below.

+

Connecting a socket

+

When connecting a socket to a peer address using zmq_connect() with the pgm +or epgm transport, the endpoint shall be interpreted as an interface +followed by a semicolon, followed by a multicast address, followed by a colon +and a port number.

+

An interface may be specified by either of the following:

+
    +
  • +

    +The interface name as defined by the operating system. +

    +
    • +
  • +

    +The primary IPv4 address assigned to the interface, in it’s numeric + representation. +

    +
    • +
+
+ + + +
+
Note
+		Interface names are not standardised in any way and should be assumed to +be arbitrary and platform dependent. On Win32 platforms no short interface +names exist, thus only the primary IPv4 address may be used to specify an +interface.
+
+

A multicast address is specified by an IPv4 multicast address in it’s numeric +representation.

+
+

WIRE FORMAT

+
+

Consecutive PGM datagrams are interpreted by ØMQ as a single continuous stream +of data where ØMQ messages are not necessarily aligned with PGM datagram +boundaries and a single ØMQ message may span several PGM datagrams. This stream +of data consists of ØMQ messages encapsulated in frames as described in +zmq_tcp(7).

+

PGM datagram payload

+

The following ABNF grammar represents the payload of a single PGM datagram as +used by ØMQ:

+
+
+
datagram               = (offset data)
+offset                 = 2OCTET
+data                   = *OCTET
+
+

In order for late joining consumers to be able to identify message boundaries, +each PGM datagram payload starts with a 16-bit unsigned integer in network byte +order specifying either the offset of the first message frame in the datagram +or containing the value 0xFFFF if the datagram contains solely an +intermediate part of a larger message.

+

The following diagram illustrates the layout of a single PGM datagram payload:

+
+
+
+------------------+----------------------+
+| offset (16 bits) |         data         |
++------------------+----------------------+
+
+

The following diagram further illustrates how three example ØMQ frames are laid +out in consecutive PGM datagram payloads:

+
+
+
First datagram payload
++--------------+-------------+---------------------+
+| Frame offset |   Frame 1   |   Frame 2, part 1   |
+|    0x0000    | (Message 1) | (Message 2, part 1) |
++--------------+-------------+---------------------+
+
+Second datagram payload
++--------------+---------------------+
+| Frame offset |   Frame 2, part 2   |
+| 0xFFFF       | (Message 2, part 2) |
++--------------+---------------------+
+
+Third datagram payload
++--------------+----------------------------+-------------+
+| Frame offset |   Frame 2, final 8 bytes   |   Frame 3   |
+| 0x0008       | (Message 2, final 8 bytes) | (Message 3) |
++--------------+----------------------------+-------------+
+
+
+

EXAMPLE

+
+
+
Connecting a socket
+
+
/* Connecting to the multicast address 239.192.1.1, port 5555, */
+/* using the first Ethernet network interface on Linux */
+/* and the Encapsulated PGM protocol */
+rc = zmq_connect(socket, "epgm://eth0;239.192.1.1:5555");
+assert (rc == 0);
+/* Connecting to the multicast address 239.192.1.1, port 5555, */
+/* using the network interface with the address 192.168.1.1 */
+/* and the standard PGM protocol */
+rc = zmq_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555");
+assert (rc == 0);
+
+
+

SEE ALSO

+
+

zmq_connect(3) +zmq_setsockopt(3) +zmq_tcp(7) +zmq_ipc(7) +zmq_inproc(7) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_errno.3 b/doc/zmq_errno.3 index 9e9a688..407ca79 100644 --- a/doc/zmq_errno.3 +++ b/doc/zmq_errno.3 @@ -2,12 +2,12 @@ .\" Title: zmq_errno .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_ERRNO" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_ERRNO" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_errno.html b/doc/zmq_errno.html new file mode 100644 index 0000000..b84c35b --- /dev/null +++ b/doc/zmq_errno.html @@ -0,0 +1,634 @@ + + + + + +zmq_errno(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_errno (void);

+
+

DESCRIPTION

+
+

The zmq_errno() function shall retrieve the value of the errno variable for +the calling thread.

+

The zmq_errno() function is provided to assist users on non-POSIX systems who +are experiencing issues with retrieving the correct value of errno directly. +Specifically, users on Win32 systems whose application is using a different C +run-time library from the C run-time library in use by ØMQ will need to use +zmq_errno() for correct operation.

+
+ + + +
+
Important
+		Users not experiencing issues with retrieving the correct value of +errno should not use this function and should instead access the errno +variable directly.
+
+
+

RETURN VALUE

+
+

The zmq_errno() function shall return the value of the errno variable for +the calling thread.

+
+

ERRORS

+
+

No errors are defined.

+
+

SEE ALSO

+
+

zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_getsockopt.3 b/doc/zmq_getsockopt.3 index 9ab4ec9..774dca8 100644 --- a/doc/zmq_getsockopt.3 +++ b/doc/zmq_getsockopt.3 @@ -2,12 +2,12 @@ .\" Title: zmq_getsockopt .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_GETSOCKOPT" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_GETSOCKOPT" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_getsockopt.html b/doc/zmq_getsockopt.html new file mode 100644 index 0000000..1c8af72 --- /dev/null +++ b/doc/zmq_getsockopt.html @@ -0,0 +1,1713 @@ + + + + + +zmq_getsockopt(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_getsockopt (void *socket, int option_name, void *option_value, size_t *option_len);

+
+

DESCRIPTION

+
+

The zmq_getsockopt() function shall retrieve the value for the option +specified by the option_name argument for the ØMQ socket pointed to by the +socket argument, and store it in the buffer pointed to by the option_value +argument. The option_len argument is the size in bytes of the buffer pointed +to by option_value; upon successful completion zmq_getsockopt() shall +modify the option_len argument to indicate the actual size of the option +value stored in the buffer.

+

The following options can be retrieved with the zmq_getsockopt() function:

+

ZMQ_TYPE: Retrieve socket type

+

The ZMQ_TYPE option shall retrieve the socket type for the specified +socket. The socket type is specified at socket creation time and +cannot be modified afterwards.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int +

+
+Option value unit +
+		 +

+N/A +

+
+Default value +
+		 +

+N/A +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_RCVMORE: More message parts to follow

+

The ZMQ_RCVMORE option shall return a boolean value indicating if the +multi-part message currently being read from the specified socket has more +message parts to follow. If there are no message parts to follow or if the +message currently being read is not a multi-part message a value of zero shall +be returned. Otherwise, a value of 1 shall be returned.

+

Refer to zmq_send(3) and zmq_recv(3) for a detailed description +of sending/receiving multi-part messages.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int64_t +

+
+Option value unit +
+		 +

+boolean +

+
+Default value +
+		 +

+N/A +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_HWM: Retrieve high water mark

+

The ZMQ_HWM option shall retrieve the high water mark for the specified +socket. The high water mark is a hard limit on the maximum number of +outstanding messages ØMQ shall queue in memory for any single peer that the +specified socket is communicating with.

+

If this limit has been reached the socket shall enter an exceptional state and +depending on the socket type, ØMQ shall take appropriate action such as +blocking or dropping sent messages. Refer to the individual socket descriptions +in zmq_socket(3) for details on the exact action taken for each socket +type.

+

The default ZMQ_HWM value of zero means "no limit".

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+uint64_t +

+
+Option value unit +
+		 +

+messages +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_SWAP: Retrieve disk offload size

+

The ZMQ_SWAP option shall retrieve the disk offload (swap) size for the +specified socket. A socket which has ZMQ_SWAP set to a non-zero value may +exceed it’s high water mark; in this case outstanding messages shall be +offloaded to storage on disk rather than held in memory.

+

The value of ZMQ_SWAP defines the maximum size of the swap space in bytes.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int64_t +

+
+Option value unit +
+		 +

+bytes +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_AFFINITY: Retrieve I/O thread affinity

+

The ZMQ_AFFINITY option shall retrieve the I/O thread affinity for newly +created connections on the specified socket.

+

Affinity determines which threads from the ØMQ I/O thread pool associated with +the socket’s context shall handle newly created connections. A value of zero +specifies no affinity, meaning that work shall be distributed fairly among all +ØMQ I/O threads in the thread pool. For non-zero values, the lowest bit +corresponds to thread 1, second lowest bit to thread 2 and so on. For example, +a value of 3 specifies that subsequent connections on socket shall be handled +exclusively by I/O threads 1 and 2.

+

See also zmq_init(3) for details on allocating the number of I/O +threads for a specific context.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+uint64_t +

+
+Option value unit +
+		 +

+N/A (bitmap) +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+N/A +

+
+

ZMQ_IDENTITY: Retrieve socket identity

+

The ZMQ_IDENTITY option shall retrieve the identity of the specified +socket. Socket identity determines if existing ØMQ infrastructure (message +queues, forwarding devices) shall be identified with a specific application +and persist across multiple runs of the application.

+

If the socket has no identity, each run of an application is completely +separate from other runs. However, with identity set the socket shall re-use +any existing ØMQ infrastructure configured by the previous run(s). Thus the +application may receive messages that were sent in the meantime, message +queue limits shall be shared with previous run(s) and so on.

+

Identity can be at least one byte and at most 255 bytes long. Identities +starting with binary zero are reserved for use by ØMQ infrastructure.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+binary data +

+
+Option value unit +
+		 +

+N/A +

+
+Default value +
+		 +

+NULL +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_RATE: Retrieve multicast data rate

+

The ZMQ_RATE option shall retrieve the maximum send or receive data rate for +multicast transports using the specified socket.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int64_t +

+
+Option value unit +
+		 +

+kilobits per second +

+
+Default value +
+		 +

+100 +

+
+Applicable socket types +
+		 +

+all, when using multicast transports +

+
+

ZMQ_RECOVERY_IVL: Get multicast recovery interval

+

The ZMQ_RECOVERY_IVL option shall retrieve the recovery interval for +multicast transports using the specified socket. The recovery interval +determines the maximum time in seconds that a receiver can be absent from a +multicast group before unrecoverable data loss will occur.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int64_t +

+
+Option value unit +
+		 +

+seconds +

+
+Default value +
+		 +

+10 +

+
+Applicable socket types +
+		 +

+all, when using multicast transports +

+
+

ZMQ_RECOVERY_IVL_MSEC: Get multicast recovery interval in milliseconds

+

The ZMQ_RECOVERY_IVL’_MSEC option shall retrieve the recovery interval, in +milliseconds, for multicast transports using the specified 'socket. The +recovery interval determines the maximum time in seconds that a receiver +can be absent from a multicast group before unrecoverable data loss will +occur.

+

For backward compatibility, the default value of ZMQ_RECOVERY_IVL_MSEC is +-1 indicating that the recovery interval should be obtained from the +ZMQ_RECOVERY_IVL option. However, if the ZMQ_RECOVERY_IVL_MSEC value is +not zero, then it will take precedence, and be used.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int64_t +

+
+Option value unit +
+		 +

+milliseconds +

+
+Default value +
+		 +

+-1 +

+
+Applicable socket types +
+		 +

+all, when using multicast transports +

+
+

ZMQ_MCAST_LOOP: Control multicast loop-back

+

The ZMQ_MCAST_LOOP option controls whether data sent via multicast +transports can also be received by the sending host via loop-back. A value of +zero indicates that the loop-back functionality is disabled, while the default +value of 1 indicates that the loop-back functionality is enabled. Leaving +multicast loop-back enabled when it is not required can have a negative impact +on performance. Where possible, disable ZMQ_MCAST_LOOP in production +environments.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int64_t +

+
+Option value unit +
+		 +

+boolean +

+
+Default value +
+		 +

+1 +

+
+Applicable socket types +
+		 +

+all, when using multicast transports +

+
+

ZMQ_SNDBUF: Retrieve kernel transmit buffer size

+

The ZMQ_SNDBUF option shall retrieve the underlying kernel transmit buffer +size for the specified socket. A value of zero means that the OS default is +in effect. For details refer to your operating system documentation for the +SO_SNDBUF socket option.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+uint64_t +

+
+Option value unit +
+		 +

+bytes +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_RCVBUF: Retrieve kernel receive buffer size

+

The ZMQ_RCVBUF option shall retrieve the underlying kernel receive buffer +size for the specified socket. A value of zero means that the OS default is +in effect. For details refer to your operating system documentation for the +SO_RCVBUF socket option.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+uint64_t +

+
+Option value unit +
+		 +

+bytes +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_LINGER: Retrieve linger period for socket shutdown

+

The ZMQ_LINGER option shall retrieve the linger period for the specified +socket. The linger period determines how long pending messages which have +yet to be sent to a peer shall linger in memory after a socket is closed with +zmq_close(3), and further affects the termination of the socket’s +context with zmq_term(3). The following outlines the different +behaviours:

+
    +
  • +

    +The default value of -1 specifies an infinite linger period. Pending + messages shall not be discarded after a call to zmq_close(); attempting to + terminate the socket’s context with zmq_term() shall block until all + pending messages have been sent to a peer. +

    +
    • +
  • +

    +The value of 0 specifies no linger period. Pending messages shall be + discarded immediately when the socket is closed with zmq_close(). +

    +
    • +
  • +

    +Positive values specify an upper bound for the linger period in milliseconds. + Pending messages shall not be discarded after a call to zmq_close(); + attempting to terminate the socket’s context with zmq_term() shall block + until either all pending messages have been sent to a peer, or the linger + period expires, after which any pending messages shall be discarded. +

    +
    + + + + + + + + + + + + + + + + +
    +Option value type +
    +    		 +

    +int +

    +
    +Option value unit +
    +    		 +

    +milliseconds +

    +
    +Default value +
    +    		 +

    +-1 (infinite) +

    +
    +Applicable socket types +
    +    		 +

    +all +

    +
    +
    • +
+

ZMQ_RECONNECT_IVL: Retrieve reconnection interval

+

The ZMQ_RECONNECT_IVL option shall retrieve the initial reconnection interval +for the specified socket. The reconnection interval is the period ØMQ shall +wait between attempts to reconnect disconnected peers when using +connection-oriented transports.

+
+ + + +
+
Note
+		The reconnection interval may be randomized by ØMQ to prevent +reconnection storms in topologies with a large number of peers per socket.
+
+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int +

+
+Option value unit +
+		 +

+milliseconds +

+
+Default value +
+		 +

+100 +

+
+Applicable socket types +
+		 +

+all, only for connection-oriented transports +

+
+

ZMQ_RECONNECT_IVL_MAX: Retrieve maximum reconnection interval

+

The ZMQ_RECONNECT_IVL_MAX option shall retrieve the maximum reconnection +interval for the specified socket. This is the maximum period ØMQ shall wait +between attempts to reconnect. On each reconnect attempt, the previous interval +shall be doubled untill ZMQ_RECONNECT_IVL_MAX is reached. This allows for +exponential backoff strategy. Default value means no exponential backoff is +performed and reconnect interval calculations are only based on ZMQ_RECONNECT_IVL.

+
+ + + +
+
Note
+		Values less than ZMQ_RECONNECT_IVL will be ignored.
+
+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int +

+
+Option value unit +
+		 +

+milliseconds +

+
+Default value +
+		 +

+0 (only use ZMQ_RECONNECT_IVL) +

+
+Applicable socket types +
+		 +

+all, only for connection-oriented transport +

+
+

ZMQ_BACKLOG: Retrieve maximum length of the queue of outstanding connections

+

The ZMQ_BACKLOG option shall retrieve the maximum length of the queue of +outstanding peer connections for the specified socket; this only applies to +connection-oriented transports. For details refer to your operating system +documentation for the listen function.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int +

+
+Option value unit +
+		 +

+connections +

+
+Default value +
+		 +

+100 +

+
+Applicable socket types +
+		 +

+all, only for connection-oriented transports +

+
+

ZMQ_FD: Retrieve file descriptor associated with the socket

+

The ZMQ_FD option shall retrieve the file descriptor associated with the +specified socket. The returned file descriptor can be used to integrate the +socket into an existing event loop; the ØMQ library shall signal any pending +events on the socket in an edge-triggered fashion by making the file +descriptor become ready for reading.

+
+ + + +
+
Note
+		The ability to read from the returned file descriptor does not +necessarily indicate that messages are available to be read from, or can be +written to, the underlying socket; applications must retrieve the actual event +state with a subsequent retrieval of the ZMQ_EVENTS option.
+
+
+ + + +
+
Caution
+		The returned file descriptor is intended for use with a poll or +similar system call only. Applications must never attempt to read or write data +to it directly, neither should they try to close it.
+
+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int on POSIX systems, SOCKET on Windows +

+
+Option value unit +
+		 +

+N/A +

+
+Default value +
+		 +

+N/A +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_EVENTS: Retrieve socket event state

+

The ZMQ_EVENTS option shall retrieve the event state for the specified +socket. The returned value is a bit mask constructed by OR’ing a combination +of the following event flags:

+
+
+ZMQ_POLLIN +
+
+

+Indicates that at least one message may be received from the specified socket +without blocking. +

+
+
+ZMQ_POLLOUT +
+
+

+Indicates that at least one message may be sent to the specified socket without +blocking. +

+
+
+

The combination of a file descriptor returned by the ZMQ_FD option being +ready for reading but no actual events returned by a subsequent retrieval of +the ZMQ_EVENTS option is valid; applications should simply ignore this case +and restart their polling operation/event loop.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+uint32_t +

+
+Option value unit +
+		 +

+N/A (flags) +

+
+Default value +
+		 +

+N/A +

+
+Applicable socket types +
+		 +

+all +

+
+
+

RETURN VALUE

+
+

The zmq_getsockopt() function shall return zero if successful. Otherwise it +shall return -1 and set errno to one of the values defined below.

+
+

ERRORS

+
+
+
+EINVAL +
+
+

+The requested option option_name is unknown, or the requested option_len or +option_value is invalid, or the size of the buffer pointed to by +option_value, as specified by option_len, is insufficient for storing the +option value. +

+
+
+ETERM +
+
+

+The ØMQ context associated with the specified socket was terminated. +

+
+
+EFAULT +
+
+

+The provided socket was not valid (NULL). +

+
+
+EINTR +
+
+

+The operation was interrupted by delivery of a signal. +

+
+
+
+

EXAMPLE

+
+
+
Retrieving the high water mark
+
+
/* Retrieve high water mark into hwm */
+int64_t hwm;
+size_t hwm_size = sizeof (hwm);
+rc = zmq_getsockopt (socket, ZMQ_HWM, &hwm, &hwm_size);
+assert (rc == 0);
+
+
+

SEE ALSO

+
+

zmq_setsockopt(3) +zmq_socket(3) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_init.3 b/doc/zmq_init.3 index 12fbe75..d52d393 100644 --- a/doc/zmq_init.3 +++ b/doc/zmq_init.3 @@ -2,12 +2,12 @@ .\" Title: zmq_init .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_INIT" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_INIT" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_init.html b/doc/zmq_init.html new file mode 100644 index 0000000..17f2614 --- /dev/null +++ b/doc/zmq_init.html @@ -0,0 +1,635 @@ + + + + + +zmq_init(3) + + + + + +
+

SYNOPSIS

+
+

void *zmq_init (int io_threads);

+
+

DESCRIPTION

+
+

The zmq_init() function initialises a ØMQ context.

+

The io_threads argument specifies the size of the ØMQ thread pool to handle +I/O operations. If your application is using only the inproc transport for +messaging you may set this to zero, otherwise set it to at least one.

+
Thread safety

A ØMQ context is thread safe and may be shared among as many application +threads as necessary, without any additional locking required on the part of +the caller.

+
+

RETURN VALUE

+
+

The zmq_init() function shall return an opaque handle to the initialised +context if successful. Otherwise it shall return NULL and set errno to one +of the values defined below.

+
+

ERRORS

+
+
+
+EINVAL +
+
+

+An invalid number of io_threads was requested. +

+
+
+
+

SEE ALSO

+
+

zmq(7) +zmq_term(3)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_inproc.7 b/doc/zmq_inproc.7 index a6839e3..830d1fa 100644 --- a/doc/zmq_inproc.7 +++ b/doc/zmq_inproc.7 @@ -2,12 +2,12 @@ .\" Title: zmq_inproc .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_INPROC" "7" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_INPROC" "7" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_inproc.html b/doc/zmq_inproc.html new file mode 100644 index 0000000..6bc6959 --- /dev/null +++ b/doc/zmq_inproc.html @@ -0,0 +1,669 @@ + + + + + +zmq_inproc(7) + + + + + +
+

SYNOPSIS

+
+

The in-process transport passes messages via memory directly between threads +sharing a single ØMQ context.

+
+ + + +
+
Note
+		No I/O threads are involved in passing messages using the inproc +transport. Therefore, if you are using a ØMQ context for in-process messaging +only you can initialise the context with zero I/O threads. See +zmq_init(3) for details.
+
+
+

ADDRESSING

+
+

A ØMQ address string consists of two parts as follows: +transport://endpoint. The transport part specifies the underlying +transport protocol to use, and for the in-process transport shall be set to +inproc. The meaning of the endpoint part for the in-process transport is +defined below.

+

Assigning a local address to a socket

+

When assigning a local address to a socket using zmq_bind() with the +inproc transport, the endpoint shall be interpreted as an arbitrary string +identifying the name to create. The name must be unique within the ØMQ +context associated with the socket and may be up to 256 characters in +length. No other restrictions are placed on the format of the name.

+

Connecting a socket

+

When connecting a socket to a peer address using zmq_connect() with the +inproc transport, the endpoint shall be interpreted as an arbitrary string +identifying the name to connect to. The name must have been previously +created by assigning it to at least one socket within the same ØMQ context +as the socket being connected.

+
+

WIRE FORMAT

+
+

Not applicable.

+
+

EXAMPLES

+
+
+
Assigning a local address to a socket
+
+
/* Assign the in-process name "#1" */
+rc = zmq_bind(socket, "inproc://#1");
+assert (rc == 0);
+/* Assign the in-process name "my-endpoint" */
+rc = zmq_bind(socket, "inproc://my-endpoint");
+assert (rc == 0);
+
+
+
Connecting a socket
+
+
/* Connect to the in-process name "#1" */
+rc = zmq_connect(socket, "inproc://#1");
+assert (rc == 0);
+/* Connect to the in-process name "my-endpoint" */
+rc = zmq_connect(socket, "inproc://my-endpoint");
+assert (rc == 0);
+
+
+

SEE ALSO

+
+

zmq_bind(3) +zmq_connect(3) +zmq_ipc(7) +zmq_tcp(7) +zmq_pgm(7) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_ipc.7 b/doc/zmq_ipc.7 index 0d20a4a..a0ef8bd 100644 --- a/doc/zmq_ipc.7 +++ b/doc/zmq_ipc.7 @@ -2,12 +2,12 @@ .\" Title: zmq_ipc .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_IPC" "7" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_IPC" "7" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_ipc.html b/doc/zmq_ipc.html new file mode 100644 index 0000000..f07b58a --- /dev/null +++ b/doc/zmq_ipc.html @@ -0,0 +1,662 @@ + + + + + +zmq_ipc(7) + + + + + +
+

SYNOPSIS

+
+

The inter-process transport passes messages between local processes using a +system-dependent IPC mechanism.

+
+ + + +
+
Note
+		The inter-process transport is currently only implemented on operating +systems that provide UNIX domain sockets.
+
+
+

ADDRESSING

+
+

A ØMQ address string consists of two parts as follows: +transport://endpoint. The transport part specifies the underlying +transport protocol to use, and for the inter-process transport shall be set to +ipc. The meaning of the endpoint part for the inter-process transport is +defined below.

+

Assigning a local address to a socket

+

When assigning a local address to a socket using zmq_bind() with the ipc +transport, the endpoint shall be interpreted as an arbitrary string +identifying the pathname to create. The pathname must be unique within the +operating system namespace used by the ipc implementation, and must fulfill +any restrictions placed by the operating system on the format and length of a +pathname.

+

Connecting a socket

+

When connecting a socket to a peer address using zmq_connect() with the +ipc transport, the endpoint shall be interpreted as an arbitrary string +identifying the pathname to connect to. The pathname must have been +previously created within the operating system namespace by assigning it to a +socket with zmq_bind().

+
+

WIRE FORMAT

+
+

Not applicable.

+
+

EXAMPLES

+
+
+
Assigning a local address to a socket
+
+
/* Assign the pathname "/tmp/feeds/0" */
+rc = zmq_bind(socket, "ipc:///tmp/feeds/0");
+assert (rc == 0);
+
+
+
Connecting a socket
+
+
/* Connect to the pathname "/tmp/feeds/0" */
+rc = zmq_connect(socket, "ipc:///tmp/feeds/0");
+assert (rc == 0);
+
+
+

SEE ALSO

+
+

zmq_bind(3) +zmq_connect(3) +zmq_inproc(7) +zmq_tcp(7) +zmq_pgm(7) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_msg_close.3 b/doc/zmq_msg_close.3 index 1e7cdae..76d5cb8 100644 --- a/doc/zmq_msg_close.3 +++ b/doc/zmq_msg_close.3 @@ -2,12 +2,12 @@ .\" Title: zmq_msg_close .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_MSG_CLOSE" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_MSG_CLOSE" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_msg_close.html b/doc/zmq_msg_close.html new file mode 100644 index 0000000..7942587 --- /dev/null +++ b/doc/zmq_msg_close.html @@ -0,0 +1,638 @@ + + + + + +zmq_msg_close(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_msg_close (zmq_msg_t *msg);

+
+

DESCRIPTION

+
+

The zmq_msg_close() function shall inform the ØMQ infrastructure that any +resources associated with the message object referenced by msg are no longer +required and may be released. Actual release of resources associated with the +message object shall be postponed by ØMQ until all users of the message or +underlying data buffer have indicated it is no longer required.

+

Applications should ensure that zmq_msg_close() is called once a message is +no longer required, otherwise memory leaks may occur.

+
+ + + +
+
Caution
+		Never access zmq_msg_t members directly, instead always use the +zmq_msg family of functions.
+
+
+

RETURN VALUE

+
+

The zmq_msg_close() function shall return zero if successful. Otherwise +it shall return -1 and set errno to one of the values defined below.

+
+

ERRORS

+
+

No errors are defined.

+
+

SEE ALSO

+
+

zmq_msg_init(3) +zmq_msg_init_size(3) +zmq_msg_init_data(3) +zmq_msg_data(3) +zmq_msg_size(3) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_msg_copy.3 b/doc/zmq_msg_copy.3 index 9fc0f7e..2471cdc 100644 --- a/doc/zmq_msg_copy.3 +++ b/doc/zmq_msg_copy.3 @@ -2,12 +2,12 @@ .\" Title: zmq_msg_copy .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_MSG_COPY" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_MSG_COPY" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_msg_copy.html b/doc/zmq_msg_copy.html new file mode 100644 index 0000000..5017c3c --- /dev/null +++ b/doc/zmq_msg_copy.html @@ -0,0 +1,647 @@ + + + + + +zmq_msg_copy(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_msg_copy (zmq_msg_t *dest, zmq_msg_t *src);

+
+

DESCRIPTION

+
+

The zmq_msg_copy() function shall copy the message object referenced by src +to the message object referenced by dest. The original content of dest, if +any, shall be released.

+
+ + + +
+
Caution
+		The implementation may choose not to physically copy the message +content, rather to share the underlying buffer between src and dest. Avoid +modifying message content after a message has been copied with +zmq_msg_copy(), doing so can result in undefined behaviour. If what you need +is an actual hard copy, allocate a new message using zmq_msg_init_size() and +copy the message content using memcpy().
+
+
+ + + +
+
Caution
+		Never access zmq_msg_t members directly, instead always use the +zmq_msg family of functions.
+
+
+

RETURN VALUE

+
+

The zmq_msg_copy() function shall return zero if successful. Otherwise it +shall return -1 and set errno to one of the values defined below.

+
+

ERRORS

+
+

No errors are defined.

+
+

SEE ALSO

+
+

zmq_msg_move(3) +zmq_msg_init(3) +zmq_msg_init_size(3) +zmq_msg_init_data(3) +zmq_msg_close(3) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_msg_data.3 b/doc/zmq_msg_data.3 index a2d31a4..6470f6b 100644 --- a/doc/zmq_msg_data.3 +++ b/doc/zmq_msg_data.3 @@ -2,12 +2,12 @@ .\" Title: zmq_msg_data .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_MSG_DATA" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_MSG_DATA" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_msg_data.html b/doc/zmq_msg_data.html new file mode 100644 index 0000000..dbce1bc --- /dev/null +++ b/doc/zmq_msg_data.html @@ -0,0 +1,633 @@ + + + + + +zmq_msg_data(3) + + + + + +
+

SYNOPSIS

+
+

void *zmq_msg_data (zmq_msg_t *msg);

+
+

DESCRIPTION

+
+

The zmq_msg_data() function shall return a pointer to the message content of +the message object referenced by msg.

+
+ + + +
+
Caution
+		Never access zmq_msg_t members directly, instead always use the +zmq_msg family of functions.
+
+
+

RETURN VALUE

+
+

Upon successful completion, zmq_msg_data() shall return a pointer to the +message content.

+
+

ERRORS

+
+

No errors are defined.

+
+

SEE ALSO

+
+

zmq_msg_size(3) +zmq_msg_init(3) +zmq_msg_init_size(3) +zmq_msg_init_data(3) +zmq_msg_close(3) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_msg_init.3 b/doc/zmq_msg_init.3 index dc080dd..f4cc7c7 100644 --- a/doc/zmq_msg_init.3 +++ b/doc/zmq_msg_init.3 @@ -2,12 +2,12 @@ .\" Title: zmq_msg_init .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_MSG_INIT" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_MSG_INIT" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_msg_init.html b/doc/zmq_msg_init.html new file mode 100644 index 0000000..227b6df --- /dev/null +++ b/doc/zmq_msg_init.html @@ -0,0 +1,656 @@ + + + + + +zmq_msg_init(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_msg_init (zmq_msg_t *msg);

+
+

DESCRIPTION

+
+

The zmq_msg_init() function shall initialise the message object referenced by +msg to represent an empty message. This function is most useful when called +before receiving a message with zmq_recv().

+
+ + + +
+
Caution
+		Never access zmq_msg_t members directly, instead always use the +zmq_msg family of functions.
+
+
+ + + +
+
Caution
+		The functions zmq_msg_init(), zmq_msg_init_data() and +zmq_msg_init_size() are mutually exclusive. Never initialize the same +zmq_msg_t twice.
+
+
+

RETURN VALUE

+
+

The zmq_msg_init() function shall return zero if successful. Otherwise it +shall return -1 and set errno to one of the values defined below.

+
+

ERRORS

+
+

No errors are defined.

+
+

EXAMPLE

+
+
+
Receiving a message from a socket
+
+
zmq_msg_t msg;
+rc = zmq_msg_init (&msg);
+assert (rc == 0);
+rc = zmq_recv (socket, &msg, 0);
+assert (rc == 0);
+
+
+

SEE ALSO

+
+

zmq_msg_init_size(3) +zmq_msg_init_data(3) +zmq_msg_close(3) +zmq_msg_data(3) +zmq_msg_size(3) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_msg_init_data.3 b/doc/zmq_msg_init_data.3 index 11f822d..b89821f 100644 --- a/doc/zmq_msg_init_data.3 +++ b/doc/zmq_msg_init_data.3 @@ -2,12 +2,12 @@ .\" Title: zmq_msg_init_data .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_MSG_INIT_DATA" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_MSG_INIT_DATA" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_msg_init_data.html b/doc/zmq_msg_init_data.html new file mode 100644 index 0000000..efc259f --- /dev/null +++ b/doc/zmq_msg_init_data.html @@ -0,0 +1,669 @@ + + + + + +zmq_msg_init_data(3) + + + + + +
+

SYNOPSIS

+
+

typedef void (zmq_free_fn) (void *data, void *hint);

+

int zmq_msg_init_data (zmq_msg_t *msg, void *data, size_t size, zmq_free_fn *ffn, void *hint);

+
+

DESCRIPTION

+
+

The zmq_msg_init_data() function shall initialise the message object +referenced by msg to represent the content referenced by the buffer located +at address data, size bytes long. No copy of data shall be performed and +ØMQ shall take ownership of the supplied buffer.

+

If provided, the deallocation function ffn shall be called once the data +buffer is no longer required by ØMQ, with the data and hint arguments +supplied to zmq_msg_init_data().

+
+ + + +
+
Caution
+		Never access zmq_msg_t members directly, instead always use the +zmq_msg family of functions.
+
+
+ + + +
+
Caution
+		The functions zmq_msg_init(), zmq_msg_init_data() and +zmq_msg_init_size() are mutually exclusive. Never initialize the same +zmq_msg_t twice.
+
+
+

RETURN VALUE

+
+

The zmq_msg_init_data() function shall return zero if successful. Otherwise +it shall return -1 and set errno to one of the values defined below.

+
+

ERRORS

+
+

No errors are defined.

+
+

EXAMPLE

+
+
+
Initialising a message from a supplied buffer
+
+
void my_free (void *data, void *hint)
+{
+    free (data);
+}
+
+    /*  ...  */
+
+void *data = malloc (6);
+assert (data);
+memcpy (data, "ABCDEF", 6);
+zmq_msg_t msg;
+rc = zmq_msg_init_data (&msg, data, 6, my_free, NULL);
+assert (rc == 0);
+
+
+

SEE ALSO

+
+

zmq_msg_init_size(3) +zmq_msg_init(3) +zmq_msg_close(3) +zmq_msg_data(3) +zmq_msg_size(3) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_msg_init_size.3 b/doc/zmq_msg_init_size.3 index 2f7c494..324f751 100644 --- a/doc/zmq_msg_init_size.3 +++ b/doc/zmq_msg_init_size.3 @@ -2,12 +2,12 @@ .\" Title: zmq_msg_init_size .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_MSG_INIT_SIZE" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_MSG_INIT_SIZE" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_msg_init_size.html b/doc/zmq_msg_init_size.html new file mode 100644 index 0000000..706788f --- /dev/null +++ b/doc/zmq_msg_init_size.html @@ -0,0 +1,656 @@ + + + + + +zmq_msg_init_size(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_msg_init_size (zmq_msg_t *msg, size_t size);

+
+

DESCRIPTION

+
+

The zmq_msg_init_size() function shall allocate any resources required to +store a message size bytes long and initialise the message object referenced +by msg to represent the newly allocated message.

+

The implementation shall choose whether to store message content on the stack +(small messages) or on the heap (large messages). For performance reasons +zmq_msg_init_size() shall not clear the message data.

+
+ + + +
+
Caution
+		Never access zmq_msg_t members directly, instead always use the +zmq_msg family of functions.
+
+
+ + + +
+
Caution
+		The functions zmq_msg_init(), zmq_msg_init_data() and +zmq_msg_init_size() are mutually exclusive. Never initialize the same +zmq_msg_t twice.
+
+
+

RETURN VALUE

+
+

The zmq_msg_init_size() function shall return zero if successful. Otherwise +it shall return -1 and set errno to one of the values defined below.

+
+

ERRORS

+
+
+
+ENOMEM +
+
+

+Insufficient storage space is available. +

+
+
+
+

SEE ALSO

+
+

zmq_msg_init_data(3) +zmq_msg_init(3) +zmq_msg_close(3) +zmq_msg_data(3) +zmq_msg_size(3) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_msg_move.3 b/doc/zmq_msg_move.3 index 6a3f97c..1899c63 100644 --- a/doc/zmq_msg_move.3 +++ b/doc/zmq_msg_move.3 @@ -2,12 +2,12 @@ .\" Title: zmq_msg_move .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_MSG_MOVE" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_MSG_MOVE" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_msg_move.html b/doc/zmq_msg_move.html new file mode 100644 index 0000000..78f09a8 --- /dev/null +++ b/doc/zmq_msg_move.html @@ -0,0 +1,636 @@ + + + + + +zmq_msg_move(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_msg_move (zmq_msg_t *dest, zmq_msg_t *src);

+
+

DESCRIPTION

+
+

The zmq_msg_move() function shall move the content of the message object +referenced by src to the message object referenced by dest. No actual +copying of message content is performed, dest is simply updated to reference +the new content. src becomes an empty message after calling zmq_msg_move(). +The original content of dest, if any, shall be released.

+
+ + + +
+
Caution
+		Never access zmq_msg_t members directly, instead always use the +zmq_msg family of functions.
+
+
+

RETURN VALUE

+
+

The zmq_msg_move() function shall return zero if successful. Otherwise it +shall return -1 and set errno to one of the values defined below.

+
+

ERRORS

+
+

No errors are defined.

+
+

SEE ALSO

+
+

zmq_msg_copy(3) +zmq_msg_init(3) +zmq_msg_init_size(3) +zmq_msg_init_data(3) +zmq_msg_close(3) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_msg_size.3 b/doc/zmq_msg_size.3 index 627c084..4cead02 100644 --- a/doc/zmq_msg_size.3 +++ b/doc/zmq_msg_size.3 @@ -2,12 +2,12 @@ .\" Title: zmq_msg_size .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_MSG_SIZE" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_MSG_SIZE" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_msg_size.html b/doc/zmq_msg_size.html new file mode 100644 index 0000000..068232d --- /dev/null +++ b/doc/zmq_msg_size.html @@ -0,0 +1,633 @@ + + + + + +zmq_msg_size(3) + + + + + +
+

SYNOPSIS

+
+

size_t zmq_msg_size (zmq_msg_t *msg);

+
+

DESCRIPTION

+
+

The zmq_msg_size() function shall return the size in bytes of the content of +the message object referenced by msg.

+
+ + + +
+
Caution
+		Never access zmq_msg_t members directly, instead always use the +zmq_msg family of functions.
+
+
+

RETURN VALUE

+
+

Upon successful completion, zmq_msg_data() shall return the size of the +message content in bytes.

+
+

ERRORS

+
+

No errors are defined.

+
+

SEE ALSO

+
+

zmq_msg_data(3) +zmq_msg_init(3) +zmq_msg_init_size(3) +zmq_msg_init_data(3) +zmq_msg_close(3) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_pgm.7 b/doc/zmq_pgm.7 index 06cc456..1559950 100644 --- a/doc/zmq_pgm.7 +++ b/doc/zmq_pgm.7 @@ -2,12 +2,12 @@ .\" Title: zmq_pgm .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_PGM" "7" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_PGM" "7" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_pgm.html b/doc/zmq_pgm.html new file mode 100644 index 0000000..5506fa1 --- /dev/null +++ b/doc/zmq_pgm.html @@ -0,0 +1,745 @@ + + + + + +zmq_pgm(7) + + + + + +
+

SYNOPSIS

+
+

PGM (Pragmatic General Multicast) is a protocol for reliable multicast +transport of data over IP networks.

+
+

DESCRIPTION

+
+

ØMQ implements two variants of PGM, the standard protocol where PGM datagrams +are layered directly on top of IP datagrams as defined by RFC 3208 (the pgm +transport) and "Encapsulated PGM" where PGM datagrams are encapsulated inside +UDP datagrams (the epgm transport).

+

The pgm and epgm transports can only be used with the ZMQ_PUB and +ZMQ_SUB socket types.

+

Further, PGM sockets are rate limited by default and incur a performance +penalty when used over a loop-back interface. For details, refer to the +ZMQ_RATE, ZMQ_RECOVERY_IVL and ZMQ_MCAST_LOOP options documented in +zmq_setsockopt(3).

+
+ + + +
+
Caution
+		The pgm transport implementation requires access to raw IP sockets. +Additional privileges may be required on some operating systems for this +operation. Applications not requiring direct interoperability with other PGM +implementations are encouraged to use the epgm transport instead which does +not require any special privileges.
+
+
+

ADDRESSING

+
+

A ØMQ address string consists of two parts as follows: +transport://endpoint. The transport part specifies the underlying +transport protocol to use. For the standard PGM protocol, transport shall be +set to pgm. For the "Encapsulated PGM" protocol transport shall be set to +epgm. The meaning of the endpoint part for both the pgm and epgm +transport is defined below.

+

Connecting a socket

+

When connecting a socket to a peer address using zmq_connect() with the pgm +or epgm transport, the endpoint shall be interpreted as an interface +followed by a semicolon, followed by a multicast address, followed by a colon +and a port number.

+

An interface may be specified by either of the following:

+
    +
  • +

    +The interface name as defined by the operating system. +

    +
    • +
  • +

    +The primary IPv4 address assigned to the interface, in it’s numeric + representation. +

    +
    • +
+
+ + + +
+
Note
+		Interface names are not standardised in any way and should be assumed to +be arbitrary and platform dependent. On Win32 platforms no short interface +names exist, thus only the primary IPv4 address may be used to specify an +interface.
+
+

A multicast address is specified by an IPv4 multicast address in it’s numeric +representation.

+
+

WIRE FORMAT

+
+

Consecutive PGM datagrams are interpreted by ØMQ as a single continuous stream +of data where ØMQ messages are not necessarily aligned with PGM datagram +boundaries and a single ØMQ message may span several PGM datagrams. This stream +of data consists of ØMQ messages encapsulated in frames as described in +zmq_tcp(7).

+

PGM datagram payload

+

The following ABNF grammar represents the payload of a single PGM datagram as +used by ØMQ:

+
+
+
datagram               = (offset data)
+offset                 = 2OCTET
+data                   = *OCTET
+
+

In order for late joining consumers to be able to identify message boundaries, +each PGM datagram payload starts with a 16-bit unsigned integer in network byte +order specifying either the offset of the first message frame in the datagram +or containing the value 0xFFFF if the datagram contains solely an +intermediate part of a larger message.

+

The following diagram illustrates the layout of a single PGM datagram payload:

+
+
+
+------------------+----------------------+
+| offset (16 bits) |         data         |
++------------------+----------------------+
+
+

The following diagram further illustrates how three example ØMQ frames are laid +out in consecutive PGM datagram payloads:

+
+
+
First datagram payload
++--------------+-------------+---------------------+
+| Frame offset |   Frame 1   |   Frame 2, part 1   |
+|    0x0000    | (Message 1) | (Message 2, part 1) |
++--------------+-------------+---------------------+
+
+Second datagram payload
++--------------+---------------------+
+| Frame offset |   Frame 2, part 2   |
+| 0xFFFF       | (Message 2, part 2) |
++--------------+---------------------+
+
+Third datagram payload
++--------------+----------------------------+-------------+
+| Frame offset |   Frame 2, final 8 bytes   |   Frame 3   |
+| 0x0008       | (Message 2, final 8 bytes) | (Message 3) |
++--------------+----------------------------+-------------+
+
+
+

EXAMPLE

+
+
+
Connecting a socket
+
+
/* Connecting to the multicast address 239.192.1.1, port 5555, */
+/* using the first Ethernet network interface on Linux */
+/* and the Encapsulated PGM protocol */
+rc = zmq_connect(socket, "epgm://eth0;239.192.1.1:5555");
+assert (rc == 0);
+/* Connecting to the multicast address 239.192.1.1, port 5555, */
+/* using the network interface with the address 192.168.1.1 */
+/* and the standard PGM protocol */
+rc = zmq_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555");
+assert (rc == 0);
+
+
+

SEE ALSO

+
+

zmq_connect(3) +zmq_setsockopt(3) +zmq_tcp(7) +zmq_ipc(7) +zmq_inproc(7) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_poll.3 b/doc/zmq_poll.3 index a5d005c..a3cc9fc 100644 --- a/doc/zmq_poll.3 +++ b/doc/zmq_poll.3 @@ -2,12 +2,12 @@ .\" Title: zmq_poll .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_POLL" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_POLL" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_poll.html b/doc/zmq_poll.html new file mode 100644 index 0000000..da4b8fb --- /dev/null +++ b/doc/zmq_poll.html @@ -0,0 +1,755 @@ + + + + + +zmq_poll(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_poll (zmq_pollitem_t *items, int nitems, long timeout);

+
+

DESCRIPTION

+
+

The zmq_poll() function provides a mechanism for applications to multiplex +input/output events in a level-triggered fashion over a set of sockets. Each +member of the array pointed to by the items argument is a zmq_pollitem_t +structure. The nitems argument specifies the number of items in the items +array. The zmq_pollitem_t structure is defined as follows:

+
+
+
typedef struct
+{
+    void *socket;
+    int fd;
+    short events;
+    short revents;
+} zmq_pollitem_t;
+
+

For each zmq_pollitem_t item, zmq_poll() shall examine either the ØMQ +socket referenced by socket or the standard socket specified by the file +descriptor fd, for the event(s) specified in events. If both socket and +fd are set in a single zmq_pollitem_t, the ØMQ socket referenced by +socket shall take precedence and the value of fd shall be ignored.

+
+ + + +
+
Note
+		All ØMQ sockets passed to the zmq_poll() function must share the +same ØMQ context and must belong to the thread calling zmq_poll().
+
+

For each zmq_pollitem_t item, zmq_poll() shall first clear the revents +member, and then indicate any requested events that have occurred by setting the +bit corresponding to the event condition in the revents member.

+

If none of the requested events have occurred on any zmq_pollitem_t item, +zmq_poll() shall wait timeout microseconds for an event to occur on +any of the requested items. If the value of timeout is 0, zmq_poll() +shall return immediately. If the value of timeout is -1, zmq_poll() shall +block indefinitely until a requested event has occurred on at least one +zmq_pollitem_t.

+

The events and revents members of zmq_pollitem_t are bit masks constructed +by OR’ing a combination of the following event flags:

+
+
+ZMQ_POLLIN +
+
+

+For ØMQ sockets, at least one message may be received from the socket without +blocking. For standard sockets this is equivalent to the POLLIN flag of the +poll() system call and generally means that at least one byte of data may be +read from fd without blocking. +

+
+
+ZMQ_POLLOUT +
+
+

+For ØMQ sockets, at least one message may be sent to the socket without +blocking. For standard sockets this is equivalent to the POLLOUT flag of the +poll() system call and generally means that at least one byte of data may be +written to fd without blocking. +

+
+
+ZMQ_POLLERR +
+
+

+For standard sockets, this flag is passed through zmq_poll() to the +underlying poll() system call and generally means that some sort of error +condition is present on the socket specified by fd. For ØMQ sockets this flag +has no effect if set in events, and shall never be returned in revents by +zmq_poll(). +

+
+
+
+ + + +
+
Note
+		The zmq_poll() function may be implemented or emulated using operating +system interfaces other than poll(), and as such may be subject to the limits +of those interfaces in ways not defined in this documentation.
+
+
+

RETURN VALUE

+
+

Upon successful completion, the zmq_poll() function shall return the number +of zmq_pollitem_t structures with events signaled in revents or 0 if no +events have been signaled. Upon failure, zmq_poll() shall return -1 and set +errno to one of the values defined below.

+
+

ERRORS

+
+
+
+ETERM +
+
+

+At least one of the members of the items array refers to a socket whose +associated ØMQ context was terminated. +

+
+
+EFAULT +
+
+

+The provided items was not valid (NULL). +

+
+
+EINTR +
+
+

+The operation was interrupted by delivery of a signal before any events were +available. +

+
+
+
+

EXAMPLE

+
+
+
Polling indefinitely for input events on both a ØMQ socket and a standard socket.
+
+
zmq_pollitem_t items [2];
+/* First item refers to 0MQ socket 'socket' */
+items[0].socket = socket;
+items[0].events = ZMQ_POLLIN;
+/* Second item refers to standard socket 'fd' */
+items[1].socket = NULL;
+items[1].fd = fd;
+items[1].events = ZMQ_POLLIN;
+/* Poll for events indefinitely */
+int rc = zmq_poll (items, 2, -1);
+assert (rc >= 0);
+/* Returned events will be stored in items[].revents */
+
+
+

SEE ALSO

+
+

zmq_socket(3) +zmq_send(3) +zmq_recv(3) +zmq(7)

+

Your operating system documentation for the poll() system call.

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_recv.3 b/doc/zmq_recv.3 index 970d1ba..0103c7f 100644 --- a/doc/zmq_recv.3 +++ b/doc/zmq_recv.3 @@ -2,12 +2,12 @@ .\" Title: zmq_recv .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_RECV" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_RECV" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_recv.html b/doc/zmq_recv.html new file mode 100644 index 0000000..9ee3454 --- /dev/null +++ b/doc/zmq_recv.html @@ -0,0 +1,738 @@ + + + + + +zmq_recv(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_recv (void *socket, zmq_msg_t *msg, int flags);

+
+

DESCRIPTION

+
+

The zmq_recv() function shall receive a message from the socket referenced by +the socket argument and store it in the message referenced by the msg +argument. Any content previously stored in msg shall be properly deallocated. +If there are no messages available on the specified socket the zmq_recv() +function shall block until the request can be satisfied. The flags argument +is a combination of the flags defined below:

+
+
+ZMQ_NOBLOCK +
+
+

+Specifies that the operation should be performed in non-blocking mode. If there +are no messages available on the specified socket, the zmq_recv() function +shall fail with errno set to EAGAIN. +

+
+
+

Multi-part messages

+

A ØMQ message is composed of 1 or more message parts; each message part is an +independent zmq_msg_t in its own right. ØMQ ensures atomic delivery of +messages; peers shall receive either all message parts of a message or none +at all.

+

The total number of message parts is unlimited.

+

An application wishing to determine if a message is composed of multiple parts +does so by retrieving the value of the ZMQ_RCVMORE socket option on the +socket it is receiving the message from. If there are no message parts to +follow, or if the message is not composed of multiple parts, ZMQ_RCVMORE +shall report a value of zero. Otherwise, ZMQ_RCVMORE shall report a value of +1, indicating that more message parts are to follow.

+
+

RETURN VALUE

+
+

The zmq_recv() function shall return zero if successful. Otherwise it shall +return -1 and set errno to one of the values defined below.

+
+

ERRORS

+
+
+
+EAGAIN +
+
+

+Non-blocking mode was requested and no messages are available at the moment. +

+
+
+ENOTSUP +
+
+

+The zmq_recv() operation is not supported by this socket type. +

+
+
+EFSM +
+
+

+The zmq_recv() operation cannot be performed on this socket at the moment due +to the socket not being in the appropriate state. This error may occur with +socket types that switch between several states, such as ZMQ_REP. See the +messaging patterns section of zmq_socket(3) for more information. +

+
+
+ETERM +
+
+

+The ØMQ context associated with the specified socket was terminated. +

+
+
+EFAULT +
+
+

+The provided socket was not valid (NULL). +

+
+
+EINTR +
+
+

+The operation was interrupted by delivery of a signal before a message was +available. +

+
+
+
+

EXAMPLE

+
+
+
Receiving a message from a socket
+
+
/* Create an empty 0MQ message */
+zmq_msg_t msg;
+int rc = zmq_msg_init (&msg);
+assert (rc == 0);
+/* Block until a message is available to be received from socket */
+rc = zmq_recv (socket, &msg, 0);
+assert (rc == 0);
+/* Release message */
+zmq_msg_close (&msg);
+
+
+
Receiving a multi-part message
+
+
int64_t more;
+size_t more_size = sizeof more;
+do {
+    /* Create an empty 0MQ message to hold the message part */
+    zmq_msg_t part;
+    int rc = zmq_msg_init (&part);
+    assert (rc == 0);
+    /* Block until a message is available to be received from socket */
+    rc = zmq_recv (socket, &part, 0);
+    assert (rc == 0);
+    /* Determine if more message parts are to follow */
+    rc = zmq_getsockopt (socket, ZMQ_RCVMORE, &more, &more_size);
+    assert (rc == 0);
+    zmq_msg_close (&part);
+} while (more);
+
+
+

SEE ALSO

+
+

zmq_send(3) +zmq_getsockopt(3) +zmq_socket(7) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_send.3 b/doc/zmq_send.3 index 039d5f1..b6ebcd5 100644 --- a/doc/zmq_send.3 +++ b/doc/zmq_send.3 @@ -2,12 +2,12 @@ .\" Title: zmq_send .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_SEND" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_SEND" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_send.html b/doc/zmq_send.html new file mode 100644 index 0000000..eeb4654 --- /dev/null +++ b/doc/zmq_send.html @@ -0,0 +1,744 @@ + + + + + +zmq_send(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_send (void *socket, zmq_msg_t *msg, int flags);

+
+

DESCRIPTION

+
+

The zmq_send() function shall queue the message referenced by the msg +argument to be sent to the socket referenced by the socket argument. The +flags argument is a combination of the flags defined below:

+
+
+ZMQ_NOBLOCK +
+
+

+Specifies that the operation should be performed in non-blocking mode. If the +message cannot be queued on the socket, the zmq_send() function shall fail +with errno set to EAGAIN. +

+
+
+ZMQ_SNDMORE +
+
+

+Specifies that the message being sent is a multi-part message, and that further +message parts are to follow. Refer to the section regarding multi-part messages +below for a detailed description. +

+
+
+
+ + + +
+
Note
+		A successful invocation of zmq_send() does not indicate that the +message has been transmitted to the network, only that it has been queued on +the socket and ØMQ has assumed responsibility for the message.
+
+

Multi-part messages

+

A ØMQ message is composed of 1 or more message parts; each message part is an +independent zmq_msg_t in its own right. ØMQ ensures atomic delivery of +messages; peers shall receive either all message parts of a message or none +at all.

+

The total number of message parts is unlimited.

+

An application wishing to send a multi-part message does so by specifying the +ZMQ_SNDMORE flag to zmq_send(). The presence of this flag indicates to ØMQ +that the message being sent is a multi-part message and that more message parts +are to follow. When the application wishes to send the final message part it +does so by calling zmq_send() without the ZMQ_SNDMORE flag; this indicates +that no more message parts are to follow.

+
+

RETURN VALUE

+
+

The zmq_send() function shall return zero if successful. Otherwise it shall +return -1 and set errno to one of the values defined below.

+
+

ERRORS

+
+
+
+EAGAIN +
+
+

+Non-blocking mode was requested and the message cannot be sent at the moment. +

+
+
+ENOTSUP +
+
+

+The zmq_send() operation is not supported by this socket type. +

+
+
+EFSM +
+
+

+The zmq_send() operation cannot be performed on this socket at the moment due +to the socket not being in the appropriate state. This error may occur with +socket types that switch between several states, such as ZMQ_REP. See the +messaging patterns section of zmq_socket(3) for more information. +

+
+
+ETERM +
+
+

+The ØMQ context associated with the specified socket was terminated. +

+
+
+EFAULT +
+
+

+The provided socket was not valid (NULL). +

+
+
+EINTR +
+
+

+The operation was interrupted by delivery of a signal before the message was +sent. +

+
+
+
+

EXAMPLE

+
+
+
Filling in a message and sending it to a socket
+
+
/* Create a new message, allocating 6 bytes for message content */
+zmq_msg_t msg;
+int rc = zmq_msg_init_size (&msg, 6);
+assert (rc == 0);
+/* Fill in message content with 'AAAAAA' */
+memset (zmq_msg_data (&msg), 'A', 6);
+/* Send the message to the socket */
+rc = zmq_send (socket, &msg, 0);
+assert (rc == 0);
+
+
+
Sending a multi-part message
+
+
/* Send a multi-part message consisting of three parts to socket */
+rc = zmq_send (socket, &part1, ZMQ_SNDMORE);
+rc = zmq_send (socket, &part2, ZMQ_SNDMORE);
+/* Final part; no more parts to follow */
+rc = zmq_send (socket, &part3, 0);
+
+
+

SEE ALSO

+
+

zmq_recv(3) +zmq_socket(7) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_setsockopt.3 b/doc/zmq_setsockopt.3 index 094e946..029a2de 100644 --- a/doc/zmq_setsockopt.3 +++ b/doc/zmq_setsockopt.3 @@ -2,12 +2,12 @@ .\" Title: zmq_setsockopt .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/20/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_SETSOCKOPT" "3" "03/20/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_SETSOCKOPT" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_setsockopt.html b/doc/zmq_setsockopt.html new file mode 100644 index 0000000..93d0611 --- /dev/null +++ b/doc/zmq_setsockopt.html @@ -0,0 +1,1603 @@ + + + + + +zmq_setsockopt(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_setsockopt (void *socket, int option_name, const void *option_value, size_t option_len);

+

Caution: All options, with the exception of ZMQ_SUBSCRIBE, ZMQ_UNSUBSCRIBE and +ZMQ_LINGER, only take effect for subsequent socket bind/connects.

+
+

DESCRIPTION

+
+

The zmq_setsockopt() function shall set the option specified by the +option_name argument to the value pointed to by the option_value argument +for the ØMQ socket pointed to by the socket argument. The option_len +argument is the size of the option value in bytes.

+

The following socket options can be set with the zmq_setsockopt() function:

+

ZMQ_HWM: Set high water mark

+

The ZMQ_HWM option shall set the high water mark for the specified socket. +The high water mark is a hard limit on the maximum number of outstanding +messages ØMQ shall queue in memory for any single peer that the specified +socket is communicating with.

+

If this limit has been reached the socket shall enter an exceptional state and +depending on the socket type, ØMQ shall take appropriate action such as +blocking or dropping sent messages. Refer to the individual socket descriptions +in zmq_socket(3) for details on the exact action taken for each socket +type.

+

The default ZMQ_HWM value of zero means "no limit".

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+uint64_t +

+
+Option value unit +
+		 +

+messages +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_SWAP: Set disk offload size

+

The ZMQ_SWAP option shall set the disk offload (swap) size for the specified +socket. A socket which has ZMQ_SWAP set to a non-zero value may exceed it’s +high water mark; in this case outstanding messages shall be offloaded to +storage on disk rather than held in memory.

+

The value of ZMQ_SWAP defines the maximum size of the swap space in bytes.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int64_t +

+
+Option value unit +
+		 +

+bytes +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_AFFINITY: Set I/O thread affinity

+

The ZMQ_AFFINITY option shall set the I/O thread affinity for newly created +connections on the specified socket.

+

Affinity determines which threads from the ØMQ I/O thread pool associated with +the socket’s context shall handle newly created connections. A value of zero +specifies no affinity, meaning that work shall be distributed fairly among all +ØMQ I/O threads in the thread pool. For non-zero values, the lowest bit +corresponds to thread 1, second lowest bit to thread 2 and so on. For example, +a value of 3 specifies that subsequent connections on socket shall be handled +exclusively by I/O threads 1 and 2.

+

See also zmq_init(3) for details on allocating the number of I/O +threads for a specific context.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+uint64_t +

+
+Option value unit +
+		 +

+N/A (bitmap) +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+N/A +

+
+

ZMQ_IDENTITY: Set socket identity

+

The ZMQ_IDENTITY option shall set the identity of the specified socket. +Socket identity determines if existing ØMQ infrastructure (message queues, +forwarding devices) shall be identified with a specific application and +persist across multiple runs of the application.

+

If the socket has no identity, each run of an application is completely +separate from other runs. However, with identity set the socket shall re-use +any existing ØMQ infrastructure configured by the previous run(s). Thus the +application may receive messages that were sent in the meantime, message +queue limits shall be shared with previous run(s) and so on.

+

Identity should be at least one byte and at most 255 bytes long. Identities +starting with binary zero are reserved for use by ØMQ infrastructure.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+binary data +

+
+Option value unit +
+		 +

+N/A +

+
+Default value +
+		 +

+NULL +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_SUBSCRIBE: Establish message filter

+

The ZMQ_SUBSCRIBE option shall establish a new message filter on a ZMQ_SUB +socket. Newly created ZMQ_SUB sockets shall filter out all incoming messages, +therefore you should call this option to establish an initial message filter.

+

An empty option_value of length zero shall subscribe to all incoming +messages. A non-empty option_value shall subscribe to all messages beginning +with the specified prefix. Multiple filters may be attached to a single +ZMQ_SUB socket, in which case a message shall be accepted if it matches at +least one filter.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+binary data +

+
+Option value unit +
+		 +

+N/A +

+
+Default value +
+		 +

+N/A +

+
+Applicable socket types +
+		 +

+ZMQ_SUB +

+
+

ZMQ_UNSUBSCRIBE: Remove message filter

+

The ZMQ_UNSUBSCRIBE option shall remove an existing message filter on a +ZMQ_SUB socket. The filter specified must match an existing filter previously +established with the ZMQ_SUBSCRIBE option. If the socket has several +instances of the same filter attached the ZMQ_UNSUBSCRIBE option shall remove +only one instance, leaving the rest in place and functional.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+binary data +

+
+Option value unit +
+		 +

+N/A +

+
+Default value +
+		 +

+N/A +

+
+Applicable socket types +
+		 +

+ZMQ_SUB +

+
+

ZMQ_RATE: Set multicast data rate

+

The ZMQ_RATE option shall set the maximum send or receive data rate for +multicast transports such as zmq_pgm(7) using the specified socket.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int64_t +

+
+Option value unit +
+		 +

+kilobits per second +

+
+Default value +
+		 +

+100 +

+
+Applicable socket types +
+		 +

+all, when using multicast transports +

+
+

ZMQ_RECOVERY_IVL: Set multicast recovery interval

+

The ZMQ_RECOVERY_IVL option shall set the recovery interval for multicast +transports using the specified socket. The recovery interval determines the +maximum time in seconds that a receiver can be absent from a multicast group +before unrecoverable data loss will occur.

+
+ + + +
+
Caution
+		Exercise care when setting large recovery intervals as the data +needed for recovery will be held in memory. For example, a 1 minute recovery +interval at a data rate of 1Gbps requires a 7GB in-memory buffer.
+
+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int64_t +

+
+Option value unit +
+		 +

+seconds +

+
+Default value +
+		 +

+10 +

+
+Applicable socket types +
+		 +

+all, when using multicast transports +

+
+

ZMQ_RECOVERY_IVL_MSEC: Set multicast recovery interval in milliseconds

+

The ZMQ_RECOVERY_IVL_MSEC option shall set the recovery interval, specified +in milliseconds (ms) for multicast transports using the specified socket. +The recovery interval determines the maximum time in milliseconds that a +receiver can be absent from a multicast group before unrecoverable data loss +will occur.

+

A non-zero value of the ZMQ_RECOVERY_IVL_MSEC option will take precedence +over the ZMQ_RECOVERY_IVL option, but since the default for the +ZMQ_RECOVERY_IVL_MSEC is -1, the default is to use the ZMQ_RECOVERY_IVL +option value.

+
+ + + +
+
Caution
+		Exercise care when setting large recovery intervals as the data +needed for recovery will be held in memory. For example, a 1 minute recovery +interval at a data rate of 1Gbps requires a 7GB in-memory buffer.
+
+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int64_t +

+
+Option value unit +
+		 +

+milliseconds +

+
+Default value +
+		 +

+-1 +

+
+Applicable socket types +
+		 +

+all, when using multicast transports +

+
+

ZMQ_MCAST_LOOP: Control multicast loop-back

+

The ZMQ_MCAST_LOOP option shall control whether data sent via multicast +transports using the specified socket can also be received by the sending +host via loop-back. A value of zero disables the loop-back functionality, while +the default value of 1 enables the loop-back functionality. Leaving multicast +loop-back enabled when it is not required can have a negative impact on +performance. Where possible, disable ZMQ_MCAST_LOOP in production +environments.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int64_t +

+
+Option value unit +
+		 +

+boolean +

+
+Default value +
+		 +

+1 +

+
+Applicable socket types +
+		 +

+all, when using multicast transports +

+
+

ZMQ_SNDBUF: Set kernel transmit buffer size

+

The ZMQ_SNDBUF option shall set the underlying kernel transmit buffer size +for the socket to the specified size in bytes. A value of zero means leave +the OS default unchanged. For details please refer to your operating system +documentation for the SO_SNDBUF socket option.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+uint64_t +

+
+Option value unit +
+		 +

+bytes +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_RCVBUF: Set kernel receive buffer size

+

The ZMQ_RCVBUF option shall set the underlying kernel receive buffer size for +the socket to the specified size in bytes. A value of zero means leave the +OS default unchanged. For details refer to your operating system documentation +for the SO_RCVBUF socket option.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+uint64_t +

+
+Option value unit +
+		 +

+bytes +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_LINGER: Set linger period for socket shutdown

+

The ZMQ_LINGER option shall set the linger period for the specified socket. +The linger period determines how long pending messages which have yet to be +sent to a peer shall linger in memory after a socket is closed with +zmq_close(3), and further affects the termination of the socket’s +context with zmq_term(3). The following outlines the different +behaviours:

+
    +
  • +

    +The default value of -1 specifies an infinite linger period. Pending + messages shall not be discarded after a call to zmq_close(); attempting to + terminate the socket’s context with zmq_term() shall block until all + pending messages have been sent to a peer. +

    +
    • +
  • +

    +The value of 0 specifies no linger period. Pending messages shall be + discarded immediately when the socket is closed with zmq_close(). +

    +
    • +
  • +

    +Positive values specify an upper bound for the linger period in milliseconds. + Pending messages shall not be discarded after a call to zmq_close(); + attempting to terminate the socket’s context with zmq_term() shall block + until either all pending messages have been sent to a peer, or the linger + period expires, after which any pending messages shall be discarded. +

    +
    + + + + + + + + + + + + + + + + +
    +Option value type +
    +    		 +

    +int +

    +
    +Option value unit +
    +    		 +

    +milliseconds +

    +
    +Default value +
    +    		 +

    +-1 (infinite) +

    +
    +Applicable socket types +
    +    		 +

    +all +

    +
    +
    • +
+

ZMQ_RECONNECT_IVL: Set reconnection interval

+

The ZMQ_RECONNECT_IVL option shall set the initial reconnection interval for +the specified socket. The reconnection interval is the period ØMQ +shall wait between attempts to reconnect disconnected peers when using +connection-oriented transports.

+
+ + + +
+
Note
+		The reconnection interval may be randomized by ØMQ to prevent +reconnection storms in topologies with a large number of peers per socket.
+
+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int +

+
+Option value unit +
+		 +

+milliseconds +

+
+Default value +
+		 +

+100 +

+
+Applicable socket types +
+		 +

+all, only for connection-oriented transports +

+
+

ZMQ_RECONNECT_IVL_MAX: Set maximum reconnection interval

+

The ZMQ_RECONNECT_IVL_MAX option shall set the maximum reconnection interval +for the specified socket. This is the maximum period ØMQ shall wait between +attempts to reconnect. On each reconnect attempt, the previous interval shall be +doubled untill ZMQ_RECONNECT_IVL_MAX is reached. This allows for exponential +backoff strategy. Default value means no exponential backoff is performed and +reconnect interval calculations are only based on ZMQ_RECONNECT_IVL.

+
+ + + +
+
Note
+		Values less than ZMQ_RECONNECT_IVL will be ignored.
+
+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int +

+
+Option value unit +
+		 +

+milliseconds +

+
+Default value +
+		 +

+0 (only use ZMQ_RECONNECT_IVL) +

+
+Applicable socket types +
+		 +

+all, only for connection-oriented transports +

+
+

ZMQ_BACKLOG: Set maximum length of the queue of outstanding connections

+

The ZMQ_BACKLOG option shall set the maximum length of the queue of +outstanding peer connections for the specified socket; this only applies to +connection-oriented transports. For details refer to your operating system +documentation for the listen function.

+
+ + + + + + + + + + + + + + + + +
+Option value type +
+		 +

+int +

+
+Option value unit +
+		 +

+connections +

+
+Default value +
+		 +

+100 +

+
+Applicable socket types +
+		 +

+all, only for connection-oriented transports. +

+
+
+

RETURN VALUE

+
+

The zmq_setsockopt() function shall return zero if successful. Otherwise it +shall return -1 and set errno to one of the values defined below.

+
+

ERRORS

+
+
+
+EINVAL +
+
+

+The requested option option_name is unknown, or the requested option_len or +option_value is invalid. +

+
+
+ETERM +
+
+

+The ØMQ context associated with the specified socket was terminated. +

+
+
+EFAULT +
+
+

+The provided socket was not valid (NULL). +

+
+
+EINTR +
+
+

+The operation was interrupted by delivery of a signal. +

+
+
+
+

EXAMPLE

+
+
+
Subscribing to messages on a ZMQ_SUB socket
+
+
/* Subscribe to all messages */
+rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "", 0);
+assert (rc == 0);
+/* Subscribe to messages prefixed with "ANIMALS.CATS" */
+rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "ANIMALS.CATS", 12);
+
+
+
Setting I/O thread affinity
+
+
int64_t affinity;
+/* Incoming connections on TCP port 5555 shall be handled by I/O thread 1 */
+affinity = 1;
+rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof affinity);
+assert (rc);
+rc = zmq_bind (socket, "tcp://lo:5555");
+assert (rc);
+/* Incoming connections on TCP port 5556 shall be handled by I/O thread 2 */
+affinity = 2;
+rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof affinity);
+assert (rc);
+rc = zmq_bind (socket, "tcp://lo:5556");
+assert (rc);
+
+
+

SEE ALSO

+
+

zmq_getsockopt(3) +zmq_socket(3) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_socket.3 b/doc/zmq_socket.3 index 000cb0f..fc86d6d 100644 --- a/doc/zmq_socket.3 +++ b/doc/zmq_socket.3 @@ -2,12 +2,12 @@ .\" Title: zmq_socket .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/20/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_SOCKET" "3" "03/20/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_SOCKET" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_socket.html b/doc/zmq_socket.html new file mode 100644 index 0000000..3815b04 --- /dev/null +++ b/doc/zmq_socket.html @@ -0,0 +1,1416 @@ + + + + + +zmq_socket(3) + + + + + +
+

SYNOPSIS

+
+

void *zmq_socket (void *context, int type);

+
+

DESCRIPTION

+
+

The zmq_socket() function shall create a ØMQ socket within the specified +context and return an opaque handle to the newly created socket. The type +argument specifies the socket type, which determines the semantics of +communication over the socket.

+

The newly created socket is initially unbound, and not associated with any +endpoints. In order to establish a message flow a socket must first be +connected to at least one endpoint with zmq_connect(3), or at least one +endpoint must be created for accepting incoming connections with +zmq_bind(3).

+
Key differences to conventional sockets

Generally speaking, conventional sockets present a synchronous interface to +either connection-oriented reliable byte streams (SOCK_STREAM), or +connection-less unreliable datagrams (SOCK_DGRAM). In comparison, ØMQ sockets +present an abstraction of an asynchronous message queue, with the exact +queueing semantics depending on the socket type in use. Where conventional +sockets transfer streams of bytes or discrete datagrams, ØMQ sockets transfer +discrete messages.

+

ØMQ sockets being asynchronous means that the timings of the physical +connection setup and tear down, reconnect and effective delivery are transparent +to the user and organized by ØMQ itself. Further, messages may be queued in +the event that a peer is unavailable to receive them.

+

Conventional sockets allow only strict one-to-one (two peers), many-to-one +(many clients, one server), or in some cases one-to-many (multicast) +relationships. With the exception of ZMQ_PAIR, ØMQ sockets may be connected +to multiple endpoints using zmq_connect(), while simultaneously accepting +incoming connections from multiple endpoints bound to the socket using +zmq_bind(), thus allowing many-to-many relationships.

+
Thread safety

ØMQ sockets are not thread safe. Applications MUST NOT use a socket +from multiple threads except after migrating a socket from one thread to +another with a "full fence" memory barrier.

+
Socket types

The following sections present the socket types defined by ØMQ, grouped by the +general messaging pattern which is built from related socket types.

+

Request-reply pattern

+

The request-reply pattern is used for sending requests from a client to one +or more instances of a service, and receiving subsequent replies to each +request sent.

+

ZMQ_REQ

+

A socket of type ZMQ_REQ is used by a client to send requests to and +receive replies from a service. This socket type allows only an alternating +sequence of zmq_send(request) and subsequent zmq_recv(reply) calls. Each +request sent is load-balanced among all services, and each reply received is +matched with the last issued request.

+

When a ZMQ_REQ socket enters an exceptional state due to having reached the +high water mark for all services, or if there are no services at all, then +any zmq_send(3) operations on the socket shall block until the +exceptional state ends or at least one service becomes available for sending; +messages are not discarded.

+
Summary of ZMQ_REQ characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + +
+Compatible peer sockets +
+		 +

+ZMQ_REP +

+
+Direction +
+		 +

+Bidirectional +

+
+Send/receive pattern +
+		 +

+Send, Receive, Send, Receive, … +

+
+Outgoing routing strategy +
+		 +

+Load-balanced +

+
+Incoming routing strategy +
+		 +

+Last peer +

+
+ZMQ_HWM option action +
+		 +

+Block +

+
+

ZMQ_REP

+

A socket of type ZMQ_REP is used by a service to receive requests from and +send replies to a client. This socket type allows only an alternating +sequence of zmq_recv(request) and subsequent zmq_send(reply) calls. Each +request received is fair-queued from among all clients, and each reply sent +is routed to the client that issued the last request. If the original +requester doesn’t exist any more the reply is silently discarded.

+

When a ZMQ_REP socket enters an exceptional state due to having reached the +high water mark for a client, then any replies sent to the client in +question shall be dropped until the exceptional state ends.

+
Summary of ZMQ_REP characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + +
+Compatible peer sockets +
+		 +

+ZMQ_REQ +

+
+Direction +
+		 +

+Bidirectional +

+
+Send/receive pattern +
+		 +

+Receive, Send, Receive, Send, … +

+
+Incoming routing strategy +
+		 +

+Fair-queued +

+
+Outgoing routing strategy +
+		 +

+Last peer +

+
+ZMQ_HWM option action +
+		 +

+Drop +

+
+

ZMQ_DEALER

+

A socket of type ZMQ_DEALER is an advanced pattern used for extending +request/reply sockets. Each message sent is load-balanced among all connected +peers, and each message received is fair-queued from all connected peers.

+

Previously this socket was called ZMQ_XREQ and that name remains available +for backwards compatibility.

+

When a ZMQ_DEALER socket enters an exceptional state due to having reached the +high water mark for all peers, or if there are no peers at all, then any +zmq_send(3) operations on the socket shall block until the exceptional +state ends or at least one peer becomes available for sending; messages are not +discarded.

+

When a ZMQ_DEALER socket is connected to a ZMQ_REP socket each message sent +must consist of an empty message part, the delimiter, followed by one or more +body parts.

+
Summary of ZMQ_DEALER characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + +
+Compatible peer sockets +
+		 +

+ZMQ_ROUTER, ZMQ_REP +

+
+Direction +
+		 +

+Bidirectional +

+
+Send/receive pattern +
+		 +

+Unrestricted +

+
+Outgoing routing strategy +
+		 +

+Load-balanced +

+
+Incoming routing strategy +
+		 +

+Fair-queued +

+
+ZMQ_HWM option action +
+		 +

+Block +

+
+

ZMQ_ROUTER

+

A socket of type ZMQ_ROUTER is an advanced pattern used for extending +request/reply sockets. When receiving messages a ZMQ_ROUTER socket shall +prepend a message part containing the identity of the originating peer to the +message before passing it to the application. Messages received are fair-queued +from among all connected peers. When sending messages a ZMQ_ROUTER socket shall +remove the first part of the message and use it to determine the identity of +the peer the message shall be routed to. If the peer does not exist anymore +the message shall be silently discarded.

+

Previously this socket was called ZMQ_XREP and that name remains available +for backwards compatibility.

+

When a ZMQ_ROUTER socket enters an exceptional state due to having reached the +high water mark for all peers, or if there are no peers at all, then any +messages sent to the socket shall be dropped until the exceptional state ends. +Likewise, any messages routed to a non-existent peer or a peer for which the +individual high water mark has been reached shall also be dropped.

+

When a ZMQ_REQ socket is connected to a ZMQ_ROUTER socket, in addition to the +identity of the originating peer each message received shall contain an empty +delimiter message part. Hence, the entire structure of each received message +as seen by the application becomes: one or more identity parts, delimiter +part, one or more body parts. When sending replies to a ZMQ_REQ socket the +application must include the delimiter part.

+
Summary of ZMQ_ROUTER characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + +
+Compatible peer sockets +
+		 +

+ZMQ_DEALER, ZMQ_REQ +

+
+Direction +
+		 +

+Bidirectional +

+
+Send/receive pattern +
+		 +

+Unrestricted +

+
+Outgoing routing strategy +
+		 +

+See text +

+
+Incoming routing strategy +
+		 +

+Fair-queued +

+
+ZMQ_HWM option action +
+		 +

+Drop +

+
+

Publish-subscribe pattern

+

The publish-subscribe pattern is used for one-to-many distribution of data from +a single publisher to multiple subscribers in a fan out fashion.

+

ZMQ_PUB

+

A socket of type ZMQ_PUB is used by a publisher to distribute data. +Messages sent are distributed in a fan out fashion to all connected peers. +The zmq_recv(3) function is not implemented for this socket type.

+

When a ZMQ_PUB socket enters an exceptional state due to having reached the +high water mark for a subscriber, then any messages that would be sent to the +subscriber in question shall instead be dropped until the exceptional state +ends. The zmq_send() function shall never block for this socket type.

+
Summary of ZMQ_PUB characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + +
+Compatible peer sockets +
+		 +

+ZMQ_SUB +

+
+Direction +
+		 +

+Unidirectional +

+
+Send/receive pattern +
+		 +

+Send only +

+
+Incoming routing strategy +
+		 +

+N/A +

+
+Outgoing routing strategy +
+		 +

+Fan out +

+
+ZMQ_HWM option action +
+		 +

+Drop +

+
+

ZMQ_SUB

+

A socket of type ZMQ_SUB is used by a subscriber to subscribe to data +distributed by a publisher. Initially a ZMQ_SUB socket is not subscribed to +any messages, use the ZMQ_SUBSCRIBE option of zmq_setsockopt(3) to +specify which messages to subscribe to. The zmq_send() function is not +implemented for this socket type.

+
Summary of ZMQ_SUB characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + +
+Compatible peer sockets +
+		 +

+ZMQ_PUB +

+
+Direction +
+		 +

+Unidirectional +

+
+Send/receive pattern +
+		 +

+Receive only +

+
+Incoming routing strategy +
+		 +

+Fair-queued +

+
+Outgoing routing strategy +
+		 +

+N/A +

+
+ZMQ_HWM option action +
+		 +

+Drop +

+
+

Pipeline pattern

+

The pipeline pattern is used for distributing data to nodes arranged in +a pipeline. Data always flows down the pipeline, and each stage of the pipeline +is connected to at least one node. When a pipeline stage is connected to +multiple nodes data is load-balanced among all connected nodes.

+

ZMQ_PUSH

+

A socket of type ZMQ_PUSH is used by a pipeline node to send messages +to downstream pipeline nodes. Messages are load-balanced to all connected +downstream nodes. The zmq_recv() function is not implemented for this +socket type.

+

When a ZMQ_PUSH socket enters an exceptional state due to having reached the +high water mark for all downstream nodes, or if there are no downstream +nodes at all, then any zmq_send(3) operations on the socket shall +block until the exceptional state ends or at least one downstream node +becomes available for sending; messages are not discarded.

+

Deprecated alias: ZMQ_DOWNSTREAM.

+
Summary of ZMQ_PUSH characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + +
+Compatible peer sockets +
+		 +

+ZMQ_PULL +

+
+Direction +
+		 +

+Unidirectional +

+
+Send/receive pattern +
+		 +

+Send only +

+
+Incoming routing strategy +
+		 +

+N/A +

+
+Outgoing routing strategy +
+		 +

+Load-balanced +

+
+ZMQ_HWM option action +
+		 +

+Block +

+
+

ZMQ_PULL

+

A socket of type ZMQ_PULL is used by a pipeline node to receive messages +from upstream pipeline nodes. Messages are fair-queued from among all +connected upstream nodes. The zmq_send() function is not implemented for +this socket type.

+

Deprecated alias: ZMQ_UPSTREAM.

+
Summary of ZMQ_PULL characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + +
+Compatible peer sockets +
+		 +

+ZMQ_PUSH +

+
+Direction +
+		 +

+Unidirectional +

+
+Send/receive pattern +
+		 +

+Receive only +

+
+Incoming routing strategy +
+		 +

+Fair-queued +

+
+Outgoing routing strategy +
+		 +

+N/A +

+
+ZMQ_HWM option action +
+		 +

+N/A +

+
+

Exclusive pair pattern

+

The exclusive pair pattern is used to connect a peer to precisely one other +peer. This pattern is used for inter-thread communication across the inproc +transport.

+

ZMQ_PAIR

+

A socket of type ZMQ_PAIR can only be connected to a single peer at any one +time. No message routing or filtering is performed on messages sent over a +ZMQ_PAIR socket.

+

When a ZMQ_PAIR socket enters an exceptional state due to having reached the +high water mark for the connected peer, or if no peer is connected, then +any zmq_send(3) operations on the socket shall block until the peer +becomes available for sending; messages are not discarded.

+
+ + + +
+
Note
+		ZMQ_PAIR sockets are designed for inter-thread communication across +the zmq_inproc(7) transport and do not implement functionality such +as auto-reconnection. ZMQ_PAIR sockets are considered experimental and may +have other missing or broken aspects.
+
+
Summary of ZMQ_PAIR characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + +
+Compatible peer sockets +
+		 +

+ZMQ_PAIR +

+
+Direction +
+		 +

+Bidirectional +

+
+Send/receive pattern +
+		 +

+Unrestricted +

+
+Incoming routing strategy +
+		 +

+N/A +

+
+Outgoing routing strategy +
+		 +

+N/A +

+
+ZMQ_HWM option action +
+		 +

+Block +

+
+
+

RETURN VALUE

+
+

The zmq_socket() function shall return an opaque handle to the newly created +socket if successful. Otherwise, it shall return NULL and set errno to one of +the values defined below.

+
+

ERRORS

+
+
+
+EINVAL +
+
+

+The requested socket type is invalid. +

+
+
+EFAULT +
+
+

+The provided context was not valid (NULL). +

+
+
+ETERM +
+
+

+The context specified was terminated. +

+
+
+
+

SEE ALSO

+
+

zmq_init(3) +zmq_setsockopt(3) +zmq_bind(3) +zmq_connect(3) +zmq_send(3) +zmq_recv(3) +zmq_inproc(7) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_strerror.3 b/doc/zmq_strerror.3 index 43bb42e..e334d86 100644 --- a/doc/zmq_strerror.3 +++ b/doc/zmq_strerror.3 @@ -2,12 +2,12 @@ .\" Title: zmq_strerror .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_STRERROR" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_STRERROR" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_strerror.html b/doc/zmq_strerror.html new file mode 100644 index 0000000..2648aa5 --- /dev/null +++ b/doc/zmq_strerror.html @@ -0,0 +1,634 @@ + + + + + +zmq_strerror(3) + + + + + +
+

SYNOPSIS

+
+

const char *zmq_strerror (int errnum);

+
+

DESCRIPTION

+
+

The zmq_strerror() function shall return a pointer to an error message string +corresponding to the error number specified by the errnum argument. As ØMQ +defines additional error numbers over and above those defined by the operating +system, applications should use zmq_strerror() in preference to the standard +strerror() function.

+
+

RETURN VALUE

+
+

The zmq_strerror() function shall return a pointer to an error message +string.

+
+

ERRORS

+
+

No errors are defined.

+
+

EXAMPLE

+
+
+
Displaying an error message when a ØMQ context cannot be initialised
+
+
void *ctx = zmq_init (1, 1, 0);
+if (!ctx) {
+    printf ("Error occurred during zmq_init(): %s\n", zmq_strerror (errno));
+    abort ();
+}
+
+
+

SEE ALSO

+
+

zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_tcp.7 b/doc/zmq_tcp.7 index 08fba12..cee6c1b 100644 --- a/doc/zmq_tcp.7 +++ b/doc/zmq_tcp.7 @@ -2,12 +2,12 @@ .\" Title: zmq_tcp .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_TCP" "7" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_TCP" "7" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_tcp.html b/doc/zmq_tcp.html new file mode 100644 index 0000000..78356f5 --- /dev/null +++ b/doc/zmq_tcp.html @@ -0,0 +1,755 @@ + + + + + +zmq_tcp(7) + + + + + +
+

SYNOPSIS

+
+

TCP is an ubiquitous, reliable, unicast transport. When connecting distributed +applications over a network with ØMQ, using the TCP transport will likely be +your first choice.

+
+

ADDRESSING

+
+

A ØMQ address string consists of two parts as follows: +transport://endpoint. The transport part specifies the underlying +transport protocol to use, and for the TCP transport shall be set to tcp. +The meaning of the endpoint part for the TCP transport is defined below.

+

Assigning a local address to a socket

+

When assigning a local address to a socket using zmq_bind() with the tcp +transport, the endpoint shall be interpreted as an interface followed by a +colon and the TCP port number to use.

+

An interface may be specified by either of the following:

+
    +
  • +

    +The wild-card *, meaning all available interfaces. +

    +
    • +
  • +

    +The primary IPv4 address assigned to the interface, in its numeric + representation. +

    +
    • +
  • +

    +The interface name as defined by the operating system. +

    +
    • +
+
+ + + +
+
Note
+		Interface names are not standardised in any way and should be assumed to +be arbitrary and platform dependent. On Win32 platforms no short interface +names exist, thus only the primary IPv4 address may be used to specify an +interface.
+
+

Connecting a socket

+

When connecting a socket to a peer address using zmq_connect() with the tcp +transport, the endpoint shall be interpreted as a peer address followed by +a colon and the TCP port number to use.

+

A peer address may be specified by either of the following:

+
    +
  • +

    +The DNS name of the peer. +

    +
    • +
  • +

    +The IPv4 address of the peer, in it’s numeric representation. +

    +
    • +
+
+

WIRE FORMAT

+
+

ØMQ messages are transmitted over TCP in frames consisting of an encoded +payload length, followed by a flags field and the message body. The payload +length is defined as the combined length in octets of the message body and the +flags field.

+

For frames with a payload length not exceeding 254 octets, the payload +length shall be encoded as a single octet. The minimum valid payload length +of a frame is 1 octet, thus a payload length of 0 octets is invalid and such +frames SHOULD be ignored.

+

For frames with a payload length exceeding 254 octets, the payload length +shall be encoded as a single octet with the value 255 followed by the +payload length represented as a 64-bit unsigned integer in network byte +order.

+

The flags field consists of a single octet containing various control flags:

+

Bit 0 (MORE): More message parts to follow. A value of 0 indicates that there +are no more message parts to follow; or that the message being sent is not a +multi-part message. A value of 1 indicates that the message being sent is a +multi-part message and more message parts are to follow.

+

Bits 1-7: Reserved. Bits 1-7 are reserved for future expansion and MUST be +set to zero.

+

The following ABNF grammar represents a single frame:

+
+
+
    frame           = (length flags data)
+    length          = OCTET / (escape 8OCTET)
+    flags           = OCTET
+    escape          = %xFF
+    data            = *OCTET
+
+

The following diagram illustrates the layout of a frame with a payload length +not exceeding 254 octets:

+
+
+
0                   1                   2                   3
+0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+| Payload length|     Flags     |       Message body        ... |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+| Message body ...
++-+-+-+-+-+-+- ...
+
+

The following diagram illustrates the layout of a frame with a payload length +exceeding 254 octets:

+
+
+
0                   1                   2                   3
+0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|     0xff      |               Payload length              ... |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                       Payload length                      ... |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+| Payload length|     Flags     |        Message body       ... |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|  Message body ...
++-+-+-+-+-+-+-+ ...
+
+
+

EXAMPLES

+
+
+
Assigning a local address to a socket
+
+
/* TCP port 5555 on all available interfaces */
+rc = zmq_bind(socket, "tcp://*:5555");
+assert (rc == 0);
+/* TCP port 5555 on the local loop-back interface on all platforms */
+rc = zmq_bind(socket, "tcp://127.0.0.1:5555");
+assert (rc == 0);
+/* TCP port 5555 on the first Ethernet network interface on Linux */
+rc = zmq_bind(socket, "tcp://eth0:5555");
+assert (rc == 0);
+
+
+
Connecting a socket
+
+
/* Connecting using an IP address */
+rc = zmq_connect(socket, "tcp://192.168.1.1:5555");
+assert (rc == 0);
+/* Connecting using a DNS name */
+rc = zmq_connect(socket, "tcp://server1:5555");
+assert (rc == 0);
+
+
+

SEE ALSO

+
+

zmq_bind(3) +zmq_connect(3) +zmq_pgm(7) +zmq_ipc(7) +zmq_inproc(7) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_term.3 b/doc/zmq_term.3 index 608df99..f45add6 100644 --- a/doc/zmq_term.3 +++ b/doc/zmq_term.3 @@ -2,12 +2,12 @@ .\" Title: zmq_term .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_TERM" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_TERM" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_term.html b/doc/zmq_term.html new file mode 100644 index 0000000..590897a --- /dev/null +++ b/doc/zmq_term.html @@ -0,0 +1,672 @@ + + + + + +zmq_term(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_term (void *context);

+
+

DESCRIPTION

+
+

The zmq_term() function shall terminate the ØMQ context context.

+

Context termination is performed in the following steps:

+
    +
  1. +

    +Any blocking operations currently in progress on sockets open within + context shall return immediately with an error code of ETERM. With the + exception of zmq_close(), any further operations on sockets open within + context shall fail with an error code of ETERM. +

    +
    2. +
  2. +

    +After interrupting all blocking calls, zmq_term() shall block until the + following conditions are satisfied: +

    +
      +
    • +

      +All sockets open within context have been closed with zmq_close(). +

      +
      • +
    • +

      +For each socket within context, all messages sent by the application + with zmq_send() have either been physically transferred to a network + peer, or the socket’s linger period set with the ZMQ_LINGER socket + option has expired. +

      +
      • +
    +
    3. +
+

For further details regarding socket linger behaviour refer to the ZMQ_LINGER +option in zmq_setsockopt(3).

+
+

RETURN VALUE

+
+

The zmq_term() function shall return zero if successful. Otherwise it shall +return -1 and set errno to one of the values defined below.

+
+

ERRORS

+
+
+
+EFAULT +
+
+

+The provided context was not valid (NULL). +

+
+
+EINTR +
+
+

+Termination was interrupted by a signal. It can be restarted if needed. +

+
+
+
+

SEE ALSO

+
+

zmq(7) +zmq_init(3) +zmq_close(3) +zmq_setsockopt(3)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + diff --git a/doc/zmq_version.3 b/doc/zmq_version.3 index 36248e5..c8fcd6e 100644 --- a/doc/zmq_version.3 +++ b/doc/zmq_version.3 @@ -2,12 +2,12 @@ .\" Title: zmq_version .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/15/2011 +.\" Date: 03/30/2011 .\" Manual: 0MQ Manual -.\" Source: 0MQ 2.1.3 +.\" Source: 0MQ 2.1.4 .\" Language: English .\" -.TH "ZMQ_VERSION" "3" "03/15/2011" "0MQ 2\&.1\&.3" "0MQ Manual" +.TH "ZMQ_VERSION" "3" "03/30/2011" "0MQ 2\&.1\&.4" "0MQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/zmq_version.html b/doc/zmq_version.html new file mode 100644 index 0000000..fc59a72 --- /dev/null +++ b/doc/zmq_version.html @@ -0,0 +1,632 @@ + + + + + +zmq_version(3) + + + + + +
+

SYNOPSIS

+
+

void zmq_version (int *major, int *minor, int *patch);

+
+

DESCRIPTION

+
+

The zmq_version() function shall fill in the integer variables pointed to by +the major, minor and patch arguments with the major, minor and patch level +components of the ØMQ library version.

+

This functionality is intended for applications or language bindings +dynamically linking to the ØMQ library that wish to determine the actual +version of the ØMQ library they are using.

+
+

RETURN VALUE

+
+

There is no return value.

+
+

ERRORS

+
+

No errors are defined.

+
+

EXAMPLE

+
+
+
Printing out the version of the ØMQ library
+
+
int major, minor, patch;
+zmq_version (&major, &minor, &patch);
+printf ("Current 0MQ version is %d.%d.%d\n", major, minor, patch);
+
+
+

SEE ALSO

+
+

zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + -- cgit v1.2.3