generic-library/libzmq
1
0
Fork 0
mirror of https://github.com/zeromq/libzmq.git synced 2024-12-12 10:33:52 +01:00
Code Issues Projects Releases Wiki Activity

Feature: modernize API documentation

Browse Source 
* 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
This commit is contained in:
Francesco Montorsi 2023-10-21 01:50:38 +02:00
parent b30a19ebde
commit b6ca9b2983
87 changed files with 1254 additions and 2046 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/CI.yaml vendored
View File

@ -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

50
.github/workflows/Docs.yaml vendored Normal file
View File

@ -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

23
CMakeLists.txt
View File

@ -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)
"${CMAKE_CURRENT_SOURCE_DIR}/doc/*.adoc")
string(REPLACE ".txt" ".html" html_files ${asciidoc_files})
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}
OUTPUT ${html_files}
COMMAND asciidoctor -b html -azmq_version=${ZMQ_VERSION} *.adoc
DEPENDS ${asciidoc_files}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Generating ${html}")
list(APPEND html-docs ${CMAKE_CURRENT_BINARY_DIR}/${dst})
endif()
endforeach()
endif()
if(ZMQ_BUILD_FRAMEWORK)

9
acinclude.m4
View File

@ -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

26
builds/cmake/Modules/FindAsciiDoc.cmake
View File

@ -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)

23
builds/cmake/Modules/FindAsciiDoctor.cmake Normal file
View File

@ -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)

4
configure.ac
View File

@ -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

74
doc/Makefile.am
View File

@ -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

56
doc/asciidoc.conf
View File

