From b6ca9b2983cbcac8c1988e1aee7b84143b484761 Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Sat, 21 Oct 2023 01:50:38 +0200 Subject: [PATCH] Feature: modernize API documentation * migrate from the old, unmaintained "asciidoc-py" tool to the new "asciidoctor" generator * migrate from asciidoc-py syntax to the modern Asciidoc syntax (especially page titles and section titles) * remove the need of "xmlto" utility to create the manpage output; use asciidoctor for that * add HTML output support to the doc/Makefile by using asciidoctor * change API documentation files extension from .txt to .adoc to make it more explicit that they are Asciidoc-encoded (as a bonus several IDE plugins will autodetect the .adoc format as Asciidoc) * remove asciidoc.conf: asciidoctor does not support that; this also required replacing the macro linkzmq into all documentation pages * add a new Github action CI do deploy to Github Pages the static HTMLs produced by Asciidoctors * removed references to the "xmlto" and "a2x" tools from the build and packaging systems: Asciidoctor can convert the documentation directly to e.g. pdf (via extended converters) and anyway there was no code/target for using "xmlto" and "a2x" tools anyway --- .github/workflows/CI.yaml | 2 +- .github/workflows/Docs.yaml | 50 ++++++ CMakeLists.txt | 29 ++-- acinclude.m4 | 9 +- builds/cmake/Modules/FindAsciiDoc.cmake | 26 --- builds/cmake/Modules/FindAsciiDoctor.cmake | 23 +++ configure.ac | 4 - doc/Makefile.am | 74 +++++---- doc/asciidoc.conf | 56 ------- doc/{zmq.txt => zmq.adoc} | 151 ++++++++---------- ...er_dec.txt => zmq_atomic_counter_dec.adoc} | 34 ++-- ...oy.txt => zmq_atomic_counter_destroy.adoc} | 34 ++-- ...er_inc.txt => zmq_atomic_counter_inc.adoc} | 34 ++-- ...er_new.txt => zmq_atomic_counter_new.adoc} | 34 ++-- ...er_set.txt => zmq_atomic_counter_set.adoc} | 34 ++-- ...alue.txt => zmq_atomic_counter_value.adoc} | 34 ++-- doc/{zmq_bind.txt => zmq_bind.adoc} | 55 +++---- doc/{zmq_close.txt => zmq_close.adoc} | 34 ++-- doc/{zmq_connect.txt => zmq_connect.adoc} | 49 +++--- ...connect_peer.txt => zmq_connect_peer.adoc} | 45 +++--- doc/zmq_ctx_destroy.txt | 67 -------- doc/{zmq_ctx_get.txt => zmq_ctx_get.adoc} | 33 ++-- ...q_ctx_get_ext.txt => zmq_ctx_get_ext.adoc} | 31 ++-- doc/{zmq_ctx_new.txt => zmq_ctx_new.adoc} | 34 ++-- doc/{zmq_ctx_set.txt => zmq_ctx_set.adoc} | 37 ++--- ...q_ctx_set_ext.txt => zmq_ctx_set_ext.adoc} | 31 ++-- ...ctx_shutdown.txt => zmq_ctx_shutdown.adoc} | 36 ++--- doc/{zmq_ctx_term.txt => zmq_ctx_term.adoc} | 38 ++--- doc/{zmq_curve.txt => zmq_curve.adoc} | 36 ++--- ...rve_keypair.txt => zmq_curve_keypair.adoc} | 35 ++-- ...curve_public.txt => zmq_curve_public.adoc} | 37 ++--- ...zmq_disconnect.txt => zmq_disconnect.adoc} | 37 ++--- doc/{zmq_errno.txt => zmq_errno.adoc} | 26 ++- ...zmq_getsockopt.txt => zmq_getsockopt.adoc} | 47 +++--- doc/{zmq_gssapi.txt => zmq_gssapi.adoc} | 32 ++-- doc/{zmq_has.txt => zmq_has.adoc} | 18 +-- doc/zmq_init.txt | 52 ------ doc/{zmq_inproc.txt => zmq_inproc.adoc} | 37 ++--- doc/{zmq_ipc.txt => zmq_ipc.adoc} | 39 ++--- doc/{zmq_msg_close.txt => zmq_msg_close.adoc} | 38 ++--- doc/{zmq_msg_copy.txt => zmq_msg_copy.adoc} | 41 ++--- doc/{zmq_msg_data.txt => zmq_msg_data.adoc} | 38 ++--- doc/{zmq_msg_get.txt => zmq_msg_get.adoc} | 35 ++-- doc/{zmq_msg_gets.txt => zmq_msg_gets.adoc} | 33 ++-- doc/{zmq_msg_init.txt => zmq_msg_init.adoc} | 41 ++--- ...it_buffer.txt => zmq_msg_init_buffer.adoc} | 38 ++--- ...g_init_data.txt => zmq_msg_init_data.adoc} | 41 ++--- ...g_init_size.txt => zmq_msg_init_size.adoc} | 38 ++--- doc/{zmq_msg_more.txt => zmq_msg_more.adoc} | 34 ++-- doc/{zmq_msg_move.txt => zmq_msg_move.adoc} | 38 ++--- doc/{zmq_msg_recv.txt => zmq_msg_recv.adoc} | 49 +++--- ...routing_id.txt => zmq_msg_routing_id.adoc} | 26 ++- doc/{zmq_msg_send.txt => zmq_msg_send.adoc} | 41 ++--- doc/{zmq_msg_set.txt => zmq_msg_set.adoc} | 28 ++-- ...ing_id.txt => zmq_msg_set_routing_id.adoc} | 28 ++-- doc/{zmq_msg_size.txt => zmq_msg_size.adoc} | 38 ++--- doc/{zmq_null.txt => zmq_null.adoc} | 21 +-- doc/{zmq_pgm.txt => zmq_pgm.adoc} | 50 +++--- doc/{zmq_plain.txt => zmq_plain.adoc} | 26 ++- doc/{zmq_poll.txt => zmq_poll.adoc} | 38 ++--- doc/{zmq_poller.txt => zmq_poller.adoc} | 41 ++--- doc/{zmq_ppoll.txt => zmq_ppoll.adoc} | 44 ++--- doc/{zmq_proxy.txt => zmq_proxy.adoc} | 37 ++--- ...steerable.txt => zmq_proxy_steerable.adoc} | 34 ++-- doc/{zmq_recv.txt => zmq_recv.adoc} | 43 ++--- doc/{zmq_recvmsg.txt => zmq_recvmsg.adoc} | 45 +++--- doc/{zmq_send.txt => zmq_send.adoc} | 37 ++--- ...zmq_send_const.txt => zmq_send_const.adoc} | 37 ++--- doc/{zmq_sendmsg.txt => zmq_sendmsg.adoc} | 35 ++-- ...zmq_setsockopt.txt => zmq_setsockopt.adoc} | 90 +++++------ doc/{zmq_socket.txt => zmq_socket.adoc} | 93 +++++------ ...et_monitor.txt => zmq_socket_monitor.adoc} | 31 ++-- ....txt => zmq_socket_monitor_versioned.adoc} | 28 ++-- doc/{zmq_strerror.txt => zmq_strerror.adoc} | 29 ++-- doc/{zmq_tcp.txt => zmq_tcp.adoc} | 40 ++--- doc/zmq_term.txt | 66 -------- doc/{zmq_timers.txt => zmq_timers.adoc} | 32 ++-- doc/{zmq_tipc.txt => zmq_tipc.adoc} | 37 ++--- doc/{zmq_udp.txt => zmq_udp.adoc} | 38 ++--- doc/{zmq_unbind.txt => zmq_unbind.adoc} | 42 ++--- doc/{zmq_version.txt => zmq_version.adoc} | 29 ++-- doc/{zmq_vmci.txt => zmq_vmci.adoc} | 37 ++--- ...zmq_z85_decode.txt => zmq_z85_decode.adoc} | 32 ++-- ...zmq_z85_encode.txt => zmq_z85_encode.adoc} | 32 ++-- packaging/debian/control | 2 +- packaging/debian/zeromq.dsc | 2 +- packaging/redhat/zeromq.spec | 13 +- 87 files changed, 1254 insertions(+), 2046 deletions(-) create mode 100644 .github/workflows/Docs.yaml delete mode 100644 builds/cmake/Modules/FindAsciiDoc.cmake create mode 100644 builds/cmake/Modules/FindAsciiDoctor.cmake delete mode 100644 doc/asciidoc.conf rename doc/{zmq.txt => zmq.adoc} (68%) rename doc/{zmq_atomic_counter_dec.txt => zmq_atomic_counter_dec.adoc} (74%) rename doc/{zmq_atomic_counter_destroy.txt => zmq_atomic_counter_destroy.adoc} (76%) rename doc/{zmq_atomic_counter_inc.txt => zmq_atomic_counter_inc.adoc} (73%) rename doc/{zmq_atomic_counter_new.txt => zmq_atomic_counter_new.adoc} (75%) rename doc/{zmq_atomic_counter_set.txt => zmq_atomic_counter_set.adoc} (74%) rename doc/{zmq_atomic_counter_value.txt => zmq_atomic_counter_value.adoc} (76%) rename doc/{zmq_bind.txt => zmq_bind.adoc} (71%) rename doc/{zmq_close.txt => zmq_close.adoc} (80%) rename doc/{zmq_connect.txt => zmq_connect.adoc} (80%) rename doc/{zmq_connect_peer.txt => zmq_connect_peer.adoc} (79%) delete mode 100644 doc/zmq_ctx_destroy.txt rename doc/{zmq_ctx_get.txt => zmq_ctx_get.adoc} (92%) rename doc/{zmq_ctx_get_ext.txt => zmq_ctx_get_ext.adoc} (89%) rename doc/{zmq_ctx_new.txt => zmq_ctx_new.adoc} (74%) rename doc/{zmq_ctx_set.txt => zmq_ctx_set.adoc} (94%) rename doc/{zmq_ctx_set_ext.txt => zmq_ctx_set_ext.adoc} (91%) rename doc/{zmq_ctx_shutdown.txt => zmq_ctx_shutdown.adoc} (78%) rename doc/{zmq_ctx_term.txt => zmq_ctx_term.adoc} (78%) rename doc/{zmq_curve.txt => zmq_curve.adoc} (88%) rename doc/{zmq_curve_keypair.txt => zmq_curve_keypair.adoc} (72%) rename doc/{zmq_curve_public.txt => zmq_curve_public.adoc} (77%) rename doc/{zmq_disconnect.txt => zmq_disconnect.adoc} (83%) rename doc/{zmq_errno.txt => zmq_errno.adoc} (85%) rename doc/{zmq_getsockopt.txt => zmq_getsockopt.adoc} (98%) rename doc/{zmq_gssapi.txt => zmq_gssapi.adoc} (88%) rename doc/{zmq_has.txt => zmq_has.adoc} (90%) delete mode 100644 doc/zmq_init.txt rename doc/{zmq_inproc.txt => zmq_inproc.adoc} (88%) rename doc/{zmq_ipc.txt => zmq_ipc.adoc} (89%) rename doc/{zmq_msg_close.txt => zmq_msg_close.adoc} (74%) rename doc/{zmq_msg_copy.txt => zmq_msg_copy.adoc} (78%) rename doc/{zmq_msg_data.txt => zmq_msg_data.adoc} (61%) rename doc/{zmq_msg_get.txt => zmq_msg_get.adoc} (86%) rename doc/{zmq_msg_gets.txt => zmq_msg_gets.adoc} (87%) rename doc/{zmq_msg_init.txt => zmq_msg_init.adoc} (71%) rename doc/{zmq_msg_init_buffer.txt => zmq_msg_init_buffer.adoc} (75%) rename doc/{zmq_msg_init_data.txt => zmq_msg_init_data.adoc} (83%) rename doc/{zmq_msg_init_size.txt => zmq_msg_init_size.adoc} (76%) rename doc/{zmq_msg_more.txt => zmq_msg_more.adoc} (81%) rename doc/{zmq_msg_move.txt => zmq_msg_move.adoc} (70%) rename doc/{zmq_msg_recv.txt => zmq_msg_recv.adoc} (82%) rename doc/{zmq_msg_routing_id.txt => zmq_msg_routing_id.adoc} (85%) rename doc/{zmq_msg_send.txt => zmq_msg_send.adoc} (90%) rename doc/{zmq_msg_set.txt => zmq_msg_set.adoc} (79%) rename doc/{zmq_msg_set_routing_id.txt => zmq_msg_set_routing_id.adoc} (78%) rename doc/{zmq_msg_size.txt => zmq_msg_size.adoc} (61%) rename doc/{zmq_null.txt => zmq_null.adoc} (71%) rename doc/{zmq_pgm.txt => zmq_pgm.adoc} (92%) rename doc/{zmq_plain.txt => zmq_plain.adoc} (79%) rename doc/{zmq_poll.txt => zmq_poll.adoc} (94%) rename doc/{zmq_poller.txt => zmq_poller.adoc} (97%) rename doc/{zmq_ppoll.txt => zmq_ppoll.adoc} (91%) rename doc/{zmq_proxy.txt => zmq_proxy.adoc} (89%) rename doc/{zmq_proxy_steerable.txt => zmq_proxy_steerable.adoc} (92%) rename doc/{zmq_recv.txt => zmq_recv.adoc} (82%) rename doc/{zmq_recvmsg.txt => zmq_recvmsg.adoc} (84%) rename doc/{zmq_send.txt => zmq_send.adoc} (90%) rename doc/{zmq_send_const.txt => zmq_send_const.adoc} (90%) rename doc/{zmq_sendmsg.txt => zmq_sendmsg.adoc} (92%) rename doc/{zmq_setsockopt.txt => zmq_setsockopt.adoc} (96%) rename doc/{zmq_socket.txt => zmq_socket.adoc} (92%) rename doc/{zmq_socket_monitor.txt => zmq_socket_monitor.adoc} (97%) rename doc/{zmq_socket_monitor_versioned.txt => zmq_socket_monitor_versioned.adoc} (98%) rename doc/{zmq_strerror.txt => zmq_strerror.adoc} (82%) rename doc/{zmq_tcp.txt => zmq_tcp.adoc} (92%) delete mode 100644 doc/zmq_term.txt rename doc/{zmq_timers.txt => zmq_timers.adoc} (95%) rename doc/{zmq_tipc.txt => zmq_tipc.adoc} (85%) rename doc/{zmq_udp.txt => zmq_udp.adoc} (91%) rename doc/{zmq_unbind.txt => zmq_unbind.adoc} (84%) rename doc/{zmq_version.txt => zmq_version.adoc} (82%) rename doc/{zmq_vmci.txt => zmq_vmci.adoc} (88%) rename doc/{zmq_z85_decode.txt => zmq_z85_decode.adoc} (74%) rename doc/{zmq_z85_encode.txt => zmq_z85_encode.adoc} (79%) diff --git a/.github/workflows/CI.yaml b/.github/workflows/CI.yaml index b1043ccf..dd6af666 100644 --- a/.github/workflows/CI.yaml +++ b/.github/workflows/CI.yaml @@ -25,7 +25,7 @@ jobs: ENABLE_DRAFTS: ON - os: ubuntu-latest BUILD_TYPE: default - PACKAGES: asciidoc xmlto + PACKAGES: asciidoctor DRAFT: disabled POLLER: select - os: ubuntu-latest diff --git a/.github/workflows/Docs.yaml b/.github/workflows/Docs.yaml new file mode 100644 index 00000000..bd243a3b --- /dev/null +++ b/.github/workflows/Docs.yaml @@ -0,0 +1,50 @@ +# Simple workflow for deploying static content to GitHub Pages +name: Deploy API docs content to Pages + +on: + # Runs on pushes targeting the default branch + push: + branches: ["master"] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + # Single deploy job since we're just deploying + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + + ## libzmq-specific CI/CD ## + - name: Install AsciiDoctor + run: sudo apt install -y asciidoctor + - name: Convert AsciiDoc with AsciiDoctor into HTML + run: ./autogen.sh && ./configure && make --directory=doc + + ## boilerplate steps to publish github Pages ## + - name: Setup Pages + uses: actions/configure-pages@v3 + - name: Upload artifact + uses: actions/upload-pages-artifact@v2 + with: + path: 'doc/' + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 diff --git a/CMakeLists.txt b/CMakeLists.txt index c64ccc1f..68fb7251 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -770,7 +770,7 @@ elseif(CMAKE_SYSTEM_NAME MATCHES "Darwin") add_definitions(-D_DARWIN_C_SOURCE) endif() -find_package(AsciiDoc) +find_package(AsciiDoctor) cmake_dependent_option(WITH_DOC "Build Reference Guide documentation(requires DocBook)" ON "ASCIIDOC_FOUND;NOT WIN32" OFF) # Do not build docs on Windows due to issues with symlinks @@ -1256,25 +1256,16 @@ option(WITH_DOCS "Build html docs" ON) if(WITH_DOCS) file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doc) file( - GLOB docs + GLOB asciidoc_files RELATIVE ${CMAKE_CURRENT_BINARY_DIR}/ - "${CMAKE_CURRENT_SOURCE_DIR}/doc/*.txt") - set(html-docs) - foreach(txt ${docs}) - string(REGEX REPLACE ".*/(.*)\\.txt" "\\1.html" html ${txt}) - set(src ${txt}) - set(dst doc/${html}) - if(WITH_DOC) - add_custom_command( - OUTPUT ${dst} - COMMAND ${ASCIIDOC_EXECUTABLE} -d manpage -b xhtml11 -f ${CMAKE_CURRENT_SOURCE_DIR}/doc/asciidoc.conf - -azmq_version=${ZMQ_VERSION} -o ${dst} ${src} - DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${src} - WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} - COMMENT "Generating ${html}") - list(APPEND html-docs ${CMAKE_CURRENT_BINARY_DIR}/${dst}) - endif() - endforeach() + "${CMAKE_CURRENT_SOURCE_DIR}/doc/*.adoc") + string(REPLACE ".txt" ".html" html_files ${asciidoc_files}) + add_custom_command( + OUTPUT ${html_files} + COMMAND asciidoctor -b html -azmq_version=${ZMQ_VERSION} *.adoc + DEPENDS ${asciidoc_files} + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} + COMMENT "Generating ${html}") endif() if(ZMQ_BUILD_FRAMEWORK) diff --git a/acinclude.m4 b/acinclude.m4 index f27fc8e8..a156da81 100644 --- a/acinclude.m4 +++ b/acinclude.m4 @@ -89,7 +89,7 @@ dnl # Check whether to build documentation and install man-pages dnl ############################################################################## AC_DEFUN([LIBZMQ_CHECK_DOC_BUILD], [{ - # Man pages are built/installed if asciidoc and xmlto are present + # Man pages are built/installed if asciidoctor and xmlto are present # --with-docs=no overrides this AC_ARG_WITH([docs], AS_HELP_STRING([--without-docs], @@ -109,14 +109,13 @@ AC_DEFUN([LIBZMQ_CHECK_DOC_BUILD], [{ libzmq_build_doc="yes" libzmq_install_man="yes" # Check for asciidoc and xmlto and don't build the docs if these are not installed. - AC_CHECK_PROG(libzmq_have_asciidoc, asciidoc, yes, no) - AC_CHECK_PROG(libzmq_have_xmlto, xmlto, yes, no) - if test "x$libzmq_have_asciidoc" = "xno" -o "x$libzmq_have_xmlto" = "xno"; then + AC_CHECK_PROG(libzmq_have_asciidoctor, asciidoctor, yes, no) + if test "x$libzmq_have_asciidoctor" = "xno"; then libzmq_build_doc="no" # Tarballs built with 'make dist' ship with prebuilt documentation. if ! test -f doc/zmq.7; then libzmq_install_man="no" - AC_MSG_WARN([You are building an unreleased version of 0MQ and asciidoc or xmlto are not installed.]) + AC_MSG_WARN([You are building an unreleased version of 0MQ and asciidoctor is not installed.]) AC_MSG_WARN([Documentation will not be built and manual pages will not be installed.]) fi fi diff --git a/builds/cmake/Modules/FindAsciiDoc.cmake b/builds/cmake/Modules/FindAsciiDoc.cmake deleted file mode 100644 index 049ac007..00000000 --- a/builds/cmake/Modules/FindAsciiDoc.cmake +++ /dev/null @@ -1,26 +0,0 @@ -# - Find Asciidoc -# this module looks for asciidoc and a2x -# -# ASCIIDOC_EXECUTABLE - the full path to asciidoc -# ASCIIDOC_FOUND - If false, don't attempt to use asciidoc. -# A2X_EXECUTABLE - the full path to a2x -# A2X_FOUND - If false, don't attempt to use a2x. - -set (PROGRAMFILESX86 "PROGRAMFILES(X86)") - -find_program(ASCIIDOC_EXECUTABLE asciidoc asciidoc.py - PATHS "$ENV{ASCIIDOC_ROOT}" - "$ENV{PROGRAMW6432}/asciidoc" - "$ENV{PROGRAMFILES}/asciidoc" - "$ENV{${PROGRAMFILESX86}}/asciidoc") - -find_program(A2X_EXECUTABLE a2x - PATHS "$ENV{ASCIIDOC_ROOT}" - "$ENV{PROGRAMW6432}/asciidoc" - "$ENV{PROGRAMFILES}/asciidoc" - "$ENV{${PROGRAMFILESX86}}/asciidoc") - - -include(FindPackageHandleStandardArgs) -find_package_handle_standard_ARGS(AsciiDoc REQUIRED_VARS ASCIIDOC_EXECUTABLE) -mark_as_advanced(ASCIIDOC_EXECUTABLE A2X_EXECUTABLE) diff --git a/builds/cmake/Modules/FindAsciiDoctor.cmake b/builds/cmake/Modules/FindAsciiDoctor.cmake new file mode 100644 index 00000000..1972fd25 --- /dev/null +++ b/builds/cmake/Modules/FindAsciiDoctor.cmake @@ -0,0 +1,23 @@ +# - Find Asciidoctor +# this module looks for asciidoctor +# +# ASCIIDOCTOR_EXECUTABLE - the full path to asciidoc +# ASCIIDOCTOR_FOUND - If false, don't attempt to use asciidoc. +set (PROGRAMFILESX86 "PROGRAMFILES(X86)") + +find_program(ASCIIDOCTOR_EXECUTABLE asciidoctor asciidoctor + PATHS "$ENV{ASCIIDOCTOR_ROOT}" + "$ENV{PROGRAMW6432}/asciidoctor" + "$ENV{PROGRAMFILES}/asciidoctor" + "$ENV{${PROGRAMFILESX86}}/asciidoctor") + +find_program(A2X_EXECUTABLE a2x + PATHS "$ENV{ASCIIDOCTOR_ROOT}" + "$ENV{PROGRAMW6432}/asciidoctor" + "$ENV{PROGRAMFILES}/asciidoctor" + "$ENV{${PROGRAMFILESX86}}/asciidoctor") + + +include(FindPackageHandleStandardArgs) +find_package_handle_standard_ARGS(AsciiDoctor REQUIRED_VARS ASCIIDOCTOR_EXECUTABLE) +mark_as_advanced(ASCIIDOCTOR_EXECUTABLE) diff --git a/configure.ac b/configure.ac index d3f4f019..b9e13d4f 100644 --- a/configure.ac +++ b/configure.ac @@ -76,10 +76,6 @@ PKG_PROG_PKG_CONFIG m4_pattern_forbid([^PKG_[A-Z_]+$], [missing some pkg-config macros (pkg-config package)]) # Libtool configuration for different targets. See acinclude.m4 -AC_ARG_VAR([XMLTO], [path to xmlto command]) -AC_PATH_PROG([XMLTO], [xmlto]) -AC_ARG_VAR([ASCIIDOC], [path to asciidoc command]) -AC_PATH_PROG([ASCIIDOC], [asciidoc]) LIBZMQ_CONFIG_LIBTOOL AC_LIBTOOL_WIN32_DLL AC_PROG_LIBTOOL diff --git a/doc/Makefile.am b/doc/Makefile.am index 67eb55e8..de710d3a 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,7 +1,8 @@ # # documentation # -MAN3 = zmq_bind.3 zmq_unbind.3 zmq_connect.3 zmq_connect_peer.3 zmq_disconnect.3 zmq_close.3 \ +MAN3 = \ + zmq_bind.3 zmq_unbind.3 zmq_connect.3 zmq_connect_peer.3 zmq_disconnect.3 zmq_close.3 \ zmq_ctx_new.3 zmq_ctx_term.3 zmq_ctx_get.3 zmq_ctx_set.3 zmq_ctx_shutdown.3 \ zmq_msg_init.3 zmq_msg_init_data.3 zmq_msg_init_size.3 zmq_msg_init_buffer.3 \ zmq_msg_move.3 zmq_msg_copy.3 zmq_msg_size.3 zmq_msg_data.3 zmq_msg_close.3 \ @@ -22,45 +23,58 @@ MAN3 = zmq_bind.3 zmq_unbind.3 zmq_connect.3 zmq_connect_peer.3 zmq_disconnect.3 zmq_atomic_counter_inc.3 zmq_atomic_counter_dec.3 \ zmq_atomic_counter_value.3 zmq_atomic_counter_destroy.3 -MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_inproc.7 zmq_ipc.7 \ +MAN7 = \ + zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_inproc.7 zmq_ipc.7 \ zmq_null.7 zmq_plain.7 zmq_curve.7 zmq_tipc.7 zmq_vmci.7 zmq_udp.7 \ zmq_gssapi.7 -MAN_DOC = +# MAN_ADOC contains all original Asciidoc files from git repo +MAN_ADOC = $(MAN3:%.3=%.adoc) $(MAN7:%.7=%.adoc) -MAN_TXT = $(MAN3:%.3=%.txt) -MAN_TXT += $(MAN7:%.7=%.txt) -MAN_HTML = +# MAN_DOC contains all the MANUAL PAGES (generated from asciidoc files) +MAN_DOC = $(MAN3) $(MAN7) + +# MAN_HTML contains all the HTML PAGES (generated from asciidoc files) +MAN_HTML = $(MAN_ADOC:%.adoc=%.html) MAINTAINERCLEANFILES = +EXTRA_DIST = $(MAN_ADOC) -EXTRA_DIST = asciidoc.conf $(MAN_TXT) - -if INSTALL_MAN -MAN_DOC += $(MAN1) $(MAN3) $(MAN7) -dist_man_MANS = $(MAN_DOC) -MAINTAINERCLEANFILES += $(MAN_DOC) -endif +# +# BUILD_DOC is set when Asciidoctor has been found +# Declare here all the rules to produce documentation from .adoc files +# if BUILD_DOC -MAN_HTML += $(MAN_TXT:%.txt=%.html) -EXTRA_DIST += $(MAN_HTML) -MAINTAINERCLEANFILES += $(MAN_HTML) -SUFFIXES=.html .txt .xml .3 .7 +EXTRA_DIST += $(MAN_HTML) $(MAN_DOC) +MAINTAINERCLEANFILES += $(MAN_HTML) $(MAN_DOC) +SUFFIXES=.html .adoc .3 .7 -.txt.html: - asciidoc -d manpage -b xhtml11 -f $(srcdir)/asciidoc.conf \ - -azmq_version=@PACKAGE_VERSION@ -o$@ $< -.txt.xml: - asciidoc -d manpage -b docbook -f $(srcdir)/asciidoc.conf \ - -azmq_version=@PACKAGE_VERSION@ -o$@ $< -.xml.1: - xmlto man $< -.xml.3: - xmlto man $< -.xml.7: - xmlto man $< -endif +.adoc.html: + asciidoctor -b html -azmq_version=@PACKAGE_VERSION@ $< +.adoc.3: + asciidoctor -b manpage -azmq_version=@PACKAGE_VERSION@ $< +.adoc.7: + asciidoctor -b manpage -azmq_version=@PACKAGE_VERSION@ $< dist-hook : $(MAN_DOC) $(MAN_HTML) + +# To help publishing HTML files into github Pages, we indicate github that the "zmq.html" page is the index page; +# that page contains a link to all other documentation pages +all-local : $(MAN_DOC) $(MAN_HTML) + ln -sf zmq.html index.html + +clean-local : + rm -f $(MAN3) $(MAN7) $(MAN_HTML) + +endif + + + +# +# INSTALL_MAN is set when BUILD_DOC was set and additionally the manpages need to be installed +# +if INSTALL_MAN +dist_man_MANS = $(MAN_DOC) +endif diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf deleted file mode 100644 index d73d7119..00000000 --- a/doc/asciidoc.conf +++ /dev/null @@ -1,56 +0,0 @@ -[paradef-default] -literal-style=template="literalparagraph" - -[macros] -(?su)[\\]?(?Plinkzmq):(?P\S*?)\[(?P.*?)\]= - -ifdef::backend-docbook[] -[linkzmq-inlinemacro] -{0%{target}} -{0#} -{0#{target}{0}} -{0#} -endif::backend-docbook[] - -ifdef::backend-xhtml11[] -[linkzmq-inlinemacro] -{target}{0?({0})} -endif::backend-xhtml11[] - -ifdef::doctype-manpage[] -ifdef::backend-docbook[] -[header] -template::[header-declarations] - - -{mantitle} -{manvolnum} -0MQ -{zmq_version} -0MQ Manual - - - {manname} - {manpurpose} - -endif::backend-docbook[] -endif::doctype-manpage[] - -ifdef::backend-xhtml11[] -[footer] - -{disable-javascript%
} - - - -endif::backend-xhtml11[] - -[replacements] -ifdef::backend-xhtml11[] -0MQ=ØMQ -endif::backend-xhtml11[] diff --git a/doc/zmq.txt b/doc/zmq.adoc similarity index 68% rename from doc/zmq.txt rename to doc/zmq.adoc index 30909bc0..146e3c9f 100644 --- a/doc/zmq.txt +++ b/doc/zmq.adoc @@ -1,21 +1,17 @@ -zmq(7) -====== += zmq(7) -NAME ----- +== NAME zmq - 0MQ lightweight messaging kernel -SYNOPSIS --------- +== SYNOPSIS *#include * *cc* ['flags'] 'files' *-lzmq* ['libraries'] -DESCRIPTION ------------ +== DESCRIPTION The 0MQ lightweight messaging kernel is a library which extends the standard socket interfaces with features traditionally provided by specialised _messaging middleware_ products. 0MQ sockets provide an abstraction of @@ -38,15 +34,15 @@ 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] + * xref:zmq_ctx_new.adoc[zmq_ctx_new] Work with context properties:: - linkzmq:zmq_ctx_set[3] - linkzmq:zmq_ctx_get[3] + * xref:zmq_ctx_set.adoc[zmq_ctx_set] + * xref:zmq_ctx_get.adoc[zmq_ctx_get] Destroy a 0MQ context:: - linkzmq:zmq_ctx_shutdown[3] - linkzmq:zmq_ctx_term[3] + * xref:zmq_ctx_shutdown.adoc[zmq_ctx_shutdown] + * xref:zmq_ctx_term.adoc[zmq_ctx_term] Thread safety ^^^^^^^^^^^^^ @@ -80,73 +76,73 @@ 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_buffer[3] - linkzmq:zmq_msg_init_data[3] + * xref:zmq_msg_init.adoc[zmq_msg_init] + * xref:zmq_msg_init_size.adoc[zmq_msg_init_size] + * xref:zmq_msg_init_buffer.adoc[zmq_msg_init_buffer] + * xref:zmq_msg_init_data.adoc[zmq_msg_init_data] Sending and receiving a message:: - linkzmq:zmq_msg_send[3] - linkzmq:zmq_msg_recv[3] + * xref:zmq_msg_send.adoc[zmq_msg_send] + * xref:zmq_msg_recv.adoc[zmq_msg_recv] Release a message:: - linkzmq:zmq_msg_close[3] + * xref:zmq_msg_close.adoc[zmq_msg_close] Access message content:: - linkzmq:zmq_msg_data[3] - linkzmq:zmq_msg_size[3] - linkzmq:zmq_msg_more[3] + * xref:zmq_msg_data.adoc[zmq_msg_data] + * xref:zmq_msg_size.adoc[zmq_msg_size] + * xref:zmq_msg_more.adoc[zmq_msg_more] Work with message properties:: - linkzmq:zmq_msg_gets[3] - linkzmq:zmq_msg_get[3] - linkzmq:zmq_msg_set[3] + * xref:zmq_msg_gets.adoc[zmq_msg_gets] + * xref:zmq_msg_get.adoc[zmq_msg_get] + * xref:zmq_msg_set.adoc[zmq_msg_set] Message manipulation:: - linkzmq:zmq_msg_copy[3] - linkzmq:zmq_msg_move[3] + * xref:zmq_msg_copy.adoc[zmq_msg_copy] + * xref:zmq_msg_move.adoc[zmq_msg_move] Sockets ~~~~~~~ 0MQ sockets present an abstraction of an 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. +xref:zmq_socket.adoc[zmq_socket] for the socket types provided. The following functions are provided to work with sockets: Creating a socket:: - linkzmq:zmq_socket[3] + * xref:zmq_socket.adoc[zmq_socket] Closing a socket:: - linkzmq:zmq_close[3] + * xref:zmq_close.adoc[zmq_close] Manipulating socket options:: - linkzmq:zmq_getsockopt[3] - linkzmq:zmq_setsockopt[3] + * xref:zmq_getsockopt.adoc[zmq_getsockopt] + * xref:zmq_setsockopt.adoc[zmq_setsockopt] Establishing a message flow:: - linkzmq:zmq_bind[3] - linkzmq:zmq_connect[3] + * xref:zmq_bind.adoc[zmq_bind] + * xref:zmq_connect.adoc[zmq_connect] Sending and receiving messages:: - linkzmq:zmq_msg_send[3] - linkzmq:zmq_msg_recv[3] - linkzmq:zmq_send[3] - linkzmq:zmq_recv[3] - linkzmq:zmq_send_const[3] + * xref:zmq_msg_send.adoc[zmq_msg_send] + * xref:zmq_msg_recv.adoc[zmq_msg_recv] + * xref:zmq_send.adoc[zmq_send] + * xref:zmq_recv.adoc[zmq_recv] + * xref:zmq_send_const.adoc[zmq_send_const] Monitoring socket events:: - linkzmq:zmq_socket_monitor[3] + * xref:zmq_socket_monitor.adoc[zmq_socket_monitor] .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]. This API is deprecated, however. +xref:zmq_poll.adoc[zmq_poll] This API is deprecated, however. There is a new DRAFT API with multiple zmq_poller_* function, which is described -in linkzmq:zmq_poller[3]. +in xref:zmq_poller.adoc[zmq_poller] Transports @@ -158,22 +154,22 @@ advantages and drawbacks. The following transport mechanisms are provided: Unicast transport using TCP:: - linkzmq:zmq_tcp[7] + * xref:zmq_tcp.adoc[zmq_tcp] Reliable multicast transport using PGM:: - linkzmq:zmq_pgm[7] + * xref:zmq_pgm.adoc[zmq_pgm] Local inter-process communication transport:: - linkzmq:zmq_ipc[7] + * xref:zmq_ipc.adoc[zmq_ipc] Local in-process (inter-thread) communication transport:: - linkzmq:zmq_inproc[7] + * xref:zmq_inproc.adoc[zmq_inproc] Virtual Machine Communications Interface (VMC) transport:: - linkzmq:zmq_vmci[7] + * xref:zmq_vmci.adoc[zmq_vmci] Unreliable unicast and multicast using UDP:: - linkzmq:zmq_udp[7] + * xref:zmq_udp.adoc[zmq_udp] Proxies @@ -181,7 +177,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 xref:zmq_proxy.adoc[zmq_proxy] Security @@ -192,27 +188,26 @@ security mechanism. The following security mechanisms are provided for IPC and TCP connections: Null security:: - linkzmq:zmq_null[7] + * xref:zmq_null.adoc[zmq_null] Plain-text authentication using username and password:: - linkzmq:zmq_plain[7] + * xref:zmq_plain.adoc[zmq_plain] Elliptic curve authentication and encryption:: - linkzmq:zmq_curve[7] + * xref:zmq_curve.adoc[zmq_curve] Generate a CURVE keypair in armored text format:: - linkzmq:zmq_curve_keypair[3] + * xref:zmq_curve_keypair.adoc[zmq_curve_keypair] -Derive a CURVE public key from a secret key: - linkzmq:zmq_curve_public[3] +Derive a CURVE public key from a secret key:: + * xref:zmq_curve_public.adoc[zmq_curve_public] Converting keys to/from armoured text strings:: - linkzmq:zmq_z85_decode[3] - linkzmq:zmq_z85_encode[3] + * xref:zmq_z85_decode.adoc[zmq_z85_decode] + * xref:zmq_z85_encode.adoc[zmq_z85_encode] -ERROR HANDLING --------------- +== ERROR HANDLING The 0MQ library functions handle errors using the standard conventions found on POSIX systems. Generally, this means that upon failure a 0MQ library function shall return either a NULL value (if returning a pointer) or a negative value @@ -221,35 +216,32 @@ 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 xref:zmq_errno.adoc[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 xref:zmq_strerror.adoc[zmq_strerror] -UTILITY -------- +== UTILITY The following utility functions are provided: Working with atomic counters:: - linkzmq:zmq_atomic_counter_new[3] - linkzmq:zmq_atomic_counter_set[3] - linkzmq:zmq_atomic_counter_inc[3] - linkzmq:zmq_atomic_counter_dec[3] - linkzmq:zmq_atomic_counter_value[3] - linkzmq:zmq_atomic_counter_destroy[3] + * xref:zmq_atomic_counter_new.adoc[zmq_atomic_counter_new] + * xref:zmq_atomic_counter_set.adoc[zmq_atomic_counter_set] + * xref:zmq_atomic_counter_inc.adoc[zmq_atomic_counter_inc] + * xref:zmq_atomic_counter_dec.adoc[zmq_atomic_counter_dec] + * xref:zmq_atomic_counter_value.adoc[zmq_atomic_counter_value] + * xref:zmq_atomic_counter_destroy.adoc[zmq_atomic_counter_destroy] -MISCELLANEOUS -------------- +== MISCELLANEOUS The following miscellaneous functions are provided: Report 0MQ library version:: - linkzmq:zmq_version[3] + * xref:zmq_version.adoc[zmq_version] -LANGUAGE BINDINGS ------------------ +== LANGUAGE BINDINGS The 0MQ 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 0MQ from other languages @@ -260,21 +252,18 @@ Language bindings ($$C++$$, Python, PHP, Ruby, Java and more) are provided by members of the 0MQ community and pointers can be found on the 0MQ website. -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . -RESOURCES ---------- +== RESOURCES Main web site: Report bugs to the 0MQ development mailing list: -LICENSE -------- +== LICENSE Free use of this software is granted under the terms of the Mozilla Public License Version 2.0 (MPL-2.0). For details see the file `LICENSE` included with the 0MQ distribution. diff --git a/doc/zmq_atomic_counter_dec.txt b/doc/zmq_atomic_counter_dec.adoc similarity index 74% rename from doc/zmq_atomic_counter_dec.txt rename to doc/zmq_atomic_counter_dec.adoc index 53a088c4..cc311bea 100644 --- a/doc/zmq_atomic_counter_dec.txt +++ b/doc/zmq_atomic_counter_dec.adoc @@ -1,33 +1,27 @@ -zmq_atomic_counter_dec(3) -========================= += zmq_atomic_counter_dec(3) -NAME ----- +== NAME zmq_atomic_counter_dec - decrement an atomic counter -SYNOPSIS --------- +== SYNOPSIS *int zmq_atomic_counter_dec (void *counter);* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_atomic_counter_dec_ function decrements an atomic counter in a threadsafe fashion. This function uses platform specific atomic operations. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_atomic_counter_dec()_ function returns 1 if the counter is greater than zero after decrementing, or zero if the counter reached zero. -EXAMPLE -------- +== EXAMPLE .Test code for atomic counters ---- void *counter = zmq_atomic_counter_new (); @@ -47,16 +41,14 @@ return 0; ---- -SEE ALSO --------- -linkzmq:zmq_atomic_counter_new[3] -linkzmq:zmq_atomic_counter_set[3] -linkzmq:zmq_atomic_counter_inc[3] -linkzmq:zmq_atomic_counter_value[3] -linkzmq:zmq_atomic_counter_destroy[3] +== SEE ALSO +xref:zmq_atomic_counter_new.adoc[zmq_atomic_counter_new] +xref:zmq_atomic_counter_set.adoc[zmq_atomic_counter_set] +xref:zmq_atomic_counter_inc.adoc[zmq_atomic_counter_inc] +xref:zmq_atomic_counter_value.adoc[zmq_atomic_counter_value] +xref:zmq_atomic_counter_destroy.adoc[zmq_atomic_counter_destroy] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_atomic_counter_destroy.txt b/doc/zmq_atomic_counter_destroy.adoc similarity index 76% rename from doc/zmq_atomic_counter_destroy.txt rename to doc/zmq_atomic_counter_destroy.adoc index ee7c863f..5c136b20 100644 --- a/doc/zmq_atomic_counter_destroy.txt +++ b/doc/zmq_atomic_counter_destroy.adoc @@ -1,19 +1,15 @@ -zmq_atomic_counter_destroy(3) -============================= += zmq_atomic_counter_destroy(3) -NAME ----- +== NAME zmq_atomic_counter_destroy - destroy an atomic counter -SYNOPSIS --------- +== SYNOPSIS *void zmq_atomic_counter_destroy (void **counter_p);* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_atomic_counter_destroy_ function destroys an atomic counter and nullifies its reference. Pass the address of an atomic counter (void **) rather than the counter itself. You must destroy all counters that you @@ -21,13 +17,11 @@ create, to avoid memory leakage. This function uses platform specific atomic operations. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_atomic_counter_destroy()_ function has no return value. -EXAMPLE -------- +== EXAMPLE .Test code for atomic counters ---- void *counter = zmq_atomic_counter_new (); @@ -47,16 +41,14 @@ return 0; ---- -SEE ALSO --------- -linkzmq:zmq_atomic_counter_new[3] -linkzmq:zmq_atomic_counter_set[3] -linkzmq:zmq_atomic_counter_inc[3] -linkzmq:zmq_atomic_counter_dec[3] -linkzmq:zmq_atomic_counter_value[3] +== SEE ALSO +xref:zmq_atomic_counter_new.adoc[zmq_atomic_counter_new] +xref:zmq_atomic_counter_set.adoc[zmq_atomic_counter_set] +xref:zmq_atomic_counter_inc.adoc[zmq_atomic_counter_inc] +xref:zmq_atomic_counter_dec.adoc[zmq_atomic_counter_dec] +xref:zmq_atomic_counter_value.adoc[zmq_atomic_counter_value] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_atomic_counter_inc.txt b/doc/zmq_atomic_counter_inc.adoc similarity index 73% rename from doc/zmq_atomic_counter_inc.txt rename to doc/zmq_atomic_counter_inc.adoc index 6346ea13..65e600d2 100644 --- a/doc/zmq_atomic_counter_inc.txt +++ b/doc/zmq_atomic_counter_inc.adoc @@ -1,32 +1,26 @@ -zmq_atomic_counter_inc(3) -========================= += zmq_atomic_counter_inc(3) -NAME ----- +== NAME zmq_atomic_counter_inc - increment an atomic counter -SYNOPSIS --------- +== SYNOPSIS *int zmq_atomic_counter_inc (void *counter);* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_atomic_counter_inc_ function increments an atomic counter in a threadsafe fashion. This function uses platform specific atomic operations. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_atomic_counter_inc()_ function returns the old value of the counter, before incrementing. -EXAMPLE -------- +== EXAMPLE .Test code for atomic counters ---- void *counter = zmq_atomic_counter_new (); @@ -46,16 +40,14 @@ return 0; ---- -SEE ALSO --------- -linkzmq:zmq_atomic_counter_new[3] -linkzmq:zmq_atomic_counter_set[3] -linkzmq:zmq_atomic_counter_dec[3] -linkzmq:zmq_atomic_counter_value[3] -linkzmq:zmq_atomic_counter_destroy[3] +== SEE ALSO +xref:zmq_atomic_counter_new.adoc[zmq_atomic_counter_new] +xref:zmq_atomic_counter_set.adoc[zmq_atomic_counter_set] +xref:zmq_atomic_counter_dec.adoc[zmq_atomic_counter_dec] +xref:zmq_atomic_counter_value.adoc[zmq_atomic_counter_value] +xref:zmq_atomic_counter_destroy.adoc[zmq_atomic_counter_destroy] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_atomic_counter_new.txt b/doc/zmq_atomic_counter_new.adoc similarity index 75% rename from doc/zmq_atomic_counter_new.txt rename to doc/zmq_atomic_counter_new.adoc index 7278f2b7..a63ef432 100644 --- a/doc/zmq_atomic_counter_new.txt +++ b/doc/zmq_atomic_counter_new.adoc @@ -1,33 +1,27 @@ -zmq_atomic_counter_new(3) -========================= += zmq_atomic_counter_new(3) -NAME ----- +== NAME zmq_atomic_counter_new - create a new atomic counter -SYNOPSIS --------- +== SYNOPSIS *void *zmq_atomic_counter_new (void);* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_atomic_counter_new_ function creates a new atomic counter. You can use this in multithreaded applications to do, for example, reference counting of shared objects. The atomic counter is at least 32 bits large. This function uses platform specific atomic operations. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_atomic_counter_new()_ function returns the new atomic counter if successful. Otherwise it returns NULL. -EXAMPLE -------- +== EXAMPLE .Test code for atomic counters ---- void *counter = zmq_atomic_counter_new (); @@ -47,16 +41,14 @@ return 0; ---- -SEE ALSO --------- -linkzmq:zmq_atomic_counter_set[3] -linkzmq:zmq_atomic_counter_inc[3] -linkzmq:zmq_atomic_counter_dec[3] -linkzmq:zmq_atomic_counter_value[3] -linkzmq:zmq_atomic_counter_destroy[3] +== SEE ALSO +xref:zmq_atomic_counter_set.adoc[zmq_atomic_counter_set] +xref:zmq_atomic_counter_inc.adoc[zmq_atomic_counter_inc] +xref:zmq_atomic_counter_dec.adoc[zmq_atomic_counter_dec] +xref:zmq_atomic_counter_value.adoc[zmq_atomic_counter_value] +xref:zmq_atomic_counter_destroy.adoc[zmq_atomic_counter_destroy] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_atomic_counter_set.txt b/doc/zmq_atomic_counter_set.adoc similarity index 74% rename from doc/zmq_atomic_counter_set.txt rename to doc/zmq_atomic_counter_set.adoc index 3b0812f6..a2325149 100644 --- a/doc/zmq_atomic_counter_set.txt +++ b/doc/zmq_atomic_counter_set.adoc @@ -1,32 +1,26 @@ -zmq_atomic_counter_set(3) -========================= += zmq_atomic_counter_set(3) -NAME ----- +== NAME zmq_atomic_counter_set - set atomic counter to new value -SYNOPSIS --------- +== SYNOPSIS *void zmq_atomic_counter_set (void *counter, int value);* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_atomic_counter_set_ function sets the counter to a new value, in a threadsafe fashion. The largest value that is guaranteed to work across all platforms is 2^31-1. This function uses platform specific atomic operations. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_atomic_counter_set()_ function has no return value. -EXAMPLE -------- +== EXAMPLE .Test code for atomic counters ---- void *counter = zmq_atomic_counter_new (); @@ -46,16 +40,14 @@ return 0; ---- -SEE ALSO --------- -linkzmq:zmq_atomic_counter_new[3] -linkzmq:zmq_atomic_counter_inc[3] -linkzmq:zmq_atomic_counter_dec[3] -linkzmq:zmq_atomic_counter_value[3] -linkzmq:zmq_atomic_counter_destroy[3] +== SEE ALSO +xref:zmq_atomic_counter_new.adoc[zmq_atomic_counter_new] +xref:zmq_atomic_counter_inc.adoc[zmq_atomic_counter_inc] +xref:zmq_atomic_counter_dec.adoc[zmq_atomic_counter_dec] +xref:zmq_atomic_counter_value.adoc[zmq_atomic_counter_value] +xref:zmq_atomic_counter_destroy.adoc[zmq_atomic_counter_destroy] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_atomic_counter_value.txt b/doc/zmq_atomic_counter_value.adoc similarity index 76% rename from doc/zmq_atomic_counter_value.txt rename to doc/zmq_atomic_counter_value.adoc index f2e34475..ff93c7e2 100644 --- a/doc/zmq_atomic_counter_value.txt +++ b/doc/zmq_atomic_counter_value.adoc @@ -1,33 +1,27 @@ -zmq_atomic_counter_value(3) -=========================== += zmq_atomic_counter_value(3) -NAME ----- +== NAME zmq_atomic_counter_value - return value of atomic counter -SYNOPSIS --------- +== SYNOPSIS *int zmq_atomic_counter_value (void *counter);* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_atomic_counter_value_ function returns the value of an atomic counter created by _zmq_atomic_counter_new()_. This function uses platform specific atomic operations. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_atomic_counter_value()_ function returns the value of the atomic counter. If _counter_ does not point to an atomic counter created by _zmq_atomic_counter_new()_, the behaviour is undefined. -EXAMPLE -------- +== EXAMPLE .Test code for atomic counters ---- void *counter = zmq_atomic_counter_new (); @@ -47,16 +41,14 @@ return 0; ---- -SEE ALSO --------- -linkzmq:zmq_atomic_counter_new[3] -linkzmq:zmq_atomic_counter_set[3] -linkzmq:zmq_atomic_counter_inc[3] -linkzmq:zmq_atomic_counter_dec[3] -linkzmq:zmq_atomic_counter_destroy[3] +== SEE ALSO +xref:zmq_atomic_counter_new.adoc[zmq_atomic_counter_new] +xref:zmq_atomic_counter_set.adoc[zmq_atomic_counter_set] +xref:zmq_atomic_counter_inc.adoc[zmq_atomic_counter_inc] +xref:zmq_atomic_counter_dec.adoc[zmq_atomic_counter_dec] +xref:zmq_atomic_counter_destroy.adoc[zmq_atomic_counter_destroy] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_bind.txt b/doc/zmq_bind.adoc similarity index 71% rename from doc/zmq_bind.txt rename to doc/zmq_bind.adoc index 6305cfc6..1f15b941 100644 --- a/doc/zmq_bind.txt +++ b/doc/zmq_bind.adoc @@ -1,19 +1,15 @@ -zmq_bind(3) -=========== += zmq_bind(3) -NAME ----- +== NAME zmq_bind - accept incoming connections on a socket -SYNOPSIS --------- +== SYNOPSIS *int zmq_bind (void '*socket', const char '*endpoint');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_bind()_ function binds the 'socket' to a local 'endpoint' and then accepts incoming connections on that endpoint. @@ -23,20 +19,20 @@ 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] -'vmci':: virtual machine communications interface (VMCI), see linkzmq:zmq_vmci[7] -'udp':: unreliable unicast and multicast using UDP, see linkzmq:zmq_udp[7] +'tcp':: unicast transport using TCP, see xref:zmq_tcp.adoc[zmq_tcp] +'ipc':: local inter-process communication transport, see xref:zmq_ipc.adoc[zmq_ipc] +'inproc':: local in-process (inter-thread) communication transport, see xref:zmq_inproc.adoc[zmq_inproc] +'pgm', 'epgm':: reliable multicast transport using PGM, see xref:zmq_pgm.adoc[zmq_pgm] +'vmci':: virtual machine communications interface (VMCI), see xref:zmq_vmci.adoc[zmq_vmci] +'udp':: unreliable unicast and multicast using UDP, see xref:zmq_udp.adoc[zmq_udp] Every 0MQ socket type except 'ZMQ_PAIR' and 'ZMQ_CHANNEL' 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]. +xref:zmq_socket.adoc[zmq_socket] The 'ipc', 'tcp', 'vmci' and 'udp' transports accept wildcard addresses: see -linkzmq:zmq_ipc[7], linkzmq:zmq_tcp[7], linkzmq:zmq_vmci[7] and -linkzmq:zmq_udp[7] for details. +xref:zmq_ipc.adoc[zmq_ipc], xref:zmq_tcp.adoc[zmq_tcp], xref:zmq_vmci.adoc[zmq_vmci] and +xref:zmq_udp.adoc[zmq_udp] for details. NOTE: the address syntax may be different for _zmq_bind()_ and _zmq_connect()_ especially for the 'tcp', 'pgm' and 'epgm' transports. @@ -44,18 +40,16 @@ 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]. -By contrast, following a libzmq:zmq_connect[3], the socket enters the 'ready' state. +drops messages according to the socket type, as defined in xref:zmq_socket.adoc[zmq_socket] +By contrast, following a libzmq:zmq_connect, the socket enters the 'ready' state. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_bind()_ function returns zero if successful. Otherwise it returns `-1` and sets 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EINVAL*:: The endpoint supplied is invalid. *EPROTONOSUPPORT*:: @@ -76,8 +70,7 @@ The provided 'socket' was invalid. No I/O thread is available to accomplish the task. -EXAMPLE -------- +== EXAMPLE .Binding a publisher socket to an in-process and a TCP transport ---- /* Create a ZMQ_PUB socket */ @@ -92,14 +85,12 @@ assert (rc == 0); ---- -SEE ALSO --------- -linkzmq:zmq_connect[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_connect.adoc[zmq_connect] +xref:zmq_socket.adoc[zmq_socket] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_close.txt b/doc/zmq_close.adoc similarity index 80% rename from doc/zmq_close.txt rename to doc/zmq_close.adoc index 961d7b9e..70674be9 100644 --- a/doc/zmq_close.txt +++ b/doc/zmq_close.adoc @@ -1,19 +1,15 @@ -zmq_close(3) -============ += zmq_close(3) -NAME ----- +== NAME zmq_close - close 0MQ socket -SYNOPSIS --------- +== SYNOPSIS *int zmq_close (void '*socket');* -DESCRIPTION ------------ +== 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 @@ -27,33 +23,29 @@ socket or if 'socket' does not point to a socket, the behaviour is undefined. NOTE: The default setting of _ZMQ_LINGER_ does not discard unsent messages; this behaviour may cause the application to block when calling _zmq_ctx_term()_. -For details refer to linkzmq:zmq_setsockopt[3] and linkzmq:zmq_ctx_term[3]. +For details refer to xref:zmq_setsockopt.adoc[zmq_setsockopt] and xref:zmq_ctx_term.adoc[zmq_ctx_term] NOTE: This API will complete asynchronously, so not everything will be deallocated after it returns. See above for details about linger. -RETURN VALUE ------------- +== 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 ------- +== ERRORS *ENOTSOCK*:: The provided 'socket' was NULL. -SEE ALSO --------- -linkzmq:zmq_socket[3] -linkzmq:zmq_ctx_term[3] -linkzmq:zmq_setsockopt[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_socket.adoc[zmq_socket] +xref:zmq_ctx_term.adoc[zmq_ctx_term] +xref:zmq_setsockopt.adoc[zmq_setsockopt] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_connect.txt b/doc/zmq_connect.adoc similarity index 80% rename from doc/zmq_connect.txt rename to doc/zmq_connect.adoc index b06e8261..87806d70 100644 --- a/doc/zmq_connect.txt +++ b/doc/zmq_connect.adoc @@ -1,19 +1,15 @@ -zmq_connect(3) -============== += zmq_connect(3) -NAME ----- +== NAME zmq_connect - create outgoing connection from socket -SYNOPSIS --------- +== SYNOPSIS *int zmq_connect (void '*socket', const char '*endpoint');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_connect()_ function connects the 'socket' to an 'endpoint' and then accepts incoming connections on that endpoint. @@ -23,16 +19,16 @@ 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] -'vmci':: virtual machine communications interface (VMCI), see linkzmq:zmq_vmci[7] -'udp':: unreliable unicast and multicast using UDP, see linkzmq:zmq_udp[7] +'tcp':: unicast transport using TCP, see xref:zmq_tcp.adoc[zmq_tcp] +'ipc':: local inter-process communication transport, see xref:zmq_ipc.adoc[zmq_ipc] +'inproc':: local in-process (inter-thread) communication transport, see xref:zmq_inproc.adoc[zmq_inproc] +'pgm', 'epgm':: reliable multicast transport using PGM, see xref:zmq_pgm.adoc[zmq_pgm] +'vmci':: virtual machine communications interface (VMCI), see xref:zmq_vmci.adoc[zmq_vmci] +'udp':: unreliable unicast and multicast using UDP, see xref:zmq_udp.adoc[zmq_udp] Every 0MQ socket type except 'ZMQ_PAIR' and 'ZMQ_CHANNEL' 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]. +xref:zmq_socket.adoc[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()_ @@ -46,7 +42,7 @@ NOTE: following a _zmq_connect()_, for socket types except for ZMQ_ROUTER, 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]. A ZMQ_ROUTER socket enters its normal 'ready' state +xref:zmq_socket.adoc[zmq_socket] A ZMQ_ROUTER socket enters its normal 'ready' state for a specific peer only when handshaking is complete for that peer, which may take an arbitrary time. @@ -58,14 +54,12 @@ is silently ignored (i.e., returns zero). This behavior applies to ZMQ_DEALER, ZMQ_SUB, ZMQ_PUB, and ZMQ_REQ socket types. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_connect()_ function returns zero if successful. Otherwise it returns `-1` and sets 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EINVAL*:: The endpoint supplied is invalid. *EPROTONOSUPPORT*:: @@ -80,8 +74,7 @@ The provided 'socket' was invalid. No I/O thread is available to accomplish the task. -EXAMPLE -------- +== EXAMPLE .Connecting a subscriber socket to an in-process and a TCP transport ---- /* Create a ZMQ_SUB socket */ @@ -96,14 +89,12 @@ assert (rc == 0); ---- -SEE ALSO --------- -linkzmq:zmq_bind[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_bind.adoc[zmq_bind] +xref:zmq_socket.adoc[zmq_socket] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_connect_peer.txt b/doc/zmq_connect_peer.adoc similarity index 79% rename from doc/zmq_connect_peer.txt rename to doc/zmq_connect_peer.adoc index 5375d1ba..2ffc232f 100644 --- a/doc/zmq_connect_peer.txt +++ b/doc/zmq_connect_peer.adoc @@ -1,19 +1,15 @@ -zmq_connect_peer(3) -=================== += zmq_connect_peer(3) -NAME ----- +== NAME zmq_connect_peer - create outgoing connection from socket and return the connection routing id in thread-safe and atomic way. -SYNOPSIS --------- +== SYNOPSIS *uint32_t zmq_connect_peer (void '*socket', const char '*endpoint');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_connect_peer()_ function connects a 'ZMQ_PEER' socket to an 'endpoint' and then returns the endpoint 'routing_id'. The 'endpoint' is a string consisting of a 'transport'`://` followed by an @@ -24,20 +20,18 @@ The function is supported only on the 'ZMQ_PEER' socket type and would return `0 The _zmq_connect_peer()_ support 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] -'ws':: unicast transport using WebSockets, see linkzmq:zmq_ws[7] -'wss':: unicast transport using WebSockets over TLS, see linkzmq:zmq_wss[7] +'tcp':: unicast transport using TCP, see xref:zmq_tcp.adoc[zmq_tcp] +'ipc':: local inter-process communication transport, see xref:zmq_ipc.adoc[zmq_ipc] +'inproc':: local in-process (inter-thread) communication transport, see xref:zmq_inproc.adoc[zmq_inproc] +'ws':: unicast transport using WebSockets, see xref:zmq_ws.adoc[zmq_ws] +'wss':: unicast transport using WebSockets over TLS, see xref:zmq_wss.adoc[zmq_wss] -RETURN VALUE ------------- +== RETURN VALUE The _zmq_connect_peer()_ function returns the peer 'routing_id' if successful. Otherwise it returns `0` and sets 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EINVAL*:: The endpoint supplied is invalid. *EPROTONOSUPPORT*:: @@ -55,8 +49,7 @@ The socket is not of type 'ZMQ_PEER'. *EFAULT*:: The 'ZMQ_IMMEDIATE' option is set on the socket. -EXAMPLE -------- +== EXAMPLE .Connecting a peer socket to a TCP transport and sending a message ---- /* Create a ZMQ_SUB socket */ @@ -78,15 +71,13 @@ assert (rc == 0); ---- -SEE ALSO --------- -linkzmq:zmq_connect[3] -linkzmq:zmq_bind[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_connect.adoc[zmq_connect] +xref:zmq_bind.adoc[zmq_bind] +xref:zmq_socket.adoc[zmq_socket] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_ctx_destroy.txt b/doc/zmq_ctx_destroy.txt deleted file mode 100644 index c11f86da..00000000 --- a/doc/zmq_ctx_destroy.txt +++ /dev/null @@ -1,67 +0,0 @@ -zmq_ctx_destroy(3) -================== - - -NAME ----- -zmq_ctx_destroy - terminate a 0MQ context - - -SYNOPSIS --------- -*int zmq_ctx_destroy (void '*context');* - - -DESCRIPTION ------------ -The _zmq_ctx_destroy()_ function shall destroy the 0MQ 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. After interrupting all blocking calls, _zmq_ctx_destroy()_ 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. - -For further details regarding socket linger behaviour refer to the _ZMQ_LINGER_ -option in linkzmq:zmq_setsockopt[3]. - -This function is deprecated by linkzmq:zmq_ctx_term[3]. - - -RETURN VALUE ------------- -The _zmq_ctx_destroy()_ 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 invalid. -*EINTR*:: -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] - - -AUTHORS -------- -This page was written by the 0MQ community. To make a change please -read the 0MQ Contribution Policy at . diff --git a/doc/zmq_ctx_get.txt b/doc/zmq_ctx_get.adoc similarity index 92% rename from doc/zmq_ctx_get.txt rename to doc/zmq_ctx_get.adoc index 84a0afda..e191a051 100644 --- a/doc/zmq_ctx_get.txt +++ b/doc/zmq_ctx_get.adoc @@ -1,20 +1,16 @@ -zmq_ctx_get(3) -============== += zmq_ctx_get(3) -NAME ----- +== NAME zmq_ctx_get - get context options -SYNOPSIS --------- +== SYNOPSIS *int zmq_ctx_get (void '*context', int 'option_name');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_ctx_get()_ function shall return the option specified by the 'option_name' argument. @@ -49,7 +45,7 @@ NOTE: in DRAFT state, not yet available in stable releases. ZMQ_SOCKET_LIMIT: Get largest configurable number of sockets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'ZMQ_SOCKET_LIMIT' argument returns the largest number of sockets that -linkzmq:zmq_ctx_set[3] will accept. +xref:zmq_ctx_set.adoc[zmq_ctx_set] will accept. ZMQ_IPV6: Set IPv6 option @@ -83,23 +79,20 @@ runtime, as defined in the include/zmq.h public header. This is useful for example for FFI bindings that can't simply do a sizeof(). -RETURN VALUE ------------- +== RETURN VALUE The _zmq_ctx_get()_ function returns a value of 0 or greater if successful. Otherwise it returns `-1` and sets 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EINVAL*:: The requested option _option_name_ is unknown. *EFAULT*:: The provided 'context' is invalid. -EXAMPLE -------- +== EXAMPLE .Setting a limit on the number of sockets ---- void *context = zmq_ctx_new (); @@ -113,13 +106,11 @@ zmq_ctx_set (ctx, ZMQ_BLOCKY, false); ---- -SEE ALSO --------- -linkzmq:zmq_ctx_set[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_ctx_set.adoc[zmq_ctx_set] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_ctx_get_ext.txt b/doc/zmq_ctx_get_ext.adoc similarity index 89% rename from doc/zmq_ctx_get_ext.txt rename to doc/zmq_ctx_get_ext.adoc index 48480553..9309d5bc 100644 --- a/doc/zmq_ctx_get_ext.txt +++ b/doc/zmq_ctx_get_ext.adoc @@ -1,20 +1,16 @@ -zmq_ctx_get_ext(3) -================== += zmq_ctx_get_ext(3) -NAME ----- +== NAME zmq_ctx_get_ext - get extended context options -SYNOPSIS --------- +== SYNOPSIS *int zmq_ctx_get_ext (void '*context', int 'option_name', void '*option_value', size_t '*option_len');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_ctx_get()_ function shall retrieve the value for the option specified by the 'option_name' argument and store it in the buffer pointed to by the 'option_value' argument. @@ -39,23 +35,20 @@ Option value unit:: N/A Default value:: empty string -RETURN VALUE ------------- +== RETURN VALUE The _zmq_ctx_get_ext()_ function returns a value of 0 or greater if successful. Otherwise it returns `-1` and sets 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EINVAL*:: The requested option _option_name_ is unknown. *EFAULT*:: The provided 'context' is invalid. -EXAMPLE -------- +== EXAMPLE .Setting a prefix on internal ZMQ thread names: ---- void *context = zmq_ctx_new (); @@ -72,13 +65,11 @@ assert (buffLen == prefixLen); ---- -SEE ALSO --------- -linkzmq:zmq_ctx_get[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_ctx_get.adoc[zmq_ctx_get] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_ctx_new.txt b/doc/zmq_ctx_new.adoc similarity index 74% rename from doc/zmq_ctx_new.txt rename to doc/zmq_ctx_new.adoc index 24dea18e..283d10b4 100644 --- a/doc/zmq_ctx_new.txt +++ b/doc/zmq_ctx_new.adoc @@ -1,22 +1,18 @@ -zmq_ctx_new(3) -============== += zmq_ctx_new(3) -NAME ----- +== NAME zmq_ctx_new - create new 0MQ context -SYNOPSIS --------- +== SYNOPSIS *void *zmq_ctx_new ();* -DESCRIPTION ------------ +== 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 xref:zmq_init.adoc[zmq_init] .Thread safety A 0MQ 'context' is thread safe and may be shared among as many application @@ -24,15 +20,13 @@ threads as necessary, without any additional locking required on the part of the caller. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_ctx_new()_ function shall return an opaque handle to the newly created 'context' if successful. Otherwise it shall return NULL and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EMFILE*:: The limit on the total number of open files has been reached and it wasn't possible to create a new context. @@ -41,15 +35,13 @@ The limit on the total number of open files in system has been reached and it wasn't possible to create a new context. -SEE ALSO --------- -linkzmq:zmq[7] -linkzmq:zmq_ctx_set[3] -linkzmq:zmq_ctx_get[3] -linkzmq:zmq_ctx_term[3] +== SEE ALSO +xref:zmq.adoc[zmq] +xref:zmq_ctx_set.adoc[zmq_ctx_set] +xref:zmq_ctx_get.adoc[zmq_ctx_get] +xref:zmq_ctx_term.adoc[zmq_ctx_term] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_ctx_set.txt b/doc/zmq_ctx_set.adoc similarity index 94% rename from doc/zmq_ctx_set.txt rename to doc/zmq_ctx_set.adoc index 6544e00e..a68c2223 100644 --- a/doc/zmq_ctx_set.txt +++ b/doc/zmq_ctx_set.adoc @@ -1,20 +1,16 @@ -zmq_ctx_set(3) -============== += zmq_ctx_set(3) -NAME ----- +== NAME zmq_ctx_set - set context options -SYNOPSIS --------- +== SYNOPSIS *int zmq_ctx_set (void '*context', int 'option_name', int 'option_value');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_ctx_set()_ function shall set the option specified by the 'option_name' argument to the value of the 'option_value' argument. @@ -120,7 +116,7 @@ ZMQ_MAX_MSGSZ: Set maximum message size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'ZMQ_MAX_MSGSZ' argument sets the maximum allowed size of a message sent in the context. You can query the maximal -allowed value with linkzmq:zmq_ctx_get[3] using the +allowed value with xref:zmq_ctx_get.adoc[zmq_ctx_get] using the 'ZMQ_MAX_MSGSZ' option. [horizontal] @@ -134,7 +130,7 @@ The 'ZMQ_ZERO_COPY_RECV' argument specifies whether the message decoder should use a zero copy strategy when receiving messages. The zero copy strategy can lead to increased memory usage in some cases. This option allows you to use the older copying strategy. You can query the value of this option with -linkzmq:zmq_ctx_get[3] using the 'ZMQ_ZERO_COPY_RECV' option. +xref:zmq_ctx_get.adoc[zmq_ctx_get] using the 'ZMQ_ZERO_COPY_RECV' option. NOTE: in DRAFT state, not yet available in stable releases. [horizontal] @@ -145,7 +141,7 @@ ZMQ_MAX_SOCKETS: Set maximum number of sockets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'ZMQ_MAX_SOCKETS' argument sets the maximum number of sockets allowed on the context. You can query the maximal allowed value with -linkzmq:zmq_ctx_get[3] using the 'ZMQ_SOCKET_LIMIT' option. +xref:zmq_ctx_get.adoc[zmq_ctx_get] using the 'ZMQ_SOCKET_LIMIT' option. [horizontal] Default value:: 1023 @@ -163,20 +159,17 @@ IPv4 and IPv6 hosts. Default value:: 0 -RETURN VALUE ------------- +== RETURN VALUE The _zmq_ctx_set()_ function returns zero if successful. Otherwise it returns `-1` and sets 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EINVAL*:: The requested option _option_name_ is unknown. -EXAMPLE -------- +== EXAMPLE .Setting a limit on the number of sockets ---- void *context = zmq_ctx_new (); @@ -186,13 +179,11 @@ assert (max_sockets == 256); ---- -SEE ALSO --------- -linkzmq:zmq_ctx_get[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_ctx_get.adoc[zmq_ctx_get] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_ctx_set_ext.txt b/doc/zmq_ctx_set_ext.adoc similarity index 91% rename from doc/zmq_ctx_set_ext.txt rename to doc/zmq_ctx_set_ext.adoc index 5438487b..e4353895 100644 --- a/doc/zmq_ctx_set_ext.txt +++ b/doc/zmq_ctx_set_ext.adoc @@ -1,20 +1,16 @@ -zmq_ctx_set_ext(3) -================== += zmq_ctx_set_ext(3) -NAME ----- +== NAME zmq_ctx_set_ext - set extended context options -SYNOPSIS --------- +== SYNOPSIS *int zmq_ctx_set_ext (void '*context', int 'option_name', const void '*option_value', size_t 'option_len');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_ctx_set_ext()_ function shall set the option specified by the 'option_name' argument to the value pointed to by the 'option_value' argument @@ -44,22 +40,19 @@ Option value unit:: N/A Default value:: empty string -RETURN VALUE ------------- +== RETURN VALUE The _zmq_ctx_set_ext()_ function returns zero if successful. Otherwise it returns `-1` and sets 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EINVAL*:: The requested option _option_name_ is unknown. *EFAULT*:: The provided 'context' is invalid. -EXAMPLE -------- +== EXAMPLE .Setting a prefix on internal ZMQ thread names: ---- void *context = zmq_ctx_new (); @@ -76,13 +69,11 @@ assert (buffLen == prefixLen); ---- -SEE ALSO --------- -linkzmq:zmq_ctx_set[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_ctx_set.adoc[zmq_ctx_set] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_ctx_shutdown.txt b/doc/zmq_ctx_shutdown.adoc similarity index 78% rename from doc/zmq_ctx_shutdown.txt rename to doc/zmq_ctx_shutdown.adoc index 8194dc0e..160d2004 100644 --- a/doc/zmq_ctx_shutdown.txt +++ b/doc/zmq_ctx_shutdown.adoc @@ -1,19 +1,15 @@ -zmq_ctx_shutdown(3) -================== += zmq_ctx_shutdown(3) -NAME ----- +== NAME zmq_ctx_shutdown - shutdown a 0MQ context -SYNOPSIS --------- +== SYNOPSIS *int zmq_ctx_shutdown (void '*context');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_ctx_shutdown()_ function shall shutdown the 0MQ context 'context'. Context shutdown will cause any blocking operations currently in progress on @@ -23,32 +19,28 @@ With the exception of _zmq_close()_, any further operations on sockets open with using _zmq_socket()_ on a context for which _zmq_ctx_shutdown()_ has been called, it will return and set errno to ETERM. -This function is optional, client code is still required to call the linkzmq:zmq_ctx_term[3] +This function is optional, client code is still required to call the xref:zmq_ctx_term.adoc[zmq_ctx_term] function to free all resources allocated by zeromq. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_ctx_shutdown()_ function shall return zero if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EFAULT*:: The provided 'context' was invalid. -SEE ALSO --------- -linkzmq:zmq[7] -linkzmq:zmq_init[3] -linkzmq:zmq_ctx_term[3] -linkzmq:zmq_close[3] -linkzmq:zmq_setsockopt[3] +== SEE ALSO +xref:zmq.adoc[zmq] +xref:zmq_init.adoc[zmq_init] +xref:zmq_ctx_term.adoc[zmq_ctx_term] +xref:zmq_close.adoc[zmq_close] +xref:zmq_setsockopt.adoc[zmq_setsockopt] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_ctx_term.txt b/doc/zmq_ctx_term.adoc similarity index 78% rename from doc/zmq_ctx_term.txt rename to doc/zmq_ctx_term.adoc index 79aad1c5..9e40764d 100644 --- a/doc/zmq_ctx_term.txt +++ b/doc/zmq_ctx_term.adoc @@ -1,19 +1,15 @@ -zmq_ctx_term(3) -=============== += zmq_ctx_term(3) -NAME ----- +== NAME zmq_ctx_term - terminate a 0MQ context -SYNOPSIS --------- +== SYNOPSIS *int zmq_ctx_term (void '*context');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_ctx_term()_ function shall destroy the 0MQ context 'context'. Context termination is performed in the following steps: @@ -34,35 +30,31 @@ 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 xref:zmq_setsockopt.adoc[zmq_setsockopt] -This function replaces the deprecated functions linkzmq:zmq_term[3] and -linkzmq:zmq_ctx_destroy[3]. +This function replaces the deprecated functions xref:zmq_term.adoc[zmq_term] and +xref:zmq_ctx_destroy.adoc[zmq_ctx_destroy] -RETURN VALUE ------------- +== RETURN VALUE The _zmq_ctx_term()_ function shall return zero if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EFAULT*:: The provided 'context' was invalid. *EINTR*:: 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] +== SEE ALSO +xref:zmq.adoc[zmq] +xref:zmq_init.adoc[zmq_init] +xref:zmq_close.adoc[zmq_close] +xref:zmq_setsockopt.adoc[zmq_setsockopt] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_curve.txt b/doc/zmq_curve.adoc similarity index 88% rename from doc/zmq_curve.txt rename to doc/zmq_curve.adoc index e1fe6971..8e9f5514 100644 --- a/doc/zmq_curve.txt +++ b/doc/zmq_curve.adoc @@ -1,22 +1,18 @@ -zmq_curve(7) -============ += zmq_curve(7) -NAME ----- +== NAME zmq_curve - secure authentication and confidentiality -SYNOPSIS --------- +== SYNOPSIS The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks. The CURVE mechanism is defined by this document: . -CLIENT AND SERVER ROLES ------------------------ +== CLIENT AND SERVER ROLES A socket using CURVE can be either client or server, at any moment, but not both. The role is independent of bind/connect direction. @@ -37,8 +33,7 @@ long-term key pair. If the server does authentication it will be based on the client's long term public key. -KEY ENCODING ------------- +== KEY ENCODING The standard representation for keys in source code is either 32 bytes of base 256 (binary) data, or 40 characters of base 85 data encoded using the Z85 algorithm defined by http://rfc.zeromq.org/spec:32. @@ -48,8 +43,7 @@ configuration files, the command line, and code. There is a reference implementation in C at https://github.com/zeromq/rfc/tree/master/src. -TEST KEY VALUES ---------------- +== TEST KEY VALUES For test cases, the client shall use this long-term key pair (specified as hexadecimal and in Z85): @@ -76,17 +70,15 @@ secret: JTKVSB%%)wK0E.X)V>+}o?pNmC{O&4W4b!Ni{Lh6 ---- -SEE ALSO --------- -linkzmq:zmq_z85_encode[3] -linkzmq:zmq_z85_decode[3] -linkzmq:zmq_setsockopt[3] -linkzmq:zmq_null[7] -linkzmq:zmq_plain[7] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_z85_encode.adoc[zmq_z85_encode] +xref:zmq_z85_decode.adoc[zmq_z85_decode] +xref:zmq_setsockopt.adoc[zmq_setsockopt] +xref:zmq_null.adoc[zmq_null] +xref:zmq_plain.adoc[zmq_plain] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_curve_keypair.txt b/doc/zmq_curve_keypair.adoc similarity index 72% rename from doc/zmq_curve_keypair.txt rename to doc/zmq_curve_keypair.adoc index 82c13d6c..598ad018 100644 --- a/doc/zmq_curve_keypair.txt +++ b/doc/zmq_curve_keypair.adoc @@ -1,39 +1,32 @@ -zmq_curve_keypair(3) -==================== += zmq_curve_keypair(3) -NAME ----- +== NAME zmq_curve_keypair - generate a new CURVE keypair -SYNOPSIS --------- +== SYNOPSIS *int zmq_curve_keypair (char *z85_public_key, char *z85_secret_key);* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_curve_keypair()_ function shall return a newly generated random keypair consisting of a public key and a secret key. The caller provides two buffers, each at least 41 octets large, in which this method will -store the keys. The keys are encoded using linkzmq:zmq_z85_encode[3]. +store the keys. The keys are encoded using xref:zmq_z85_encode.adoc[zmq_z85_encode]. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_curve_keypair()_ function shall return 0 if successful, else it shall return `-1` and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *ENOTSUP*:: The libzmq library was not built with cryptographic support (libsodium). -EXAMPLE -------- +== EXAMPLE .Generating a new CURVE keypair ---- char public_key [41]; @@ -43,14 +36,12 @@ assert (rc == 0); ---- -SEE ALSO --------- -linkzmq:zmq_z85_decode[3] -linkzmq:zmq_z85_encode[3] -linkzmq:zmq_curve[7] +== SEE ALSO +xref:zmq_z85_encode.adoc[zmq_z85_encode] +xref:zmq_z85_decode.adoc[zmq_z85_decode] +xref:zmq_curve.adoc[zmq_curve] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_curve_public.txt b/doc/zmq_curve_public.adoc similarity index 77% rename from doc/zmq_curve_public.txt rename to doc/zmq_curve_public.adoc index fd8adf16..faade635 100644 --- a/doc/zmq_curve_public.txt +++ b/doc/zmq_curve_public.adoc @@ -1,40 +1,33 @@ -zmq_curve_public(3) -=================== += zmq_curve_public(3) -NAME ----- +== NAME zmq_curve_public - derive the public key from a private key -SYNOPSIS --------- +== SYNOPSIS *int zmq_curve_public (char *z85_public_key, char *z85_secret_key);* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_curve_public()_ function shall derive the public key from a private key. The caller provides two buffers, each at least 41 octets large. In z85_secret_key the caller shall provide the private key, and the function will store the public key in z85_public_key. The keys are -encoded using linkzmq:zmq_z85_encode[3]. +encoded using xref:zmq_z85_encode.adoc[zmq_z85_encode]. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_curve_public()_ function shall return 0 if successful, else it shall return `-1` and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *ENOTSUP*:: The libzmq library was not built with cryptographic support (libsodium). -EXAMPLE -------- +== EXAMPLE .Deriving the public key from a CURVE private key ---- char public_key [41]; @@ -48,15 +41,13 @@ assert (!strcmp (derived_public, public_key)); ---- -SEE ALSO --------- -linkzmq:zmq_z85_decode[3] -linkzmq:zmq_z85_encode[3] -linkzmq:zmq_curve_keypair[3] -linkzmq:zmq_curve[7] +== SEE ALSO +xref:zmq_z85_encode.adoc[zmq_z85_encode] +xref:zmq_z85_decode.adoc[zmq_z85_decode] +xref:zmq_curve_keypair.adoc[zmq_curve_keypair] +xref:zmq_curve.adoc[zmq_curve] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_disconnect.txt b/doc/zmq_disconnect.adoc similarity index 83% rename from doc/zmq_disconnect.txt rename to doc/zmq_disconnect.adoc index 0b2783d7..53ecaecc 100644 --- a/doc/zmq_disconnect.txt +++ b/doc/zmq_disconnect.adoc @@ -1,19 +1,15 @@ -zmq_disconnect(3) -================= += zmq_disconnect(3) -NAME ----- +== NAME zmq_disconnect - Disconnect a socket from an endpoint -SYNOPSIS --------- +== SYNOPSIS *int zmq_disconnect (void '*socket', const char '*endpoint');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_disconnect()_ function shall disconnect a socket specified by the 'socket' argument from the endpoint specified by the 'endpoint' argument. Note the actual disconnect system call might occur at a later time. @@ -25,19 +21,17 @@ associated with the endpoint will be discarded. However, if the socket's linger period is non-zero, libzmq will still attempt to transmit these discarded messages, until the linger period expires. -The 'endpoint' argument is as described in linkzmq:zmq_connect[3] +The 'endpoint' argument is as described in xref:zmq_connect.adoc[zmq_connect] NOTE: The default setting of _ZMQ_LINGER_ does not discard unsent messages; this behaviour may cause the application to block when calling _zmq_ctx_term()_. -For details refer to linkzmq:zmq_setsockopt[3] and linkzmq:zmq_ctx_term[3]. +For details refer to xref:zmq_setsockopt.adoc[zmq_setsockopt] and xref:zmq_ctx_term.adoc[zmq_ctx_term] -RETURN VALUE ------------- +== RETURN VALUE The _zmq_disconnect()_ function shall return zero if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EINVAL*:: The endpoint supplied is invalid. *ETERM*:: @@ -48,8 +42,7 @@ The provided 'socket' was invalid. The provided endpoint is not in use by the socket. -EXAMPLE -------- +== EXAMPLE .Connecting a subscriber socket to an in-process and a TCP transport ---- /* Create a ZMQ_SUB socket */ @@ -63,14 +56,12 @@ rc = zmq_disconnect (socket, "tcp://server001:5555"); assert (rc == 0); ---- -SEE ALSO --------- -linkzmq:zmq_connect[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_connect.adoc[zmq_connect] +xref:zmq_socket.adoc[zmq_socket] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_errno.txt b/doc/zmq_errno.adoc similarity index 85% rename from doc/zmq_errno.txt rename to doc/zmq_errno.adoc index 3a0e0b29..255510a4 100644 --- a/doc/zmq_errno.txt +++ b/doc/zmq_errno.adoc @@ -1,19 +1,15 @@ -zmq_errno(3) -============ += zmq_errno(3) -NAME ----- +== NAME zmq_errno - retrieve value of errno for the calling thread -SYNOPSIS --------- +== SYNOPSIS *int zmq_errno (void);* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_errno()_ function shall retrieve the value of the 'errno' variable for the calling thread. @@ -28,23 +24,19 @@ IMPORTANT: Users not experiencing issues with retrieving the correct value of variable directly. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_errno()_ function shall return the value of the 'errno' variable for the calling thread. -ERRORS ------- +== ERRORS No errors are defined. -SEE ALSO --------- -linkzmq:zmq[7] +== SEE ALSO +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.adoc similarity index 98% rename from doc/zmq_getsockopt.txt rename to doc/zmq_getsockopt.adoc index 6fb1f818..e25c5f06 100644 --- a/doc/zmq_getsockopt.txt +++ b/doc/zmq_getsockopt.adoc @@ -1,20 +1,16 @@ -zmq_getsockopt(3) -================= += zmq_getsockopt(3) -NAME ----- +== NAME zmq_getsockopt - get 0MQ socket options -SYNOPSIS --------- +== SYNOPSIS *int zmq_getsockopt (void '*socket', int 'option_name', void '*option_value', size_t '*option_len');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_getsockopt()_ function shall retrieve the value for the option specified by the 'option_name' argument for the 0MQ socket pointed to by the 'socket' argument, and store it in the buffer pointed to by the 'option_value' @@ -39,7 +35,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 xref:zmq_init.adoc[zmq_init] for details on allocating the number of I/O threads for a specific _context_. [horizontal] @@ -384,8 +380,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_ctx_term[3]. The following outlines the different +xref:zmq_close.adoc[zmq_close], and further affects the termination of the socket's +context with xref:zmq_ctx_term.adoc[zmq_ctx_term] The following outlines the different behaviours: * The default value of '-1' specifies an infinite linger period. Pending @@ -561,7 +557,7 @@ limit. 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 xref:zmq_socket.adoc[zmq_socket] for details on the exact action taken for each socket type. [horizontal] @@ -577,7 +573,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 xref:zmq_send.adoc[zmq_send] and xref:zmq_recv.adoc[zmq_recv] for a detailed description of multi-part messages. [horizontal] @@ -709,7 +705,7 @@ limit. 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 xref:zmq_socket.adoc[zmq_socket] for details on the exact action taken for each socket type. [horizontal] @@ -814,7 +810,7 @@ Applicable socket types:: all, when using TCP transports. ZMQ_THREAD_SAFE: Retrieve socket thread safety ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'ZMQ_THREAD_SAFE' option shall retrieve a boolean value indicating whether -or not the socket is threadsafe. See linkzmq:zmq_socket[3] for which sockets are +or not the socket is threadsafe. See xref:zmq_socket.adoc[zmq_socket] for which sockets are thread-safe. [horizontal] @@ -1137,14 +1133,12 @@ Default value:: 0 (false) Applicable socket types:: All, when using NORM transport. -RETURN VALUE ------------- +== 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 ------- +== 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 @@ -1158,8 +1152,7 @@ The provided 'socket' was invalid. The operation was interrupted by delivery of a signal. -EXAMPLE -------- +== EXAMPLE .Retrieving the high water mark for outgoing messages ---- /* Retrieve high water mark into sndhwm */ @@ -1170,14 +1163,12 @@ assert (rc == 0); ---- -SEE ALSO --------- -linkzmq:zmq_setsockopt[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_setsockopt.adoc[zmq_setsockopt] +xref:zmq_socket.adoc[zmq_socket] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_gssapi.txt b/doc/zmq_gssapi.adoc similarity index 88% rename from doc/zmq_gssapi.txt rename to doc/zmq_gssapi.adoc index 6834599b..374d194f 100644 --- a/doc/zmq_gssapi.txt +++ b/doc/zmq_gssapi.adoc @@ -1,14 +1,11 @@ -zmq_gssapi(7) -============ += zmq_gssapi(7) -NAME ----- +== NAME zmq_gssapi - secure authentication and confidentiality -SYNOPSIS --------- +== SYNOPSIS The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the @@ -18,8 +15,7 @@ defined in IETF RFC-2743: . The ZeroMQ GSSAPI mechanism is defined by this document: . -CLIENT AND SERVER ROLES ------------------------ +== CLIENT AND SERVER ROLES A socket using GSSAPI can be either client or server, but not both. To become a GSSAPI server, the application sets the ZMQ_GSSAPI_SERVER @@ -35,8 +31,7 @@ principal for whom GSSAPI credentials should be acquired. If this option is not set, default credentials are used. -OPTIONAL ENCRYPTION -------------------- +== OPTIONAL ENCRYPTION By default, the GSSAPI mechanism will encrypt all communications between client and server. If encryption is not desired (e.g. on private networks), the client and server applications can disable it by setting the @@ -44,8 +39,7 @@ ZMQ_GSSAPI_PLAINTEXT option. Both the client and server must set this option to the same value. -PRINCIPAL NAMES ---------------- +== PRINCIPAL NAMES Principal names specified with the ZMQ_GSSAPI_SERVICE_PRINCIPAL or ZMQ_GSSAPI_PRINCIPAL options are interpreted as "host based" name types by default. The ZMQ_GSSAPI_PRINCIPAL_NAMETYPE and @@ -64,15 +58,13 @@ The name is a principal name string. This name type only works with the krb5 GSSAPI mechanism. -SEE ALSO --------- -linkzmq:zmq_setsockopt[3] -linkzmq:zmq_null[7] -linkzmq:zmq_curve[7] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_setsockopt.adoc[zmq_setsockopt] +xref:zmq_null.adoc[zmq_null] +xref:zmq_curve.adoc[zmq_curve] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_has.txt b/doc/zmq_has.adoc similarity index 90% rename from doc/zmq_has.txt rename to doc/zmq_has.adoc index 847711b4..aab0faf1 100644 --- a/doc/zmq_has.txt +++ b/doc/zmq_has.adoc @@ -1,19 +1,15 @@ -zmq_has(3) -========== += zmq_has(3) -NAME ----- +== NAME zmq_has - check a ZMQ capability -SYNOPSIS --------- +== SYNOPSIS *int zmq_has (const char *capability);* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_has()_ function shall report whether a specified capability is available in the library. This allows bindings and applications to probe a library directly, for transport and security options. @@ -32,13 +28,11 @@ defined: When this method is provided, the zmq.h header file will define ZMQ_HAS_CAPABILITIES. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_has()_ function shall return 1 if the specified capability is provided. Otherwise it shall return 0. -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_init.txt b/doc/zmq_init.txt deleted file mode 100644 index aab86ab1..00000000 --- a/doc/zmq_init.txt +++ /dev/null @@ -1,52 +0,0 @@ -zmq_init(3) -=========== - - -NAME ----- -zmq_init - initialise 0MQ context - - -SYNOPSIS --------- -*void *zmq_init (int 'io_threads');* - - -DESCRIPTION ------------ -The _zmq_init()_ function initialises a 0MQ 'context'. - -The 'io_threads' argument specifies the size of the 0MQ 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 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]. - -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 --------- -linkzmq:zmq[7] -linkzmq:zmq_ctx_term[3] - - -AUTHORS -------- -This page was written by the 0MQ community. To make a change please -read the 0MQ Contribution Policy at . diff --git a/doc/zmq_inproc.txt b/doc/zmq_inproc.adoc similarity index 88% rename from doc/zmq_inproc.txt rename to doc/zmq_inproc.adoc index 94621016..af7edd9a 100644 --- a/doc/zmq_inproc.txt +++ b/doc/zmq_inproc.adoc @@ -1,25 +1,21 @@ -zmq_inproc(7) -============= += zmq_inproc(7) -NAME ----- +== NAME zmq_inproc - 0MQ local in-process (inter-thread) communication transport -SYNOPSIS --------- +== SYNOPSIS The in-process transport passes messages via memory directly between threads 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. +xref:zmq_init.adoc[zmq_init] for details. -ADDRESSING ----------- +== 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. @@ -48,8 +44,7 @@ order of _zmq_bind()_ and _zmq_connect()_ does not matter just like for the tcp transport type. -EXAMPLES --------- +== EXAMPLES .Assigning a local address to a socket ---- // Assign the in-process name "#1" @@ -71,18 +66,16 @@ 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_vmci[7] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_bind.adoc[zmq_bind] +xref:zmq_connect.adoc[zmq_connect] +xref:zmq_ipc.adoc[zmq_ipc] +xref:zmq_tcp.adoc[zmq_tcp] +xref:zmq_pgm.adoc[zmq_pgm] +xref:zmq_vmci.adoc[zmq_vmci] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_ipc.txt b/doc/zmq_ipc.adoc similarity index 89% rename from doc/zmq_ipc.txt rename to doc/zmq_ipc.adoc index 9ec6e69a..7125ae0b 100644 --- a/doc/zmq_ipc.txt +++ b/doc/zmq_ipc.adoc @@ -1,14 +1,11 @@ -zmq_ipc(7) -========== += zmq_ipc(7) -NAME ----- +== NAME zmq_ipc - 0MQ local inter-process communication transport -SYNOPSIS --------- +== SYNOPSIS The inter-process transport passes messages between local processes using a system-dependent IPC mechanism. @@ -16,8 +13,7 @@ NOTE: The inter-process transport is currently only implemented on operating systems that provide UNIX domain sockets. -ADDRESSING ----------- +== 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. @@ -37,7 +33,7 @@ any restrictions placed by the operating system on the format and length of a When the address is wild-card `*`, _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 xref:zmq_getsockopt.adoc[zmq_getsockopt] for details. NOTE: any existing binding to the same endpoint shall be overridden. That is, if a second process binds to an endpoint already bound by a process, this @@ -72,8 +68,7 @@ previously created within the operating system namespace by assigning it to a 'socket' with _zmq_bind()_. -EXAMPLES --------- +== EXAMPLES .Assigning a local address to a socket ---- // Assign the pathname "/tmp/feeds/0" @@ -88,19 +83,17 @@ rc = zmq_connect(socket, "ipc:///tmp/feeds/0"); 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_vmci[7] -linkzmq:zmq_getsockopt[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_bind.adoc[zmq_bind] +xref:zmq_connect.adoc[zmq_connect] +xref:zmq_inproc.adoc[zmq_inproc] +xref:zmq_tcp.adoc[zmq_tcp] +xref:zmq_pgm.adoc[zmq_pgm] +xref:zmq_vmci.adoc[zmq_vmci] +xref:zmq_getsockopt.adoc[zmq_getsockopt] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_msg_close.txt b/doc/zmq_msg_close.adoc similarity index 74% rename from doc/zmq_msg_close.txt rename to doc/zmq_msg_close.adoc index 649c70ee..cda20691 100644 --- a/doc/zmq_msg_close.txt +++ b/doc/zmq_msg_close.adoc @@ -1,19 +1,15 @@ -zmq_msg_close(3) -================ += zmq_msg_close(3) -NAME ----- +== NAME zmq_msg_close - release 0MQ message -SYNOPSIS --------- +== SYNOPSIS *int zmq_msg_close (zmq_msg_t '*msg');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_msg_close()_ function shall inform the 0MQ 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 @@ -28,30 +24,26 @@ CAUTION: Never access 'zmq_msg_t' members directly, instead always use the _zmq_msg_ family of functions. -RETURN VALUE ------------- +== 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 ------- +== ERRORS *EFAULT*:: Invalid message. -SEE ALSO --------- -linkzmq:zmq_msg_init[3] -linkzmq:zmq_msg_init_size[3] -linkzmq:zmq_msg_init_buffer[3] -linkzmq:zmq_msg_init_data[3] -linkzmq:zmq_msg_data[3] -linkzmq:zmq_msg_size[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_msg_init.adoc[zmq_msg_init] +xref:zmq_msg_init_size.adoc[zmq_msg_init_size] +xref:zmq_msg_init_buffer.adoc[zmq_msg_init_buffer] +xref:zmq_msg_init_data.adoc[zmq_msg_init_data] +xref:zmq_msg_data.adoc[zmq_msg_data] +xref:zmq_msg_size.adoc[zmq_msg_size] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_msg_copy.txt b/doc/zmq_msg_copy.adoc similarity index 78% rename from doc/zmq_msg_copy.txt rename to doc/zmq_msg_copy.adoc index 2cc0a3d7..23046401 100644 --- a/doc/zmq_msg_copy.txt +++ b/doc/zmq_msg_copy.adoc @@ -1,19 +1,15 @@ -zmq_msg_copy(3) -=============== += zmq_msg_copy(3) -NAME ----- +== NAME zmq_msg_copy - copy content of a message to another message -SYNOPSIS --------- +== SYNOPSIS *int zmq_msg_copy (zmq_msg_t '*dest', zmq_msg_t '*src');* -DESCRIPTION ------------ +== 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. You must initialise 'dest' before copying to it. @@ -29,20 +25,17 @@ CAUTION: Never access 'zmq_msg_t' members directly, instead always use the _zmq_msg_ family of functions. -RETURN VALUE ------------- +== 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 ------- +== ERRORS *EFAULT*:: Invalid message. -EXAMPLE -------- +== EXAMPLE .Copying a message ---- zmq_msg_t msg; @@ -55,18 +48,16 @@ zmq_msg_close (©); zmq_msg_close (&msg); ---- -SEE ALSO --------- -linkzmq:zmq_msg_move[3] -linkzmq:zmq_msg_init[3] -linkzmq:zmq_msg_init_size[3] -linkzmq:zmq_msg_init_buffer[3] -linkzmq:zmq_msg_init_data[3] -linkzmq:zmq_msg_close[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_msg_move.adoc[zmq_msg_move] +xref:zmq_msg_init.adoc[zmq_msg_init] +xref:zmq_msg_init_size.adoc[zmq_msg_init_size] +xref:zmq_msg_init_buffer.adoc[zmq_msg_init_buffer] +xref:zmq_msg_init_data.adoc[zmq_msg_init_data] +xref:zmq_msg_close.adoc[zmq_msg_close] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_msg_data.txt b/doc/zmq_msg_data.adoc similarity index 61% rename from doc/zmq_msg_data.txt rename to doc/zmq_msg_data.adoc index b6929829..da75c811 100644 --- a/doc/zmq_msg_data.txt +++ b/doc/zmq_msg_data.adoc @@ -1,19 +1,15 @@ -zmq_msg_data(3) -=============== += zmq_msg_data(3) -NAME ----- +== NAME zmq_msg_data - retrieve pointer to message content -SYNOPSIS --------- +== SYNOPSIS *void *zmq_msg_data (zmq_msg_t '*msg');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_msg_data()_ function shall return a pointer to the message content of the message object referenced by 'msg'. @@ -21,29 +17,25 @@ CAUTION: Never access 'zmq_msg_t' members directly, instead always use the _zmq_msg_ family of functions. -RETURN VALUE ------------- +== RETURN VALUE Upon successful completion, _zmq_msg_data()_ shall return a pointer to the message content. -ERRORS ------- +== ERRORS 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_buffer[3] -linkzmq:zmq_msg_init_data[3] -linkzmq:zmq_msg_close[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_msg_size.adoc[zmq_msg_size] +xref:zmq_msg_init.adoc[zmq_msg_init] +xref:zmq_msg_init_size.adoc[zmq_msg_init_size] +xref:zmq_msg_init_buffer.adoc[zmq_msg_init_buffer] +xref:zmq_msg_init_data.adoc[zmq_msg_init_data] +xref:zmq_msg_close.adoc[zmq_msg_close] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_msg_get.txt b/doc/zmq_msg_get.adoc similarity index 86% rename from doc/zmq_msg_get.txt rename to doc/zmq_msg_get.adoc index 11c934ec..5605a4ca 100644 --- a/doc/zmq_msg_get.txt +++ b/doc/zmq_msg_get.adoc @@ -1,19 +1,15 @@ -zmq_msg_get(3) -============== += zmq_msg_get(3) -NAME ----- +== NAME zmq_msg_get - get message property -SYNOPSIS --------- +== SYNOPSIS *int zmq_msg_get (zmq_msg_t '*message', int 'property');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_msg_get()_ function shall return the value for the property specified by the 'property' argument for the message pointed to by the 'message' argument. @@ -33,21 +29,18 @@ Currently only implemented for TCP sockets. Indicates that a message MAY share underlying storage with another copy of this message. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_msg_get()_ function shall return the value for the property if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EINVAL*:: The requested _property_ is unknown. -EXAMPLE -------- +== EXAMPLE .Receiving a multi-frame message ---- zmq_msg_t frame; @@ -69,15 +62,13 @@ while (true) { ---- -SEE ALSO --------- -linkzmq:zmq_msg_set[3] -linkzmq:zmq_msg_init[3] -linkzmq:zmq_msg_close[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_msg_set.adoc[zmq_msg_set] +xref:zmq_msg_init.adoc[zmq_msg_init] +xref:zmq_msg_close.adoc[zmq_msg_close] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_msg_gets.txt b/doc/zmq_msg_gets.adoc similarity index 87% rename from doc/zmq_msg_gets.txt rename to doc/zmq_msg_gets.adoc index f887b407..56b7b051 100644 --- a/doc/zmq_msg_gets.txt +++ b/doc/zmq_msg_gets.adoc @@ -1,19 +1,15 @@ -zmq_msg_gets(3) -=============== += zmq_msg_gets(3) -NAME ----- +== NAME zmq_msg_gets - get message metadata property -SYNOPSIS --------- +== SYNOPSIS *const char *zmq_msg_gets (zmq_msg_t '*message', const char *'property');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_msg_gets()_ function shall return the string value for the metadata property specified by the 'property' argument for the message pointed to by the 'message' argument. Both the 'property' argument and the 'value' @@ -21,7 +17,7 @@ shall be NULL-terminated UTF8-encoded strings. Metadata is defined on a per-connection basis during the ZeroMQ connection handshake as specified in . Applications can set -metadata properties using linkzmq:zmq_setsockopt[3] option ZMQ_METADATA. +metadata properties using xref:zmq_setsockopt.adoc[zmq_setsockopt] option ZMQ_METADATA. Application metadata properties must be prefixed with 'X-'. In addition to application metadata, the following ZMTP properties can be @@ -44,8 +40,7 @@ Currently, these definitions are only available as a DRAFT API. Other properties may be defined based on the underlying security mechanism, see ZAP authenticated connection sample below. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_msg_gets()_ function shall return the string value for the property if successful. Otherwise it shall return NULL and set 'errno' to one of the values defined below. The caller shall not modify or free the returned value, @@ -53,14 +48,12 @@ which shall be owned by the message. The encoding of the property and value shall be UTF8. -ERRORS ------- +== ERRORS *EINVAL*:: The requested _property_ is unknown. -EXAMPLE -------- +== EXAMPLE .Getting the ZAP authenticated user id for a message: ---- zmq_msg_t msg; @@ -72,12 +65,10 @@ zmq_msg_close (&msg); ---- -SEE ALSO --------- -linkzmq:zmq[7] -linkzmq:zmq_setsockopt[3] +== SEE ALSO +xref:zmq.adoc[zmq] +xref:zmq_setsockopt.adoc[zmq_setsockopt] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_msg_init.txt b/doc/zmq_msg_init.adoc similarity index 71% rename from doc/zmq_msg_init.txt rename to doc/zmq_msg_init.adoc index b329bf71..19dc27f2 100644 --- a/doc/zmq_msg_init.txt +++ b/doc/zmq_msg_init.adoc @@ -1,19 +1,15 @@ -zmq_msg_init(3) -=============== += zmq_msg_init(3) -NAME ----- +== NAME zmq_msg_init - initialise empty 0MQ message -SYNOPSIS --------- +== SYNOPSIS *int zmq_msg_init (zmq_msg_t '*msg');* -DESCRIPTION ------------ +== 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_msg_recv()_. @@ -26,18 +22,15 @@ _zmq_msg_init_size()_ and _zmq_msg_init_buffer()_ are mutually exclusive. Never initialise the same 'zmq_msg_t' twice. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_msg_init()_ function always returns zero. -ERRORS ------- +== ERRORS No errors are defined. -EXAMPLE -------- +== EXAMPLE .Receiving a message from a socket ---- zmq_msg_t msg; @@ -48,18 +41,16 @@ assert (nbytes != -1); ---- -SEE ALSO --------- -linkzmq:zmq_msg_init_size[3] -linkzmq:zmq_msg_init_buffer[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] +== SEE ALSO +xref:zmq_msg_init_size.adoc[zmq_msg_init_size] +xref:zmq_msg_init_buffer.adoc[zmq_msg_init_buffer] +xref:zmq_msg_init_data.adoc[zmq_msg_init_data] +xref:zmq_msg_close.adoc[zmq_msg_close] +xref:zmq_msg_data.adoc[zmq_msg_data] +xref:zmq_msg_size.adoc[zmq_msg_size] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_msg_init_buffer.txt b/doc/zmq_msg_init_buffer.adoc similarity index 75% rename from doc/zmq_msg_init_buffer.txt rename to doc/zmq_msg_init_buffer.adoc index 23bf83f4..561e5535 100644 --- a/doc/zmq_msg_init_buffer.txt +++ b/doc/zmq_msg_init_buffer.adoc @@ -1,19 +1,15 @@ -zmq_msg_init_buffer(3) -====================== += zmq_msg_init_buffer(3) -NAME ----- +== NAME zmq_msg_init_buffer - initialise 0MQ message with buffer copy -SYNOPSIS --------- +== SYNOPSIS *int zmq_msg_init_buffer (zmq_msg_t '*msg', const void '*buf', size_t 'size');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_msg_init_buffer()_ function shall allocate any resources required to store a message 'size' bytes long and initialise the message object referenced by 'msg' to represent a copy of the buffer referenced by the 'buf' and @@ -30,30 +26,26 @@ _zmq_msg_init_buffer()_ and _zmq_msg_init_buffer()_ are mutually exclusive. Never initialise the same 'zmq_msg_t' twice. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_msg_init_buffer()_ function shall return zero if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *ENOMEM*:: Insufficient storage space is available. -SEE ALSO --------- -linkzmq:zmq_msg_init_data[3] -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] +== SEE ALSO +xref:zmq_msg_init_data.adoc[zmq_msg_init_data] +xref:zmq_msg_init_size.adoc[zmq_msg_init_size] +xref:zmq_msg_init.adoc[zmq_msg_init] +xref:zmq_msg_close.adoc[zmq_msg_close] +xref:zmq_msg_data.adoc[zmq_msg_data] +xref:zmq_msg_size.adoc[zmq_msg_size] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_msg_init_data.txt b/doc/zmq_msg_init_data.adoc similarity index 83% rename from doc/zmq_msg_init_data.txt rename to doc/zmq_msg_init_data.adoc index 1adcc6be..f0d11885 100644 --- a/doc/zmq_msg_init_data.txt +++ b/doc/zmq_msg_init_data.adoc @@ -1,21 +1,17 @@ -zmq_msg_init_data(3) -==================== += zmq_msg_init_data(3) -NAME ----- +== NAME zmq_msg_init_data - initialise 0MQ message from a supplied buffer -SYNOPSIS --------- +== 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 ------------ +== 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 @@ -40,21 +36,18 @@ _zmq_msg_init_size()_ and _zmq_msg_init_buffer()_ are mutually exclusive. Never initialise the same 'zmq_msg_t' twice. -RETURN VALUE ------------- +== 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 ------- +== ERRORS *ENOMEM*:: Insufficient storage space is available. -EXAMPLE -------- +== EXAMPLE .Initialising a message from a supplied buffer ---- void my_free (void *data, void *hint) @@ -73,18 +66,16 @@ assert (rc == 0); ---- -SEE ALSO --------- -linkzmq:zmq_msg_init_size[3] -linkzmq:zmq_msg_init_buffer[3] -linkzmq:zmq_msg_init[3] -linkzmq:zmq_msg_close[3] -linkzmq:zmq_msg_data[3] -linkzmq:zmq_msg_size[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_msg_init_size.adoc[zmq_msg_init_size] +xref:zmq_msg_init_buffer.adoc[zmq_msg_init_buffer] +xref:zmq_msg_init.adoc[zmq_msg_init] +xref:zmq_msg_close.adoc[zmq_msg_close] +xref:zmq_msg_data.adoc[zmq_msg_data] +xref:zmq_msg_size.adoc[zmq_msg_size] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_msg_init_size.txt b/doc/zmq_msg_init_size.adoc similarity index 76% rename from doc/zmq_msg_init_size.txt rename to doc/zmq_msg_init_size.adoc index 231d1a22..d815c52f 100644 --- a/doc/zmq_msg_init_size.txt +++ b/doc/zmq_msg_init_size.adoc @@ -1,19 +1,15 @@ -zmq_msg_init_size(3) -==================== += zmq_msg_init_size(3) -NAME ----- +== NAME zmq_msg_init_size - initialise 0MQ message of a specified size -SYNOPSIS --------- +== SYNOPSIS *int zmq_msg_init_size (zmq_msg_t '*msg', size_t 'size');* -DESCRIPTION ------------ +== 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. @@ -30,30 +26,26 @@ _zmq_msg_init_size()_ and _zmq_msg_init_buffer()_ are mutually exclusive. Never initialise the same 'zmq_msg_t' twice. -RETURN VALUE ------------- +== 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 ------- +== ERRORS *ENOMEM*:: Insufficient storage space is available. -SEE ALSO --------- -linkzmq:zmq_msg_init_data[3] -linkzmq:zmq_msg_init_buffer[3] -linkzmq:zmq_msg_init[3] -linkzmq:zmq_msg_close[3] -linkzmq:zmq_msg_data[3] -linkzmq:zmq_msg_size[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_msg_init_data.adoc[zmq_msg_init_data] +xref:zmq_msg_init_buffer.adoc[zmq_msg_init_buffer] +xref:zmq_msg_init.adoc[zmq_msg_init] +xref:zmq_msg_close.adoc[zmq_msg_close] +xref:zmq_msg_data.adoc[zmq_msg_data] +xref:zmq_msg_size.adoc[zmq_msg_size] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_msg_more.txt b/doc/zmq_msg_more.adoc similarity index 81% rename from doc/zmq_msg_more.txt rename to doc/zmq_msg_more.adoc index 179f4d34..de0aaebb 100644 --- a/doc/zmq_msg_more.txt +++ b/doc/zmq_msg_more.adoc @@ -1,34 +1,28 @@ -zmq_msg_more(3) -=============== += zmq_msg_more(3) -NAME ----- +== NAME zmq_msg_more - indicate if there are more message parts to receive -SYNOPSIS --------- +== SYNOPSIS *int zmq_msg_more (zmq_msg_t '*message');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_msg_more()_ function indicates whether this is part of a multi-part message, and there are further parts to receive. This method can safely be called after _zmq_msg_close()_. This method is identical to _zmq_msg_get()_ with an argument of ZMQ_MORE. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_msg_more()_ function shall return zero if this is the final part of a multi-part message, or the only part of a single-part message. It shall return 1 if there are further parts to receive. -EXAMPLE -------- +== EXAMPLE .Receiving a multi-part message ---- zmq_msg_t part; @@ -50,16 +44,14 @@ 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] +== SEE ALSO +xref:zmq_msg_get.adoc[zmq_msg_get] +xref:zmq_msg_set.adoc[zmq_msg_set] +xref:zmq_msg_init.adoc[zmq_msg_init] +xref:zmq_msg_close.adoc[zmq_msg_close] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_msg_move.txt b/doc/zmq_msg_move.adoc similarity index 70% rename from doc/zmq_msg_move.txt rename to doc/zmq_msg_move.adoc index ed28c168..e17b61a0 100644 --- a/doc/zmq_msg_move.txt +++ b/doc/zmq_msg_move.adoc @@ -1,19 +1,15 @@ -zmq_msg_move(3) -=============== += zmq_msg_move(3) -NAME ----- +== NAME zmq_msg_move - move content of a message to another message -SYNOPSIS --------- +== SYNOPSIS *int zmq_msg_move (zmq_msg_t '*dest', zmq_msg_t '*src');* -DESCRIPTION ------------ +== 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 @@ -24,30 +20,26 @@ CAUTION: Never access 'zmq_msg_t' members directly, instead always use the _zmq_msg_ family of functions. -RETURN VALUE ------------- +== 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 ------- +== ERRORS *EFAULT*:: Invalid message. -SEE ALSO --------- -linkzmq:zmq_msg_copy[3] -linkzmq:zmq_msg_init[3] -linkzmq:zmq_msg_init_size[3] -linkzmq:zmq_msg_init_buffer[3] -linkzmq:zmq_msg_init_data[3] -linkzmq:zmq_msg_close[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_msg_copy.adoc[zmq_msg_copy] +xref:zmq_msg_init.adoc[zmq_msg_init] +xref:zmq_msg_init_size.adoc[zmq_msg_init_size] +xref:zmq_msg_init_buffer.adoc[zmq_msg_init_buffer] +xref:zmq_msg_init_data.adoc[zmq_msg_init_data] +xref:zmq_msg_close.adoc[zmq_msg_close] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_msg_recv.txt b/doc/zmq_msg_recv.adoc similarity index 82% rename from doc/zmq_msg_recv.txt rename to doc/zmq_msg_recv.adoc index 436011f8..301b2cf2 100644 --- a/doc/zmq_msg_recv.txt +++ b/doc/zmq_msg_recv.adoc @@ -1,20 +1,16 @@ -zmq_msg_recv(3) -=============== += zmq_msg_recv(3) -NAME ----- +== NAME zmq_msg_recv - receive a message part from a socket -SYNOPSIS --------- +== SYNOPSIS *int zmq_msg_recv (zmq_msg_t '*msg', void '*socket', int 'flags');* -DESCRIPTION ------------ -The _zmq_msg_recv()_ function is identical to linkzmq:zmq_recvmsg[3], which +== DESCRIPTION +The _zmq_msg_recv()_ function is identical to xref:zmq_recvmsg.adoc[zmq_recvmsg], which shall be deprecated in future versions. _zmq_msg_recv()_ is more consistent with other message manipulation functions. @@ -40,21 +36,19 @@ 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 +xref:zmq_getsockopt.adoc[zmq_getsockopt] option after calling _zmq_msg_recv()_ to determine if there are further parts to receive. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_msg_recv()_ function shall return number of bytes in the message if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EAGAIN*:: -Either the timeout set via the socket-option ZMQ_RCVTIMEO (see linkzmq:zmq_setsockopt[3]) +Either the timeout set via the socket-option ZMQ_RCVTIMEO (see xref:zmq_setsockopt.adoc[zmq_setsockopt]) has been reached (flag ZMQ_DONTWAIT not set) without being able to read a message from the socket or there are no messages available at the moment (flag ZMQ_DONTWAIT set) and the operation would block. @@ -64,7 +58,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 xref:zmq_socket.adoc[zmq_socket] for more information. *ETERM*:: The 0MQ 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: @@ -76,8 +70,7 @@ available. The message passed to the function was invalid. -EXAMPLE -------- +== EXAMPLE .Receiving a message from a socket ---- /* Create an empty 0MQ message */ @@ -111,18 +104,16 @@ do { ---- -SEE ALSO --------- -linkzmq:zmq_recv[3] -linkzmq:zmq_send[3] -linkzmq:zmq_msg_send[3] -linkzmq:zmq_getsockopt[3] -linkzmq:zmq_setsockopt[3] -linkzmq:zmq_socket[7] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_recv.adoc[zmq_recv] +xref:zmq_send.adoc[zmq_send] +xref:zmq_msg_send.adoc[zmq_msg_send] +xref:zmq_getsockopt.adoc[zmq_getsockopt] +xref:zmq_setsockopt.adoc[zmq_setsockopt] +xref:zmq_socket.adoc[zmq_socket] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_msg_routing_id.txt b/doc/zmq_msg_routing_id.adoc similarity index 85% rename from doc/zmq_msg_routing_id.txt rename to doc/zmq_msg_routing_id.adoc index 47f05a29..373e72a4 100644 --- a/doc/zmq_msg_routing_id.txt +++ b/doc/zmq_msg_routing_id.adoc @@ -1,33 +1,27 @@ -zmq_msg_routing_id(3) -===================== += zmq_msg_routing_id(3) -NAME ----- +== NAME zmq_msg_routing_id - return routing ID for message, if any -SYNOPSIS --------- +== SYNOPSIS *uint32_t zmq_msg_routing_id (zmq_msg_t '*message');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_msg_routing_id()_ function returns the routing ID for the message, if any. The routing ID is set on all messages received from a 'ZMQ_SERVER' socket. To send a message to a 'ZMQ_SERVER' socket you must set the routing ID of a connected 'ZMQ_CLIENT' peer. Routing IDs are transient. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_msg_routing_id()_ function shall return zero if there is no routing ID, otherwise it shall return an unsigned 32-bit integer greater than zero. -EXAMPLE -------- +== EXAMPLE .Receiving a client message and routing ID ---- void *ctx = zmq_ctx_new (); @@ -50,12 +44,10 @@ assert (routing_id); ---- -SEE ALSO --------- -linkzmq:zmq_msg_set_routing_id[3] +== SEE ALSO +xref:zmq_msg_set_routing_id.adoc[zmq_msg_set_routing_id] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_msg_send.txt b/doc/zmq_msg_send.adoc similarity index 90% rename from doc/zmq_msg_send.txt rename to doc/zmq_msg_send.adoc index 672a1687..77864057 100644 --- a/doc/zmq_msg_send.txt +++ b/doc/zmq_msg_send.adoc @@ -1,20 +1,16 @@ -zmq_msg_send(3) -=============== += zmq_msg_send(3) -NAME ----- +== NAME zmq_msg_send - send a message part on a socket -SYNOPSIS --------- +== SYNOPSIS *int zmq_msg_send (zmq_msg_t '*msg', void '*socket', int 'flags');* -DESCRIPTION ------------ -The _zmq_msg_send()_ function is identical to linkzmq:zmq_sendmsg[3], which +== DESCRIPTION +The _zmq_msg_send()_ function is identical to xref:zmq_sendmsg.adoc[zmq_sendmsg], which shall be deprecated in future versions. _zmq_msg_send()_ is more consistent with other message manipulation functions. @@ -58,16 +54,14 @@ by available memory. An application that sends multi-part messages must use the _ZMQ_SNDMORE_ flag when sending each message part except the final one. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_msg_send()_ function shall return number of bytes in the message if successful (if number of bytes is higher than 'MAX_INT', the function will return 'MAX_INT'). Otherwise it shall return `-1` and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EAGAIN*:: Non-blocking mode was requested and the message cannot be sent at the moment. *ENOTSUP*:: @@ -78,7 +72,7 @@ The sender tried to send multipart data, which the socket type does not allow. 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 xref:zmq_socket.adoc[zmq_socket] for more information. *ETERM*:: The 0MQ 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: @@ -92,8 +86,7 @@ Invalid message. The message cannot be routed. -EXAMPLE -------- +== EXAMPLE .Filling in a message and sending it to a socket ---- /* Create a new message, allocating 6 bytes for message content */ @@ -117,16 +110,14 @@ 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] +== SEE ALSO +xref:zmq_recv.adoc[zmq_recv] +xref:zmq_send.adoc[zmq_send] +xref:zmq_msg_recv.adoc[zmq_msg_recv] +xref:zmq_socket.adoc[zmq_socket] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_msg_set.txt b/doc/zmq_msg_set.adoc similarity index 79% rename from doc/zmq_msg_set.txt rename to doc/zmq_msg_set.adoc index 6784478e..d7d67907 100644 --- a/doc/zmq_msg_set.txt +++ b/doc/zmq_msg_set.adoc @@ -1,20 +1,16 @@ -zmq_msg_set(3) -============== += zmq_msg_set(3) -NAME ----- +== NAME zmq_msg_set - set message property -SYNOPSIS --------- +== SYNOPSIS *int zmq_msg_set (zmq_msg_t '*message', int 'property', int 'value');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_msg_set()_ function shall set the property specified by the 'property' argument to the value of the 'value' argument for the 0MQ message fragment pointed to by the 'message' argument. @@ -22,25 +18,21 @@ message fragment pointed to by the 'message' argument. Currently the _zmq_msg_set()_ function does not support any property names. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_msg_set()_ function shall return zero if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EINVAL*:: The requested property _property_ is unknown. -SEE ALSO --------- -linkzmq:zmq_msg_get[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_msg_get.adoc[zmq_msg_get] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_msg_set_routing_id.txt b/doc/zmq_msg_set_routing_id.adoc similarity index 78% rename from doc/zmq_msg_set_routing_id.txt rename to doc/zmq_msg_set_routing_id.adoc index b0f2c3a7..8d08acaa 100644 --- a/doc/zmq_msg_set_routing_id.txt +++ b/doc/zmq_msg_set_routing_id.adoc @@ -1,20 +1,16 @@ -zmq_msg_set_routing_id(3) -========================= += zmq_msg_set_routing_id(3) -NAME ----- +== NAME zmq_msg_set_routing_id - set routing ID property on message -SYNOPSIS --------- +== SYNOPSIS *int zmq_msg_set_routing_id (zmq_msg_t '*message', uint32_t 'routing_id');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_msg_set_routing_id()_ function sets the 'routing_id' specified, on the the message pointed to by the 'message' argument. The 'routing_id' must be greater than zero. To get a valid routing ID, you must receive a message @@ -22,25 +18,21 @@ from a 'ZMQ_SERVER' socket, and use the libzmq:zmq_msg_routing_id method. Routing IDs are transient. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_msg_set_routing_id()_ function shall return zero if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EINVAL*:: The provided 'routing_id' is zero. -SEE ALSO --------- -linkzmq:zmq_msg_routing_id[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_msg_routing_id.adoc[zmq_msg_routing_id] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_msg_size.txt b/doc/zmq_msg_size.adoc similarity index 61% rename from doc/zmq_msg_size.txt rename to doc/zmq_msg_size.adoc index bcf898e3..0c72e911 100644 --- a/doc/zmq_msg_size.txt +++ b/doc/zmq_msg_size.adoc @@ -1,19 +1,15 @@ -zmq_msg_size(3) -=============== += zmq_msg_size(3) -NAME ----- +== NAME zmq_msg_size - retrieve message content size in bytes -SYNOPSIS --------- +== SYNOPSIS *size_t zmq_msg_size (zmq_msg_t '*msg');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_msg_size()_ function shall return the size in bytes of the content of the message object referenced by 'msg'. @@ -21,29 +17,25 @@ CAUTION: Never access 'zmq_msg_t' members directly, instead always use the _zmq_msg_ family of functions. -RETURN VALUE ------------- +== RETURN VALUE Upon successful completion, _zmq_msg_size()_ shall return the size of the message content in bytes. -ERRORS ------- +== ERRORS 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_buffer[3] -linkzmq:zmq_msg_init_data[3] -linkzmq:zmq_msg_close[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_msg_data.adoc[zmq_msg_data] +xref:zmq_msg_init.adoc[zmq_msg_init] +xref:zmq_msg_init_size.adoc[zmq_msg_init_size] +xref:zmq_msg_init_buffer.adoc[zmq_msg_init_buffer] +xref:zmq_msg_init_data.adoc[zmq_msg_init_data] +xref:zmq_msg_close.adoc[zmq_msg_close] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_null.txt b/doc/zmq_null.adoc similarity index 71% rename from doc/zmq_null.txt rename to doc/zmq_null.adoc index abb9fff8..1fea9d5f 100644 --- a/doc/zmq_null.txt +++ b/doc/zmq_null.adoc @@ -1,27 +1,22 @@ -zmq_null(7) -=========== += zmq_null(7) -NAME ----- +== NAME zmq_null - no security or confidentiality -SYNOPSIS --------- +== SYNOPSIS The NULL mechanism is defined by the ZMTP 3.0 specification: . This is the default security mechanism for ZeroMQ sockets. -SEE ALSO --------- -linkzmq:zmq_plain[7] -linkzmq:zmq_curve[7] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_plain.adoc[zmq_plain] +xref:zmq_curve.adoc[zmq_curve] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_pgm.txt b/doc/zmq_pgm.adoc similarity index 92% rename from doc/zmq_pgm.txt rename to doc/zmq_pgm.adoc index 4233af4a..f439585d 100644 --- a/doc/zmq_pgm.txt +++ b/doc/zmq_pgm.adoc @@ -1,20 +1,16 @@ -zmq_pgm(7) -========== += zmq_pgm(7) -NAME ----- +== NAME zmq_pgm - 0MQ reliable multicast transport using PGM -SYNOPSIS --------- +== SYNOPSIS PGM (Pragmatic General Multicast) is a protocol for reliable multicast transport of data over IP networks. -DESCRIPTION ------------ +== 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 @@ -25,7 +21,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]. +xref:zmq_setsockopt.adoc[zmq_setsockopt] CAUTION: The 'pgm' transport implementation requires access to raw IP sockets. Additional privileges may be required on some operating systems for this @@ -34,8 +30,7 @@ implementations are encouraged to use the 'epgm' transport instead which does not require any special privileges. -ADDRESSING ----------- +== 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. @@ -67,13 +62,12 @@ A 'multicast address' is specified by an IPv4 multicast address in its numeric representation. -WIRE FORMAT ------------ +== 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 -linkzmq:zmq_tcp[7]. +xref:zmq_tcp.adoc[zmq_tcp] PGM datagram payload @@ -130,12 +124,11 @@ Third datagram payload .... -CONFIGURATION -------------- +== CONFIGURATION The PGM is protocol is capable of multicasting data at high rates (500Mbps+) with large messages (1MB+), however it requires setting the relevant ZMQ socket -options that are documented in linkzmq:zmq_setsockopt[3]: +options that are documented in xref:zmq_setsockopt.adoc[zmq_setsockopt]: * The 'ZMQ_RATE' should be set sufficiently high, e.g. 1Gbps * The 'ZMQ_RCVBUF' should be increased on the subscriber, e.g. 4MB @@ -154,8 +147,7 @@ sudo sysctl -w net.core.wmem_default=4194304 .... -EXAMPLE -------- +== EXAMPLE .Connecting a socket ---- // Connecting to the multicast address 239.192.1.1, port 5555, @@ -171,18 +163,16 @@ 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_vmci[7] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_connect.adoc[zmq_connect] +xref:zmq_setsockopt.adoc[zmq_setsockopt] +xref:zmq_tcp.adoc[zmq_tcp] +xref:zmq_ipc.adoc[zmq_ipc] +xref:zmq_inproc.adoc[zmq_inproc] +xref:zmq_vmci.adoc[zmq_vmci] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_plain.txt b/doc/zmq_plain.adoc similarity index 79% rename from doc/zmq_plain.txt rename to doc/zmq_plain.adoc index 7dd40dc8..5d8062e2 100644 --- a/doc/zmq_plain.txt +++ b/doc/zmq_plain.adoc @@ -1,14 +1,11 @@ -zmq_plain(7) -============ += zmq_plain(7) -NAME ----- +== NAME zmq_plain - clear-text authentication -SYNOPSIS --------- +== SYNOPSIS The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality. It is intended for use on internal networks where @@ -16,22 +13,19 @@ security requirements are low. The PLAIN mechanism is defined by this document: . -USAGE ------ +== USAGE To use PLAIN, the server shall set the ZMQ_PLAIN_SERVER option, and the client shall set the ZMQ_PLAIN_USERNAME and ZMQ_PLAIN_PASSWORD socket options. Which peer binds, and which connects, is not relevant. -SEE ALSO --------- -linkzmq:zmq_setsockopt[3] -linkzmq:zmq_null[7] -linkzmq:zmq_curve[7] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_setsockopt.adoc[zmq_setsockopt] +xref:zmq_null.adoc[zmq_null] +xref:zmq_curve.adoc[zmq_curve] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_poll.txt b/doc/zmq_poll.adoc similarity index 94% rename from doc/zmq_poll.txt rename to doc/zmq_poll.adoc index ec2e3279..4f8d3ac1 100644 --- a/doc/zmq_poll.txt +++ b/doc/zmq_poll.adoc @@ -1,20 +1,16 @@ -zmq_poll(3) -=========== += zmq_poll(3) -NAME ----- +== NAME zmq_poll - input/output multiplexing -SYNOPSIS --------- +== SYNOPSIS *int zmq_poll (zmq_pollitem_t '*items', int 'nitems', long 'timeout');* -DESCRIPTION ------------ +== 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* @@ -80,8 +76,7 @@ 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. -THREAD SAFETY -------------- +== THREAD SAFETY The *zmq_pollitem_t* array must only be used by the thread which will/is calling _zmq_poll_. @@ -90,16 +85,14 @@ different thread, the socket itself needs to be thread-safe (Server, Client, ... Otherwise, behaviour is undefined. -RETURN VALUE ------------- +== 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 ------- +== ERRORS *ETERM*:: At least one of the members of the 'items' array refers to a 'socket' whose associated 0MQ 'context' was terminated. @@ -110,8 +103,7 @@ The operation was interrupted by delivery of a signal before any events were available. -EXAMPLE -------- +== EXAMPLE .Polling indefinitely for input events on both a 0MQ socket and a standard socket. ---- zmq_pollitem_t items [2]; @@ -129,17 +121,15 @@ assert (rc >= 0); ---- -SEE ALSO --------- -linkzmq:zmq_socket[3] -linkzmq:zmq_send[3] -linkzmq:zmq_recv[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_socket.adoc[zmq_socket] +xref:zmq_send.adoc[zmq_send] +xref:zmq_recv.adoc[zmq_recv] +xref:zmq.adoc[zmq] Your operating system documentation for the _poll()_ system call. -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_poller.txt b/doc/zmq_poller.adoc similarity index 97% rename from doc/zmq_poller.txt rename to doc/zmq_poller.adoc index 89f43516..c0117eb8 100644 --- a/doc/zmq_poller.txt +++ b/doc/zmq_poller.adoc @@ -1,14 +1,11 @@ -zmq_poller(3) -=========== += zmq_poller(3) -NAME ----- +== NAME zmq_poller - input/output multiplexing -SYNOPSIS --------- +== SYNOPSIS *void *zmq_poller_new (void);* @@ -39,8 +36,7 @@ SYNOPSIS *int zmq_poller_fd (void '*poller', zmq_fd_t '*fd');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_poller_*_ functions provide a mechanism for applications to multiplex input/output events in a level-triggered fashion over a set of sockets. @@ -153,8 +149,7 @@ at least one thread-safe socket is currently registered. Note that closing a socket that is registered in a poller leads to undefined behavior. The socket must be unregistered first. -EVENT TYPES ------------ +== EVENT TYPES The 'events' parameter of _zmq_poller_add_ and _zmq_poller_modify_, and the 'events' member of the zmq_poller_event_t structure are bit masks constructed @@ -194,8 +189,7 @@ NOTE: The _zmq_poller_*_ functions may be implemented or emulated using operatin system interfaces other than _poll()_, and as such may be subject to the limits of those interfaces in ways not defined in this documentation. -THREAD SAFETY -------------- +== THREAD SAFETY Like most other 0MQ objects, a poller is not thread-safe. All operations must be called from the same thread. Otherwise, behaviour is undefined. @@ -203,8 +197,7 @@ In addition to that, if you want to add a socket to multiple existing poller instances, the socket itself needs to be thread-safe (Server, Client, ...). Otherwise, behaviour is undefined. -RETURN VALUE ------------- +== RETURN VALUE _zmq_poller_new_ returns a valid pointer to a poller, or NULL in case of a failure. All functions that return an int, return -1 in case of a failure. In that case, @@ -215,8 +208,7 @@ the events array. It never returns 0. All other functions return 0 in case of a successful execution. -ERRORS ------- +== ERRORS On _zmq_poller_new_: *ENOMEM*:: @@ -293,8 +285,7 @@ The poller has no associated file descriptor. *EFAULT*:: The provided 'poller' did not point to a valid poller. -EXAMPLE -------- +== EXAMPLE .Polling indefinitely for input events on both a 0MQ socket and a standard socket. ---- void *poller = zmq_poller_new (); @@ -320,15 +311,13 @@ zmq_poller_destroy (&poller); ---- -SEE ALSO --------- -linkzmq:zmq_socket[3] -linkzmq:zmq_send[3] -linkzmq:zmq_recv[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_socket.adoc[zmq_socket] +xref:zmq_send.adoc[zmq_send] +xref:zmq_recv.adoc[zmq_recv] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_ppoll.txt b/doc/zmq_ppoll.adoc similarity index 91% rename from doc/zmq_ppoll.txt rename to doc/zmq_ppoll.adoc index 9f9a93fb..4e2f628d 100644 --- a/doc/zmq_ppoll.txt +++ b/doc/zmq_ppoll.adoc @@ -1,27 +1,23 @@ -zmq_poll(3) -=========== += zmq_poll(3) -NAME ----- +== NAME zmq_ppoll - input/output multiplexing with signal mask -SYNOPSIS --------- +== SYNOPSIS *int zmq_ppoll (zmq_pollitem_t '*items', int 'nitems', long 'timeout', const sigset_t '*sigmask');* -DESCRIPTION ------------ +== DESCRIPTION The relationship between _zmq_poll()_ and _zmq_ppoll()_ is analogous to the relationship between poll(2) and ppoll(2) and between select(2) and pselect(2): _zmq_ppoll()_ allows an application to safely wait until either a file descriptor becomes ready or until a signal is caught. When using _zmq_ppoll()_ with 'sigmask' set to NULL, its behavior is identical -to that of _zmq_poll()_. See linkzmq:zmq_poll[3] for more on this. +to that of _zmq_poll()_. See xref:zmq_poll.adoc[zmq_poll] for more on this. To make full use of _zmq_ppoll()_, a non-NULL pointer to a signal mask must be constructed and passed to 'sigmask'. See sigprocmask(2) for more details. When @@ -49,8 +45,7 @@ supported in Windows builds. It is still callable, but its 'sigmask' has void pointer type (because 'sigset_t' is also not available on Windows) and _zmq_ppoll()_ will return with an error (see error section below). -THREAD SAFETY -------------- +== THREAD SAFETY The *zmq_pollitem_t* array must only be used by the thread which will/is calling _zmq_ppoll_. @@ -59,16 +54,14 @@ different thread, the socket itself needs to be thead-safe (Server, Client, ...) Otherwise, behaviour is undefined. -RETURN VALUE ------------- +== RETURN VALUE Upon successful completion, the _zmq_ppoll()_ 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_ppoll()_ shall return `-1` and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *ETERM*:: At least one of the members of the 'items' array refers to a 'socket' whose associated 0MQ 'context' was terminated. @@ -84,10 +77,9 @@ available. _zmq_ppoll()_ was not activated in this build. -EXAMPLE -------- +== EXAMPLE .Polling indefinitely for input events on both a 0MQ socket and a standard socket. -See the _example section_ of linkzmq:zmq_poll[3]. One only needs to replace +See the _example section_ of xref:zmq_poll.adoc[zmq_poll] One only needs to replace the _zmq_poll_ call with _zmq_ppoll_ and add a _NULL_ argument for the 'sigmask' parameter. @@ -123,18 +115,16 @@ if (rc < 0 && errno == EINTR && sigterm_received) { ---- -SEE ALSO --------- -linkzmq:zmq_poll[3] -linkzmq:zmq_socket[3] -linkzmq:zmq_send[3] -linkzmq:zmq_recv[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_poll.adoc[zmq_poll] +xref:zmq_socket.adoc[zmq_socket] +xref:zmq_send.adoc[zmq_send] +xref:zmq_recv.adoc[zmq_recv] +xref:zmq.adoc[zmq] Your operating system documentation for the _poll()_ system call. -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_proxy.txt b/doc/zmq_proxy.adoc similarity index 89% rename from doc/zmq_proxy.txt rename to doc/zmq_proxy.adoc index c11977ed..f3d07123 100644 --- a/doc/zmq_proxy.txt +++ b/doc/zmq_proxy.adoc @@ -1,18 +1,14 @@ -zmq_proxy(3) -============ += zmq_proxy(3) -NAME ----- +== NAME zmq_proxy - start built-in 0MQ proxy -SYNOPSIS --------- +== SYNOPSIS *int zmq_proxy (void '*frontend', void '*backend', void '*capture');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_proxy()_ function starts the built-in 0MQ proxy in the current application thread. @@ -31,10 +27,9 @@ 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 xref:zmq_socket.adoc[zmq_socket] for a description of the available socket types. -EXAMPLE USAGE -------------- +== EXAMPLE USAGE Shared Queue ~~~~~~~~~~~~ @@ -61,15 +56,13 @@ When the frontend is a ZMQ_PULL socket, and the backend is a ZMQ_PUSH socket, the proxy shall collect tasks from a set of clients and forwards these to a set of workers using the pipeline pattern. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_proxy()_ function always returns `-1` and 'errno' set to *ETERM* or *EINTR* (the 0MQ 'context' associated with either of the specified sockets was terminated) or *EFAULT* (the provided 'frontend' or 'backend' was invalid). -EXAMPLE -------- +== EXAMPLE .Creating a shared queue proxy ---- // Create frontend and backend sockets @@ -85,15 +78,13 @@ zmq_proxy (frontend, backend, NULL); ---- -SEE ALSO --------- -linkzmq:zmq_bind[3] -linkzmq:zmq_connect[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_bind.adoc[zmq_bind] +xref:zmq_connect.adoc[zmq_connect] +xref:zmq_socket.adoc[zmq_socket] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_proxy_steerable.txt b/doc/zmq_proxy_steerable.adoc similarity index 92% rename from doc/zmq_proxy_steerable.txt rename to doc/zmq_proxy_steerable.adoc index 23081fa9..5e08d1d3 100644 --- a/doc/zmq_proxy_steerable.txt +++ b/doc/zmq_proxy_steerable.adoc @@ -1,19 +1,15 @@ -zmq_proxy_steerable(3) -====================== += zmq_proxy_steerable(3) -NAME ----- +== NAME zmq_proxy_steerable - built-in 0MQ proxy with control flow -SYNOPSIS --------- +== SYNOPSIS *int zmq_proxy_steerable (const void '*frontend', const void '*backend', const void '*capture', const void '*control');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_proxy_steerable()_ function is a variant of the _zmq_proxy()_ function. It accepts a fourth _control_ socket. When the _control_ socket is _NULL_ the @@ -57,16 +53,14 @@ message reply to the _STATISTICS_ command. These are: Message totals count each part in a multipart message individually. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_proxy_steerable()_ function returns 0 if TERMINATE is received on its control socket. Otherwise, it returns -1 and errno set to ETERM or EINTR (the 0MQ context associated with either of the specified sockets was terminated) or EFAULT (the provided frontend or backend was invalid). -EXAMPLE -------- +== EXAMPLE .Create a function to run the proxy ---- // Create the frontend and backend sockets to be proxied @@ -114,16 +108,14 @@ zmq_close(control); ---- -SEE ALSO --------- -linkzmq:zmq_proxy[3] -linkzmq:zmq_bind[3] -linkzmq:zmq_connect[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_proxy.adoc[zmq_proxy] +xref:zmq_bind.adoc[zmq_bind] +xref:zmq_connect.adoc[zmq_connect] +xref:zmq_socket.adoc[zmq_socket] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_recv.txt b/doc/zmq_recv.adoc similarity index 82% rename from doc/zmq_recv.txt rename to doc/zmq_recv.adoc index 03468c1c..b2af9fd9 100644 --- a/doc/zmq_recv.txt +++ b/doc/zmq_recv.adoc @@ -1,19 +1,15 @@ -zmq_recv(3) -=========== += zmq_recv(3) -NAME ----- +== NAME zmq_recv - receive a message part from a socket -SYNOPSIS --------- +== SYNOPSIS *int zmq_recv (void '*socket', void '*buf', size_t 'len', int 'flags');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_recv()_ function shall receive a message from the socket referenced by the 'socket' argument and store it in the buffer referenced by the 'buf' argument. Any bytes exceeding the length specified by the 'len' argument shall @@ -36,21 +32,19 @@ 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 +xref:zmq_getsockopt.adoc[zmq_getsockopt] option after calling _zmq_recv()_ to determine if there are further parts to receive. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_recv()_ function shall return number of bytes in the message if successful. Note that the value can exceed the value of the 'len' parameter in case the message was truncated. If not successful the function shall return `-1` and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EAGAIN*:: -Either the timeout set via the socket-option ZMQ_RCVTIMEO (see linkzmq:zmq_setsockopt[3]) +Either the timeout set via the socket-option ZMQ_RCVTIMEO (see xref:zmq_setsockopt.adoc[zmq_setsockopt]) has been reached (flag ZMQ_DONTWAIT not set) without being able to read a message from the socket or there are no messages available at the moment (flag ZMQ_DONTWAIT set) and the operation would block. @@ -60,7 +54,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 xref:zmq_socket.adoc[zmq_socket] for more information. *ETERM*:: The 0MQ 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: @@ -70,8 +64,7 @@ The operation was interrupted by delivery of a signal before a message was available. -EXAMPLE -------- +== EXAMPLE .Receiving a message from a socket ---- char buf [256]; @@ -80,16 +73,14 @@ assert (nbytes != -1); ---- -SEE ALSO --------- -linkzmq:zmq_send[3] -linkzmq:zmq_getsockopt[3] -linkzmq:zmq_setsockopt[3] -linkzmq:zmq_socket[7] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_send.adoc[zmq_send] +xref:zmq_getsockopt.adoc[zmq_getsockopt] +xref:zmq_setsockopt.adoc[zmq_setsockopt] +xref:zmq_socket.adoc[zmq_socket] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_recvmsg.txt b/doc/zmq_recvmsg.adoc similarity index 84% rename from doc/zmq_recvmsg.txt rename to doc/zmq_recvmsg.adoc index adf2d4a9..91f6653f 100644 --- a/doc/zmq_recvmsg.txt +++ b/doc/zmq_recvmsg.adoc @@ -1,19 +1,15 @@ -zmq_recvmsg(3) -============== += zmq_recvmsg(3) -NAME ----- +== NAME zmq_recvmsg - receive a message part from a socket -SYNOPSIS --------- +== SYNOPSIS *int zmq_recvmsg (void '*socket', zmq_msg_t '*msg', int 'flags');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_recvmsg()_ function shall receive a message part 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 @@ -38,21 +34,19 @@ 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 +xref:zmq_getsockopt.adoc[zmq_getsockopt] option after calling _zmq_recvmsg()_ to determine if there are further parts to receive. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_recvmsg()_ function shall return number of bytes in the message if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EAGAIN*:: -Either the timeout set via the socket-option ZMQ_RCVTIMEO (see linkzmq:zmq_setsockopt[3]) +Either the timeout set via the socket-option ZMQ_RCVTIMEO (see xref:zmq_setsockopt.adoc[zmq_setsockopt]) has been reached (flag ZMQ_DONTWAIT not set) without being able to read a message from the socket or there are no messages available at the moment (flag ZMQ_DONTWAIT set) and the operation would block. @@ -62,7 +56,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 xref:zmq_socket.adoc[zmq_socket] for more information. *ETERM*:: The 0MQ 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: @@ -74,8 +68,7 @@ available. The message passed to the function was invalid. -EXAMPLE -------- +== EXAMPLE .Receiving a message from a socket ---- /* Create an empty 0MQ message */ @@ -109,17 +102,15 @@ do { ---- -SEE ALSO --------- -linkzmq:zmq_recv[3] -linkzmq:zmq_send[3] -linkzmq:zmq_getsockopt[3] -linkzmq:zmq_setsockopt[3] -linkzmq:zmq_socket[7] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_recv.adoc[zmq_recv] +xref:zmq_send.adoc[zmq_send] +xref:zmq_getsockopt.adoc[zmq_getsockopt] +xref:zmq_setsockopt.adoc[zmq_setsockopt] +xref:zmq_socket.adoc[zmq_socket] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_send.txt b/doc/zmq_send.adoc similarity index 90% rename from doc/zmq_send.txt rename to doc/zmq_send.adoc index 1d84063f..ada7fa45 100644 --- a/doc/zmq_send.txt +++ b/doc/zmq_send.adoc @@ -1,19 +1,15 @@ -zmq_send(3) -=========== += zmq_send(3) -NAME ----- +== NAME zmq_send - send a message part on a socket -SYNOPSIS --------- +== SYNOPSIS *int zmq_send (void '*socket', const void '*buf', size_t 'len', int 'flags');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_send()_ function shall queue a message created from the buffer referenced by the 'buf' and 'len' arguments. The 'flags' argument is a combination of the flags defined below: @@ -46,15 +42,13 @@ An application that sends multi-part messages must use the _ZMQ_SNDMORE_ flag when sending each message part except the final one. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_send()_ function shall return number of bytes in the message if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EAGAIN*:: Non-blocking mode was requested and the message cannot be sent at the moment. *ENOTSUP*:: @@ -65,7 +59,7 @@ The sender tried to send multipart data, which the socket type does not allow. 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 xref:zmq_socket.adoc[zmq_socket] for more information. *ETERM*:: The 0MQ 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: @@ -77,8 +71,7 @@ sent. The message cannot be routed. -EXAMPLE -------- +== EXAMPLE .Sending a multi-part message ---- /* Send a multi-part message consisting of three parts to socket */ @@ -91,15 +84,13 @@ rc = zmq_send (socket, "JK", 2, 0); assert (rc == 2); ---- -SEE ALSO --------- -linkzmq:zmq_send_const[3] -linkzmq:zmq_recv[3] -linkzmq:zmq_socket[7] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_send_const.adoc[zmq_send_const] +xref:zmq_recv.adoc[zmq_recv] +xref:zmq_socket.adoc[zmq_socket] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_send_const.txt b/doc/zmq_send_const.adoc similarity index 90% rename from doc/zmq_send_const.txt rename to doc/zmq_send_const.adoc index 2a6efa2e..4dd03966 100644 --- a/doc/zmq_send_const.txt +++ b/doc/zmq_send_const.adoc @@ -1,19 +1,15 @@ -zmq_send_const(3) -================= += zmq_send_const(3) -NAME ----- +== NAME zmq_send_const - send a constant-memory message part on a socket -SYNOPSIS --------- +== SYNOPSIS *int zmq_send_const (void '*socket', const void '*buf', size_t 'len', int 'flags');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_send_const()_ function shall queue a message created from the buffer referenced by the 'buf' and 'len' arguments. The message buffer is assumed to be constant-memory and will therefore not be copied or deallocated @@ -47,15 +43,13 @@ An application that sends multi-part messages must use the _ZMQ_SNDMORE_ flag when sending each message part except the final one. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_send_const()_ function shall return number of bytes in the message if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EAGAIN*:: Non-blocking mode was requested and the message cannot be sent at the moment. *ENOTSUP*:: @@ -64,7 +58,7 @@ The _zmq_send_const()_ operation is not supported by this socket type. The _zmq_send_const()_ 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 xref:zmq_socket.adoc[zmq_socket] for more information. *ETERM*:: The 0MQ 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: @@ -76,8 +70,7 @@ sent. The message cannot be routed. -EXAMPLE -------- +== EXAMPLE .Sending a multi-part message ---- /* Send a multi-part message consisting of three parts to socket */ @@ -90,15 +83,13 @@ rc = zmq_send_const (socket, "JK", 2, 0); assert (rc == 2); ---- -SEE ALSO --------- -linkzmq:zmq_send[3] -linkzmq:zmq_recv[3] -linkzmq:zmq_socket[7] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_send.adoc[zmq_send] +xref:zmq_recv.adoc[zmq_recv] +xref:zmq_socket.adoc[zmq_socket] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_sendmsg.txt b/doc/zmq_sendmsg.adoc similarity index 92% rename from doc/zmq_sendmsg.txt rename to doc/zmq_sendmsg.adoc index 52652464..b8045dfd 100644 --- a/doc/zmq_sendmsg.txt +++ b/doc/zmq_sendmsg.adoc @@ -1,19 +1,15 @@ -zmq_sendmsg(3) -============== += zmq_sendmsg(3) -NAME ----- +== NAME zmq_sendmsg - send a message part on a socket -SYNOPSIS --------- +== SYNOPSIS *int zmq_sendmsg (void '*socket', zmq_msg_t '*msg', int 'flags');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_sendmsg()_ 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: @@ -51,15 +47,13 @@ by available memory. An application that sends multi-part messages must use the _ZMQ_SNDMORE_ flag when sending each message part except the final one. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_sendmsg()_ function shall return number of bytes in the message if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EAGAIN*:: Non-blocking mode was requested and the message cannot be sent at the moment. *ENOTSUP*:: @@ -70,7 +64,7 @@ The sender tried to send multipart data, which the socket type does not allow. 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 xref:zmq_socket.adoc[zmq_socket] for more information. *ETERM*:: The 0MQ 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: @@ -84,8 +78,7 @@ Invalid message. The message cannot be routed. -EXAMPLE -------- +== EXAMPLE .Filling in a message and sending it to a socket ---- /* Create a new message, allocating 6 bytes for message content */ @@ -109,14 +102,12 @@ rc = zmq_sendmsg (socket, &part3, 0); ---- -SEE ALSO --------- -linkzmq:zmq_recv[3] -linkzmq:zmq_socket[7] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_recv.adoc[zmq_recv] +xref:zmq_socket.adoc[zmq_socket] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.adoc similarity index 96% rename from doc/zmq_setsockopt.txt rename to doc/zmq_setsockopt.adoc index 4d5a712d..bb83fc89 100644 --- a/doc/zmq_setsockopt.txt +++ b/doc/zmq_setsockopt.adoc @@ -1,15 +1,12 @@ -zmq_setsockopt(3) -================= += zmq_setsockopt(3) -NAME ----- +== NAME zmq_setsockopt - set 0MQ socket options -SYNOPSIS --------- +== 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, @@ -21,8 +18,7 @@ subsequent socket bind/connects. Specifically, security options take effect for subsequent bind/connect calls, and can be changed at any time to affect subsequent binds and/or connects. -DESCRIPTION ------------ +== 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 0MQ socket pointed to by the 'socket' argument. The 'option_len' @@ -46,7 +42,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 xref:zmq_init.adoc[zmq_init] for details on allocating the number of I/O threads for a specific _context_. [horizontal] @@ -144,7 +140,7 @@ support multi-part messages, in particular, only one part of it is kept in the socket internal queue. NOTE: If recv is not called on the inbound socket, the queue and memory will -grow with each message received. Use linkzmq:zmq_getsockopt[3] with ZMQ_EVENTS +grow with each message received. Use xref:zmq_getsockopt.adoc[zmq_getsockopt] with ZMQ_EVENTS to trigger the conflation of the messages. [horizontal] @@ -171,12 +167,12 @@ Applicable socket types:: all, when using TCP transports. ZMQ_CURVE_PUBLICKEY: Set CURVE public key ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sets the socket's long term public key. You must set this on CURVE client -sockets, see linkzmq:zmq_curve[7]. You can provide the key as 32 binary +sockets, see xref:zmq_curve.adoc[zmq_curve] You can provide the key as 32 binary bytes, or as a 40-character string encoded in the Z85 encoding format and terminated in a null byte. The public key must always be used with the matching secret key. To generate a public/secret key pair, use -linkzmq:zmq_curve_keypair[3]. To derive the public key from a secret key, -use linkzmq:zmq_curve_public[3]. +xref:zmq_curve_keypair.adoc[zmq_curve_keypair] To derive the public key from a secret key, +use xref:zmq_curve_public.adoc[zmq_curve_public] NOTE: an option value size of 40 is supported for backwards compatibility, though is deprecated. @@ -191,11 +187,11 @@ Applicable socket types:: all, when using TCP transport ZMQ_CURVE_SECRETKEY: Set CURVE secret key ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sets the socket's long term secret key. You must set this on both CURVE -client and server sockets, see linkzmq:zmq_curve[7]. You can provide the +client and server sockets, see xref:zmq_curve.adoc[zmq_curve] You can provide the key as 32 binary bytes, or as a 40-character string encoded in the Z85 encoding format and terminated in a null byte. To generate a public/secret -key pair, use linkzmq:zmq_curve_keypair[3]. To derive the public key from -a secret key, use linkzmq:zmq_curve_public[3]. +key pair, use xref:zmq_curve_keypair.adoc[zmq_curve_keypair] To derive the public key from +a secret key, use xref:zmq_curve_public.adoc[zmq_curve_public] NOTE: an option value size of 40 is supported for backwards compatibility, though is deprecated. @@ -210,7 +206,7 @@ Applicable socket types:: all, when using TCP transport ZMQ_CURVE_SERVER: Set CURVE server role ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Defines whether the socket will act as server for CURVE security, see -linkzmq:zmq_curve[7]. A value of '1' means the socket will act as +xref:zmq_curve.adoc[zmq_curve] A value of '1' means the socket will act as CURVE server. A value of '0' means the socket will not act as CURVE server, and its security role then depends on other option settings. Setting this to '0' shall reset the socket security to NULL. When you @@ -228,11 +224,11 @@ Applicable socket types:: all, when using TCP transport ZMQ_CURVE_SERVERKEY: Set CURVE server key ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sets the socket's long term server key. You must set this on CURVE client -sockets, see linkzmq:zmq_curve[7]. You can provide the key as 32 binary +sockets, see xref:zmq_curve.adoc[zmq_curve] You can provide the key as 32 binary bytes, or as a 40-character string encoded in the Z85 encoding format and terminated in a null byte. This key must have been generated together with the server's secret key. To generate a public/secret key pair, use -linkzmq:zmq_curve_keypair[3]. +xref:zmq_curve_keypair.adoc[zmq_curve_keypair] NOTE: an option value size of 40 is supported for backwards compatibility, though is deprecated. @@ -274,7 +270,7 @@ Applicable socket types:: ZMQ_DEALER, ZMQ_CLIENT and ZMQ_PEER ZMQ_GSSAPI_PLAINTEXT: Disable GSSAPI encryption ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Defines whether communications on the socket will be encrypted, see -linkzmq:zmq_gssapi[7]. A value of '1' means that communications will be +xref:zmq_gssapi.adoc[zmq_gssapi] A value of '1' means that communications will be plaintext. A value of '0' means communications will be encrypted. [horizontal] @@ -298,7 +294,7 @@ Applicable socket types:: all, when using TCP transport ZMQ_GSSAPI_SERVER: Set GSSAPI server role ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Defines whether the socket will act as server for GSSAPI security, see -linkzmq:zmq_gssapi[7]. A value of '1' means the socket will act as GSSAPI +xref:zmq_gssapi.adoc[zmq_gssapi] A value of '1' means the socket will act as GSSAPI server. A value of '0' means the socket will act as GSSAPI client. [horizontal] @@ -486,8 +482,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 disconnected with -linkzmq:zmq_disconnect[3] or closed with linkzmq:zmq_close[3], and further -affects the termination of the socket's context with linkzmq:zmq_ctx_term[3]. +xref:zmq_disconnect.adoc[zmq_disconnect] or closed with xref:zmq_close.adoc[zmq_close], and further +affects the termination of the socket's context with xref:zmq_ctx_term.adoc[zmq_ctx_term] The following outlines the different behaviours: * A value of '-1' specifies an infinite linger period. Pending @@ -532,7 +528,8 @@ followed by the metadata value, for example "X-key:value". _Property_ names are restricted to maximum 255 characters and must be prefixed by "X-". Multiple application metadata properties can be added to a socket by executing zmq_setsockopt() multiple times. As the argument is a null-terminated string, binary data must be encoded -before it is added e.g. using Z85 (linkzmq:zmq_z85_encode[3]). +before it is added e.g. using Z85 (xref:zmq_z85_encode.adoc[zmq_z85_encode]). + NOTE: in DRAFT state, not yet available in stable releases. @@ -575,8 +572,8 @@ ZMQ_PLAIN_PASSWORD: Set PLAIN security password ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be -PLAIN, see linkzmq:zmq_plain[7]. If you set this to a null value, the security -mechanism used for connections shall be NULL, see linkzmq:zmq_null[3]. +PLAIN, see xref:zmq_plain.adoc[zmq_plain] If you set this to a null value, the security +mechanism used for connections shall be NULL, see xref:zmq_null.adoc[zmq_null] [horizontal] Option value type:: character string @@ -588,7 +585,7 @@ Applicable socket types:: all, when using TCP transport ZMQ_PLAIN_SERVER: Set PLAIN server role ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Defines whether the socket will act as server for PLAIN security, see -linkzmq:zmq_plain[7]. A value of '1' means the socket will act as +xref:zmq_plain.adoc[zmq_plain] A value of '1' means the socket will act as PLAIN server. A value of '0' means the socket will not act as PLAIN server, and its security role then depends on other option settings. Setting this to '0' shall reset the socket security to NULL. @@ -604,8 +601,8 @@ ZMQ_PLAIN_USERNAME: Set PLAIN security username ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be -PLAIN, see linkzmq:zmq_plain[7]. If you set this to a null value, the security -mechanism used for connections shall be NULL, see linkzmq:zmq_null[3]. +PLAIN, see xref:zmq_plain.adoc[zmq_plain] If you set this to a null value, the security +mechanism used for connections shall be NULL, see xref:zmq_null.adoc[zmq_null] [horizontal] Option value type:: character string @@ -670,7 +667,7 @@ Applicable socket types:: ZMQ_ROUTER, ZMQ_DEALER, ZMQ_REQ 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 xref:zmq_pgm.adoc[zmq_pgm] using the specified 'socket'. [horizontal] Option value type:: int @@ -704,12 +701,12 @@ limit. 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 xref:zmq_socket.adoc[zmq_socket] for details on the exact action taken for each socket type. NOTE: 0MQ does not guarantee that the socket will be able to queue as many as ZMQ_RCVHWM messages, and the actual limit may be lower or higher, depending on socket transport. -A notable example is for sockets using TCP transport; see linkzmq:zmq_tcp[7]. +A notable example is for sockets using TCP transport; see xref:zmq_tcp.adoc[zmq_tcp] [horizontal] Option value type:: int @@ -956,14 +953,14 @@ limit. 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 xref:zmq_socket.adoc[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 messages, and the actual limit may be as much as 90% lower depending on the flow of messages on the socket. The socket may even be able to accept more messages than the ZMQ_SNDHWM threshold; a notable example is for sockets using TCP transport; -see linkzmq:zmq_tcp[7]. +see xref:zmq_tcp.adoc[zmq_tcp] [horizontal] Option value type:: int @@ -1669,13 +1666,11 @@ Default value:: 0 (false) Applicable socket types:: All, when using NORM transport. -RETURN VALUE ------------- +== 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 ------- +== ERRORS *EINVAL*:: The requested option _option_name_ is unknown, or the requested _option_len_ or _option_value_ is invalid. @@ -1687,8 +1682,7 @@ The provided 'socket' was invalid. The operation was interrupted by delivery of a signal. -EXAMPLE -------- +== EXAMPLE .Subscribing to messages on a 'ZMQ_SUB' socket ---- /* Subscribe to all messages */ @@ -1716,16 +1710,14 @@ assert (rc); ---- -SEE ALSO --------- -linkzmq:zmq_getsockopt[3] -linkzmq:zmq_socket[3] -linkzmq:zmq_plain[7] -linkzmq:zmq_curve[7] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_getsockopt.adoc[zmq_getsockopt] +xref:zmq_socket.adoc[zmq_socket] +xref:zmq_plain.adoc[zmq_plain] +xref:zmq_curve.adoc[zmq_curve] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.adoc similarity index 92% rename from doc/zmq_socket.txt rename to doc/zmq_socket.adoc index dfdbd961..bd0360ee 100644 --- a/doc/zmq_socket.txt +++ b/doc/zmq_socket.adoc @@ -1,19 +1,15 @@ -zmq_socket(3) -============= += zmq_socket(3) -NAME ----- +== NAME zmq_socket - create 0MQ socket -SYNOPSIS --------- +== SYNOPSIS *void *zmq_socket (void '*context', int 'type');* -DESCRIPTION ------------ +== DESCRIPTION The 'zmq_socket()' function shall create a 0MQ 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 @@ -21,9 +17,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 xref:zmq_connect.adoc[zmq_connect], or at least one endpoint must be created for accepting incoming connections with -linkzmq:zmq_bind[3]. +xref:zmq_bind.adoc[zmq_bind] .Key differences to conventional sockets Generally speaking, conventional sockets present a _synchronous_ interface to @@ -84,12 +80,12 @@ A 'ZMQ_CLIENT' socket talks to a 'ZMQ_SERVER' socket. Either peer can connect, though the usual and recommended model is to bind the 'ZMQ_SERVER' and connect the 'ZMQ_CLIENT'. -If the 'ZMQ_CLIENT' socket has established a connection, linkzmq:zmq_send[3] +If the 'ZMQ_CLIENT' socket has established a connection, xref:zmq_send.adoc[zmq_send] will accept messages, queue them, and send them as rapidly as the network allows. The outgoing buffer limit is defined by the high water mark for the socket. If the outgoing buffer is full, or, for connection-oriented transports, if the ZMQ_IMMEDIATE option is set and there is no connected peer, -linkzmq:zmq_send[3] will block. +xref:zmq_send.adoc[zmq_send] will block. The 'ZMQ_CLIENT' socket will not drop messages. When a 'ZMQ_CLIENT' socket is connected to multiple 'ZMQ_SERVER' sockets, @@ -99,7 +95,7 @@ connected peer. This usage is sensible only for stateless protocols. 'ZMQ_CLIENT' sockets are threadsafe and can be used from multiple threads at the same time. Note that replies from a 'ZMQ_SERVER' socket will go to -the first client thread that calls linkzmq:zmq_msg_recv[3]. If you need to get +the first client thread that calls xref:zmq_msg_recv.adoc[zmq_msg_recv] If you need to get replies back to the originating thread, use one 'ZMQ_CLIENT' socket per thread. @@ -125,9 +121,9 @@ socket can only reply to an incoming message: the 'ZMQ_CLIENT' peer must always initiate a conversation. Each received message has a 'routing_id' that is a 32-bit unsigned integer. -The application can fetch this with linkzmq:zmq_msg_routing_id[3]. To send +The application can fetch this with xref:zmq_msg_routing_id.adoc[zmq_msg_routing_id] To send a message to a given 'ZMQ_CLIENT' peer the application must set the peer's -'routing_id' on the message, using linkzmq:zmq_msg_set_routing_id[3]. +'routing_id' on the message, using xref:zmq_msg_set_routing_id.adoc[zmq_msg_set_routing_id] If the 'routing_id' is not specified, or does not refer to a connected client peer, the send call will fail with EHOSTUNREACH. If the outgoing buffer for @@ -170,9 +166,9 @@ NOTE: Radio-dish is still in draft phase. ZMQ_RADIO ^^^^^^^ A socket of type 'ZMQ_RADIO' is used by a _publisher_ to distribute data. -Each message belong to a group, a group is specified with linkzmq:zmq_msg_set_group[3]. +Each message belong to a group, a group is specified with xref:zmq_msg_set_group.adoc[zmq_msg_set_group] Messages are distributed to all members of a group. -The linkzmq:zmq_recv[3] function is not implemented for this socket type. +The xref:zmq_recv.adoc[zmq_recv] function is not implemented for this socket type. When a 'ZMQ_RADIO' 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 @@ -196,9 +192,9 @@ ZMQ_DISH ^^^^^^^^ A socket of type 'ZMQ_DISH' is used by a _subscriber_ to subscribe to groups distributed by a _radio_. Initially a 'ZMQ_DISH' socket is not subscribed to -any groups, use linkzmq:zmq_join[3] to +any groups, use xref:zmq_join.adoc[zmq_join] to join a group. -To get the group the message belong to call linkzmq:zmq_msg_group[3]. +To get the group the message belong to call xref:zmq_msg_group.adoc[zmq_msg_group] The _zmq_send()_ function is not implemented for this socket type. NOTE: 'ZMQ_DISH' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives. @@ -224,7 +220,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 xref:zmq_recv.adoc[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 @@ -245,7 +241,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 xref:zmq_setsockopt.adoc[zmq_setsockopt] to specify which messages to subscribe to. The _zmq_send()_ function is not implemented for this socket type. @@ -312,7 +308,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, for connection-oriented transports, if the ZMQ_IMMEDIATE option is set and there are no downstream _nodes_ at all, -then any linkzmq:zmq_send[3] operations on the socket shall block until the mute +then any xref:zmq_send.adoc[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. @@ -360,7 +356,7 @@ socket type. When a 'ZMQ_SCATTER' socket enters the 'mute' state due to having reached the high water mark for all downstream _nodes_, or, for connection-oriented transports, if the ZMQ_IMMEDIATE option is set and there are no downstream _nodes_ at all, -then any linkzmq:zmq_send[3] operations on the socket shall block until the mute +then any xref:zmq_send.adoc[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. @@ -414,16 +410,16 @@ 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, for connection-oriented transports, if the ZMQ_IMMEDIATE option is set and there is no connected peer, then -any linkzmq:zmq_send[3] operations on the socket shall block until the peer +any xref:zmq_send.adoc[zmq_send] operations on the socket shall block until the peer becomes available for sending; messages are not discarded. -While 'ZMQ_PAIR' sockets can be used over transports other than linkzmq:zmq_inproc[7], +While 'ZMQ_PAIR' sockets can be used over transports other than xref:zmq_inproc.adoc[zmq_inproc], their inability to auto-reconnect coupled with the fact new incoming connections will be terminated while any previous connections (including ones in a closing state) exist makes them unsuitable for TCP in most cases. NOTE: 'ZMQ_PAIR' sockets are designed for inter-thread communication across -the linkzmq:zmq_inproc[7] transport and do not implement functionality such +the xref:zmq_inproc.adoc[zmq_inproc] transport and do not implement functionality such as auto-reconnection. [horizontal] @@ -450,13 +446,13 @@ ZMQ_PEER ^^^^^^^^ A 'ZMQ_PEER' socket talks to a set of 'ZMQ_PEER' sockets. -To connect and fetch the 'routing_id' of the peer use linkzmq:zmq_connect_peer[3]. +To connect and fetch the 'routing_id' of the peer use xref:zmq_connect_peer.adoc[zmq_connect_peer] Each received message has a 'routing_id' that is a 32-bit unsigned integer. -The application can fetch this with linkzmq:zmq_msg_routing_id[3]. +The application can fetch this with xref:zmq_msg_routing_id.adoc[zmq_msg_routing_id] To send a message to a given 'ZMQ_PEER' peer the application must set the peer's -'routing_id' on the message, using linkzmq:zmq_msg_set_routing_id[3]. +'routing_id' on the message, using xref:zmq_msg_set_routing_id.adoc[zmq_msg_set_routing_id] If the 'routing_id' is not specified, or does not refer to a connected client peer, the send call will fail with EHOSTUNREACH. If the outgoing buffer for @@ -495,16 +491,16 @@ time. No message routing or filtering is performed on messages sent over a When a 'ZMQ_CHANNEL' socket enters the 'mute' state due to having reached the high water mark for the connected peer, or, for connection-oriented transports, if the ZMQ_IMMEDIATE option is set and there is no connected peer, then -any linkzmq:zmq_send[3] operations on the socket shall block until the peer +any xref:zmq_send.adoc[zmq_send] operations on the socket shall block until the peer becomes available for sending; messages are not discarded. -While 'ZMQ_CHANNEL' sockets can be used over transports other than linkzmq:zmq_inproc[7], +While 'ZMQ_CHANNEL' sockets can be used over transports other than xref:zmq_inproc.adoc[zmq_inproc], their inability to auto-reconnect coupled with the fact new incoming connections will be terminated while any previous connections (including ones in a closing state) exist makes them unsuitable for TCP in most cases. NOTE: 'ZMQ_CHANNEL' sockets are designed for inter-thread communication across -the linkzmq:zmq_inproc[7] transport and do not implement functionality such +the xref:zmq_inproc.adoc[zmq_inproc] transport and do not implement functionality such as auto-reconnection. NOTE: 'ZMQ_CHANNEL' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives. @@ -620,7 +616,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, for connection-oriented transports, if the ZMQ_IMMEDIATE option is set and there are no peers at all, then any -linkzmq:zmq_send[3] operations on the socket shall block until the mute state +xref:zmq_send.adoc[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. When a 'ZMQ_DEALER' socket is connected to a 'ZMQ_REP' socket each message sent @@ -679,15 +675,13 @@ Incoming routing strategy:: Fair-queued Action in mute state:: Drop (see text) -RETURN VALUE ------------- +== 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 ------- +== ERRORS *EINVAL*:: The requested socket 'type' is invalid. *EFAULT*:: @@ -697,8 +691,7 @@ The limit on the total number of open 0MQ sockets has been reached. *ETERM*:: The context specified was shutdown or terminated. -EXAMPLE -------- +== EXAMPLE .Creating a simple HTTP server using ZMQ_STREAM ---- void *ctx = zmq_ctx_new (); @@ -740,19 +733,17 @@ zmq_ctx_destroy (ctx); ---- -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] +== SEE ALSO +xref:zmq_init.adoc[zmq_init] +xref:zmq_setsockopt.adoc[zmq_setsockopt] +xref:zmq_bind.adoc[zmq_bind] +xref:zmq_connect.adoc[zmq_connect] +xref:zmq_send.adoc[zmq_send] +xref:zmq_recv.adoc[zmq_recv] +xref:zmq_inproc.adoc[zmq_inproc] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_socket_monitor.txt b/doc/zmq_socket_monitor.adoc similarity index 97% rename from doc/zmq_socket_monitor.txt rename to doc/zmq_socket_monitor.adoc index 46a97cc1..42a58c86 100644 --- a/doc/zmq_socket_monitor.txt +++ b/doc/zmq_socket_monitor.adoc @@ -1,27 +1,23 @@ -zmq_socket_monitor(3) -===================== += zmq_socket_monitor(3) -NAME ----- +== NAME zmq_socket_monitor - monitor socket events -SYNOPSIS --------- +== SYNOPSIS *int zmq_socket_monitor (void '*socket', char '*endpoint', int 'events');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_socket_monitor()_ method lets an application thread track socket events (like connects) on a ZeroMQ socket. Each call to this method creates a 'ZMQ_PAIR' socket and binds that to the specified inproc:// 'endpoint'. To collect the socket events, you must create your own 'ZMQ_PAIR' socket, and connect that to the endpoint. -Note that there is also a DRAFT function linkzmq:zmq_socket_monitor_versioned[3], +Note that there is also a DRAFT function xref:zmq_socket_monitor_versioned.adoc[zmq_socket_monitor_versioned], which allows to subscribe to events that provide more information. Calling zmq_socket_monitor is equivalent to calling 'zmq_socket_monitor_versioned' with the 'event_version' parameter set to 1, with the exception of error cases. @@ -150,15 +146,13 @@ The event value is the status code returned by the ZAP handler (i.e. 300, -RETURN VALUE ------------- +== RETURN VALUE The _zmq_socket_monitor()_ function returns a value of 0 or greater if successful. Otherwise it returns `-1` and sets 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *ETERM*:: The 0MQ 'context' associated with the specified 'socket' was terminated. @@ -169,8 +163,7 @@ required to use the inproc:// transport. *EINVAL*:: The endpoint supplied is invalid. -EXAMPLE -------- +== EXAMPLE .Monitoring client and server sockets ---- // Read one event off the monitor socket; return value and address @@ -285,12 +278,10 @@ int main (void) ---- -SEE ALSO --------- -linkzmq:zmq[7] +== SEE ALSO +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_socket_monitor_versioned.txt b/doc/zmq_socket_monitor_versioned.adoc similarity index 98% rename from doc/zmq_socket_monitor_versioned.txt rename to doc/zmq_socket_monitor_versioned.adoc index 9fd2e87b..f4cc477c 100644 --- a/doc/zmq_socket_monitor_versioned.txt +++ b/doc/zmq_socket_monitor_versioned.adoc @@ -1,22 +1,18 @@ -zmq_socket_monitor_versioned(3) -=============================== += zmq_socket_monitor_versioned(3) -NAME ----- +== NAME zmq_socket_monitor_versioned - monitor socket events -SYNOPSIS --------- +== SYNOPSIS *int zmq_socket_monitor_versioned (void '*socket', char '*endpoint', uint64_t 'events', int 'event_version', int 'type');* *int zmq_socket_monitor_pipes_stats (void '*socket');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_socket_monitor_versioned()_ method lets an application thread track socket events (like connects) on a ZeroMQ socket. Each call to this method creates a 'ZMQ_PAIR' socket and binds that to the specified @@ -37,7 +33,7 @@ ZMQ_CURRENT_EVENT_VERSION and ZMQ_CURRENT_EVENT_VERSION_DRAFT are always defined to the most recent stable or DRAFT event version, which are currently 1 resp. 2 This page describes the protocol for 'event_version' 2 only. For the protocol -used with 'event_version' 1, please refer to linkzmq:zmq_socket_monitor[3]. +used with 'event_version' 1, please refer to xref:zmq_socket_monitor.adoc[zmq_socket_monitor] Each event is sent in multiple frames. The first frame contains an event number (64 bits). The number and content of further frames depend on this @@ -203,8 +199,7 @@ NOTE: in DRAFT state, not yet available in stable releases. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_socket_monitor()_ and _zmq_socket_monitor_pipes_stats()_ functions return a value of 0 or greater if successful. Otherwise they return `-1` and set 'errno' to one of the values defined below. @@ -235,8 +230,7 @@ The socket did not have monitoring enabled. *EAGAIN*:: The monitored socket did not have any connections to monitor yet. -EXAMPLE -------- +== EXAMPLE .Monitoring client and server sockets ---- // Read one event off the monitor socket; return values and addresses @@ -390,12 +384,10 @@ int main (void) ---- -SEE ALSO --------- -linkzmq:zmq[7] +== SEE ALSO +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_strerror.txt b/doc/zmq_strerror.adoc similarity index 82% rename from doc/zmq_strerror.txt rename to doc/zmq_strerror.adoc index a038a9af..62941016 100644 --- a/doc/zmq_strerror.txt +++ b/doc/zmq_strerror.adoc @@ -1,19 +1,15 @@ -zmq_strerror(3) -=============== += zmq_strerror(3) -NAME ----- +== NAME zmq_strerror - get 0MQ error message string -SYNOPSIS --------- +== SYNOPSIS *const char *zmq_strerror (int 'errnum');* -DESCRIPTION ------------ +== 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 0MQ defines additional error numbers over and above those defined by the operating @@ -21,19 +17,16 @@ system, applications should use _zmq_strerror()_ in preference to the standard _strerror()_ function. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_strerror()_ function shall return a pointer to an error message string. -ERRORS ------- +== ERRORS No errors are defined. -EXAMPLE -------- +== EXAMPLE .Displaying an error message when a 0MQ context cannot be initialised ---- void *ctx = zmq_init (1, 1, 0); @@ -44,13 +37,11 @@ if (!ctx) { ---- -SEE ALSO --------- -linkzmq:zmq[7] +== SEE ALSO +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_tcp.txt b/doc/zmq_tcp.adoc similarity index 92% rename from doc/zmq_tcp.txt rename to doc/zmq_tcp.adoc index a25a95ea..ae735862 100644 --- a/doc/zmq_tcp.txt +++ b/doc/zmq_tcp.adoc @@ -1,21 +1,17 @@ -zmq_tcp(7) -========== += zmq_tcp(7) -NAME ----- +== NAME zmq_tcp - 0MQ unicast transport using TCP -SYNOPSIS --------- +== SYNOPSIS TCP is an ubiquitous, reliable, unicast transport. When connecting distributed applications over a network with 0MQ, using the TCP transport will likely be your first choice. -ADDRESSING ----------- +== 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. @@ -43,7 +39,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 xref:zmq_getsockopt.adoc[zmq_getsockopt] for details. Unbinding wild-card address from a socket @@ -70,8 +66,7 @@ Note: A description of the ZeroMQ Message Transport Protocol (ZMTP) which is used by the TCP transport can be found at -HWM ---- +== HWM For the TCP transport, the high water mark (HWM) mechanism works in conjunction with the TCP socket buffers handled at OS level. @@ -93,8 +88,7 @@ Obviously the same considerations apply for the receive HWM (see ZMQ_RCVHWM). -EXAMPLES --------- +== EXAMPLES .Assigning a local address to a socket ---- // TCP port 5555 on all available interfaces @@ -125,18 +119,16 @@ 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_vmci[7] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_bind.adoc[zmq_bind] +xref:zmq_connect.adoc[zmq_connect] +xref:zmq_pgm.adoc[zmq_pgm] +xref:zmq_ipc.adoc[zmq_ipc] +xref:zmq_inproc.adoc[zmq_inproc] +xref:zmq_vmci.adoc[zmq_vmci] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_term.txt b/doc/zmq_term.txt deleted file mode 100644 index 61527322..00000000 --- a/doc/zmq_term.txt +++ /dev/null @@ -1,66 +0,0 @@ -zmq_term(3) -=========== - - -NAME ----- -zmq_term - terminate 0MQ context - - -SYNOPSIS --------- -*int zmq_term (void '*context');* - - -DESCRIPTION ------------ -The _zmq_term()_ function shall terminate the 0MQ 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. 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. - -For further details regarding socket linger behaviour refer to the _ZMQ_LINGER_ -option in linkzmq:zmq_setsockopt[3]. - -This function is deprecated by linkzmq:zmq_ctx_term[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 invalid. -*EINTR*:: -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] - - -AUTHORS -------- -This page was written by the 0MQ community. To make a change please -read the 0MQ Contribution Policy at . diff --git a/doc/zmq_timers.txt b/doc/zmq_timers.adoc similarity index 95% rename from doc/zmq_timers.txt rename to doc/zmq_timers.adoc index b7541b19..8fdb35b5 100644 --- a/doc/zmq_timers.txt +++ b/doc/zmq_timers.adoc @@ -1,14 +1,11 @@ -zmq_timers(3) -============ += zmq_timers(3) -NAME ----- +== NAME zmq_timers - helper functions for cross-platform timers callbacks -SYNOPSIS --------- +== SYNOPSIS *typedef void(zmq_timer_fn) (int 'timer_id', void *'arg');* @@ -29,8 +26,7 @@ SYNOPSIS *int zmq_timers_execute (void *'timers');* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_timers_*_ functions provide cross-platform access to timers callbacks. Once a timer has been registered, it will repeat at the specified interval until it gets manually cancelled. To run the callbacks, _zmq_timers_execute_ must be @@ -69,14 +65,12 @@ _zmq_timers_execute_ will run callbacks of all expired timers from the instance _timers_. -THREAD SAFETY -------------- +== THREAD SAFETY Like most other 0MQ objects, timers are not thread-safe. All operations must be called from the same thread. Otherwise, behaviour is undefined. -RETURN VALUE ------------- +== RETURN VALUE _zmq_timers_new_ always returns a valid pointer to a poller. All functions that return an int, return -1 in case of a failure. In that case, @@ -88,8 +82,7 @@ timer registered with _timers_ expires, or -1 if there are no timers left. All other functions return 0 in case of a successful execution. -ERRORS ------- +== ERRORS On _zmq_timers_destroy_, _zmq_poller_cancel_, _zmq_timers_set_interval_, _zmq_timers_reset_, zmq_timers_timeout_, and _zmq_timers_execute_: *EFAULT*:: @@ -107,8 +100,7 @@ On _zmq_poller_cancel_, _zmq_timers_set_interval_ and zmq_timers_timeout_: _timer_id_ did not exist or was already cancelled. -EXAMPLE -------- +== EXAMPLE .Add one timer with a simple callback that changes a boolean. ---- void handler (int timer_id_, void *arg_) @@ -151,12 +143,10 @@ EXAMPLE ---- -SEE ALSO --------- -linkzmq:zmq[7] +== SEE ALSO +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_tipc.txt b/doc/zmq_tipc.adoc similarity index 85% rename from doc/zmq_tipc.txt rename to doc/zmq_tipc.adoc index 004c95a5..a74360a6 100644 --- a/doc/zmq_tipc.txt +++ b/doc/zmq_tipc.adoc @@ -1,19 +1,15 @@ -zmq_tipc(7) -========== += zmq_tipc(7) -NAME ----- +== NAME zmq_tipc - 0MQ unicast transport using TIPC -SYNOPSIS --------- +== SYNOPSIS TIPC is a cluster IPC protocol with a location transparent addressing scheme. -ADDRESSING ----------- +== 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. @@ -45,8 +41,7 @@ comma and the instance ID. The instance ID must be within the lower/upper range of a published port name for the endpoint to be valid. -EXAMPLES --------- +== EXAMPLES .Assigning a local address to a socket ---- // Publish TIPC service ID 5555 @@ -65,19 +60,17 @@ assert (rc == 0); ---- -SEE ALSO --------- -linkzmq:zmq_bind[3] -linkzmq:zmq_connect[3] -linkzmq:zmq_tcp[7] -linkzmq:zmq_pgm[7] -linkzmq:zmq_ipc[7] -linkzmq:zmq_inproc[7] -linkzmq:zmq_vmci[7] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_bind.adoc[zmq_bind] +xref:zmq_connect.adoc[zmq_connect] +xref:zmq_tcp.adoc[zmq_tcp] +xref:zmq_pgm.adoc[zmq_pgm] +xref:zmq_ipc.adoc[zmq_ipc] +xref:zmq_inproc.adoc[zmq_inproc] +xref:zmq_vmci.adoc[zmq_vmci] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_udp.txt b/doc/zmq_udp.adoc similarity index 91% rename from doc/zmq_udp.txt rename to doc/zmq_udp.adoc index 8dc6803f..e0184f51 100644 --- a/doc/zmq_udp.txt +++ b/doc/zmq_udp.adoc @@ -1,25 +1,20 @@ -zmq_udp(7) -========== += zmq_udp(7) -NAME ----- +== NAME zmq_udp - 0MQ UDP multicast and unicast transport -SYNOPSIS --------- +== SYNOPSIS UDP is unreliable protocol transport of data over IP networks. UDP support both unicast and multicast communication. -DESCRIPTION ------------ +== DESCRIPTION UDP transport can only be used with the 'ZMQ_RADIO' and 'ZMQ_DISH' socket types. -ADDRESSING ----------- +== 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. @@ -57,8 +52,7 @@ A 'peer address' may be specified by either of the following: or using its hostname. * Multicast address in its numeric representation. -EXAMPLES --------- +== EXAMPLES .Binding a socket ---- // Unicast - UDP port 5555 on all available interfaces @@ -99,18 +93,16 @@ 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_vmci[7] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_connect.adoc[zmq_connect] +xref:zmq_setsockopt.adoc[zmq_setsockopt] +xref:zmq_tcp.adoc[zmq_tcp] +xref:zmq_ipc.adoc[zmq_ipc] +xref:zmq_inproc.adoc[zmq_inproc] +xref:zmq_vmci.adoc[zmq_vmci] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_unbind.txt b/doc/zmq_unbind.adoc similarity index 84% rename from doc/zmq_unbind.txt rename to doc/zmq_unbind.adoc index f2304e6c..54b27164 100644 --- a/doc/zmq_unbind.txt +++ b/doc/zmq_unbind.adoc @@ -1,19 +1,15 @@ -zmq_unbind(3) -============== += zmq_unbind(3) -NAME ----- +== NAME zmq_unbind - Stop accepting connections on a socket -SYNOPSIS --------- +== SYNOPSIS int zmq_unbind (void '*socket', const char '*endpoint'); -DESCRIPTION ------------ +== DESCRIPTION The _zmq_unbind()_ function shall unbind a socket specified by the 'socket' argument from the endpoint specified by the 'endpoint' argument. @@ -23,22 +19,20 @@ discarded. This means that after unbinding an endpoint it is possible to received messages originating from that same endpoint if they were already present in the incoming message queue before unbinding. -The 'endpoint' argument is as described in linkzmq:zmq_bind[3] +The 'endpoint' argument is as described in xref:zmq_bind.adoc[zmq_bind] Unbinding wild-card address from a socket ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When wild-card `*` 'endpoint' (described in linkzmq:zmq_tcp[7], -linkzmq:zmq_ipc[7], linkzmq:zmq_udp[7] and linkzmq:zmq_vmci[7]) was used in +When wild-card `*` 'endpoint' (described in xref:zmq_tcp.adoc[zmq_tcp], +xref:zmq_ipc.adoc[zmq_ipc], xref:zmq_udp.adoc[zmq_udp] and xref:zmq_vmci.adoc[zmq_vmci]) was used in _zmq_bind()_, the caller should use real 'endpoint' obtained from the ZMQ_LAST_ENDPOINT socket option to unbind this 'endpoint' from a socket. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_unbind()_ function shall return zero if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. -ERRORS ------- +== ERRORS *EINVAL*:: The endpoint supplied is invalid. *ETERM*:: @@ -49,8 +43,7 @@ The provided 'socket' was invalid. The endpoint supplied was not previously bound. -EXAMPLES --------- +== EXAMPLES .Unbind a subscriber socket from a TCP transport ---- /* Create a ZMQ_SUB socket */ @@ -82,22 +75,19 @@ rc = zmq_unbind (socket, buf); assert (rc == 0); ---- -NOTE ----- +== NOTE Note that while the implementation is similar to _zmq_disconnect()_, the semantics are different and the two functions should not be used interchangeably. Bound sockets should be unbound, and connected sockets should be disconnected. -SEE ALSO --------- -linkzmq:zmq_bind[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_bind.adoc[zmq_bind] +xref:zmq_socket.adoc[zmq_socket] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_version.txt b/doc/zmq_version.adoc similarity index 82% rename from doc/zmq_version.txt rename to doc/zmq_version.adoc index d96a106b..023f0c8d 100644 --- a/doc/zmq_version.txt +++ b/doc/zmq_version.adoc @@ -1,19 +1,15 @@ -zmq_version(3) -============== += zmq_version(3) -NAME ----- +== NAME zmq_version - report 0MQ library version -SYNOPSIS --------- +== SYNOPSIS *void zmq_version (int '*major', int '*minor', int '*patch');* -DESCRIPTION ------------ +== 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 0MQ library version. @@ -23,18 +19,15 @@ dynamically linking to the 0MQ library that wish to determine the actual version of the 0MQ library they are using. -RETURN VALUE ------------- +== RETURN VALUE There is no return value. -ERRORS ------- +== ERRORS No errors are defined. -EXAMPLE -------- +== EXAMPLE .Printing out the version of the 0MQ library ---- int major, minor, patch; @@ -43,12 +36,10 @@ printf ("Current 0MQ version is %d.%d.%d\n", major, minor, patch); ---- -SEE ALSO --------- -linkzmq:zmq[7] +== SEE ALSO +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_vmci.txt b/doc/zmq_vmci.adoc similarity index 88% rename from doc/zmq_vmci.txt rename to doc/zmq_vmci.adoc index 1a25a007..b902f72b 100644 --- a/doc/zmq_vmci.txt +++ b/doc/zmq_vmci.adoc @@ -1,22 +1,18 @@ -zmq_vmci(7) -=========== += zmq_vmci(7) -NAME ----- +== NAME zmq_vmci - 0MQ transport over virtual machine communicatios interface (VMCI) sockets -SYNOPSIS --------- +== SYNOPSIS The VMCI transport passes messages between VMware virtual machines running on the same host, between virtual machine and the host and within virtual machines (inter-process transport like ipc). NOTE: Communication between a virtual machine and the host is not supported on Mac OS X 10.9 and above. -ADDRESSING ----------- +== 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. @@ -56,8 +52,7 @@ a colon and the port number to use. A 'peer address' must be a CID of the peer. -EXAMPLES --------- +== EXAMPLES .Assigning a local address to a socket ---- // VMCI port 5555 on all available interfaces @@ -79,19 +74,17 @@ 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_vmci[7] -linkzmq:zmq_getsockopt[3] -linkzmq:zmq[7] +== SEE ALSO +xref:zmq_bind.adoc[zmq_bind] +xref:zmq_connect.adoc[zmq_connect] +xref:zmq_inproc.adoc[zmq_inproc] +xref:zmq_tcp.adoc[zmq_tcp] +xref:zmq_pgm.adoc[zmq_pgm] +xref:zmq_vmci.adoc[zmq_vmci] +xref:zmq_getsockopt.adoc[zmq_getsockopt] +xref:zmq.adoc[zmq] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_z85_decode.txt b/doc/zmq_z85_decode.adoc similarity index 74% rename from doc/zmq_z85_decode.txt rename to doc/zmq_z85_decode.adoc index 2649547f..2f0c5a8d 100644 --- a/doc/zmq_z85_decode.txt +++ b/doc/zmq_z85_decode.adoc @@ -1,19 +1,15 @@ -zmq_z85_decode(3) -================= += zmq_z85_decode(3) -NAME ----- +== NAME zmq_z85_decode - decode a binary key from Z85 printable text -SYNOPSIS --------- +== SYNOPSIS *uint8_t *zmq_z85_decode (uint8_t *dest, const char *string);* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_z85_decode()_ function shall decode 'string' into 'dest'. The length of 'string' shall be divisible by 5. 'dest' must be large enough for the decoded value (0.8 x strlen (string)). @@ -21,14 +17,12 @@ enough for the decoded value (0.8 x strlen (string)). The encoding shall follow the ZMQ RFC 32 specification. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_z85_decode()_ function shall return 'dest' if successful, else it shall return NULL. -EXAMPLE -------- +== EXAMPLE .Decoding a CURVE key ---- const char decoded [] = "rq:rM>}U?@Lns47E1%kR.o@n%FcmmsL/@{H8]yf7"; @@ -37,15 +31,13 @@ zmq_z85_decode (public_key, decoded); ---- -SEE ALSO --------- -linkzmq:zmq_z85_decode[3] -linkzmq:zmq_curve_keypair[3] -linkzmq:zmq_curve_public[3] -linkzmq:zmq_curve[7] +== SEE ALSO +xref:zmq_z85_encode.adoc[zmq_z85_encode] +xref:zmq_curve_keypair.adoc[zmq_curve_keypair] +xref:zmq_curve_public.adoc[zmq_curve_public] +xref:zmq_curve.adoc[zmq_curve] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/doc/zmq_z85_encode.txt b/doc/zmq_z85_encode.adoc similarity index 79% rename from doc/zmq_z85_encode.txt rename to doc/zmq_z85_encode.adoc index f578f4d2..feb10cf1 100644 --- a/doc/zmq_z85_encode.txt +++ b/doc/zmq_z85_encode.adoc @@ -1,19 +1,15 @@ -zmq_z85_encode(3) -================= += zmq_z85_encode(3) -NAME ----- +== NAME zmq_z85_encode - encode a binary key as Z85 printable text -SYNOPSIS --------- +== SYNOPSIS *char *zmq_z85_encode (char *dest, const uint8_t *data, size_t size);* -DESCRIPTION ------------ +== DESCRIPTION The _zmq_z85_encode()_ function shall encode the binary block specified by 'data' and 'size' into a string in 'dest'. The size of the binary block must be divisible by 4. The 'dest' must have sufficient space for size * 1.25 @@ -23,14 +19,12 @@ characters plus a null terminator. The encoding shall follow the ZMQ RFC 32 specification. -RETURN VALUE ------------- +== RETURN VALUE The _zmq_z85_encode()_ function shall return 'dest' if successful, else it shall return NULL. -EXAMPLE -------- +== EXAMPLE .Encoding a CURVE key ---- #include @@ -44,15 +38,13 @@ puts (encoded); ---- -SEE ALSO --------- -linkzmq:zmq_z85_decode[3] -linkzmq:zmq_curve_keypair[3] -linkzmq:zmq_curve_public[3] -linkzmq:zmq_curve[7] +== SEE ALSO +xref:zmq_z85_decode.adoc[zmq_z85_decode] +xref:zmq_curve_keypair.adoc[zmq_curve_keypair] +xref:zmq_curve_public.adoc[zmq_curve_public] +xref:zmq_curve.adoc[zmq_curve] -AUTHORS -------- +== AUTHORS This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at . diff --git a/packaging/debian/control b/packaging/debian/control index 23c86a6d..910d53fd 100644 --- a/packaging/debian/control +++ b/packaging/debian/control @@ -13,7 +13,7 @@ Build-Depends: debhelper (>= 9), libgnutls28-dev | libgnutls-dev, libbsd-dev, pkg-config, - asciidoc-base | asciidoc, xmlto, + asciidoctor, Standards-Version: 3.9.8 Homepage: http://www.zeromq.org/ diff --git a/packaging/debian/zeromq.dsc b/packaging/debian/zeromq.dsc index 6b209e8d..7941eb57 100644 --- a/packaging/debian/zeromq.dsc +++ b/packaging/debian/zeromq.dsc @@ -6,7 +6,7 @@ Version: 4.3.6-0.1 Maintainer: libzmq Developers Homepage: http://www.zeromq.org/ Standards-Version: 3.9.8 -Build-Depends: debhelper (>= 9), dh-autoreconf, libkrb5-dev, libpgm-dev, libnorm-dev, libsodium-dev, libunwind-dev | libunwind8-dev | libunwind7-dev, libnss3-dev, libgnutls28-dev | libgnutls-dev, libbsd-dev, pkg-config, asciidoc-base | asciidoc, xmlto +Build-Depends: debhelper (>= 9), dh-autoreconf, libkrb5-dev, libpgm-dev, libnorm-dev, libsodium-dev, libunwind-dev | libunwind8-dev | libunwind7-dev, libnss3-dev, libgnutls28-dev | libgnutls-dev, libbsd-dev, pkg-config, asciidoctor Package-List: libzmq3-dev deb libdevel optional arch=any libzmq5 deb libs optional arch=any diff --git a/packaging/redhat/zeromq.spec b/packaging/redhat/zeromq.spec index 9faddbd8..a61625a2 100644 --- a/packaging/redhat/zeromq.spec +++ b/packaging/redhat/zeromq.spec @@ -67,7 +67,18 @@ BuildRequires: gnutls-devel %else %define TLS no %endif -BuildRequires: gcc, make, gcc-c++, libstdc++-devel, asciidoc, xmlto +%if 0%{?rhel_version} +%if 0%{?rhel_version} >= 800 +# note1: on OBS the RHEL7 target for some reason is unable to find the asciidoctor package, so on RHEL7 docs are not built +# note2: on RHEL8/Centos8 the asciidoctor package depends from the ruby module; this might require some extra config on the +# build farm where this .spec file is used +BuildRequires: asciidoctor +%endif +%else +# on non-RHEL targets, listing asciidoctor in BuildRequires works just fine: +BuildRequires: rubygem(asciidoctor) +%endif +BuildRequires: gcc, make, gcc-c++, libstdc++-devel Requires: libstdc++ %ifarch pentium3 pentium4 athlon i386 i486 i586 i686 x86_64