From 525c7b125cb9e927ca0bb1063b633f5e8a866e39 Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Thu, 2 Nov 2023 21:45:48 +0100 Subject: [PATCH] Feature: zeromq3-x: integrate with ReadTheDocs (#4617) * add ReadTheDocs integration --- .gitignore | 1 - .readthedocs.yaml | 37 +++++++++ doc/create_page_list.sh | 20 +++++ doc/index.txt | 9 ++ doc/zmq.txt | 80 +++++++++--------- doc/zmq_bind.txt | 22 ++--- doc/zmq_close.txt | 10 +-- doc/zmq_connect.txt | 18 ++-- doc/zmq_ctx_destroy.txt | 12 +-- doc/zmq_ctx_get.txt | 4 +- doc/zmq_ctx_new.txt | 10 +-- doc/zmq_ctx_set.txt | 4 +- doc/zmq_disconnect.txt | 8 +- doc/zmq_epgm.txt | 163 ++++++++++++++++++++++++++++++++++++- doc/zmq_errno.txt | 2 +- doc/zmq_getsockopt.txt | 18 ++-- doc/zmq_init.txt | 6 +- doc/zmq_inproc.txt | 14 ++-- doc/zmq_ipc.txt | 16 ++-- doc/zmq_msg_close.txt | 12 +-- doc/zmq_msg_copy.txt | 12 +-- doc/zmq_msg_data.txt | 12 +-- doc/zmq_msg_get.txt | 8 +- doc/zmq_msg_init.txt | 12 +-- doc/zmq_msg_init_data.txt | 12 +-- doc/zmq_msg_init_size.txt | 12 +-- doc/zmq_msg_more.txt | 10 +-- doc/zmq_msg_move.txt | 12 +-- doc/zmq_msg_recv.txt | 18 ++-- doc/zmq_msg_send.txt | 14 ++-- doc/zmq_msg_set.txt | 4 +- doc/zmq_msg_size.txt | 12 +-- doc/zmq_pgm.txt | 16 ++-- doc/zmq_poll.txt | 8 +- doc/zmq_proxy.txt | 10 +-- doc/zmq_recv.txt | 16 ++-- doc/zmq_recvmsg.txt | 16 ++-- doc/zmq_send.txt | 12 +-- doc/zmq_sendmsg.txt | 12 +-- doc/zmq_setsockopt.txt | 18 ++-- doc/zmq_socket.txt | 34 ++++---- doc/zmq_socket_monitor.txt | 2 +- doc/zmq_strerror.txt | 2 +- doc/zmq_tcp.txt | 14 ++-- doc/zmq_term.txt | 12 +-- doc/zmq_unbind.txt | 8 +- doc/zmq_version.txt | 2 +- 47 files changed, 506 insertions(+), 280 deletions(-) create mode 100644 .readthedocs.yaml create mode 100755 doc/create_page_list.sh create mode 100644 doc/index.txt mode change 120000 => 100644 doc/zmq_epgm.txt diff --git a/.gitignore b/.gitignore index e8e20640..984b5eaa 100644 --- a/.gitignore +++ b/.gitignore @@ -17,7 +17,6 @@ autom4te.cache *.html *.pdf *.ps -.* *~ .*~ tests/test_term_endpoint diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..4bbdc6ca --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,37 @@ +# +# libzmq readthedocs.io integration +# +# This configuration file is processed by readthedocs.io to rebuild the +# libzmq documentation using Asciidoctor, see +# https://docs.readthedocs.io/en/stable/build-customization.html#asciidoc + +version: "2" + +formats: + - htmlzip + +build: + os: "ubuntu-22.04" + tools: + nodejs: "20" + # NOTE: as of Nov 2023, build.apt_packages is NOT considered when using build.commands + #apt_packages: + # - automake + # - autoconf + # - cmake + # - libtool + commands: + # install required tools + - npm install -g asciidoctor + + # HTML docs + # --------- + - doc/create_page_list.sh "$(pwd)/doc/__pagelist" "$(pwd)/doc" + - asciidoctor --backend html --destination-dir $READTHEDOCS_OUTPUT/html --attribute zmq_version='3.2.6' --attribute zmq_pagelist_dir=$(pwd)/doc doc/*.txt + + # HTMLZIP docs + # ------------ + # Note that for usability we make sure zip will create a zipfile containing just a flat list of HTML files; + # to achieve that it's important to avoid storing absolute paths when invoking "zip", thus we use -j + - mkdir -p $READTHEDOCS_OUTPUT/htmlzip/ + - cd $READTHEDOCS_OUTPUT/html && zip -j ../htmlzip/zeromq.zip *.html diff --git a/doc/create_page_list.sh b/doc/create_page_list.sh new file mode 100755 index 00000000..e49bfdcc --- /dev/null +++ b/doc/create_page_list.sh @@ -0,0 +1,20 @@ +#!/bin/bash + +# This Bash snippet is used to automatically generate an alphabetical list included by index.adoc +# It's invoked by at least 2 callers: +# - the Makefile[.am] for automake builds +# - the ReadTheDocs pipeline, see .readthedocs.yaml + +OUTPUT_FILE="$1" +ASCIIDOC_DIR="$2" + +echo >$OUTPUT_FILE +for adocfile in $(ls ${ASCIIDOC_DIR}/*.txt); do + adocfile_basename=$(basename ${adocfile}) + + # this script is used to produce an Asciidoc snippet that goes inside index.adoc... avoid listing index.adoc itself! + if [ "${adocfile_basename}" != "index.txt" ]; then + adocfile_basename_noext=${adocfile_basename//.txt/} + echo "* link:${adocfile_basename_noext}.html[${adocfile_basename_noext}]" >>$OUTPUT_FILE + fi +done diff --git a/doc/index.txt b/doc/index.txt new file mode 100644 index 00000000..e0d2a312 --- /dev/null +++ b/doc/index.txt @@ -0,0 +1,9 @@ +ZMQ API reference +================= + +This documentation is for libzmq {zmq_version}. + +Alphabetic list of documentation pages +-------------------------------------- + +include::{zmq_pagelist_dir}/__pagelist[] diff --git a/doc/zmq.txt b/doc/zmq.txt index 4c79e4d6..ad11fae3 100644 --- a/doc/zmq.txt +++ b/doc/zmq.txt @@ -35,25 +35,25 @@ you exit your application you must destroy the 'context'. These functions let you work with 'contexts': Create a new 0MQ context:: - linkzmq:zmq_ctx_new[3] + link:zmq_ctx_new.html[zmq_ctx_new] Work with context properties:: - linkzmq:zmq_ctx_set[3] - linkzmq:zmq_ctx_get[3] + link:zmq_ctx_set.html[zmq_ctx_set] + link:zmq_ctx_get.html[zmq_ctx_get] Destroy a 0MQ context:: - linkzmq:zmq_ctx_destroy[3] + link:zmq_ctx_destroy.html[zmq_ctx_destroy] Monitor a 0MQ context:: - linkzmq:zmq_ctx_set_monitor[3] + link:zmq_ctx_set_monitor.html[zmq_ctx_set_monitor] These deprecated functions let you create and destroy 'contexts': Initialise 0MQ context:: - linkzmq:zmq_init[3] + link:zmq_init.html[zmq_init] Terminate 0MQ context:: - linkzmq:zmq_term[3] + link:zmq_term.html[zmq_term] Thread safety @@ -88,64 +88,64 @@ data. The following functions are provided to work with messages: Initialise a message:: - linkzmq:zmq_msg_init[3] - linkzmq:zmq_msg_init_size[3] - linkzmq:zmq_msg_init_data[3] + link:zmq_msg_init.html[zmq_msg_init] + link:zmq_msg_init_size.html[zmq_msg_init_size] + link:zmq_msg_init_data.html[zmq_msg_init_data] Sending and receiving a message:: - linkzmq:zmq_msg_send[3] - linkzmq:zmq_msg_recv[3] + link:zmq_msg_send.html[zmq_msg_send] + link:zmq_msg_recv.html[zmq_msg_recv] Release a message:: - linkzmq:zmq_msg_close[3] + link:zmq_msg_close.html[zmq_msg_close] Access message content:: - linkzmq:zmq_msg_data[3] - linkzmq:zmq_msg_size[3] - linkzmq:zmq_msg_more[3] + link:zmq_msg_data.html[zmq_msg_data] + link:zmq_msg_size.html[zmq_msg_size] + link:zmq_msg_more.html[zmq_msg_more] Work with message properties:: - linkzmq:zmq_msg_get[3] - linkzmq:zmq_msg_set[3] + link:zmq_msg_get.html[zmq_msg_get] + link:zmq_msg_set.html[zmq_msg_set] Message manipulation:: - linkzmq:zmq_msg_copy[3] - linkzmq:zmq_msg_move[3] + link:zmq_msg_copy.html[zmq_msg_copy] + link:zmq_msg_move.html[zmq_msg_move] Sockets ~~~~~~~ 0MQ sockets present an abstraction of a asynchronous _message queue_, with the exact queueing semantics depending on the socket type in use. See -linkzmq:zmq_socket[3] for the socket types provided. +link:zmq_socket.html[zmq_socket] for the socket types provided. The following functions are provided to work with sockets: Creating a socket:: - linkzmq:zmq_socket[3] + link:zmq_socket.html[zmq_socket] Closing a socket:: - linkzmq:zmq_close[3] + link:zmq_close.html[zmq_close] Manipulating socket options:: - linkzmq:zmq_getsockopt[3] - linkzmq:zmq_setsockopt[3] + link:zmq_getsockopt.html[zmq_getsockopt] + link:zmq_setsockopt.html[zmq_setsockopt] Establishing a message flow:: - linkzmq:zmq_bind[3] - linkzmq:zmq_connect[3] + link:zmq_bind.html[zmq_bind] + link:zmq_connect.html[zmq_connect] Sending and receiving messages:: - linkzmq:zmq_msg_send[3] - linkzmq:zmq_msg_recv[3] - linkzmq:zmq_send[3] - linkzmq:zmq_recv[3] + link:zmq_msg_send.html[zmq_msg_send] + link:zmq_msg_recv.html[zmq_msg_recv] + link:zmq_send.html[zmq_send] + link:zmq_recv.html[zmq_recv] .Input/output multiplexing 0MQ provides a mechanism for applications to multiplex input/output events over a set containing both 0MQ sockets and standard sockets. This mechanism mirrors the standard _poll()_ system call, and is described in detail in -linkzmq:zmq_poll[3]. +link:zmq_poll.html[zmq_poll]. Transports @@ -157,16 +157,16 @@ advantages and drawbacks. The following transport mechanisms are provided: Unicast transport using TCP:: - linkzmq:zmq_tcp[7] + link:zmq_tcp.html[zmq_tcp] Reliable multicast transport using PGM:: - linkzmq:zmq_pgm[7] + link:zmq_pgm.html[zmq_pgm] Local inter-process communication transport:: - linkzmq:zmq_ipc[7] + link:zmq_ipc.html[zmq_ipc] Local in-process (inter-thread) communication transport:: - linkzmq:zmq_inproc[7] + link:zmq_inproc.html[zmq_inproc] Proxies @@ -174,7 +174,7 @@ Proxies 0MQ provides 'proxies' to create fanout and fan-in topologies. A proxy connects a 'frontend' socket to a 'backend' socket and switches all messages between the two sockets, opaquely. A proxy may optionally capture all traffic to a third -socket. To start a proxy in an application thread, use linkzmq:zmq_proxy[3]. +socket. To start a proxy in an application thread, use link:zmq_proxy.html[zmq_proxy]. ERROR HANDLING @@ -187,10 +187,10 @@ shall return either a NULL value (if returning a pointer) or a negative value 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 linkzmq:zmq_errno[3]. +to assist in these cases; for details refer to link:zmq_errno.html[zmq_errno]. The _zmq_strerror()_ function is provided to translate 0MQ-specific error codes -into error message strings; for details refer to linkzmq:zmq_strerror[3]. +into error message strings; for details refer to link:zmq_strerror.html[zmq_strerror]. MISCELLANEOUS @@ -198,7 +198,7 @@ MISCELLANEOUS The following miscellaneous functions are provided: Report 0MQ library version:: - linkzmq:zmq_version[3] + link:zmq_version.html[zmq_version] LANGUAGE BINDINGS diff --git a/doc/zmq_bind.txt b/doc/zmq_bind.txt index d45ba8c3..533b3428 100644 --- a/doc/zmq_bind.txt +++ b/doc/zmq_bind.txt @@ -23,17 +23,17 @@ The 'endpoint' is a string consisting of a 'transport'`://` followed by an 0MQ provides the the following transports: -'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7] -'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7] -'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7] -'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7] +'tcp':: unicast transport using TCP, see link:zmq_tcp.html[zmq_tcp] +'ipc':: local inter-process communication transport, see link:zmq_ipc.html[zmq_ipc] +'inproc':: local in-process (inter-thread) communication transport, see link:zmq_inproc.html[zmq_inproc] +'pgm', 'epgm':: reliable multicast transport using PGM, see link:zmq_pgm.html[zmq_pgm] Every 0MQ socket type except 'ZMQ_PAIR' supports one-to-many and many-to-one semantics. The precise semantics depend on the socket type and are defined in -linkzmq:zmq_socket[3]. +link:zmq_socket.html[zmq_socket]. -The 'ipc' and 'tcp' transports accept wildcard addresses: see linkzmq:zmq_ipc[7] -and linkzmq:zmq_tcp[7] for details. +The 'ipc' and 'tcp' transports accept wildcard addresses: see link:zmq_ipc.html[zmq_ipc] +and link:zmq_tcp.html[zmq_tcp] for details. NOTE: the address syntax may be different for _zmq_bind()_ and _zmq_connect()_ especially for the 'tcp', 'pgm' and 'epgm' transports. @@ -41,7 +41,7 @@ especially for the 'tcp', 'pgm' and 'epgm' transports. NOTE: following a _zmq_bind()_, the socket enters a 'mute' state unless or until at least one incoming or outgoing connection is made, at which point the socket enters a 'ready' state. In the mute state, the socket blocks or -drops messages according to the socket type, as defined in linkzmq:zmq_socket[3]. +drops messages according to the socket type, as defined in link:zmq_socket.html[zmq_socket]. By contrast, following a libzmq:zmq_connect[3], the socket enters the 'ready' state. @@ -91,9 +91,9 @@ assert (rc == 0); SEE ALSO -------- -linkzmq:zmq_connect[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +link:zmq_connect.html[zmq_connect] +link:zmq_socket.html[zmq_socket] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_close.txt b/doc/zmq_close.txt index 47f9bb2e..8d191bfc 100644 --- a/doc/zmq_close.txt +++ b/doc/zmq_close.txt @@ -23,7 +23,7 @@ _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 linkzmq:zmq_setsockopt[3] and linkzmq:zmq_term[3]. +For details refer to link:zmq_setsockopt.html[zmq_setsockopt] and link:zmq_term.html[zmq_term]. RETURN VALUE @@ -40,10 +40,10 @@ The provided 'socket' was invalid. SEE ALSO -------- -linkzmq:zmq_socket[3] -linkzmq:zmq_term[3] -linkzmq:zmq_setsockopt[3] -linkzmq:zmq[7] +link:zmq_socket.html[zmq_socket] +link:zmq_term.html[zmq_term] +link:zmq_setsockopt.html[zmq_setsockopt] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_connect.txt b/doc/zmq_connect.txt index 8028e381..2394ee49 100644 --- a/doc/zmq_connect.txt +++ b/doc/zmq_connect.txt @@ -23,14 +23,14 @@ The 'endpoint' is a string consisting of a 'transport'`://` followed by an 0MQ provides the the following transports: -'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7] -'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7] -'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7] -'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7] +'tcp':: unicast transport using TCP, see link:zmq_tcp.html[zmq_tcp] +'ipc':: local inter-process communication transport, see link:zmq_ipc.html[zmq_ipc] +'inproc':: local in-process (inter-thread) communication transport, see link:zmq_inproc.html[zmq_inproc] +'pgm', 'epgm':: reliable multicast transport using PGM, see link:zmq_pgm.html[zmq_pgm] Every 0MQ socket type except 'ZMQ_PAIR' supports one-to-many and many-to-one semantics. The precise semantics depend on the socket type and are defined in -linkzmq:zmq_socket[3]. +link:zmq_socket.html[zmq_socket]. NOTE: for most transports and socket types the connection is not performed immediately but as needed by 0MQ. Thus a successful call to _zmq_connect()_ @@ -44,7 +44,7 @@ _ZMQ_PAIR_ sockets, which do not automatically reconnect to endpoints. NOTE: following a _zmq_connect()_, the socket enters its normal 'ready' state. By contrast, following a _zmq_bind()_ alone, the socket enters a 'mute' state in which the socket blocks or drops messages according to the socket type, as -defined in linkzmq:zmq_socket[3]. +defined in link:zmq_socket.html[zmq_socket]. RETURN VALUE @@ -87,9 +87,9 @@ assert (rc == 0); SEE ALSO -------- -linkzmq:zmq_bind[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +link:zmq_bind.html[zmq_bind] +link:zmq_socket.html[zmq_socket] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_ctx_destroy.txt b/doc/zmq_ctx_destroy.txt index 640b6b8a..4fbba9a1 100644 --- a/doc/zmq_ctx_destroy.txt +++ b/doc/zmq_ctx_destroy.txt @@ -34,9 +34,9 @@ Context termination is performed in the following steps: option has expired. For further details regarding socket linger behavior refer to the _ZMQ_LINGER_ -option in linkzmq:zmq_setsockopt[3]. +option in link:zmq_setsockopt.html[zmq_setsockopt]. -This function replaces the deprecated function linkzmq:zmq_term[3]. +This function replaces the deprecated function link:zmq_term.html[zmq_term]. RETURN VALUE @@ -55,10 +55,10 @@ Termination was interrupted by a signal. It can be restarted if needed. SEE ALSO -------- -linkzmq:zmq[7] -linkzmq:zmq_init[3] -linkzmq:zmq_close[3] -linkzmq:zmq_setsockopt[3] +link:zmq.html[zmq] +link:zmq_init.html[zmq_init] +link:zmq_close.html[zmq_close] +link:zmq_setsockopt.html[zmq_setsockopt] AUTHORS diff --git a/doc/zmq_ctx_get.txt b/doc/zmq_ctx_get.txt index a39337f8..ad531388 100644 --- a/doc/zmq_ctx_get.txt +++ b/doc/zmq_ctx_get.txt @@ -58,8 +58,8 @@ assert (max_sockets == 256); SEE ALSO -------- -linkzmq:zmq_ctx_set[3] -linkzmq:zmq[7] +link:zmq_ctx_set.html[zmq_ctx_set] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_ctx_new.txt b/doc/zmq_ctx_new.txt index cd1bbca8..7bb4e068 100644 --- a/doc/zmq_ctx_new.txt +++ b/doc/zmq_ctx_new.txt @@ -16,7 +16,7 @@ DESCRIPTION ----------- The _zmq_ctx_new()_ function creates a new 0MQ 'context'. -This function replaces the deprecated function linkzmq:zmq_init[3]. +This function replaces the deprecated function link:zmq_init.html[zmq_init]. .Thread safety A 0MQ 'context' is thread safe and may be shared among as many application @@ -38,10 +38,10 @@ No error values are defined for this function. SEE ALSO -------- -linkzmq:zmq[7] -linkzmq:zmq_ctx_set[3] -linkzmq:zmq_ctx_get[3] -linkzmq:zmq_ctx_destroy[3] +link:zmq.html[zmq] +link:zmq_ctx_set.html[zmq_ctx_set] +link:zmq_ctx_get.html[zmq_ctx_get] +link:zmq_ctx_destroy.html[zmq_ctx_destroy] AUTHORS diff --git a/doc/zmq_ctx_set.txt b/doc/zmq_ctx_set.txt index 88fcc1e0..d48b9b97 100644 --- a/doc/zmq_ctx_set.txt +++ b/doc/zmq_ctx_set.txt @@ -66,8 +66,8 @@ assert (max_sockets == 256); SEE ALSO -------- -linkzmq:zmq_ctx_get[3] -linkzmq:zmq[7] +link:zmq_ctx_get.html[zmq_ctx_get] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_disconnect.txt b/doc/zmq_disconnect.txt index 13a4c2b7..4a01b164 100644 --- a/doc/zmq_disconnect.txt +++ b/doc/zmq_disconnect.txt @@ -18,7 +18,7 @@ The _zmq_disconnect()_ function shall disconnect a socket specified by the 'socket' argument from the endpoint specified by the 'endpoint' argument. -The 'endpoint' argument is as described in linkzmq:zmq_connect[3] +The 'endpoint' argument is as described in link:zmq_connect.html[zmq_connect] RETURN VALUE @@ -56,9 +56,9 @@ assert (rc == 0); SEE ALSO -------- -linkzmq:zmq_connect[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +link:zmq_connect.html[zmq_connect] +link:zmq_socket.html[zmq_socket] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_epgm.txt b/doc/zmq_epgm.txt deleted file mode 120000 index 4d58b1be..00000000 --- a/doc/zmq_epgm.txt +++ /dev/null @@ -1 +0,0 @@ -zmq_pgm.txt \ No newline at end of file diff --git a/doc/zmq_epgm.txt b/doc/zmq_epgm.txt new file mode 100644 index 00000000..cef43cc0 --- /dev/null +++ b/doc/zmq_epgm.txt @@ -0,0 +1,162 @@ +zmq_pgm(7) +========== + + +NAME +---- +zmq_pgm - 0MQ reliable multicast transport using PGM + + +SYNOPSIS +-------- +PGM (Pragmatic General Multicast) is a protocol for reliable multicast +transport of data over IP networks. + + +DESCRIPTION +----------- +0MQ 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" or EPGM 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. For details, refer to the +'ZMQ_RATE', and 'ZMQ_RECOVERY_IVL' options documented in +link:zmq_setsockopt.html[zmq_setsockopt]. + +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 0MQ endpoint is a string consisting of a 'transport'`://` followed by an +'address'. The 'transport' specifies the underlying protocol to use. The +'address' specifies the transport-specific address to connect to. + +For the PGM transport, the transport is `pgm`, and for the EPGM protocol the +transport is `epgm`. The meaning of the 'address' part 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'. The 'interface' part can be omitted, in that case the default one +will be selected. + +A 'multicast address' is specified by an IPv4 multicast address in it's numeric +representation. + + +WIRE FORMAT +----------- +Consecutive PGM datagrams are interpreted by 0MQ as a single continuous stream +of data where 0MQ messages are not necessarily aligned with PGM datagram +boundaries and a single 0MQ message may span several PGM datagrams. This stream +of data consists of 0MQ messages encapsulated in 'frames' as described in +link:zmq_tcp.html[zmq_tcp]. + + +PGM datagram payload +~~~~~~~~~~~~~~~~~~~~ +The following ABNF grammar represents the payload of a single PGM datagram as +used by 0MQ: + +.... +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. + +Note that offset specifies where the first message begins rather than the first +message part. Thus, if there are trailing message parts at the beginning of +the packet the offset ignores them and points to first initial message part +in the packet. + +The following diagram illustrates the layout of a single PGM datagram payload: + +.... ++------------------+----------------------+ +| offset (16 bits) | data | ++------------------+----------------------+ +.... + +The following diagram further illustrates how three example 0MQ 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 +-------- +link:zmq_connect.html[zmq_connect] +link:zmq_setsockopt.html[zmq_setsockopt] +link:zmq_tcp.html[zmq_tcp] +link:zmq_ipc.html[zmq_ipc] +link:zmq_inproc.html[zmq_inproc] +link:zmq.html[zmq] + +AUTHORS +------- +This 0MQ manual page was written by Pieter Hintjens , +Martin Sustrik and Martin Lucina . diff --git a/doc/zmq_errno.txt b/doc/zmq_errno.txt index f9cf6cb0..7aa43b7e 100644 --- a/doc/zmq_errno.txt +++ b/doc/zmq_errno.txt @@ -41,7 +41,7 @@ No errors are defined. SEE ALSO -------- -linkzmq:zmq[7] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt index 0876ac85..1b3b30c0 100644 --- a/doc/zmq_getsockopt.txt +++ b/doc/zmq_getsockopt.txt @@ -45,7 +45,7 @@ The 'ZMQ_RCVMORE' option shall return True (1) if the message part last received from the 'socket' was a data part with more parts to follow. If there are no data parts to follow, this option shall return False (0). -Refer to linkzmq:zmq_send[3] and linkzmq:zmq_recv[3] for a detailed description +Refer to link:zmq_send.html[zmq_send] and link:zmq_recv.html[zmq_recv] for a detailed description of multi-part messages. [horizontal] @@ -65,7 +65,7 @@ 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, 0MQ shall take appropriate action such as blocking or dropping sent messages. Refer to the individual socket descriptions -in linkzmq:zmq_socket[3] for details on the exact action taken for each socket +in link:zmq_socket.html[zmq_socket] for details on the exact action taken for each socket type. [horizontal] @@ -85,7 +85,7 @@ 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, 0MQ shall take appropriate action such as blocking or dropping sent messages. Refer to the individual socket descriptions -in linkzmq:zmq_socket[3] for details on the exact action taken for each socket +in link:zmq_socket.html[zmq_socket] for details on the exact action taken for each socket type. [horizontal] @@ -108,7 +108,7 @@ 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 linkzmq:zmq_init[3] for details on allocating the number of I/O +See also link:zmq_init.html[zmq_init] for details on allocating the number of I/O threads for a specific _context_. [horizontal] @@ -194,8 +194,8 @@ 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 -linkzmq:zmq_close[3], and further affects the termination of the socket's -context with linkzmq:zmq_term[3]. The following outlines the different +link:zmq_close.html[zmq_close], and further affects the termination of the socket's +context with link:zmq_term.html[zmq_term]. The following outlines the different behaviours: * The default value of '-1' specifies an infinite linger period. Pending @@ -505,9 +505,9 @@ assert (rc == 0); SEE ALSO -------- -linkzmq:zmq_setsockopt[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +link:zmq_setsockopt.html[zmq_setsockopt] +link:zmq_socket.html[zmq_socket] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_init.txt b/doc/zmq_init.txt index 94795bf7..03bcff0e 100644 --- a/doc/zmq_init.txt +++ b/doc/zmq_init.txt @@ -25,7 +25,7 @@ A 0MQ '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. -This function is deprecated by linkzmq:zmq_ctx_new[3]. +This function is deprecated by link:zmq_ctx_new.html[zmq_ctx_new]. RETURN VALUE ------------ @@ -42,8 +42,8 @@ An invalid number of 'io_threads' was requested. SEE ALSO -------- -linkzmq:zmq[7] -linkzmq:zmq_term[3] +link:zmq.html[zmq] +link:zmq_term.html[zmq_term] AUTHORS diff --git a/doc/zmq_inproc.txt b/doc/zmq_inproc.txt index c6e3ea87..4c346520 100644 --- a/doc/zmq_inproc.txt +++ b/doc/zmq_inproc.txt @@ -15,7 +15,7 @@ sharing a single 0MQ 'context'. NOTE: No I/O threads are involved in passing messages using the 'inproc' transport. Therefore, if you are using a 0MQ 'context' for in-process messaging only you can initialise the 'context' with zero I/O threads. See -linkzmq:zmq_init[3] for details. +link:zmq_init.html[zmq_init] for details. ADDRESSING @@ -71,12 +71,12 @@ assert (rc == 0); SEE ALSO -------- -linkzmq:zmq_bind[3] -linkzmq:zmq_connect[3] -linkzmq:zmq_ipc[7] -linkzmq:zmq_tcp[7] -linkzmq:zmq_pgm[7] -linkzmq:zmq[7] +link:zmq_bind.html[zmq_bind] +link:zmq_connect.html[zmq_connect] +link:zmq_ipc.html[zmq_ipc] +link:zmq_tcp.html[zmq_tcp] +link:zmq_pgm.html[zmq_pgm] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_ipc.txt b/doc/zmq_ipc.txt index 4d9f6f1f..2ae13556 100644 --- a/doc/zmq_ipc.txt +++ b/doc/zmq_ipc.txt @@ -37,7 +37,7 @@ any restrictions placed by the operating system on the format and length of a When the address is `*`, _zmq_bind()_ shall generate a unique temporary pathname. The caller should retrieve this pathname using the ZMQ_LAST_ENDPOINT -socket option. See linkzmq:zmq_getsockopt[3] for details. +socket option. See link:zmq_getsockopt.html[zmq_getsockopt] for details. NOTE: any existing binding to the same endpoint shall be overridden. In this behavior, the 'ipc' transport is not consistent with the 'tcp' or 'inproc' @@ -70,13 +70,13 @@ assert (rc == 0); SEE ALSO -------- -linkzmq:zmq_bind[3] -linkzmq:zmq_connect[3] -linkzmq:zmq_inproc[7] -linkzmq:zmq_tcp[7] -linkzmq:zmq_pgm[7] -linkzmq:zmq_getsockopt[3] -linkzmq:zmq[7] +link:zmq_bind.html[zmq_bind] +link:zmq_connect.html[zmq_connect] +link:zmq_inproc.html[zmq_inproc] +link:zmq_tcp.html[zmq_tcp] +link:zmq_pgm.html[zmq_pgm] +link:zmq_getsockopt.html[zmq_getsockopt] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_msg_close.txt b/doc/zmq_msg_close.txt index 025302b7..b6ea4911 100644 --- a/doc/zmq_msg_close.txt +++ b/doc/zmq_msg_close.txt @@ -41,12 +41,12 @@ Invalid message. SEE ALSO -------- -linkzmq:zmq_msg_init[3] -linkzmq:zmq_msg_init_size[3] -linkzmq:zmq_msg_init_data[3] -linkzmq:zmq_msg_data[3] -linkzmq:zmq_msg_size[3] -linkzmq:zmq[7] +link:zmq_msg_init.html[zmq_msg_init] +link:zmq_msg_init_size.html[zmq_msg_init_size] +link:zmq_msg_init_data.html[zmq_msg_init_data] +link:zmq_msg_data.html[zmq_msg_data] +link:zmq_msg_size.html[zmq_msg_size] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_msg_copy.txt b/doc/zmq_msg_copy.txt index d6ce1b9c..d34d099b 100644 --- a/doc/zmq_msg_copy.txt +++ b/doc/zmq_msg_copy.txt @@ -43,12 +43,12 @@ Invalid message. SEE ALSO -------- -linkzmq:zmq_msg_move[3] -linkzmq:zmq_msg_init[3] -linkzmq:zmq_msg_init_size[3] -linkzmq:zmq_msg_init_data[3] -linkzmq:zmq_msg_close[3] -linkzmq:zmq[7] +link:zmq_msg_move.html[zmq_msg_move] +link:zmq_msg_init.html[zmq_msg_init] +link:zmq_msg_init_size.html[zmq_msg_init_size] +link:zmq_msg_init_data.html[zmq_msg_init_data] +link:zmq_msg_close.html[zmq_msg_close] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_msg_data.txt b/doc/zmq_msg_data.txt index 36a3ce34..d1e06f41 100644 --- a/doc/zmq_msg_data.txt +++ b/doc/zmq_msg_data.txt @@ -34,12 +34,12 @@ No errors are defined. SEE ALSO -------- -linkzmq:zmq_msg_size[3] -linkzmq:zmq_msg_init[3] -linkzmq:zmq_msg_init_size[3] -linkzmq:zmq_msg_init_data[3] -linkzmq:zmq_msg_close[3] -linkzmq:zmq[7] +link:zmq_msg_size.html[zmq_msg_size] +link:zmq_msg_init.html[zmq_msg_init] +link:zmq_msg_init_size.html[zmq_msg_init_size] +link:zmq_msg_init_data.html[zmq_msg_init_data] +link:zmq_msg_close.html[zmq_msg_close] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_msg_get.txt b/doc/zmq_msg_get.txt index d5fd9186..b4a7305b 100644 --- a/doc/zmq_msg_get.txt +++ b/doc/zmq_msg_get.txt @@ -60,10 +60,10 @@ while (true) { SEE ALSO -------- -linkzmq:zmq_msg_set[3] -linkzmq:zmq_msg_init[3] -linkzmq:zmq_msg_close[3] -linkzmq:zmq[7] +link:zmq_msg_set.html[zmq_msg_set] +link:zmq_msg_init.html[zmq_msg_init] +link:zmq_msg_close.html[zmq_msg_close] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_msg_init.txt b/doc/zmq_msg_init.txt index 1c2577d3..6a528025 100644 --- a/doc/zmq_msg_init.txt +++ b/doc/zmq_msg_init.txt @@ -51,12 +51,12 @@ assert (rc == 0); SEE ALSO -------- -linkzmq:zmq_msg_init_size[3] -linkzmq:zmq_msg_init_data[3] -linkzmq:zmq_msg_close[3] -linkzmq:zmq_msg_data[3] -linkzmq:zmq_msg_size[3] -linkzmq:zmq[7] +link:zmq_msg_init_size.html[zmq_msg_init_size] +link:zmq_msg_init_data.html[zmq_msg_init_data] +link:zmq_msg_close.html[zmq_msg_close] +link:zmq_msg_data.html[zmq_msg_data] +link:zmq_msg_size.html[zmq_msg_size] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_msg_init_data.txt b/doc/zmq_msg_init_data.txt index 48bcbe94..9d87a060 100644 --- a/doc/zmq_msg_init_data.txt +++ b/doc/zmq_msg_init_data.txt @@ -71,12 +71,12 @@ assert (rc == 0); SEE ALSO -------- -linkzmq:zmq_msg_init_size[3] -linkzmq:zmq_msg_init[3] -linkzmq:zmq_msg_close[3] -linkzmq:zmq_msg_data[3] -linkzmq:zmq_msg_size[3] -linkzmq:zmq[7] +link:zmq_msg_init_size.html[zmq_msg_init_size] +link:zmq_msg_init.html[zmq_msg_init] +link:zmq_msg_close.html[zmq_msg_close] +link:zmq_msg_data.html[zmq_msg_data] +link:zmq_msg_size.html[zmq_msg_size] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_msg_init_size.txt b/doc/zmq_msg_init_size.txt index 9be62635..63b0d173 100644 --- a/doc/zmq_msg_init_size.txt +++ b/doc/zmq_msg_init_size.txt @@ -44,12 +44,12 @@ Insufficient storage space is available. SEE ALSO -------- -linkzmq:zmq_msg_init_data[3] -linkzmq:zmq_msg_init[3] -linkzmq:zmq_msg_close[3] -linkzmq:zmq_msg_data[3] -linkzmq:zmq_msg_size[3] -linkzmq:zmq[7] +link:zmq_msg_init_data.html[zmq_msg_init_data] +link:zmq_msg_init.html[zmq_msg_init] +link:zmq_msg_close.html[zmq_msg_close] +link:zmq_msg_data.html[zmq_msg_data] +link:zmq_msg_size.html[zmq_msg_size] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_msg_more.txt b/doc/zmq_msg_more.txt index 7836872a..48372b6d 100644 --- a/doc/zmq_msg_more.txt +++ b/doc/zmq_msg_more.txt @@ -50,11 +50,11 @@ while (true) { SEE ALSO -------- -linkzmq:zmq_msg_get[3] -linkzmq:zmq_msg_set[3] -linkzmq:zmq_msg_init[3] -linkzmq:zmq_msg_close[3] -linkzmq:zmq[7] +link:zmq_msg_get.html[zmq_msg_get] +link:zmq_msg_set.html[zmq_msg_set] +link:zmq_msg_init.html[zmq_msg_init] +link:zmq_msg_close.html[zmq_msg_close] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_msg_move.txt b/doc/zmq_msg_move.txt index 6ab6eab1..6d0f2811 100644 --- a/doc/zmq_msg_move.txt +++ b/doc/zmq_msg_move.txt @@ -38,12 +38,12 @@ Invalid message. SEE ALSO -------- -linkzmq:zmq_msg_copy[3] -linkzmq:zmq_msg_init[3] -linkzmq:zmq_msg_init_size[3] -linkzmq:zmq_msg_init_data[3] -linkzmq:zmq_msg_close[3] -linkzmq:zmq[7] +link:zmq_msg_copy.html[zmq_msg_copy] +link:zmq_msg_init.html[zmq_msg_init] +link:zmq_msg_init_size.html[zmq_msg_init_size] +link:zmq_msg_init_data.html[zmq_msg_init_data] +link:zmq_msg_close.html[zmq_msg_close] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_msg_recv.txt b/doc/zmq_msg_recv.txt index db16346d..f8affd2d 100644 --- a/doc/zmq_msg_recv.txt +++ b/doc/zmq_msg_recv.txt @@ -14,7 +14,7 @@ SYNOPSIS DESCRIPTION ----------- -The _zmq_msg_recv()_ function is identical to linkzmq:zmq_recvmsg[3], which +The _zmq_msg_recv()_ function is identical to link:zmq_recvmsg.html[zmq_recvmsg], which shall be deprecated in future versions. _zmq_msg_recv()_ is more consistent with other message manipulation functions. @@ -40,7 +40,7 @@ message or none at all. The total number of message parts is unlimited except by available memory. An application that processes multi-part messages must use the _ZMQ_RCVMORE_ -linkzmq:zmq_getsockopt[3] option after calling _zmq_msg_recv()_ to determine if +link:zmq_getsockopt.html[zmq_getsockopt] option after calling _zmq_msg_recv()_ to determine if there are further parts to receive. @@ -61,7 +61,7 @@ The _zmq_msg_recv()_ operation is not supported by this socket type. The _zmq_msg_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 linkzmq:zmq_socket[3] for more information. +_messaging patterns_ section of link:zmq_socket.html[zmq_socket] for more information. *ETERM*:: The 0MQ 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: @@ -110,12 +110,12 @@ do { SEE ALSO -------- -linkzmq:zmq_recv[3] -linkzmq:zmq_send[3] -linkzmq:zmq_msg_send[3] -linkzmq:zmq_getsockopt[3] -linkzmq:zmq_socket[7] -linkzmq:zmq[7] +link:zmq_recv.html[zmq_recv] +link:zmq_send.html[zmq_send] +link:zmq_msg_send.html[zmq_msg_send] +link:zmq_getsockopt.html[zmq_getsockopt] +link:zmq_socket.html[zmq_socket] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_msg_send.txt b/doc/zmq_msg_send.txt index a5b335cf..5a401a65 100644 --- a/doc/zmq_msg_send.txt +++ b/doc/zmq_msg_send.txt @@ -14,7 +14,7 @@ SYNOPSIS DESCRIPTION ----------- -The _zmq_msg_send()_ function is identical to linkzmq:zmq_sendmsg[3], which +The _zmq_msg_send()_ function is identical to link:zmq_sendmsg.html[zmq_sendmsg], which shall be deprecated in future versions. _zmq_msg_send()_ is more consistent with other message manipulation functions. @@ -69,7 +69,7 @@ The _zmq_msg_send()_ operation is not supported by this socket type. The _zmq_msg_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 linkzmq:zmq_socket[3] for more information. +_messaging patterns_ section of link:zmq_socket.html[zmq_socket] for more information. *ETERM*:: The 0MQ 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: @@ -108,11 +108,11 @@ rc = zmq_msg_send (&part3, socket, 0); SEE ALSO -------- -linkzmq:zmq_recv[3] -linkzmq:zmq_send[3] -linkzmq:zmq_msg_recv[3] -linkzmq:zmq_socket[7] -linkzmq:zmq[7] +link:zmq_recv.html[zmq_recv] +link:zmq_send.html[zmq_send] +link:zmq_msg_recv.html[zmq_msg_recv] +link:zmq_socket.html[zmq_socket] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_msg_set.txt b/doc/zmq_msg_set.txt index 2569387f..6df27aa5 100644 --- a/doc/zmq_msg_set.txt +++ b/doc/zmq_msg_set.txt @@ -36,8 +36,8 @@ The requested property _property_ is unknown. SEE ALSO -------- -linkzmq:zmq_msg_get[3] -linkzmq:zmq[7] +link:zmq_msg_get.html[zmq_msg_get] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_msg_size.txt b/doc/zmq_msg_size.txt index 08d74156..6f8a0d5b 100644 --- a/doc/zmq_msg_size.txt +++ b/doc/zmq_msg_size.txt @@ -34,12 +34,12 @@ No errors are defined. SEE ALSO -------- -linkzmq:zmq_msg_data[3] -linkzmq:zmq_msg_init[3] -linkzmq:zmq_msg_init_size[3] -linkzmq:zmq_msg_init_data[3] -linkzmq:zmq_msg_close[3] -linkzmq:zmq[7] +link:zmq_msg_data.html[zmq_msg_data] +link:zmq_msg_init.html[zmq_msg_init] +link:zmq_msg_init_size.html[zmq_msg_init_size] +link:zmq_msg_init_data.html[zmq_msg_init_data] +link:zmq_msg_close.html[zmq_msg_close] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_pgm.txt b/doc/zmq_pgm.txt index 7b6b9851..cef43cc0 100644 --- a/doc/zmq_pgm.txt +++ b/doc/zmq_pgm.txt @@ -25,7 +25,7 @@ The 'pgm' and 'epgm' transports can only be used with the 'ZMQ_PUB' and Further, PGM sockets are rate limited by default. For details, refer to the 'ZMQ_RATE', and 'ZMQ_RECOVERY_IVL' options documented in -linkzmq:zmq_setsockopt[3]. +link:zmq_setsockopt.html[zmq_setsockopt]. CAUTION: The 'pgm' transport implementation requires access to raw IP sockets. Additional privileges may be required on some operating systems for this @@ -73,7 +73,7 @@ Consecutive PGM datagrams are interpreted by 0MQ as a single continuous stream of data where 0MQ messages are not necessarily aligned with PGM datagram boundaries and a single 0MQ message may span several PGM datagrams. This stream of data consists of 0MQ messages encapsulated in 'frames' as described in -linkzmq:zmq_tcp[7]. +link:zmq_tcp.html[zmq_tcp]. PGM datagram payload @@ -149,12 +149,12 @@ assert (rc == 0); SEE ALSO -------- -linkzmq:zmq_connect[3] -linkzmq:zmq_setsockopt[3] -linkzmq:zmq_tcp[7] -linkzmq:zmq_ipc[7] -linkzmq:zmq_inproc[7] -linkzmq:zmq[7] +link:zmq_connect.html[zmq_connect] +link:zmq_setsockopt.html[zmq_setsockopt] +link:zmq_tcp.html[zmq_tcp] +link:zmq_ipc.html[zmq_ipc] +link:zmq_inproc.html[zmq_inproc] +link:zmq.html[zmq] AUTHORS ------- diff --git a/doc/zmq_poll.txt b/doc/zmq_poll.txt index fc6d3004..f0310482 100644 --- a/doc/zmq_poll.txt +++ b/doc/zmq_poll.txt @@ -118,10 +118,10 @@ assert (rc >= 0); SEE ALSO -------- -linkzmq:zmq_socket[3] -linkzmq:zmq_send[3] -linkzmq:zmq_recv[3] -linkzmq:zmq[7] +link:zmq_socket.html[zmq_socket] +link:zmq_send.html[zmq_send] +link:zmq_recv.html[zmq_recv] +link:zmq.html[zmq] Your operating system documentation for the _poll()_ system call. diff --git a/doc/zmq_proxy.txt b/doc/zmq_proxy.txt index 9368429f..cf9533d9 100644 --- a/doc/zmq_proxy.txt +++ b/doc/zmq_proxy.txt @@ -31,7 +31,7 @@ If the capture socket is not NULL, the proxy shall send all messages, received on both frontend and backend, to the capture socket. The capture socket should be a 'ZMQ_PUB', 'ZMQ_DEALER', 'ZMQ_PUSH', or 'ZMQ_PAIR' socket. -Refer to linkzmq:zmq_socket[3] for a description of the available socket types. +Refer to link:zmq_socket.html[zmq_socket] for a description of the available socket types. EXAMPLE USAGE ------------- @@ -86,10 +86,10 @@ zmq_proxy (frontend, backend, NULL); SEE ALSO -------- -linkzmq:zmq_bind[3] -linkzmq:zmq_connect[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +link:zmq_bind.html[zmq_bind] +link:zmq_connect.html[zmq_connect] +link:zmq_socket.html[zmq_socket] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_recv.txt b/doc/zmq_recv.txt index 923baddf..35760a8b 100644 --- a/doc/zmq_recv.txt +++ b/doc/zmq_recv.txt @@ -35,7 +35,7 @@ message or none at all. The total number of message parts is unlimited except by available memory. An application that processes multi-part messages must use the _ZMQ_RCVMORE_ -linkzmq:zmq_getsockopt[3] option after calling _zmq_recv()_ to determine if +link:zmq_getsockopt.html[zmq_getsockopt] option after calling _zmq_recv()_ to determine if there are further parts to receive. RETURN VALUE @@ -56,7 +56,7 @@ The _zmq_recv()_ operation is not supported by this socket type. 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 linkzmq:zmq_socket[3] for more information. +_messaging patterns_ section of link:zmq_socket.html[zmq_socket] for more information. *ETERM*:: The 0MQ 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: @@ -78,12 +78,12 @@ assert (nbytes != -1); SEE ALSO -------- -linkzmq:zmq_recvmsg[3] -linkzmq:zmq_send[3] -linkzmq:zmq_sendmsg[3] -linkzmq:zmq_getsockopt[3] -linkzmq:zmq_socket[7] -linkzmq:zmq[7] +link:zmq_recvmsg.html[zmq_recvmsg] +link:zmq_send.html[zmq_send] +link:zmq_sendmsg.html[zmq_sendmsg] +link:zmq_getsockopt.html[zmq_getsockopt] +link:zmq_socket.html[zmq_socket] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_recvmsg.txt b/doc/zmq_recvmsg.txt index 9aededda..f43ee910 100644 --- a/doc/zmq_recvmsg.txt +++ b/doc/zmq_recvmsg.txt @@ -38,7 +38,7 @@ message or none at all. The total number of message parts is unlimited except by available memory. An application that processes multi-part messages must use the _ZMQ_RCVMORE_ -linkzmq:zmq_getsockopt[3] option after calling _zmq_recvmsg()_ to determine if +link:zmq_getsockopt.html[zmq_getsockopt] option after calling _zmq_recvmsg()_ to determine if there are further parts to receive. @@ -59,7 +59,7 @@ The _zmq_recvmsg()_ operation is not supported by this socket type. The _zmq_recvmsg()_ 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 linkzmq:zmq_socket[3] for more information. +_messaging patterns_ section of link:zmq_socket.html[zmq_socket] for more information. *ETERM*:: The 0MQ 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: @@ -108,12 +108,12 @@ do { SEE ALSO -------- -linkzmq:zmq_recv[3] -linkzmq:zmq_send[3] -linkzmq:zmq_sendmsg[3] -linkzmq:zmq_getsockopt[3] -linkzmq:zmq_socket[7] -linkzmq:zmq[7] +link:zmq_recv.html[zmq_recv] +link:zmq_send.html[zmq_send] +link:zmq_sendmsg.html[zmq_sendmsg] +link:zmq_getsockopt.html[zmq_getsockopt] +link:zmq_socket.html[zmq_socket] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_send.txt b/doc/zmq_send.txt index 9409f1f8..ecf28026 100644 --- a/doc/zmq_send.txt +++ b/doc/zmq_send.txt @@ -61,7 +61,7 @@ The _zmq_send()_ operation is not supported by this socket type. 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 linkzmq:zmq_socket[3] for more information. +_messaging patterns_ section of link:zmq_socket.html[zmq_socket] for more information. *ETERM*:: The 0MQ 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: @@ -87,11 +87,11 @@ assert (rc == 2); SEE ALSO -------- -linkzmq:zmq_sendmsg[3] -linkzmq:zmq_recv[3] -linkzmq:zmq_recvmsg[3] -linkzmq:zmq_socket[7] -linkzmq:zmq[7] +link:zmq_sendmsg.html[zmq_sendmsg] +link:zmq_recv.html[zmq_recv] +link:zmq_recvmsg.html[zmq_recvmsg] +link:zmq_socket.html[zmq_socket] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_sendmsg.txt b/doc/zmq_sendmsg.txt index aacd7aec..2150b10a 100644 --- a/doc/zmq_sendmsg.txt +++ b/doc/zmq_sendmsg.txt @@ -66,7 +66,7 @@ The _zmq_sendmsg()_ operation is not supported by this socket type. The _zmq_sendmsg()_ 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 linkzmq:zmq_socket[3] for more information. +_messaging patterns_ section of link:zmq_socket.html[zmq_socket] for more information. *ETERM*:: The 0MQ 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: @@ -105,11 +105,11 @@ rc = zmq_sendmsg (socket, &part3, 0); SEE ALSO -------- -linkzmq:zmq_recv[3] -linkzmq:zmq_recv[3] -linkzmq:zmq_recvmsg[3] -linkzmq:zmq_socket[7] -linkzmq:zmq[7] +link:zmq_recv.html[zmq_recv] +link:zmq_recv.html[zmq_recv] +link:zmq_recvmsg.html[zmq_recvmsg] +link:zmq_socket.html[zmq_socket] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt index 41bc7392..218f7763 100644 --- a/doc/zmq_setsockopt.txt +++ b/doc/zmq_setsockopt.txt @@ -36,7 +36,7 @@ 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, 0MQ shall take appropriate action such as blocking or dropping sent messages. Refer to the individual socket descriptions -in linkzmq:zmq_socket[3] for details on the exact action taken for each socket +in link:zmq_socket.html[zmq_socket] for details on the exact action taken for each socket type. NOTE: 0MQ does not guarantee that the socket will accept as many as ZMQ_SNDHWM @@ -60,7 +60,7 @@ 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, 0MQ shall take appropriate action such as blocking or dropping sent messages. Refer to the individual socket descriptions -in linkzmq:zmq_socket[3] for details on the exact action taken for each socket +in link:zmq_socket.html[zmq_socket] for details on the exact action taken for each socket type. [horizontal] @@ -83,7 +83,7 @@ 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 linkzmq:zmq_init[3] for details on allocating the number of I/O +See also link:zmq_init.html[zmq_init] for details on allocating the number of I/O threads for a specific _context_. [horizontal] @@ -147,7 +147,7 @@ Applicable socket types:: ZMQ_REQ, ZMQ_REP, ZMQ_ROUTER, ZMQ_DEALER. ZMQ_RATE: Set multicast data rate ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'ZMQ_RATE' option shall set the maximum send or receive data rate for -multicast transports such as linkzmq:zmq_pgm[7] using the specified 'socket'. +multicast transports such as link:zmq_pgm.html[zmq_pgm] using the specified 'socket'. [horizontal] Option value type:: int @@ -206,8 +206,8 @@ 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 -linkzmq:zmq_close[3], and further affects the termination of the socket's -context with linkzmq:zmq_term[3]. The following outlines the different +link:zmq_close.html[zmq_close], and further affects the termination of the socket's +context with link:zmq_term.html[zmq_term]. The following outlines the different behaviours: * The default value of '-1' specifies an infinite linger period. Pending @@ -509,9 +509,9 @@ assert (rc); SEE ALSO -------- -linkzmq:zmq_getsockopt[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +link:zmq_getsockopt.html[zmq_getsockopt] +link:zmq_socket.html[zmq_socket] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt index 9a435870..e5137ed4 100644 --- a/doc/zmq_socket.txt +++ b/doc/zmq_socket.txt @@ -21,9 +21,9 @@ 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 linkzmq:zmq_connect[3], or at least one +connected to at least one endpoint with link:zmq_connect.html[zmq_connect], or at least one endpoint must be created for accepting incoming connections with -linkzmq:zmq_bind[3]. +link:zmq_bind.html[zmq_bind]. .Key differences to conventional sockets Generally speaking, conventional sockets present a _synchronous_ interface to @@ -73,7 +73,7 @@ matched with the last issued request. When a 'ZMQ_REQ' socket enters the 'mute' state due to having reached the high water mark for all _services_, or if there are no _services_ at all, then -any linkzmq:zmq_send[3] operations on the socket shall block until the +any link:zmq_send.html[zmq_send] operations on the socket shall block until the 'mute' state ends or at least one _service_ becomes available for sending; messages are not discarded. @@ -118,7 +118,7 @@ peers, and each message received is fair-queued from all connected peers. When a 'ZMQ_DEALER' socket enters the 'mute' state due to having reached the high water mark for all peers, or if there are no peers at all, then any -linkzmq:zmq_send[3] operations on the socket shall block until the mute +link:zmq_send.html[zmq_send] operations on the socket shall block until the mute state ends or at least one peer becomes available for sending; messages are not discarded. @@ -184,7 +184,7 @@ 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 linkzmq:zmq_recv[3] function is not implemented for this socket type. +The link:zmq_recv.html[zmq_recv] function is not implemented for this socket type. When a 'ZMQ_PUB' socket enters the 'mute' state due to having reached the high water mark for a _subscriber_, then any messages that would be sent to the @@ -205,7 +205,7 @@ 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 linkzmq:zmq_setsockopt[3] to +any messages, use the 'ZMQ_SUBSCRIBE' option of link:zmq_setsockopt.html[zmq_setsockopt] to specify which messages to subscribe to. The _zmq_send()_ function is not implemented for this socket type. @@ -269,7 +269,7 @@ socket type. When a 'ZMQ_PUSH' socket enters the 'mute' state due to having reached the high water mark for all downstream _nodes_, or if there are no downstream -_nodes_ at all, then any linkzmq:zmq_send[3] operations on the socket shall +_nodes_ at all, then any link:zmq_send.html[zmq_send] operations on the socket shall block until the mute state ends or at least one downstream _node_ becomes available for sending; messages are not discarded. @@ -315,11 +315,11 @@ time. No message routing or filtering is performed on messages sent over a When a 'ZMQ_PAIR' socket enters the 'mute' state due to having reached the high water mark for the connected peer, or if no peer is connected, then -any linkzmq:zmq_send[3] operations on the socket shall block until the peer +any link:zmq_send.html[zmq_send] 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 linkzmq:zmq_inproc[7] transport and do not implement functionality such +the link:zmq_inproc.html[zmq_inproc] transport and do not implement functionality such as auto-reconnection. 'ZMQ_PAIR' sockets are considered experimental and may have other missing or broken aspects. @@ -353,14 +353,14 @@ The context specified was terminated. SEE ALSO -------- -linkzmq:zmq_init[3] -linkzmq:zmq_setsockopt[3] -linkzmq:zmq_bind[3] -linkzmq:zmq_connect[3] -linkzmq:zmq_send[3] -linkzmq:zmq_recv[3] -linkzmq:zmq_inproc[7] -linkzmq:zmq[7] +link:zmq_init.html[zmq_init] +link:zmq_setsockopt.html[zmq_setsockopt] +link:zmq_bind.html[zmq_bind] +link:zmq_connect.html[zmq_connect] +link:zmq_send.html[zmq_send] +link:zmq_recv.html[zmq_recv] +link:zmq_inproc.html[zmq_inproc] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_socket_monitor.txt b/doc/zmq_socket_monitor.txt index f289c908..5b315b6c 100644 --- a/doc/zmq_socket_monitor.txt +++ b/doc/zmq_socket_monitor.txt @@ -280,7 +280,7 @@ zmq_term (ctx); SEE ALSO -------- -linkzmq:zmq[7] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_strerror.txt b/doc/zmq_strerror.txt index 2cd98296..99e2d674 100644 --- a/doc/zmq_strerror.txt +++ b/doc/zmq_strerror.txt @@ -46,7 +46,7 @@ if (!ctx) { SEE ALSO -------- -linkzmq:zmq[7] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_tcp.txt b/doc/zmq_tcp.txt index a87aaa0c..b05ed414 100644 --- a/doc/zmq_tcp.txt +++ b/doc/zmq_tcp.txt @@ -43,7 +43,7 @@ The TCP port number may be specified by: * The wild-card `*`, meaning a system-assigned ephemeral port. When using ephemeral ports, the caller should retrieve the actual assigned -port using the ZMQ_LAST_ENDPOINT socket option. See linkzmq:zmq_getsockopt[3] +port using the ZMQ_LAST_ENDPOINT socket option. See link:zmq_getsockopt.html[zmq_getsockopt] for details. @@ -87,12 +87,12 @@ assert (rc == 0); SEE ALSO -------- -linkzmq:zmq_bind[3] -linkzmq:zmq_connect[3] -linkzmq:zmq_pgm[7] -linkzmq:zmq_ipc[7] -linkzmq:zmq_inproc[7] -linkzmq:zmq[7] +link:zmq_bind.html[zmq_bind] +link:zmq_connect.html[zmq_connect] +link:zmq_pgm.html[zmq_pgm] +link:zmq_ipc.html[zmq_ipc] +link:zmq_inproc.html[zmq_inproc] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_term.txt b/doc/zmq_term.txt index f3604ce5..341c4918 100644 --- a/doc/zmq_term.txt +++ b/doc/zmq_term.txt @@ -34,9 +34,9 @@ Context termination is performed in the following steps: option has expired. For further details regarding socket linger behaviour refer to the _ZMQ_LINGER_ -option in linkzmq:zmq_setsockopt[3]. +option in link:zmq_setsockopt.html[zmq_setsockopt]. -This function is deprecated by linkzmq:zmq_ctx_destroy[3]. +This function is deprecated by link:zmq_ctx_destroy.html[zmq_ctx_destroy]. RETURN VALUE ------------ @@ -54,10 +54,10 @@ Termination was interrupted by a signal. It can be restarted if needed. SEE ALSO -------- -linkzmq:zmq[7] -linkzmq:zmq_init[3] -linkzmq:zmq_close[3] -linkzmq:zmq_setsockopt[3] +link:zmq.html[zmq] +link:zmq_init.html[zmq_init] +link:zmq_close.html[zmq_close] +link:zmq_setsockopt.html[zmq_setsockopt] AUTHORS diff --git a/doc/zmq_unbind.txt b/doc/zmq_unbind.txt index 4633ee0f..760b8248 100644 --- a/doc/zmq_unbind.txt +++ b/doc/zmq_unbind.txt @@ -18,7 +18,7 @@ The _zmq_unbind()_ function shall unbind a socket specified by the 'socket' argument from the endpoint specified by the 'endpoint' argument. -The 'endpoint' argument is as described in linkzmq:zmq_bind[3] +The 'endpoint' argument is as described in link:zmq_bind.html[zmq_bind] RETURN VALUE @@ -54,9 +54,9 @@ assert (rc == 0); SEE ALSO -------- -linkzmq:zmq_bind[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +link:zmq_bind.html[zmq_bind] +link:zmq_socket.html[zmq_socket] +link:zmq.html[zmq] AUTHORS diff --git a/doc/zmq_version.txt b/doc/zmq_version.txt index eeb0b40b..d089d024 100644 --- a/doc/zmq_version.txt +++ b/doc/zmq_version.txt @@ -45,7 +45,7 @@ printf ("Current 0MQ version is %d.%d.%d\n", major, minor, patch); SEE ALSO -------- -linkzmq:zmq[7] +link:zmq.html[zmq] AUTHORS -------