@ -1,56 +0,0 @@
[paradef-default]
literal-style=template="literalparagraph"
[macros]
(?su)[\\]?(?P<name>linkzmq):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
ifdef::backend-docbook[]
[linkzmq-inlinemacro]
{0%{target}}
{0#<citerefentry>}
{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
{0#</citerefentry>}
endif::backend-docbook[]
ifdef::backend-xhtml11[]
[linkzmq-inlinemacro]
<a href="{target}.html">{target}{0?({0})}</a>
endif::backend-xhtml11[]
ifdef::doctype-manpage[]
ifdef::backend-docbook[]
[header]
template::[header-declarations]
<refentry>
<refmeta>
<refentrytitle>{mantitle}</refentrytitle>
<manvolnum>{manvolnum}</manvolnum>
<refmiscinfo class="source">0MQ</refmiscinfo>
<refmiscinfo class="version">{zmq_version}</refmiscinfo>
<refmiscinfo class="manual">0MQ Manual</refmiscinfo>
</refmeta>
<refnamediv>
<refname>{manname}</refname>
<refpurpose>{manpurpose}</refpurpose>
</refnamediv>
endif::backend-docbook[]
endif::doctype-manpage[]
ifdef::backend-xhtml11[]
[footer]
</div>
{disable-javascript%<div id="footnotes"><hr /></div>}
<div id="footer">
<div id="footer-text">
ØMQ {zmq_version}<br />
Last updated {docdate} {doctime}
</div>
</div>
</body>
</html>
endif::backend-xhtml11[]
[replacements]
ifdef::backend-xhtml11[]
0MQ=ØMQ
endif::backend-xhtml11[]

151
doc/zmq.txt → doc/zmq.adoc
View File

@ -1,21 +1,17 @@
zmq(7)
======
= zmq(7)
NAME
----
== NAME
zmq - 0MQ lightweight messaging kernel
SYNOPSIS
--------
== SYNOPSIS
*#include <zmq.h>*
*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 <http://www.zeromq.org/docs:contributing>.
RESOURCES
---------
== RESOURCES
Main web site: <http://www.zeromq.org/>
Report bugs to the 0MQ development mailing list: <zeromq-dev@lists.zeromq.org>
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.

34
doc/zmq_atomic_counter_dec.txt → doc/zmq_atomic_counter_dec.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

34
doc/zmq_atomic_counter_destroy.txt → doc/zmq_atomic_counter_destroy.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

34
doc/zmq_atomic_counter_inc.txt → doc/zmq_atomic_counter_inc.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

34
doc/zmq_atomic_counter_new.txt → doc/zmq_atomic_counter_new.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

34
doc/zmq_atomic_counter_set.txt → doc/zmq_atomic_counter_set.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

34
doc/zmq_atomic_counter_value.txt → doc/zmq_atomic_counter_value.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

55
doc/zmq_bind.txt → doc/zmq_bind.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

34
doc/zmq_close.txt → doc/zmq_close.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

49
doc/zmq_connect.txt → doc/zmq_connect.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

45
doc/zmq_connect_peer.txt → doc/zmq_connect_peer.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

67
doc/zmq_ctx_destroy.txt
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

33
doc/zmq_ctx_get.txt → doc/zmq_ctx_get.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

31
doc/zmq_ctx_get_ext.txt → doc/zmq_ctx_get_ext.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

34
doc/zmq_ctx_new.txt → doc/zmq_ctx_new.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

37
doc/zmq_ctx_set.txt → doc/zmq_ctx_set.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

31
doc/zmq_ctx_set_ext.txt → doc/zmq_ctx_set_ext.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

36
doc/zmq_ctx_shutdown.txt → doc/zmq_ctx_shutdown.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

38
doc/zmq_ctx_term.txt → doc/zmq_ctx_term.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

36
doc/zmq_curve.txt → doc/zmq_curve.adoc
View File

@ -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: <http://rfc.zeromq.org/spec:25>.
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 <http://www.zeromq.org/docs:contributing>.

35
doc/zmq_curve_keypair.txt → doc/zmq_curve_keypair.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

37
doc/zmq_curve_public.txt → doc/zmq_curve_public.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

37
doc/zmq_disconnect.txt → doc/zmq_disconnect.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

26
doc/zmq_errno.txt → doc/zmq_errno.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

47
doc/zmq_getsockopt.txt → doc/zmq_getsockopt.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

32
doc/zmq_gssapi.txt → doc/zmq_gssapi.adoc
View File

@ -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: <http://tools.ietf.org/html/rfc2743>. The ZeroMQ
GSSAPI mechanism is defined by this document: <http://rfc.zeromq.org/spec:38>.
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 <http://www.zeromq.org/docs:contributing>.

18
doc/zmq_has.txt → doc/zmq_has.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

52
doc/zmq_init.txt
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

37
doc/zmq_inproc.txt → doc/zmq_inproc.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

39
doc/zmq_ipc.txt → doc/zmq_ipc.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

38
doc/zmq_msg_close.txt → doc/zmq_msg_close.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

41
doc/zmq_msg_copy.txt → doc/zmq_msg_copy.adoc
View File

@ -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 (&copy);
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 <http://www.zeromq.org/docs:contributing>.

38
doc/zmq_msg_data.txt → doc/zmq_msg_data.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

35
doc/zmq_msg_get.txt → doc/zmq_msg_get.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

33
doc/zmq_msg_gets.txt → doc/zmq_msg_gets.adoc
View File

@ -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 <rfc.zeromq.org/spec:37>. 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 <http://www.zeromq.org/docs:contributing>.

41
doc/zmq_msg_init.txt → doc/zmq_msg_init.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

38
doc/zmq_msg_init_buffer.txt → doc/zmq_msg_init_buffer.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

41
doc/zmq_msg_init_data.txt → doc/zmq_msg_init_data.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

38
doc/zmq_msg_init_size.txt → doc/zmq_msg_init_size.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

34
doc/zmq_msg_more.txt → doc/zmq_msg_more.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

38
doc/zmq_msg_move.txt → doc/zmq_msg_move.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

49
doc/zmq_msg_recv.txt → doc/zmq_msg_recv.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

26
doc/zmq_msg_routing_id.txt → doc/zmq_msg_routing_id.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

41
doc/zmq_msg_send.txt → doc/zmq_msg_send.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

28
doc/zmq_msg_set.txt → doc/zmq_msg_set.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

28
doc/zmq_msg_set_routing_id.txt → doc/zmq_msg_set_routing_id.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

38
doc/zmq_msg_size.txt → doc/zmq_msg_size.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

21
doc/zmq_null.txt → doc/zmq_null.adoc
View File

@ -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:
<http://rfc.zeromq.org/spec:23>. 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 <http://www.zeromq.org/docs:contributing>.

50
doc/zmq_pgm.txt → doc/zmq_pgm.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

26
doc/zmq_plain.txt → doc/zmq_plain.adoc
View File

@ -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: <http://rfc.zeromq.org/spec:24>.
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 <http://www.zeromq.org/docs:contributing>.

38
doc/zmq_poll.txt → doc/zmq_poll.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

41
doc/zmq_poller.txt → doc/zmq_poller.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

44
doc/zmq_ppoll.txt → doc/zmq_ppoll.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

37
doc/zmq_proxy.txt → doc/zmq_proxy.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

34
doc/zmq_proxy_steerable.txt → doc/zmq_proxy_steerable.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

43
doc/zmq_recv.txt → doc/zmq_recv.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

45
doc/zmq_recvmsg.txt → doc/zmq_recvmsg.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

37
doc/zmq_send.txt → doc/zmq_send.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

37
doc/zmq_send_const.txt → doc/zmq_send_const.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

35
doc/zmq_sendmsg.txt → doc/zmq_sendmsg.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

90
doc/zmq_setsockopt.txt → doc/zmq_setsockopt.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

93
doc/zmq_socket.txt → doc/zmq_socket.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

31
doc/zmq_socket_monitor.txt → doc/zmq_socket_monitor.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

28
doc/zmq_socket_monitor_versioned.txt → doc/zmq_socket_monitor_versioned.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

29
doc/zmq_strerror.txt → doc/zmq_strerror.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

40
doc/zmq_tcp.txt → doc/zmq_tcp.adoc
View File

@ -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 <http://rfc.zeromq.org/spec:23>
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 <http://www.zeromq.org/docs:contributing>.

66
doc/zmq_term.txt
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

32
doc/zmq_timers.txt → doc/zmq_timers.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

37
doc/zmq_tipc.txt → doc/zmq_tipc.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

38
doc/zmq_udp.txt → doc/zmq_udp.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

42
doc/zmq_unbind.txt → doc/zmq_unbind.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

29
doc/zmq_version.txt → doc/zmq_version.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

37
doc/zmq_vmci.txt → doc/zmq_vmci.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

32
doc/zmq_z85_decode.txt → doc/zmq_z85_decode.adoc
View File

@ -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 <http://www.zeromq.org/docs:contributing>.

32
doc/zmq_z85_encode.txt → doc/zmq_z85_encode.adoc
View File

@ -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 <sodium.h>
@ -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 <http://www.zeromq.org/docs:contributing>.

2
packaging/debian/control
View File

@ -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/

2
packaging/debian/zeromq.dsc
View File

@ -6,7 +6,7 @@ Version: 4.3.6-0.1
Maintainer: libzmq Developers <zeromq-dev@lists.zeromq.org>
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

13
packaging/redhat/zeromq.spec
View File

@ -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