From a15854bd92db69fcd0b4444fe1b8fe3610a7acf6 Mon Sep 17 00:00:00 2001 From: Martin Lucina Date: Mon, 23 Jan 2012 08:53:19 +0100 Subject: Imported Upstream version 2.0.7.dfsg --- doc/Makefile.am | 46 ++ doc/Makefile.in | 539 +++++++++++++++++++ doc/zmq.7 | 258 +++++++++ doc/zmq.html | 866 ++++++++++++++++++++++++++++++ doc/zmq.txt | 221 ++++++++ doc/zmq_bind.3 | 154 ++++++ doc/zmq_bind.html | 729 +++++++++++++++++++++++++ doc/zmq_bind.txt | 87 +++ doc/zmq_close.3 | 60 +++ doc/zmq_close.html | 625 ++++++++++++++++++++++ doc/zmq_close.txt | 47 ++ doc/zmq_connect.3 | 149 ++++++ doc/zmq_connect.html | 715 +++++++++++++++++++++++++ doc/zmq_connect.txt | 85 +++ doc/zmq_cpp.7 | 400 ++++++++++++++ doc/zmq_cpp.html | 758 ++++++++++++++++++++++++++ doc/zmq_cpp.txt | 206 +++++++ doc/zmq_epgm.7 | 207 ++++++++ doc/zmq_epgm.html | 744 ++++++++++++++++++++++++++ doc/zmq_epgm.txt | 157 ++++++ doc/zmq_errno.3 | 78 +++ doc/zmq_errno.html | 633 ++++++++++++++++++++++ doc/zmq_errno.txt | 50 ++ doc/zmq_forwarder.1 | 57 ++ doc/zmq_forwarder.html | 612 +++++++++++++++++++++ doc/zmq_forwarder.txt | 33 ++ doc/zmq_getsockopt.3 | 505 ++++++++++++++++++ doc/zmq_getsockopt.html | 1192 +++++++++++++++++++++++++++++++++++++++++ doc/zmq_getsockopt.txt | 240 +++++++++ doc/zmq_init.3 | 67 +++ doc/zmq_init.html | 631 ++++++++++++++++++++++ doc/zmq_init.txt | 46 ++ doc/zmq_inproc.7 | 115 ++++ doc/zmq_inproc.html | 668 +++++++++++++++++++++++ doc/zmq_inproc.txt | 89 ++++ doc/zmq_ipc.7 | 109 ++++ doc/zmq_ipc.html | 661 +++++++++++++++++++++++ doc/zmq_ipc.txt | 80 +++ doc/zmq_msg_close.3 | 78 +++ doc/zmq_msg_close.html | 637 ++++++++++++++++++++++ doc/zmq_msg_close.txt | 54 ++ doc/zmq_msg_copy.3 | 92 ++++ doc/zmq_msg_copy.html | 646 ++++++++++++++++++++++ doc/zmq_msg_copy.txt | 56 ++ doc/zmq_msg_data.3 | 76 +++ doc/zmq_msg_data.html | 632 ++++++++++++++++++++++ doc/zmq_msg_data.txt | 48 ++ doc/zmq_msg_init.3 | 110 ++++ doc/zmq_msg_init.html | 655 +++++++++++++++++++++++ doc/zmq_msg_init.txt | 65 +++ doc/zmq_msg_init_data.3 | 122 +++++ doc/zmq_msg_init_data.html | 668 +++++++++++++++++++++++ doc/zmq_msg_init_data.txt | 80 +++ doc/zmq_msg_init_size.3 | 97 ++++ doc/zmq_msg_init_size.html | 655 +++++++++++++++++++++++ doc/zmq_msg_init_size.txt | 58 ++ doc/zmq_msg_move.3 | 76 +++ doc/zmq_msg_move.html | 635 ++++++++++++++++++++++ doc/zmq_msg_move.txt | 51 ++ doc/zmq_msg_size.3 | 76 +++ doc/zmq_msg_size.html | 632 ++++++++++++++++++++++ doc/zmq_msg_size.txt | 48 ++ doc/zmq_pgm.7 | 207 ++++++++ doc/zmq_pgm.html | 744 ++++++++++++++++++++++++++ doc/zmq_pgm.txt | 157 ++++++ doc/zmq_poll.3 | 217 ++++++++ doc/zmq_poll.html | 755 ++++++++++++++++++++++++++ doc/zmq_poll.txt | 133 +++++ doc/zmq_queue.1 | 57 ++ doc/zmq_queue.html | 612 +++++++++++++++++++++ doc/zmq_queue.txt | 33 ++ doc/zmq_recv.3 | 152 ++++++ doc/zmq_recv.html | 717 +++++++++++++++++++++++++ doc/zmq_recv.txt | 111 ++++ doc/zmq_send.3 | 166 ++++++ doc/zmq_send.html | 726 +++++++++++++++++++++++++ doc/zmq_send.txt | 109 ++++ doc/zmq_setsockopt.3 | 583 ++++++++++++++++++++ doc/zmq_setsockopt.html | 1268 ++++++++++++++++++++++++++++++++++++++++++++ doc/zmq_setsockopt.txt | 273 ++++++++++ doc/zmq_socket.3 | 609 +++++++++++++++++++++ doc/zmq_socket.html | 1225 ++++++++++++++++++++++++++++++++++++++++++ doc/zmq_socket.txt | 260 +++++++++ doc/zmq_streamer.1 | 57 ++ doc/zmq_streamer.html | 612 +++++++++++++++++++++ doc/zmq_streamer.txt | 33 ++ doc/zmq_strerror.3 | 78 +++ doc/zmq_strerror.html | 633 ++++++++++++++++++++++ doc/zmq_strerror.txt | 55 ++ doc/zmq_tcp.7 | 244 +++++++++ doc/zmq_tcp.html | 753 ++++++++++++++++++++++++++ doc/zmq_tcp.txt | 161 ++++++ doc/zmq_term.3 | 119 +++++ doc/zmq_term.html | 648 ++++++++++++++++++++++ doc/zmq_term.txt | 58 ++ doc/zmq_version.3 | 78 +++ doc/zmq_version.html | 631 ++++++++++++++++++++++ doc/zmq_version.txt | 53 ++ 98 files changed, 32593 insertions(+) create mode 100644 doc/Makefile.am create mode 100644 doc/Makefile.in create mode 100644 doc/zmq.7 create mode 100644 doc/zmq.html create mode 100644 doc/zmq.txt create mode 100644 doc/zmq_bind.3 create mode 100644 doc/zmq_bind.html create mode 100644 doc/zmq_bind.txt create mode 100644 doc/zmq_close.3 create mode 100644 doc/zmq_close.html create mode 100644 doc/zmq_close.txt create mode 100644 doc/zmq_connect.3 create mode 100644 doc/zmq_connect.html create mode 100644 doc/zmq_connect.txt create mode 100644 doc/zmq_cpp.7 create mode 100644 doc/zmq_cpp.html create mode 100644 doc/zmq_cpp.txt create mode 100644 doc/zmq_epgm.7 create mode 100644 doc/zmq_epgm.html create mode 100644 doc/zmq_epgm.txt create mode 100644 doc/zmq_errno.3 create mode 100644 doc/zmq_errno.html create mode 100644 doc/zmq_errno.txt create mode 100644 doc/zmq_forwarder.1 create mode 100644 doc/zmq_forwarder.html create mode 100644 doc/zmq_forwarder.txt create mode 100644 doc/zmq_getsockopt.3 create mode 100644 doc/zmq_getsockopt.html create mode 100644 doc/zmq_getsockopt.txt create mode 100644 doc/zmq_init.3 create mode 100644 doc/zmq_init.html create mode 100644 doc/zmq_init.txt create mode 100644 doc/zmq_inproc.7 create mode 100644 doc/zmq_inproc.html create mode 100644 doc/zmq_inproc.txt create mode 100644 doc/zmq_ipc.7 create mode 100644 doc/zmq_ipc.html create mode 100644 doc/zmq_ipc.txt create mode 100644 doc/zmq_msg_close.3 create mode 100644 doc/zmq_msg_close.html create mode 100644 doc/zmq_msg_close.txt create mode 100644 doc/zmq_msg_copy.3 create mode 100644 doc/zmq_msg_copy.html create mode 100644 doc/zmq_msg_copy.txt create mode 100644 doc/zmq_msg_data.3 create mode 100644 doc/zmq_msg_data.html create mode 100644 doc/zmq_msg_data.txt create mode 100644 doc/zmq_msg_init.3 create mode 100644 doc/zmq_msg_init.html create mode 100644 doc/zmq_msg_init.txt create mode 100644 doc/zmq_msg_init_data.3 create mode 100644 doc/zmq_msg_init_data.html create mode 100644 doc/zmq_msg_init_data.txt create mode 100644 doc/zmq_msg_init_size.3 create mode 100644 doc/zmq_msg_init_size.html create mode 100644 doc/zmq_msg_init_size.txt create mode 100644 doc/zmq_msg_move.3 create mode 100644 doc/zmq_msg_move.html create mode 100644 doc/zmq_msg_move.txt create mode 100644 doc/zmq_msg_size.3 create mode 100644 doc/zmq_msg_size.html create mode 100644 doc/zmq_msg_size.txt create mode 100644 doc/zmq_pgm.7 create mode 100644 doc/zmq_pgm.html create mode 100644 doc/zmq_pgm.txt create mode 100644 doc/zmq_poll.3 create mode 100644 doc/zmq_poll.html create mode 100644 doc/zmq_poll.txt create mode 100644 doc/zmq_queue.1 create mode 100644 doc/zmq_queue.html create mode 100644 doc/zmq_queue.txt create mode 100644 doc/zmq_recv.3 create mode 100644 doc/zmq_recv.html create mode 100644 doc/zmq_recv.txt create mode 100644 doc/zmq_send.3 create mode 100644 doc/zmq_send.html create mode 100644 doc/zmq_send.txt create mode 100644 doc/zmq_setsockopt.3 create mode 100644 doc/zmq_setsockopt.html create mode 100644 doc/zmq_setsockopt.txt create mode 100644 doc/zmq_socket.3 create mode 100644 doc/zmq_socket.html create mode 100644 doc/zmq_socket.txt create mode 100644 doc/zmq_streamer.1 create mode 100644 doc/zmq_streamer.html create mode 100644 doc/zmq_streamer.txt create mode 100644 doc/zmq_strerror.3 create mode 100644 doc/zmq_strerror.html create mode 100644 doc/zmq_strerror.txt create mode 100644 doc/zmq_tcp.7 create mode 100644 doc/zmq_tcp.html create mode 100644 doc/zmq_tcp.txt create mode 100644 doc/zmq_term.3 create mode 100644 doc/zmq_term.html create mode 100644 doc/zmq_term.txt create mode 100644 doc/zmq_version.3 create mode 100644 doc/zmq_version.html create mode 100644 doc/zmq_version.txt (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..3c7b20b --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,46 @@ +MAN1 = zmq_forwarder.1 zmq_streamer.1 zmq_queue.1 +MAN3 = zmq_bind.3 zmq_close.3 zmq_connect.3 zmq_init.3 \ + zmq_msg_close.3 zmq_msg_copy.3 zmq_msg_data.3 zmq_msg_init.3 \ + zmq_msg_init_data.3 zmq_msg_init_size.3 zmq_msg_move.3 zmq_msg_size.3 \ + zmq_poll.3 zmq_recv.3 zmq_send.3 zmq_setsockopt.3 zmq_socket.3 \ + zmq_strerror.3 zmq_term.3 zmq_version.3 zmq_getsockopt.3 zmq_errno.3 +MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_epgm.7 zmq_inproc.7 zmq_ipc.7 \ + zmq_cpp.7 +MAN_DOC = $(MAN1) $(MAN3) $(MAN7) + +MAN_TXT = $(MAN1:%.1=%.txt) +MAN_TXT += $(MAN3:%.3=%.txt) +MAN_TXT += $(MAN7:%.7=%.txt) +MAN_HTML = $(MAN_TXT:%.txt=%.html) + +if INSTALL_MAN +dist_man_MANS = $(MAN_DOC) +endif + +EXTRA_DIST = $(MAN_TXT) +if BUILD_DOC +EXTRA_DIST += $(MAN_HTML) +endif + +MAINTAINERCLEANFILES = $(MAN_DOC) $(MAN_HTML) + +dist-hook : $(MAN_DOC) $(MAN_HTML) + +if BUILD_DOC +SUFFIXES=.html .txt .xml .1 .3 .7 + +.txt.html: + asciidoc -d manpage -b xhtml11 -f asciidoc.conf \ + -azmq_version=@PACKAGE_VERSION@ $< +.txt.xml: + asciidoc -d manpage -b docbook -f asciidoc.conf \ + -azmq_version=@PACKAGE_VERSION@ $< +.xml.1: + xmlto man $< +.xml.3: + xmlto man $< +.xml.7: + xmlto man $< +zmq_epgm.7: zmq_pgm.7 + cp zmq_pgm.7 $@ +endif diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 0000000..c75a926 --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,539 @@ +# Makefile.in generated by automake 1.10.1 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +@BUILD_DOC_TRUE@am__append_1 = $(MAN_HTML) +subdir = doc +DIST_COMMON = $(dist_man_MANS) $(srcdir)/Makefile.am \ + $(srcdir)/Makefile.in +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/config/libtool.m4 \ + $(top_srcdir)/config/ltoptions.m4 \ + $(top_srcdir)/config/ltsugar.m4 \ + $(top_srcdir)/config/ltversion.m4 \ + $(top_srcdir)/config/lt~obsolete.m4 $(top_srcdir)/configure.in +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/src/platform.hpp +CONFIG_CLEAN_FILES = +SOURCES = +DIST_SOURCES = +man1dir = $(mandir)/man1 +am__installdirs = "$(DESTDIR)$(man1dir)" "$(DESTDIR)$(man3dir)" \ + "$(DESTDIR)$(man7dir)" +man3dir = $(mandir)/man3 +man7dir = $(mandir)/man7 +NROFF = nroff +MANS = $(dist_man_MANS) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +AR = @AR@ +AS = @AS@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CXX = @CXX@ +CXXCPP = @CXXCPP@ +CXXDEPMODE = @CXXDEPMODE@ +CXXFLAGS = @CXXFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DLLTOOL = @DLLTOOL@ +DSYMUTIL = @DSYMUTIL@ +DUMPBIN = @DUMPBIN@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +FGREP = @FGREP@ +GLIB_CFLAGS = @GLIB_CFLAGS@ +GLIB_LIBS = @GLIB_LIBS@ +GREP = @GREP@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +LD = @LD@ +LDFLAGS = @LDFLAGS@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIBZMQ_EXTRA_CXXFLAGS = @LIBZMQ_EXTRA_CXXFLAGS@ +LIBZMQ_EXTRA_LDFLAGS = @LIBZMQ_EXTRA_LDFLAGS@ +LIPO = @LIPO@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +LTVER = @LTVER@ +MAKEINFO = @MAKEINFO@ +MKDIR_P = @MKDIR_P@ +NM = @NM@ +NMEDIT = @NMEDIT@ +OBJDUMP = @OBJDUMP@ +OBJEXT = @OBJEXT@ +OTOOL = @OTOOL@ +OTOOL64 = @OTOOL64@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PKG_CONFIG = @PKG_CONFIG@ +RANLIB = @RANLIB@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +VERSION = @VERSION@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CXX = @ac_ct_CXX@ +ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +have_asciidoc = @have_asciidoc@ +have_gzip = @have_gzip@ +have_perl = @have_perl@ +have_pkg_config = @have_pkg_config@ +have_python = @have_python@ +have_xmlto = @have_xmlto@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +inttypes = @inttypes@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +lt_ECHO = @lt_ECHO@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +pgm_basename = @pgm_basename@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +stdint = @stdint@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +MAN1 = zmq_forwarder.1 zmq_streamer.1 zmq_queue.1 +MAN3 = zmq_bind.3 zmq_close.3 zmq_connect.3 zmq_init.3 \ + zmq_msg_close.3 zmq_msg_copy.3 zmq_msg_data.3 zmq_msg_init.3 \ + zmq_msg_init_data.3 zmq_msg_init_size.3 zmq_msg_move.3 zmq_msg_size.3 \ + zmq_poll.3 zmq_recv.3 zmq_send.3 zmq_setsockopt.3 zmq_socket.3 \ + zmq_strerror.3 zmq_term.3 zmq_version.3 zmq_getsockopt.3 zmq_errno.3 + +MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_epgm.7 zmq_inproc.7 zmq_ipc.7 \ + zmq_cpp.7 + +MAN_DOC = $(MAN1) $(MAN3) $(MAN7) +MAN_TXT = $(MAN1:%.1=%.txt) $(MAN3:%.3=%.txt) $(MAN7:%.7=%.txt) +MAN_HTML = $(MAN_TXT:%.txt=%.html) +@INSTALL_MAN_TRUE@dist_man_MANS = $(MAN_DOC) +EXTRA_DIST = $(MAN_TXT) $(am__append_1) +MAINTAINERCLEANFILES = $(MAN_DOC) $(MAN_HTML) +@BUILD_DOC_TRUE@SUFFIXES = .html .txt .xml .1 .3 .7 +all: all-am + +.SUFFIXES: +.SUFFIXES: .html .txt .xml .1 .3 .7 +$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ + && exit 0; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \ + cd $(top_srcdir) && \ + $(AUTOMAKE) --gnu doc/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs +install-man1: $(man1_MANS) $(man_MANS) + @$(NORMAL_INSTALL) + test -z "$(man1dir)" || $(MKDIR_P) "$(DESTDIR)$(man1dir)" + @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \ + l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ + for i in $$l2; do \ + case "$$i" in \ + *.1*) list="$$list $$i" ;; \ + esac; \ + done; \ + for i in $$list; do \ + if test -f $(srcdir)/$$i; then file=$(srcdir)/$$i; \ + else file=$$i; fi; \ + ext=`echo $$i | sed -e 's/^.*\\.//'`; \ + case "$$ext" in \ + 1*) ;; \ + *) ext='1' ;; \ + esac; \ + inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ + inst=`echo $$inst | sed -e 's/^.*\///'`; \ + inst=`echo $$inst | sed '$(transform)'`.$$ext; \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst"; \ + done +uninstall-man1: + @$(NORMAL_UNINSTALL) + @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \ + l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ + for i in $$l2; do \ + case "$$i" in \ + *.1*) list="$$list $$i" ;; \ + esac; \ + done; \ + for i in $$list; do \ + ext=`echo $$i | sed -e 's/^.*\\.//'`; \ + case "$$ext" in \ + 1*) ;; \ + *) ext='1' ;; \ + esac; \ + inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ + inst=`echo $$inst | sed -e 's/^.*\///'`; \ + inst=`echo $$inst | sed '$(transform)'`.$$ext; \ + echo " rm -f '$(DESTDIR)$(man1dir)/$$inst'"; \ + rm -f "$(DESTDIR)$(man1dir)/$$inst"; \ + done +install-man3: $(man3_MANS) $(man_MANS) + @$(NORMAL_INSTALL) + test -z "$(man3dir)" || $(MKDIR_P) "$(DESTDIR)$(man3dir)" + @list='$(man3_MANS) $(dist_man3_MANS) $(nodist_man3_MANS)'; \ + l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ + for i in $$l2; do \ + case "$$i" in \ + *.3*) list="$$list $$i" ;; \ + esac; \ + done; \ + for i in $$list; do \ + if test -f $(srcdir)/$$i; then file=$(srcdir)/$$i; \ + else file=$$i; fi; \ + ext=`echo $$i | sed -e 's/^.*\\.//'`; \ + case "$$ext" in \ + 3*) ;; \ + *) ext='3' ;; \ + esac; \ + inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ + inst=`echo $$inst | sed -e 's/^.*\///'`; \ + inst=`echo $$inst | sed '$(transform)'`.$$ext; \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man3dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man3dir)/$$inst"; \ + done +uninstall-man3: + @$(NORMAL_UNINSTALL) + @list='$(man3_MANS) $(dist_man3_MANS) $(nodist_man3_MANS)'; \ + l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ + for i in $$l2; do \ + case "$$i" in \ + *.3*) list="$$list $$i" ;; \ + esac; \ + done; \ + for i in $$list; do \ + ext=`echo $$i | sed -e 's/^.*\\.//'`; \ + case "$$ext" in \ + 3*) ;; \ + *) ext='3' ;; \ + esac; \ + inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ + inst=`echo $$inst | sed -e 's/^.*\///'`; \ + inst=`echo $$inst | sed '$(transform)'`.$$ext; \ + echo " rm -f '$(DESTDIR)$(man3dir)/$$inst'"; \ + rm -f "$(DESTDIR)$(man3dir)/$$inst"; \ + done +install-man7: $(man7_MANS) $(man_MANS) + @$(NORMAL_INSTALL) + test -z "$(man7dir)" || $(MKDIR_P) "$(DESTDIR)$(man7dir)" + @list='$(man7_MANS) $(dist_man7_MANS) $(nodist_man7_MANS)'; \ + l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ + for i in $$l2; do \ + case "$$i" in \ + *.7*) list="$$list $$i" ;; \ + esac; \ + done; \ + for i in $$list; do \ + if test -f $(srcdir)/$$i; then file=$(srcdir)/$$i; \ + else file=$$i; fi; \ + ext=`echo $$i | sed -e 's/^.*\\.//'`; \ + case "$$ext" in \ + 7*) ;; \ + *) ext='7' ;; \ + esac; \ + inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ + inst=`echo $$inst | sed -e 's/^.*\///'`; \ + inst=`echo $$inst | sed '$(transform)'`.$$ext; \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man7dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man7dir)/$$inst"; \ + done +uninstall-man7: + @$(NORMAL_UNINSTALL) + @list='$(man7_MANS) $(dist_man7_MANS) $(nodist_man7_MANS)'; \ + l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ + for i in $$l2; do \ + case "$$i" in \ + *.7*) list="$$list $$i" ;; \ + esac; \ + done; \ + for i in $$list; do \ + ext=`echo $$i | sed -e 's/^.*\\.//'`; \ + case "$$ext" in \ + 7*) ;; \ + *) ext='7' ;; \ + esac; \ + inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ + inst=`echo $$inst | sed -e 's/^.*\///'`; \ + inst=`echo $$inst | sed '$(transform)'`.$$ext; \ + echo " rm -f '$(DESTDIR)$(man7dir)/$$inst'"; \ + rm -f "$(DESTDIR)$(man7dir)/$$inst"; \ + done +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ + fi; \ + cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ + else \ + test -f $(distdir)/$$file \ + || cp -p $$d/$$file $(distdir)/$$file \ + || exit 1; \ + fi; \ + done + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$(top_distdir)" distdir="$(distdir)" \ + dist-hook +check-am: all-am +check: check-am +all-am: Makefile $(MANS) +installdirs: + for dir in "$(DESTDIR)$(man1dir)" "$(DESTDIR)$(man3dir)" "$(DESTDIR)$(man7dir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." + -test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES) +clean: clean-am + +clean-am: clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: + +html: html-am + +info: info-am + +info-am: + +install-data-am: install-man + +install-dvi: install-dvi-am + +install-exec-am: + +install-html: install-html-am + +install-info: install-info-am + +install-man: install-man1 install-man3 install-man7 + +install-pdf: install-pdf-am + +install-ps: install-ps-am + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic mostlyclean-libtool + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: uninstall-man + +uninstall-man: uninstall-man1 uninstall-man3 uninstall-man7 + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic clean-libtool \ + dist-hook distclean distclean-generic distclean-libtool \ + distdir dvi dvi-am html html-am info info-am install \ + install-am install-data install-data-am install-dvi \ + install-dvi-am install-exec install-exec-am install-html \ + install-html-am install-info install-info-am install-man \ + install-man1 install-man3 install-man7 install-pdf \ + install-pdf-am install-ps install-ps-am install-strip \ + installcheck installcheck-am installdirs maintainer-clean \ + maintainer-clean-generic mostlyclean mostlyclean-generic \ + mostlyclean-libtool pdf pdf-am ps ps-am uninstall uninstall-am \ + uninstall-man uninstall-man1 uninstall-man3 uninstall-man7 + + +dist-hook : $(MAN_DOC) $(MAN_HTML) + +@BUILD_DOC_TRUE@.txt.html: +@BUILD_DOC_TRUE@ asciidoc -d manpage -b xhtml11 -f asciidoc.conf \ +@BUILD_DOC_TRUE@ -azmq_version=@PACKAGE_VERSION@ $< +@BUILD_DOC_TRUE@.txt.xml: +@BUILD_DOC_TRUE@ asciidoc -d manpage -b docbook -f asciidoc.conf \ +@BUILD_DOC_TRUE@ -azmq_version=@PACKAGE_VERSION@ $< +@BUILD_DOC_TRUE@.xml.1: +@BUILD_DOC_TRUE@ xmlto man $< +@BUILD_DOC_TRUE@.xml.3: +@BUILD_DOC_TRUE@ xmlto man $< +@BUILD_DOC_TRUE@.xml.7: +@BUILD_DOC_TRUE@ xmlto man $< +@BUILD_DOC_TRUE@zmq_epgm.7: zmq_pgm.7 +@BUILD_DOC_TRUE@ cp zmq_pgm.7 $@ +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/doc/zmq.7 b/doc/zmq.7 new file mode 100644 index 0000000..56cfe1f --- /dev/null +++ b/doc/zmq.7 @@ -0,0 +1,258 @@ +'\" t +.\" Title: zmq +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ" "7" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq \- 0MQ lightweight messaging kernel +.SH "SYNOPSIS" +.sp +\fB#include \fR +.sp +\fBcc\fR [\fIflags\fR] \fIfiles\fR \fB\-lzmq\fR [\fIlibraries\fR] +.SH "DESCRIPTION" +.sp +The 0MQ lightweight messaging kernel is a library which extends the standard socket interfaces with features traditionally provided by specialised \fImessaging middleware\fR products\&. 0MQ sockets provide an abstraction of asynchronous \fImessage queues\fR, multiple \fImessaging patterns\fR, message filtering (\fIsubscriptions\fR), seamless access to multiple \fItransport protocols\fR and more\&. +.sp +This documentation presents an overview of 0MQ concepts, describes how 0MQ abstracts standard sockets and provides a reference manual for the functions provided by the 0MQ library\&. +.SS "Context" +.sp +Before using any 0MQ library functions the caller must initialise a 0MQ \fIcontext\fR using \fIzmq_init()\fR\&. The following functions are provided to handle initialisation and termination of a \fIcontext\fR: +.PP +Initialise 0MQ context +.RS 4 + +\fBzmq_init\fR(3) +.RE +.PP +Terminate 0MQ context +.RS 4 + +\fBzmq_term\fR(3) +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBThread safety\fR +.RS 4 +.sp +A 0MQ \fIcontext\fR is thread safe and may be shared among as many application threads as the application has requested using the \fIapp_threads\fR parameter to \fIzmq_init()\fR, without any additional locking required on the part of the caller\&. Each 0MQ socket belonging to a particular \fIcontext\fR may only be used by \fBthe thread that created it\fR using \fIzmq_socket()\fR\&. +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBMultiple contexts\fR +.RS 4 +.sp +Multiple \fIcontexts\fR may coexist within a single application\&. Thus, an application can use 0MQ directly and at the same time make use of any number of additional libraries or components which themselves make use of 0MQ as long as the above guidelines regarding thread safety are adhered to\&. +.RE +.SS "Messages" +.sp +A 0MQ message is a discrete unit of data passed between applications or components of the same application\&. 0MQ messages have no internal structure and from the point of view of 0MQ itself they are considered to be opaque binary data\&. +.sp +The following functions are provided to work with messages: +.PP +Initialise a message +.RS 4 + +\fBzmq_msg_init\fR(3) +\fBzmq_msg_init_size\fR(3) +\fBzmq_msg_init_data\fR(3) +.RE +.PP +Release a message +.RS 4 + +\fBzmq_msg_close\fR(3) +.RE +.PP +Access message content +.RS 4 + +\fBzmq_msg_data\fR(3) +\fBzmq_msg_size\fR(3) +.RE +.PP +Message manipulation +.RS 4 + +\fBzmq_msg_copy\fR(3) +\fBzmq_msg_move\fR(3) +.RE +.SS "Sockets" +.sp +0MQ sockets present an abstraction of a asynchronous \fImessage queue\fR, with the exact queueing semantics depending on the socket type in use\&. See \fBzmq_socket\fR(3) for the socket types provided\&. +.sp +The following functions are provided to work with sockets: +.PP +Creating a socket +.RS 4 + +\fBzmq_socket\fR(3) +.RE +.PP +Closing a socket +.RS 4 + +\fBzmq_close\fR(3) +.RE +.PP +Manipulating socket options +.RS 4 + +\fBzmq_getsockopt\fR(3) +\fBzmq_setsockopt\fR(3) +.RE +.PP +Establishing a message flow +.RS 4 + +\fBzmq_bind\fR(3) +\fBzmq_connect\fR(3) +.RE +.PP +Sending and receiving messages +.RS 4 + +\fBzmq_send\fR(3) +\fBzmq_recv\fR(3) +.RE +.PP +\fBInput/output multiplexing\fR. 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 +\fIpoll()\fR +system call, and is described in detail in +\fBzmq_poll\fR(3)\&. +.SS "Transports" +.sp +A 0MQ socket can use multiple different underlying transport mechanisms\&. Each transport mechanism is suited to a particular purpose and has its own advantages and drawbacks\&. +.sp +The following transport mechanisms are provided: +.PP +Unicast transport using TCP +.RS 4 + +\fBzmq_tcp\fR(7) +.RE +.PP +Reliable multicast transport using PGM +.RS 4 + +\fBzmq_pgm\fR(7) +.RE +.PP +Local inter\-process communication transport +.RS 4 + +\fBzmq_ipc\fR(7) +.RE +.PP +Local in\-process (inter\-thread) communication transport +.RS 4 + +\fBzmq_inproc\fR(7) +.RE +.SS "Devices" +.sp +Apart from the 0MQ library the 0MQ distribution includes \fIdevices\fR which are building blocks intended to serve as intermediate nodes in complex messaging topologies\&. +.sp +The following devices are provided: +.PP +Forwarder device for request\-response messaging +.RS 4 + +\fBzmq_queue\fR(1) +.RE +.PP +Forwarder device for publish\-subscribe messaging +.RS 4 + +\fBzmq_forwarder\fR(1) +.RE +.PP +Streamer device for parallelized pipeline messaging +.RS 4 + +\fBzmq_streamer\fR(1) +.RE +.SH "ERROR HANDLING" +.sp +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 (if returning an integer), and the actual error code shall be stored in the \fIerrno\fR variable\&. +.sp +On non\-POSIX systems some users may experience issues with retrieving the correct value of the \fIerrno\fR variable\&. The \fIzmq_errno()\fR function is provided to assist in these cases; for details refer to \fBzmq_errno\fR(3)\&. +.sp +The \fIzmq_strerror()\fR function is provided to translate 0MQ\-specific error codes into error message strings; for details refer to \fBzmq_strerror\fR(3)\&. +.SH "MISCELLANEOUS" +.sp +The following miscellaneous functions are provided: +.PP +Report 0MQ library version +.RS 4 + +\fBzmq_version\fR(3) +.RE +.SH "LANGUAGE BINDINGS" +.sp +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 shall refer to this documentation alongside any documentation provided by the vendor of their language binding\&. +.SS "C++ language binding" +.sp +The 0MQ distribution includes a C++ language binding, which is documented separately in \fBzmq_cpp\fR(7)\&. +.SS "Other language bindings" +.sp +Other language bindings (Python, Ruby, Java and more) are provided by members of the 0MQ community and pointers can be found on the 0MQ website\&. +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "RESOURCES" +.sp +Main web site: \m[blue]\fBhttp://www\&.zeromq\&.org/\fR\m[] +.sp +Report bugs to the 0MQ development mailing list: <\m[blue]\fBzeromq\-dev@lists\&.zeromq\&.org\fR\m[]\&\s-2\u[3]\d\s+2> +.SH "COPYING" +.sp +Free use of this software is granted under the terms of the GNU Lesser General Public License (LGPL)\&. For details see the files COPYING and COPYING\&.LESSER included with the 0MQ distribution\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE +.IP " 3." 4 +zeromq-dev@lists.zeromq.org +.RS 4 +\%mailto:zeromq-dev@lists.zeromq.org +.RE diff --git a/doc/zmq.html b/doc/zmq.html new file mode 100644 index 0000000..934381a --- /dev/null +++ b/doc/zmq.html @@ -0,0 +1,866 @@ + + + + + +zmq(7) + + + + + +
+

SYNOPSIS

+
+

#include <zmq.h>

+

cc [flags] files -lzmq [libraries]

+
+

DESCRIPTION

+
+

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

+

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

+

Context

+

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

+
+
+Initialise ØMQ context +
+
+

+ zmq_init(3) +

+
+
+Terminate ØMQ context +
+
+

+ zmq_term(3) +

+
+
+

Thread safety

+

A ØMQ context is thread safe and may be shared among as many application +threads as the application has requested using the app_threads parameter to +zmq_init(), without any additional locking required on the part of the +caller. Each ØMQ socket belonging to a particular context may only be used +by the thread that created it using zmq_socket().

+

Multiple contexts

+

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

+

Messages

+

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

+

The following functions are provided to work with messages:

+
+
+Initialise a message +
+
+

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

+
+
+Release a message +
+
+

+ zmq_msg_close(3) +

+
+
+Access message content +
+
+

+ zmq_msg_data(3) + zmq_msg_size(3) +

+
+
+Message manipulation +
+
+

+ zmq_msg_copy(3) + zmq_msg_move(3) +

+
+
+

Sockets

+

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

+

The following functions are provided to work with sockets:

+
+
+Creating a socket +
+
+

+ zmq_socket(3) +

+
+
+Closing a socket +
+
+

+ zmq_close(3) +

+
+
+Manipulating socket options +
+
+

+ zmq_getsockopt(3) + zmq_setsockopt(3) +

+
+
+Establishing a message flow +
+
+

+ zmq_bind(3) + zmq_connect(3) +

+
+
+Sending and receiving messages +
+
+

+ zmq_send(3) + zmq_recv(3) +

+
+
+
Input/output multiplexing

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

+

Transports

+

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

+

The following transport mechanisms are provided:

+
+
+Unicast transport using TCP +
+
+

+ zmq_tcp(7) +

+
+
+Reliable multicast transport using PGM +
+
+

+ zmq_pgm(7) +

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

+ zmq_ipc(7) +

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

+ zmq_inproc(7) +

+
+
+

Devices

+

Apart from the ØMQ library the ØMQ distribution includes devices which are +building blocks intended to serve as intermediate nodes in complex messaging +topologies.

+

The following devices are provided:

+
+
+Forwarder device for request-response messaging +
+
+

+ zmq_queue(1) +

+
+
+Forwarder device for publish-subscribe messaging +
+
+

+ zmq_forwarder(1) +

+
+
+Streamer device for parallelized pipeline messaging +
+
+

+ zmq_streamer(1) +

+
+
+
+

ERROR HANDLING

+
+

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

+

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

+

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

+
+

MISCELLANEOUS

+
+

The following miscellaneous functions are provided:

+
+
+Report ØMQ library version +
+
+

+ zmq_version(3) +

+
+
+
+

LANGUAGE BINDINGS

+
+

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

+

C++ language binding

+

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

+

Other language bindings

+

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

+
+

AUTHORS

+
+

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

+
+

RESOURCES

+
+

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

+

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

+
+

COPYING

+
+

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

+
+
+
+ + + diff --git a/doc/zmq.txt b/doc/zmq.txt new file mode 100644 index 0000000..d13f572 --- /dev/null +++ b/doc/zmq.txt @@ -0,0 +1,221 @@ +zmq(7) +====== + + +NAME +---- +zmq - 0MQ lightweight messaging kernel + + +SYNOPSIS +-------- +*#include * + +*cc* ['flags'] 'files' *-lzmq* ['libraries'] + + +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 +asynchronous _message queues_, multiple _messaging patterns_, message +filtering (_subscriptions_), seamless access to multiple _transport protocols_ +and more. + +This documentation presents an overview of 0MQ concepts, describes how 0MQ +abstracts standard sockets and provides a reference manual for the functions +provided by the 0MQ library. + + +Context +~~~~~~~ +Before using any 0MQ library functions the caller must initialise a 0MQ +'context' using _zmq_init()_. The following functions are provided to handle +initialisation and termination of a 'context': + +Initialise 0MQ context:: + linkzmq:zmq_init[3] + +Terminate 0MQ context:: + linkzmq:zmq_term[3] + + +Thread safety +^^^^^^^^^^^^^ +A 0MQ 'context' is thread safe and may be shared among as many application +threads as the application has requested using the _app_threads_ parameter to +_zmq_init()_, without any additional locking required on the part of the +caller. Each 0MQ socket belonging to a particular 'context' may only be used +by *the thread that created it* using _zmq_socket()_. + + +Multiple contexts +^^^^^^^^^^^^^^^^^ +Multiple 'contexts' may coexist within a single application. Thus, an +application can use 0MQ directly and at the same time make use of any number of +additional libraries or components which themselves make use of 0MQ as long as +the above guidelines regarding thread safety are adhered to. + + +Messages +~~~~~~~~ +A 0MQ message is a discrete unit of data passed between applications or +components of the same application. 0MQ messages have no internal structure and +from the point of view of 0MQ itself they are considered to be opaque binary +data. + +The following functions are provided to work with messages: + +Initialise a message:: + linkzmq:zmq_msg_init[3] + linkzmq:zmq_msg_init_size[3] + linkzmq:zmq_msg_init_data[3] + +Release a message:: + linkzmq:zmq_msg_close[3] + +Access message content:: + linkzmq:zmq_msg_data[3] + linkzmq:zmq_msg_size[3] + +Message manipulation:: + linkzmq:zmq_msg_copy[3] + linkzmq:zmq_msg_move[3] + + +Sockets +~~~~~~~ +0MQ sockets present an abstraction of a asynchronous _message queue_, with the +exact queueing semantics depending on the socket type in use. See +linkzmq:zmq_socket[3] for the socket types provided. + +The following functions are provided to work with sockets: + +Creating a socket:: + linkzmq:zmq_socket[3] + +Closing a socket:: + linkzmq:zmq_close[3] + +Manipulating socket options:: + linkzmq:zmq_getsockopt[3] + linkzmq:zmq_setsockopt[3] + +Establishing a message flow:: + linkzmq:zmq_bind[3] + linkzmq:zmq_connect[3] + +Sending and receiving messages:: + linkzmq:zmq_send[3] + linkzmq:zmq_recv[3] + +.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]. + + +Transports +~~~~~~~~~~ +A 0MQ socket can use multiple different underlying transport mechanisms. +Each transport mechanism is suited to a particular purpose and has its own +advantages and drawbacks. + +The following transport mechanisms are provided: + +Unicast transport using TCP:: + linkzmq:zmq_tcp[7] + +Reliable multicast transport using PGM:: + linkzmq:zmq_pgm[7] + +Local inter-process communication transport:: + linkzmq:zmq_ipc[7] + +Local in-process (inter-thread) communication transport:: + linkzmq:zmq_inproc[7] + + +Devices +~~~~~~~ +Apart from the 0MQ library the 0MQ distribution includes 'devices' which are +building blocks intended to serve as intermediate nodes in complex messaging +topologies. + +The following devices are provided: + +Forwarder device for request-response messaging:: + linkzmq:zmq_queue[1] + +Forwarder device for publish-subscribe messaging:: + linkzmq:zmq_forwarder[1] + +Streamer device for parallelized pipeline messaging:: + linkzmq:zmq_streamer[1] + + +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 +(if returning an integer), and the actual error code shall be stored in the +'errno' variable. + +On non-POSIX systems some users may experience issues with retrieving the +correct value of the 'errno' variable. The _zmq_errno()_ function is provided +to assist in these cases; for details refer to linkzmq:zmq_errno[3]. + +The _zmq_strerror()_ function is provided to translate 0MQ-specific error codes +into error message strings; for details refer to linkzmq:zmq_strerror[3]. + + +MISCELLANEOUS +------------- +The following miscellaneous functions are provided: + +Report 0MQ library version:: + linkzmq:zmq_version[3] + + +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 +shall refer to this documentation alongside any documentation provided by the +vendor of their language binding. + + +C++ language binding +~~~~~~~~~~~~~~~~~~~~ +The 0MQ distribution includes a $$C++$$ language binding, which is documented +separately in linkzmq:zmq_cpp[7]. + + +Other language bindings +~~~~~~~~~~~~~~~~~~~~~~~ +Other language bindings (Python, Ruby, Java and more) are provided by members +of the 0MQ community and pointers can be found on the 0MQ website. + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . + + +RESOURCES +--------- +Main web site: + +Report bugs to the 0MQ development mailing list: + + +COPYING +------- +Free use of this software is granted under the terms of the GNU Lesser General +Public License (LGPL). For details see the files `COPYING` and `COPYING.LESSER` +included with the 0MQ distribution. diff --git a/doc/zmq_bind.3 b/doc/zmq_bind.3 new file mode 100644 index 0000000..164989e --- /dev/null +++ b/doc/zmq_bind.3 @@ -0,0 +1,154 @@ +'\" t +.\" Title: zmq_bind +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_BIND" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_bind \- accept connections on a socket +.SH "SYNOPSIS" +.sp +\fBint zmq_bind (void \fR\fB\fI*socket\fR\fR\fB, const char \fR\fB\fI*endpoint\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_bind()\fR function shall create an endpoint for accepting connections and bind it to the socket referenced by the \fIsocket\fR argument\&. +.sp +The \fIendpoint\fR argument is a string consisting of two parts as follows: \fItransport\fR://\fIaddress\fR\&. The \fItransport\fR part specifies the underlying transport protocol to use\&. The meaning of the \fIaddress\fR part is specific to the underlying transport protocol selected\&. +.sp +The following transports are defined: +.PP +\fIinproc\fR +.RS 4 +local in\-process (inter\-thread) communication transport, see +\fBzmq_inproc\fR(7) +.RE +.PP +\fIipc\fR +.RS 4 +local inter\-process communication transport, see +\fBzmq_ipc\fR(7) +.RE +.PP +\fItcp\fR +.RS 4 +unicast transport using TCP, see +\fBzmq_tcp\fR(7) +.RE +.PP +\fIpgm\fR, \fIepgm\fR +.RS 4 +reliable multicast transport using PGM, see +\fBzmq_pgm\fR(7) +.RE +.sp +With the exception of \fIZMQ_PAIR\fR sockets, a single socket may be connected to multiple endpoints using \fIzmq_connect()\fR, while simultaneously accepting incoming connections from multiple endpoints bound to the socket using \fIzmq_bind()\fR\&. Refer to \fBzmq_socket\fR(3) for a description of the exact semantics involved when connecting or binding a socket to multiple endpoints\&. +.SH "RETURN VALUE" +.sp +The \fIzmq_bind()\fR function shall return zero if successful\&. Otherwise it shall return \-1 and set \fIerrno\fR to one of the values defined below\&. +.SH "ERRORS" +.PP +\fBEPROTONOSUPPORT\fR +.RS 4 +The requested +\fItransport\fR +protocol is not supported\&. +.RE +.PP +\fBENOCOMPATPROTO\fR +.RS 4 +The requested +\fItransport\fR +protocol is not compatible with the socket type\&. +.RE +.PP +\fBEADDRINUSE\fR +.RS 4 +The requested +\fIaddress\fR +is already in use\&. +.RE +.PP +\fBEADDRNOTAVAIL\fR +.RS 4 +The requested +\fIaddress\fR +was not local\&. +.RE +.PP +\fBENODEV\fR +.RS 4 +The requested +\fIaddress\fR +specifies a nonexistent interface\&. +.RE +.PP +\fBETERM\fR +.RS 4 +The 0MQ +\fIcontext\fR +associated with the specified +\fIsocket\fR +was terminated\&. +.RE +.SH "EXAMPLE" +.PP +\fBBinding a publisher socket to an in-process and a TCP transport\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +/* Create a ZMQ_PUB socket */ +void *socket = zmq_socket (context, ZMQ_PUB); +assert (socket); +/* Bind it to a in\-process transport with the address \*(Aqmy_publisher\*(Aq */ +int rc = zmq_bind (socket, "inproc://my_publisher"); +assert (rc == 0); +/* Bind it to a TCP transport on port 5555 of the \*(Aqeth0\*(Aq interface */ +rc = zmq_bind (socket, "tcp://eth0:5555"); +assert (rc == 0); +.fi +.if n \{\ +.RE +.\} +.sp +.SH "SEE ALSO" +.sp +\fBzmq_connect\fR(3) \fBzmq_socket\fR(3) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_bind.html b/doc/zmq_bind.html new file mode 100644 index 0000000..5035f0c --- /dev/null +++ b/doc/zmq_bind.html @@ -0,0 +1,729 @@ + + + + + +zmq_bind(3) + + + + + +
+

SYNOPSIS

+
+

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

+
+

DESCRIPTION

+
+

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

+

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

+

The following transports are defined:

+
+
+inproc +
+
+

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

+
+
+ipc +
+
+

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

+
+
+tcp +
+
+

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

+
+
+pgm, epgm +
+
+

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

+
+
+

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

+
+

RETURN VALUE

+
+

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

+
+

ERRORS

+
+
+
+EPROTONOSUPPORT +
+
+

+The requested transport protocol is not supported. +

+
+
+ENOCOMPATPROTO +
+
+

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

+
+
+EADDRINUSE +
+
+

+The requested address is already in use. +

+
+
+EADDRNOTAVAIL +
+
+

+The requested address was not local. +

+
+
+ENODEV +
+
+

+The requested address specifies a nonexistent interface. +

+
+
+ETERM +
+
+

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

+
+
+
+

EXAMPLE

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

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_bind.txt b/doc/zmq_bind.txt new file mode 100644 index 0000000..a74e81d --- /dev/null +++ b/doc/zmq_bind.txt @@ -0,0 +1,87 @@ +zmq_bind(3) +=========== + + +NAME +---- +zmq_bind - accept connections on a socket + + +SYNOPSIS +-------- +*int zmq_bind (void '*socket', const char '*endpoint');* + + +DESCRIPTION +----------- +The _zmq_bind()_ function shall create an endpoint for accepting connections +and bind it to the socket referenced by the 'socket' argument. + +The 'endpoint' argument is a string consisting of two parts as follows: +'transport'`://`'address'. The 'transport' part specifies the underlying +transport protocol to use. The meaning of the 'address' part is specific to +the underlying transport protocol selected. + +The following transports are defined: + +'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7] +'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7] +'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7] +'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7] + +With the exception of 'ZMQ_PAIR' sockets, a single socket may be connected to +multiple endpoints using _zmq_connect()_, while simultaneously accepting +incoming connections from multiple endpoints bound to the socket using +_zmq_bind()_. Refer to linkzmq:zmq_socket[3] for a description of the exact +semantics involved when connecting or binding a socket to multiple endpoints. + + +RETURN VALUE +------------ +The _zmq_bind()_ function shall return zero if successful. Otherwise it shall +return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +*EPROTONOSUPPORT*:: +The requested 'transport' protocol is not supported. +*ENOCOMPATPROTO*:: +The requested 'transport' protocol is not compatible with the socket type. +*EADDRINUSE*:: +The requested 'address' is already in use. +*EADDRNOTAVAIL*:: +The requested 'address' was not local. +*ENODEV*:: +The requested 'address' specifies a nonexistent interface. +*ETERM*:: +The 0MQ 'context' associated with the specified 'socket' was terminated. + + +EXAMPLE +------- +.Binding a publisher socket to an in-process and a TCP transport +---- +/* Create a ZMQ_PUB socket */ +void *socket = zmq_socket (context, ZMQ_PUB); +assert (socket); +/* Bind it to a in-process transport with the address 'my_publisher' */ +int rc = zmq_bind (socket, "inproc://my_publisher"); +assert (rc == 0); +/* Bind it to a TCP transport on port 5555 of the 'eth0' interface */ +rc = zmq_bind (socket, "tcp://eth0:5555"); +assert (rc == 0); +---- + + +SEE ALSO +-------- +linkzmq:zmq_connect[3] +linkzmq:zmq_socket[3] +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_close.3 b/doc/zmq_close.3 new file mode 100644 index 0000000..7ea5e3f --- /dev/null +++ b/doc/zmq_close.3 @@ -0,0 +1,60 @@ +'\" t +.\" Title: zmq_close +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_CLOSE" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_close \- close 0MQ socket +.SH "SYNOPSIS" +.sp +\fBint zmq_close (void \fR\fB\fI*socket\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_close()\fR function shall destroy the socket referenced by the \fIsocket\fR argument\&. All active connections on the socket shall be terminated and resources associated with the socket shall be released\&. Any outstanding messages sent with \fIzmq_send()\fR but not yet physically sent to the network shall be dropped\&. Likewise, any outstanding messages physically received from the network but not yet received by the application with \fIzmq_recv()\fR shall also be dropped\&. +.SH "RETURN VALUE" +.sp +The \fIzmq_close()\fR function shall return zero if successful\&. Otherwise it shall return \-1 and set \fIerrno\fR to one of the values defined below\&. +.SH "ERRORS" +.sp +No errors are defined\&. +.SH "SEE ALSO" +.sp +\fBzmq_socket\fR(3) \fBzmq_term\fR(3) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_close.html b/doc/zmq_close.html new file mode 100644 index 0000000..ebdfa9f --- /dev/null +++ b/doc/zmq_close.html @@ -0,0 +1,625 @@ + + + + + +zmq_close(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_close (void *socket);

+
+

DESCRIPTION

+
+

The zmq_close() function shall destroy the socket referenced by the socket +argument. All active connections on the socket shall be terminated and +resources associated with the socket shall be released. Any outstanding +messages sent with zmq_send() but not yet physically sent to the network +shall be dropped. Likewise, any outstanding messages physically received from +the network but not yet received by the application with zmq_recv() shall +also be dropped.

+
+

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

+
+

No errors are defined.

+
+

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_close.txt b/doc/zmq_close.txt new file mode 100644 index 0000000..f944bda --- /dev/null +++ b/doc/zmq_close.txt @@ -0,0 +1,47 @@ +zmq_close(3) +============ + + +NAME +---- +zmq_close - close 0MQ socket + + +SYNOPSIS +-------- +*int zmq_close (void '*socket');* + + +DESCRIPTION +----------- +The _zmq_close()_ function shall destroy the socket referenced by the 'socket' +argument. All active connections on the socket shall be terminated and +resources associated with the socket shall be released. Any outstanding +messages sent with _zmq_send()_ but not yet physically sent to the network +shall be dropped. Likewise, any outstanding messages physically received from +the network but not yet received by the application with _zmq_recv()_ shall +also be dropped. + + +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 +------ +No errors are defined. + + +SEE ALSO +-------- +linkzmq:zmq_socket[3] +linkzmq:zmq_term[3] +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_connect.3 b/doc/zmq_connect.3 new file mode 100644 index 0000000..69e67c4 --- /dev/null +++ b/doc/zmq_connect.3 @@ -0,0 +1,149 @@ +'\" t +.\" Title: zmq_connect +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_CONNECT" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_connect \- connect a socket +.SH "SYNOPSIS" +.sp +\fBint zmq_connect (void \fR\fB\fI*socket\fR\fR\fB, const char \fR\fB\fI*endpoint\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_connect()\fR function shall connect the socket referenced by the \fIsocket\fR argument to the endpoint specified by the \fIendpoint\fR argument\&. +.sp +The \fIendpoint\fR argument is a string consisting of two parts as follows: \fItransport\fR://\fIaddress\fR\&. The \fItransport\fR part specifies the underlying transport protocol to use\&. The meaning of the \fIaddress\fR part is specific to the underlying transport protocol selected\&. +.sp +The following transports are defined: +.PP +\fIinproc\fR +.RS 4 +local in\-process (inter\-thread) communication transport, see +\fBzmq_inproc\fR(7) +.RE +.PP +\fIipc\fR +.RS 4 +local inter\-process communication transport, see +\fBzmq_ipc\fR(7) +.RE +.PP +\fItcp\fR +.RS 4 +unicast transport using TCP, see +\fBzmq_tcp\fR(7) +.RE +.PP +\fIpgm\fR, \fIepgm\fR +.RS 4 +reliable multicast transport using PGM, see +\fBzmq_pgm\fR(7) +.RE +.sp +With the exception of \fIZMQ_PAIR\fR sockets, a single socket may be connected to multiple endpoints using \fIzmq_connect()\fR, while simultaneously accepting incoming connections from multiple endpoints bound to the socket using \fIzmq_bind()\fR\&. Refer to \fBzmq_socket\fR(3) for a description of the exact semantics involved when connecting or binding a socket to multiple endpoints\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.sp +The connection will not be performed immediately but as needed by 0MQ\&. Thus a successful invocation of \fIzmq_connect()\fR does not indicate that a physical connection was or can actually be established\&. +.sp .5v +.RE +.SH "RETURN VALUE" +.sp +The \fIzmq_connect()\fR function shall return zero if successful\&. Otherwise it shall return \-1 and set \fIerrno\fR to one of the values defined below\&. +.SH "ERRORS" +.PP +\fBEPROTONOSUPPORT\fR +.RS 4 +The requested +\fItransport\fR +protocol is not supported\&. +.RE +.PP +\fBENOCOMPATPROTO\fR +.RS 4 +The requested +\fItransport\fR +protocol is not compatible with the socket type\&. +.RE +.PP +\fBETERM\fR +.RS 4 +The 0MQ +\fIcontext\fR +associated with the specified +\fIsocket\fR +was terminated\&. +.RE +.SH "EXAMPLE" +.PP +\fBConnecting a subscriber socket to an in-process and a TCP transport\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +/* Create a ZMQ_SUB socket */ +void *socket = zmq_socket (context, ZMQ_SUB); +assert (socket); +/* Connect it to an in\-process transport with the address \*(Aqmy_publisher\*(Aq */ +int rc = zmq_connect (socket, "inproc://my_publisher"); +assert (rc == 0); +/* Connect it to the host server001, port 5555 using a TCP transport */ +rc = zmq_connect (socket, "tcp://server001:5555"); +assert (rc == 0); +.fi +.if n \{\ +.RE +.\} +.sp +.SH "SEE ALSO" +.sp +\fBzmq_bind\fR(3) \fBzmq_socket\fR(3) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_connect.html b/doc/zmq_connect.html new file mode 100644 index 0000000..9b7c4e9 --- /dev/null +++ b/doc/zmq_connect.html @@ -0,0 +1,715 @@ + + + + + +zmq_connect(3) + + + + + +
+

SYNOPSIS

+
+

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

+
+

DESCRIPTION

+
+

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

+

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

+

The following transports are defined:

+
+
+inproc +
+
+

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

+
+
+ipc +
+
+

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

+
+
+tcp +
+
+

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

+
+
+pgm, epgm +
+
+

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

+
+
+

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

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

RETURN VALUE

+
+

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

+
+

ERRORS

+
+
+
+EPROTONOSUPPORT +
+
+

+The requested transport protocol is not supported. +

+
+
+ENOCOMPATPROTO +
+
+

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

+
+
+ETERM +
+
+

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

+
+
+
+

EXAMPLE

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

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_connect.txt b/doc/zmq_connect.txt new file mode 100644 index 0000000..0061c37 --- /dev/null +++ b/doc/zmq_connect.txt @@ -0,0 +1,85 @@ +zmq_connect(3) +============== + + +NAME +---- +zmq_connect - connect a socket + + +SYNOPSIS +-------- +*int zmq_connect (void '*socket', const char '*endpoint');* + + +DESCRIPTION +----------- +The _zmq_connect()_ function shall connect the socket referenced by the +'socket' argument to the endpoint specified by the 'endpoint' argument. + +The 'endpoint' argument is a string consisting of two parts as follows: +'transport'`://`'address'. The 'transport' part specifies the underlying +transport protocol to use. The meaning of the 'address' part is specific to +the underlying transport protocol selected. + +The following transports are defined: + +'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7] +'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7] +'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7] +'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7] + +With the exception of 'ZMQ_PAIR' sockets, a single socket may be connected to +multiple endpoints using _zmq_connect()_, while simultaneously accepting +incoming connections from multiple endpoints bound to the socket using +_zmq_bind()_. Refer to linkzmq:zmq_socket[3] for a description of the exact +semantics involved when connecting or binding a socket to multiple endpoints. + +NOTE: The connection will not be performed immediately but as needed by 0MQ. +Thus a successful invocation of _zmq_connect()_ does not indicate that a +physical connection was or can actually be established. + + +RETURN VALUE +------------ +The _zmq_connect()_ function shall return zero if successful. Otherwise it +shall return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +*EPROTONOSUPPORT*:: +The requested 'transport' protocol is not supported. +*ENOCOMPATPROTO*:: +The requested 'transport' protocol is not compatible with the socket type. +*ETERM*:: +The 0MQ 'context' associated with the specified 'socket' was terminated. + + +EXAMPLE +------- +.Connecting a subscriber socket to an in-process and a TCP transport +---- +/* Create a ZMQ_SUB socket */ +void *socket = zmq_socket (context, ZMQ_SUB); +assert (socket); +/* Connect it to an in-process transport with the address 'my_publisher' */ +int rc = zmq_connect (socket, "inproc://my_publisher"); +assert (rc == 0); +/* Connect it to the host server001, port 5555 using a TCP transport */ +rc = zmq_connect (socket, "tcp://server001:5555"); +assert (rc == 0); +---- + + +SEE ALSO +-------- +linkzmq:zmq_bind[3] +linkzmq:zmq_socket[3] +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_cpp.7 b/doc/zmq_cpp.7 new file mode 100644 index 0000000..612ecec --- /dev/null +++ b/doc/zmq_cpp.7 @@ -0,0 +1,400 @@ +'\" t +.\" Title: zmq_cpp +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_CPP" "7" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_cpp \- interface between 0MQ and C++ applications +.SH "SYNOPSIS" +.sp +\fB#include \fR +.sp +\fBc++\fR [\fIflags\fR] \fIfiles\fR \fB\-lzmq\fR [\fIlibraries\fR] +.SH "DESCRIPTION" +.sp +This manual page describes how the 0MQ C++ language binding maps to the underlying 0MQ C library functions\&. +.sp +All 0MQ constants defined by \fIzmq\&.h\fR are also available to the C++ language binding\&. +.sp +The following classes are provided in the \fIzmq\fR namespace: +.SS "Context" +.sp +The \fIcontext_t\fR class encapsulates functionality dealing with the initialisation and termination of a 0MQ \fIcontext\fR\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBConstructor\fR +.RS 4 +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBcontext_t::context_t(int \fR\fB\fIio_threads\fR\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Maps to the \fIzmq_init()\fR function, as described in \fBzmq_init\fR(3)\&. +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBDestructor\fR +.RS 4 +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBcontext_t::~context_t(void)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Maps to the \fIzmq_term()\fR function, as described in \fBzmq_term\fR(3)\&. +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBMethods\fR +.RS 4 +.sp +None\&. +.RE +.SS "Socket" +.sp +The \fIsocket_t\fR class encapsulates a 0MQ socket\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBConstructor\fR +.RS 4 +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBsocket_t::socket_t(context_t \fR\fB\fI&context\fR\fR\fB, int \fR\fB\fItype\fR\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Maps to the \fIzmq_socket()\fR function, as described in \fBzmq_socket\fR(3)\&. +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBDestructor\fR +.RS 4 +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBsocket_t::~socket_t(void)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Calls the \fIzmq_close()\fR function, as described in \fBzmq_close\fR(3)\&. +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBMethods\fR +.RS 4 +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid socket_t::getsockopt(int \fR\fB\fIoption_name\fR\fR\fB, void \fR\fB\fI*option_value\fR\fR\fB, size_t +\fR\fB\fI*option_len\fR\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Maps to the \fIzmq_getsockopt()\fR function, as described in \fBzmq_getsockopt\fR(3)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid socket_t::setsockopt(int \fR\fB\fIoption_name\fR\fR\fB, const void \fR\fB\fI*option_value\fR\fR\fB, size_t +\fR\fB\fIoption_len\fR\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Maps to the \fIzmq_setsockopt()\fR function, as described in \fBzmq_setsockopt\fR(3)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid socket_t::bind(const char \fR\fB\fI*endpoint\fR\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Maps to the \fIzmq_bind()\fR function, as described in \fBzmq_bind\fR(3)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid socket_t::connect(const char \fR\fB\fI*endpoint\fR\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Maps to the \fIzmq_connect()\fR function, as described in \fBzmq_connect\fR(3)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool socket_t::send(message_t \fR\fB\fI&msg\fR\fR\fB, int \fR\fB\fIflags\fR\fR\fB = 0)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Maps to the \fIzmq_send()\fR function, as described in \fBzmq_send\fR(3)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool socket_t::recv(message_t \fR\fB\fI*msg\fR\fR\fB, int \fR\fB\fIflags\fR\fR\fB = 0)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Maps to the \fIzmq_recv()\fR function, as described in \fBzmq_recv\fR(3)\&. +.RE +.SS "Message" +.sp +The \fIzmq::message_t\fR class encapsulates the \fIzmq_msg_t\fR structure and functions to construct, destruct and manipulate 0MQ messages\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBConstructor\fR +.RS 4 +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBmessage_t::message_t(void)\fR +\fBmessage_t::message_t(size_t \fR\fB\fIsize\fR\fR\fB)\fR +\fBmessage_t::message_t(void \fR\fB\fI*data\fR\fR\fB, size_t \fR\fB\fIsize\fR\fR\fB, free_fn \fR\fB\fI*ffn\fR\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +These map to the \fIzmq_msg_init()\fR, \fIzmq_msg_init_size()\fR and \fIzmq_msg_init_data()\fR functions, described in \fBzmq_msg_init\fR(3), \fBzmq_msg_init_size\fR(3) and \fBzmq_msg_init_data\fR(3) respectively\&. +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBDestructor\fR +.RS 4 +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBmessage_t::~message_t(void)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Calls the \fIzmq_msg_close()\fR function, as described in \fBzmq_msg_close\fR(3)\&. +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBMethods\fR +.RS 4 +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid *message_t::data (void)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Maps to the \fIzmq_msg_data()\fR function, as described in \fBzmq_msg_data\fR(3)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBsize_t message_t::size (void)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Maps to the \fIzmq_msg_size()\fR function, as described in \fBzmq_msg_size\fR(3)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid message_t::copy (message_t \fR\fB\fI*src\fR\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Maps to the \fIzmq_msg_copy()\fR function, as described in \fBzmq_msg_copy\fR(3)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid message_t::move (message_t \fR\fB\fI*src\fR\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Maps to the \fIzmq_msg_move()\fR function, as described in \fBzmq_msg_move\fR(3)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBmessage_t::rebuild(void)\fR +\fBmessage_t::rebuild(size_t \fR\fB\fIsize\fR\fR\fB)\fR +\fBmessage_t::rebuild(void \fR\fB\fI*data\fR\fR\fB, size_t \fR\fB\fIsize\fR\fR\fB, free_fn \fR\fB\fI*ffn\fR\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Equivalent to calling the \fIzmq_msg_close()\fR function followed by the corresponding \fIzmq_msg_init()\fR function\&. +.RE +.SS "Input/output multiplexing" +.sp +The \fIpoll()\fR function is a namespaced equivalent of the \fIzmq_poll()\fR function, as described in \fBzmq_poll\fR(3)\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.sp +To obtain a 0MQ \fIsocket\fR for use in a \fIzmq_pollitem_t\fR structure, you should cast an instance of the \fIsocket_t\fR class to (void *)\&. +.sp .5v +.RE +.SH "ERROR HANDLING" +.sp +All errors reported by the underlying 0MQ C library functions are automatically converted to exceptions by the C++ language binding\&. The \fIzmq::error_t\fR class is derived from the \fIstd::exception\fR class and uses the \fIzmq_strerror()\fR function to convert the error code to human\-readable string\&. +.SH "EXAMPLE" +.sp +.if n \{\ +.RS 4 +.\} +.nf +zmq::context_t ctx (1); +zmq::socket_t s (ctx, ZMQ_PUB); +s\&.connect ("tcp://192\&.168\&.0\&.115:5555"); +zmq::message_t msg (100); +memset (msg\&.data (), 0, 100); +s\&.send (msg); +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.sp +\fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_cpp.html b/doc/zmq_cpp.html new file mode 100644 index 0000000..c373f8e --- /dev/null +++ b/doc/zmq_cpp.html @@ -0,0 +1,758 @@ + + + + + +zmq_cpp(7) + + + + + +
+

SYNOPSIS

+
+

#include <zmq.hpp>

+

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

+
+

DESCRIPTION

+
+

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

+

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

+

The following classes are provided in the zmq namespace:

+

Context

+

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

+

Constructor

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

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

+

Destructor

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

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

+

Methods

+

None.

+

Socket

+

The socket_t class encapsulates a ØMQ socket.

+

Constructor

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

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

+

Destructor

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

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

+

Methods

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

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

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

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

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

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

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

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

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

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

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

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

+

Message

+

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

+

Constructor

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

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

+

Destructor

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

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

+

Methods

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

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

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

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

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

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

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

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

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

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

+

Input/output multiplexing

+

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

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

ERROR HANDLING

+
+

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

+
+

EXAMPLE

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

SEE ALSO

+
+

zmq(7)

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_cpp.txt b/doc/zmq_cpp.txt new file mode 100644 index 0000000..b7a5a42 --- /dev/null +++ b/doc/zmq_cpp.txt @@ -0,0 +1,206 @@ +zmq_cpp(7) +========== + + +NAME +---- +zmq_cpp - interface between 0MQ and C++ applications + + +SYNOPSIS +-------- +*#include * + +*c$$++$$* ['flags'] 'files' *-lzmq* ['libraries'] + + +DESCRIPTION +----------- +This manual page describes how the 0MQ C++ language binding maps to the +underlying 0MQ C library functions. + +All 0MQ constants defined by _zmq.h_ are also available to the C++ language +binding. + +The following classes are provided in the 'zmq' namespace: + + +Context +~~~~~~~ +The 'context_t' class encapsulates functionality dealing with the +initialisation and termination of a 0MQ _context_. + + +Constructor +^^^^^^^^^^^ +[verse] +*context_t::context_t(int 'io_threads')* + +Maps to the _zmq_init()_ function, as described in linkzmq:zmq_init[3]. + +Destructor +^^^^^^^^^^ +[verse] +*context_t::~context_t(void)* + +Maps to the _zmq_term()_ function, as described in linkzmq:zmq_term[3]. + + +Methods +^^^^^^^ +None. + + +Socket +~~~~~~ +The 'socket_t' class encapsulates a 0MQ socket. + + +Constructor +^^^^^^^^^^^ +[verse] +*socket_t::socket_t(context_t '&context', int 'type')* + +Maps to the _zmq_socket()_ function, as described in linkzmq:zmq_socket[3]. + + +Destructor +^^^^^^^^^^ +[verse] +*socket_t::~socket_t(void)* + +Calls the _zmq_close()_ function, as described in linkzmq:zmq_close[3]. + + +Methods +^^^^^^^ +[verse] +*void socket_t::getsockopt(int 'option_name', void '*option_value', size_t +'*option_len')* + +Maps to the _zmq_getsockopt()_ function, as described in +linkzmq:zmq_getsockopt[3]. + +[verse] +*void socket_t::setsockopt(int 'option_name', const void '*option_value', size_t +'option_len')* + +Maps to the _zmq_setsockopt()_ function, as described in +linkzmq:zmq_setsockopt[3]. + +[verse] +*void socket_t::bind(const char '*endpoint')* + +Maps to the _zmq_bind()_ function, as described in linkzmq:zmq_bind[3]. + +[verse] +*void socket_t::connect(const char '*endpoint')* + +Maps to the _zmq_connect()_ function, as described in linkzmq:zmq_connect[3]. + +[verse] +*bool socket_t::send(message_t '&msg', int 'flags' = 0)* + +Maps to the _zmq_send()_ function, as described in linkzmq:zmq_send[3]. + +[verse] +*bool socket_t::recv(message_t '*msg', int 'flags' = 0)* + +Maps to the _zmq_recv()_ function, as described in linkzmq:zmq_recv[3]. + + +Message +~~~~~~~ +The 'zmq::message_t' class encapsulates the 'zmq_msg_t' structure and +functions to construct, destruct and manipulate 0MQ messages. + + +Constructor +^^^^^^^^^^^ +[verse] +*message_t::message_t(void)* +*message_t::message_t(size_t 'size')* +*message_t::message_t(void '*data', size_t 'size', free_fn '*ffn')* + +These map to the _zmq_msg_init()_, _zmq_msg_init_size()_ and +_zmq_msg_init_data()_ functions, described in linkzmq:zmq_msg_init[3], +linkzmq:zmq_msg_init_size[3] and linkzmq:zmq_msg_init_data[3] respectively. + + +Destructor +^^^^^^^^^^ +[verse] +*message_t::~message_t(void)* + +Calls the _zmq_msg_close()_ function, as described in linkzmq:zmq_msg_close[3]. + + +Methods +^^^^^^^ +[verse] +*void *message_t::data (void)* + +Maps to the _zmq_msg_data()_ function, as described in linkzmq:zmq_msg_data[3]. + +[verse] +*size_t message_t::size (void)* + +Maps to the _zmq_msg_size()_ function, as described in linkzmq:zmq_msg_size[3]. + +[verse] +*void message_t::copy (message_t '*src')* + +Maps to the _zmq_msg_copy()_ function, as described in linkzmq:zmq_msg_copy[3]. + +[verse] +*void message_t::move (message_t '*src')* + +Maps to the _zmq_msg_move()_ function, as described in linkzmq:zmq_msg_move[3]. + +[verse] +*message_t::rebuild(void)* +*message_t::rebuild(size_t 'size')* +*message_t::rebuild(void '*data', size_t 'size', free_fn '*ffn')* + +Equivalent to calling the _zmq_msg_close()_ function followed by the +corresponding _zmq_msg_init()_ function. + + +Input/output multiplexing +~~~~~~~~~~~~~~~~~~~~~~~~~ +The _poll()_ function is a namespaced equivalent of the _zmq_poll()_ function, +as described in linkzmq:zmq_poll[3]. + +NOTE: To obtain a 0MQ _socket_ for use in a _zmq_pollitem_t_ structure, you +should cast an instance of the _socket_t_ class to `(void *)`. + + +ERROR HANDLING +-------------- +All errors reported by the underlying 0MQ C library functions are automatically +converted to exceptions by the C++ language binding. The 'zmq::error_t' class +is derived from the 'std::exception' class and uses the _zmq_strerror()_ +function to convert the error code to human-readable string. + + +EXAMPLE +------- +---- +zmq::context_t ctx (1); +zmq::socket_t s (ctx, ZMQ_PUB); +s.connect ("tcp://192.168.0.115:5555"); +zmq::message_t msg (100); +memset (msg.data (), 0, 100); +s.send (msg); +---- + + +SEE ALSO +-------- +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_epgm.7 b/doc/zmq_epgm.7 new file mode 100644 index 0000000..98318ad --- /dev/null +++ b/doc/zmq_epgm.7 @@ -0,0 +1,207 @@ +'\" t +.\" Title: zmq_pgm +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_PGM" "7" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_pgm \- 0MQ reliable multicast transport using PGM +.SH "SYNOPSIS" +.sp +PGM (Pragmatic General Multicast) is a protocol for reliable multicast transport of data over IP networks\&. +.SH "DESCRIPTION" +.sp +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 \fIpgm\fR transport) and "Encapsulated PGM" where PGM datagrams are encapsulated inside UDP datagrams (the \fIepgm\fR transport)\&. +.sp +The \fIpgm\fR and \fIepgm\fR transports can only be used with the \fIZMQ_PUB\fR and \fIZMQ_SUB\fR socket types\&. +.sp +Further, PGM sockets are rate limited by default and incur a performance penalty when used over a loopback interface\&. For details, refer to the \fIZMQ_RATE\fR, \fIZMQ_RECOVERY_IVL\fR and \fIZMQ_MCAST_LOOP\fR options documented in \fBzmq_setsockopt\fR(3)\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.sp +The \fIpgm\fR transport implementation requires access to raw IP sockets\&. Additional privileges may be required on some operating systems for this operation\&. Applications not requiring direct interoperability with other PGM implementations are encouraged to use the \fIepgm\fR transport instead which does not require any special privileges\&. +.sp .5v +.RE +.SH "ADDRESSING" +.sp +A 0MQ address string consists of two parts as follows: \fItransport\fR://\fIendpoint\fR\&. The \fItransport\fR part specifies the underlying transport protocol to use\&. For the standard PGM protocol, \fItransport\fR shall be set to pgm\&. For the "Encapsulated PGM" protocol \fItransport\fR shall be set to epgm\&. The meaning of the \fIendpoint\fR part for both the \fIpgm\fR and \fIepgm\fR transport is defined below\&. +.SS "Connecting a socket" +.sp +When connecting a socket to a peer address using \fIzmq_connect()\fR with the \fIpgm\fR or \fIepgm\fR transport, the \fIendpoint\fR shall be interpreted as an \fIinterface\fR followed by a semicolon, followed by a \fImulticast address\fR, followed by a colon and a port number\&. +.sp +An \fIinterface\fR may be specified by either of the following: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The interface name as defined by the operating system\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The primary IPv4 address assigned to the interface, in it\(cqs numeric representation\&. +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.sp +Interface names are not standardised in any way and should be assumed to be arbitrary and platform dependent\&. On Win32 platforms no short interface names exist, thus only the primary IPv4 address may be used to specify an \fIinterface\fR\&. +.sp .5v +.RE +.sp +A \fImulticast address\fR is specified by an IPv4 multicast address in it\(cqs numeric representation\&. +.SH "WIRE FORMAT" +.sp +Consecutive PGM datagrams are interpreted by 0MQ as a single continous 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 \fIframes\fR as described in \fBzmq_tcp\fR(7)\&. +.SS "PGM datagram payload" +.sp +The following ABNF grammar represents the payload of a single PGM datagram as used by 0MQ: +.sp +.if n \{\ +.RS 4 +.\} +.nf +datagram = (offset data) +offset = 2OCTET +data = *OCTET +.fi +.if n \{\ +.RE +.\} +.sp +In order for late joining consumers to be able to identify message boundaries, each PGM datagram payload starts with a 16\-bit unsigned integer in network byte order specifying either the offset of the first message \fIframe\fR in the datagram or containing the value 0xFFFF if the datagram contains solely an intermediate part of a larger message\&. +.sp +The following diagram illustrates the layout of a single PGM datagram payload: +.sp +.if n \{\ +.RS 4 +.\} +.nf ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +| offset (16 bits) | data | ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +.fi +.if n \{\ +.RE +.\} +.sp +The following diagram further illustrates how three example 0MQ frames are laid out in consecutive PGM datagram payloads: +.sp +.if n \{\ +.RS 4 +.\} +.nf +First datagram payload ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +| Frame offset | Frame 1 | Frame 2, part 1 | +| 0x0000 | (Message 1) | (Message 2, part 1) | ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ + +Second datagram payload ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +| Frame offset | Frame 2, part 2 | +| 0xFFFF | (Message 2, part 2) | ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ + +Third datagram payload ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+ +| Frame offset | Frame 2, final 8 bytes | Frame 3 | +| 0x0008 | (Message 2, final 8 bytes) | (Message 3) | ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+ +.fi +.if n \{\ +.RE +.\} +.SH "EXAMPLE" +.PP +\fBConnecting a socket\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +/* Connecting to the multicast address 239\&.192\&.1\&.1, port 5555, */ +/* using the first ethernet network interface on Linux */ +/* and the Encapsulated PGM protocol */ +rc = zmq_connect(socket, "epgm://eth0;239\&.192\&.1\&.1:5555"); +assert (rc == 0); +/* Connecting to the multicast address 239\&.192\&.1\&.1, port 5555, */ +/* using the network interface with the address 192\&.168\&.1\&.1 */ +/* and the standard PGM protocol */ +rc = zmq_connect(socket, "pgm://192\&.168\&.1\&.1;239\&.192\&.1\&.1:5555"); +assert (rc == 0); +.fi +.if n \{\ +.RE +.\} +.sp +.SH "SEE ALSO" +.sp +\fBzmq_connect\fR(3) \fBzmq_setsockopt\fR(3) \fBzmq_tcp\fR(7) \fBzmq_ipc\fR(7) \fBzmq_inproc\fR(7) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_epgm.html b/doc/zmq_epgm.html new file mode 100644 index 0000000..456fcdf --- /dev/null +++ b/doc/zmq_epgm.html @@ -0,0 +1,744 @@ + + + + + +zmq_pgm(7) + + + + + +
+

SYNOPSIS

+
+

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

+
+

DESCRIPTION

+
+

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

+

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

+

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

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

ADDRESSING

+
+

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

+

Connecting a socket

+

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

+

An interface may be specified by either of the following:

+
    +
  • +

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

    +
    • +
  • +

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

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

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

+
+

WIRE FORMAT

+
+

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

+

PGM datagram payload

+

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

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

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

+

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

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

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

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

EXAMPLE

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

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_epgm.txt b/doc/zmq_epgm.txt new file mode 100644 index 0000000..4017db2 --- /dev/null +++ b/doc/zmq_epgm.txt @@ -0,0 +1,157 @@ +zmq_pgm(7) +========== + + +NAME +---- +zmq_pgm - 0MQ reliable multicast transport using PGM + + +SYNOPSIS +-------- +PGM (Pragmatic General Multicast) is a protocol for reliable multicast +transport of data over IP networks. + + +DESCRIPTION +----------- +0MQ implements two variants of PGM, the standard protocol where PGM datagrams +are layered directly on top of IP datagrams as defined by RFC 3208 (the 'pgm' +transport) and "Encapsulated PGM" where PGM datagrams are encapsulated inside +UDP datagrams (the 'epgm' transport). + +The 'pgm' and 'epgm' transports can only be used with the 'ZMQ_PUB' and +'ZMQ_SUB' socket types. + +Further, PGM sockets are rate limited by default and incur a performance +penalty when used over a loopback interface. For details, refer to the +'ZMQ_RATE', 'ZMQ_RECOVERY_IVL' and 'ZMQ_MCAST_LOOP' options documented in +linkzmq:zmq_setsockopt[3]. + +CAUTION: The 'pgm' transport implementation requires access to raw IP sockets. +Additional privileges may be required on some operating systems for this +operation. Applications not requiring direct interoperability with other PGM +implementations are encouraged to use the 'epgm' transport instead which does +not require any special privileges. + + +ADDRESSING +---------- +A 0MQ address string consists of two parts as follows: +'transport'`://`'endpoint'. The 'transport' part specifies the underlying +transport protocol to use. For the standard PGM protocol, 'transport' shall be +set to `pgm`. For the "Encapsulated PGM" protocol 'transport' shall be set to +`epgm`. The meaning of the 'endpoint' part for both the 'pgm' and 'epgm' +transport is defined below. + + +Connecting a socket +~~~~~~~~~~~~~~~~~~~ +When connecting a socket to a peer address using _zmq_connect()_ with the 'pgm' +or 'epgm' transport, the 'endpoint' shall be interpreted as an 'interface' +followed by a semicolon, followed by a 'multicast address', followed by a colon +and a port number. + +An 'interface' may be specified by either of the following: + +* The interface name as defined by the operating system. +* The primary IPv4 address assigned to the interface, in it's numeric + representation. + +NOTE: Interface names are not standardised in any way and should be assumed to +be arbitrary and platform dependent. On Win32 platforms no short interface +names exist, thus only the primary IPv4 address may be used to specify an +'interface'. + +A 'multicast address' is specified by an IPv4 multicast address in it's numeric +representation. + + +WIRE FORMAT +----------- +Consecutive PGM datagrams are interpreted by 0MQ as a single continous 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]. + + +PGM datagram payload +~~~~~~~~~~~~~~~~~~~~ +The following ABNF grammar represents the payload of a single PGM datagram as +used by 0MQ: + +.... +datagram = (offset data) +offset = 2OCTET +data = *OCTET +.... + +In order for late joining consumers to be able to identify message boundaries, +each PGM datagram payload starts with a 16-bit unsigned integer in network byte +order specifying either the offset of the first message 'frame' in the datagram +or containing the value `0xFFFF` if the datagram contains solely an +intermediate part of a larger message. + +The following diagram illustrates the layout of a single PGM datagram payload: + +.... ++------------------+----------------------+ +| offset (16 bits) | data | ++------------------+----------------------+ +.... + +The following diagram further illustrates how three example 0MQ frames are laid +out in consecutive PGM datagram payloads: + +.... +First datagram payload ++--------------+-------------+---------------------+ +| Frame offset | Frame 1 | Frame 2, part 1 | +| 0x0000 | (Message 1) | (Message 2, part 1) | ++--------------+-------------+---------------------+ + +Second datagram payload ++--------------+---------------------+ +| Frame offset | Frame 2, part 2 | +| 0xFFFF | (Message 2, part 2) | ++--------------+---------------------+ + +Third datagram payload ++--------------+----------------------------+-------------+ +| Frame offset | Frame 2, final 8 bytes | Frame 3 | +| 0x0008 | (Message 2, final 8 bytes) | (Message 3) | ++--------------+----------------------------+-------------+ +.... + + +EXAMPLE +------- +.Connecting a socket +---- +/* Connecting to the multicast address 239.192.1.1, port 5555, */ +/* using the first ethernet network interface on Linux */ +/* and the Encapsulated PGM protocol */ +rc = zmq_connect(socket, "epgm://eth0;239.192.1.1:5555"); +assert (rc == 0); +/* Connecting to the multicast address 239.192.1.1, port 5555, */ +/* using the network interface with the address 192.168.1.1 */ +/* and the standard PGM protocol */ +rc = zmq_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555"); +assert (rc == 0); +---- + + +SEE ALSO +-------- +linkzmq:zmq_connect[3] +linkzmq:zmq_setsockopt[3] +linkzmq:zmq_tcp[7] +linkzmq:zmq_ipc[7] +linkzmq:zmq_inproc[7] +linkzmq:zmq[7] + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_errno.3 b/doc/zmq_errno.3 new file mode 100644 index 0000000..071cbc8 --- /dev/null +++ b/doc/zmq_errno.3 @@ -0,0 +1,78 @@ +'\" t +.\" Title: zmq_errno +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_ERRNO" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_errno \- retrieve value of errno for the calling thread +.SH "SYNOPSIS" +.sp +\fBint zmq_errno (void);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_errno()\fR function shall retrieve the value of the \fIerrno\fR variable for the calling thread\&. +.sp +The \fIzmq_errno()\fR function is provided to assist users on non\-POSIX systems who are experiencing issues with retrieving the correct value of \fIerrno\fR directly\&. Specifically, users on Win32 systems whose application is using a different C runtime library from the C runtime library in use by 0MQ will need to use \fIzmq_errno()\fR for correct operation\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBImportant\fR +.ps -1 +.br +.sp +Users not experiencing issues with retrieving the correct value of \fIerrno\fR should not use this function and should instead access the \fIerrno\fR variable directly\&. +.sp .5v +.RE +.SH "RETURN VALUE" +.sp +The \fIzmq_errno()\fR function shall return the value of the \fIerrno\fR variable for the calling thread\&. +.SH "ERRORS" +.sp +No errors are defined\&. +.SH "SEE ALSO" +.sp +\fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_errno.html b/doc/zmq_errno.html new file mode 100644 index 0000000..56a470e --- /dev/null +++ b/doc/zmq_errno.html @@ -0,0 +1,633 @@ + + + + + +zmq_errno(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_errno (void);

+
+

DESCRIPTION

+
+

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

+

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

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

RETURN VALUE

+
+

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

+
+

ERRORS

+
+

No errors are defined.

+
+

SEE ALSO

+
+

zmq(7)

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_errno.txt b/doc/zmq_errno.txt new file mode 100644 index 0000000..61939a5 --- /dev/null +++ b/doc/zmq_errno.txt @@ -0,0 +1,50 @@ +zmq_errno(3) +============ + + +NAME +---- +zmq_errno - retrieve value of errno for the calling thread + + +SYNOPSIS +-------- +*int zmq_errno (void);* + + +DESCRIPTION +----------- +The _zmq_errno()_ function shall retrieve the value of the 'errno' variable for +the calling thread. + +The _zmq_errno()_ function is provided to assist users on non-POSIX systems who +are experiencing issues with retrieving the correct value of 'errno' directly. +Specifically, users on Win32 systems whose application is using a different C +runtime library from the C runtime library in use by 0MQ will need to use +_zmq_errno()_ for correct operation. + +IMPORTANT: Users not experiencing issues with retrieving the correct value of +'errno' should not use this function and should instead access the 'errno' +variable directly. + + +RETURN VALUE +------------ +The _zmq_errno()_ function shall return the value of the 'errno' variable for +the calling thread. + + +ERRORS +------ +No errors are defined. + + +SEE ALSO +-------- +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_forwarder.1 b/doc/zmq_forwarder.1 new file mode 100644 index 0000000..3b22d3e --- /dev/null +++ b/doc/zmq_forwarder.1 @@ -0,0 +1,57 @@ +'\" t +.\" Title: zmq_forwarder +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_FORWARDER" "1" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_forwarder \- forwarding device for publish\-subscribe messaging +.SH "SYNOPSIS" +.sp +To be written\&. +.SH "DESCRIPTION" +.sp +To be written\&. +.SH "OPTIONS" +.sp +To be written\&. +.SH "SEE ALSO" +.sp +\fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_forwarder.html b/doc/zmq_forwarder.html new file mode 100644 index 0000000..c123dd8 --- /dev/null +++ b/doc/zmq_forwarder.html @@ -0,0 +1,612 @@ + + + + + +zmq_forwarder(1) + + + + + +
+

SYNOPSIS

+
+

To be written.

+
+

DESCRIPTION

+
+

To be written.

+
+

OPTIONS

+
+

To be written.

+
+

SEE ALSO

+
+

zmq(7)

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_forwarder.txt b/doc/zmq_forwarder.txt new file mode 100644 index 0000000..b3325f2 --- /dev/null +++ b/doc/zmq_forwarder.txt @@ -0,0 +1,33 @@ +zmq_forwarder(1) +================ + + +NAME +---- +zmq_forwarder - forwarding device for publish-subscribe messaging + + +SYNOPSIS +-------- +To be written. + + +DESCRIPTION +----------- +To be written. + + +OPTIONS +------- +To be written. + + +SEE ALSO +-------- +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_getsockopt.3 b/doc/zmq_getsockopt.3 new file mode 100644 index 0000000..90edfd4 --- /dev/null +++ b/doc/zmq_getsockopt.3 @@ -0,0 +1,505 @@ +'\" t +.\" Title: zmq_getsockopt +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_GETSOCKOPT" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_getsockopt \- get 0MQ socket options +.SH "SYNOPSIS" +.sp +\fBint zmq_getsockopt (void \fR\fB\fI*socket\fR\fR\fB, int \fR\fB\fIoption_name\fR\fR\fB, void \fR\fB\fI*option_value\fR\fR\fB, size_t \fR\fB\fI*option_len\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_getsockopt()\fR function shall retrieve the value for the option specified by the \fIoption_name\fR argument for the 0MQ socket pointed to by the \fIsocket\fR argument, and store it in the buffer pointed to by the \fIoption_value\fR argument\&. The \fIoption_len\fR argument is the size in bytes of the buffer pointed to by \fIoption_value\fR; upon successful completion \fIzmq_getsockopt()\fR shall modify the \fIoption_value\fR argument to indicate the actual size of the option value stored in the buffer\&. +.sp +The following options can be retrieved with the \fIzmq_getsockopt()\fR function: +.SS "ZMQ_RCVMORE: More message parts to follow" +.sp +The \fIZMQ_RCVMORE\fR option shall return a boolean value indicating if the multi\-part message currently being read from the specified \fIsocket\fR has more message parts to follow\&. If there are no message parts to follow or if the message currently being read is not a multi\-part message a value of zero shall be returned\&. Otherwise, a value of 1 shall be returned\&. +.sp +Refer to \fBzmq_send\fR(3) and \fBzmq_recv\fR(3) for a detailed description of sending/receiving multi\-part messages\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +int64_t +T} +T{ +.sp +Option value unit +T}:T{ +.sp +boolean +T} +T{ +.sp +Default value +T}:T{ +.sp +N/A +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +all +T} +.TE +.sp 1 +.SS "ZMQ_HWM: Retrieve high water mark" +.sp +The \fIZMQ_HWM\fR option shall retrieve the high water mark for the specified \fIsocket\fR\&. The high water mark is a hard limit on the maximum number of outstanding messages 0MQ shall queue in memory for any single peer that the specified \fIsocket\fR is communicating with\&. +.sp +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 \fBzmq_socket\fR(3) for details on the exact action taken for each socket type\&. +.sp +The default \fIZMQ_HWM\fR value of zero means "no limit"\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +int64_t +T} +T{ +.sp +Option value unit +T}:T{ +.sp +messages +T} +T{ +.sp +Default value +T}:T{ +.sp +0 +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +all +T} +.TE +.sp 1 +.SS "ZMQ_SWAP: Retrieve disk offload size" +.sp +The \fIZMQ_SWAP\fR option shall retrieve the disk offload (swap) size for the specified \fIsocket\fR\&. A socket which has \fIZMQ_SWAP\fR set to a non\-zero value may exceed it\(cqs high water mark; in this case outstanding messages shall be offloaded to storage on disk rather than held in memory\&. +.sp +The value of \fIZMQ_SWAP\fR defines the maximum size of the swap space in bytes\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +int64_t +T} +T{ +.sp +Option value unit +T}:T{ +.sp +bytes +T} +T{ +.sp +Default value +T}:T{ +.sp +0 +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +all +T} +.TE +.sp 1 +.SS "ZMQ_AFFINITY: Retrieve I/O thread affinity" +.sp +The \fIZMQ_AFFINITY\fR option shall retrieve the I/O thread affinity for newly created connections on the specified \fIsocket\fR\&. +.sp +Affinity determines which threads from the 0MQ I/O thread pool associated with the socket\(cqs \fIcontext\fR shall handle newly created connections\&. A value of zero specifies no affinity, meaning that work shall be distributed fairly among all 0MQ I/O threads in the thread pool\&. For non\-zero values, the lowest bit corresponds to thread 1, second lowest bit to thread 2 and so on\&. For example, a value of 3 specifies that subsequent connections on \fIsocket\fR shall be handled exclusively by I/O threads 1 and 2\&. +.sp +See also \fBzmq_init\fR(3) for details on allocating the number of I/O threads for a specific \fIcontext\fR\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +int64_t +T} +T{ +.sp +Option value unit +T}:T{ +.sp +N/A (bitmap) +T} +T{ +.sp +Default value +T}:T{ +.sp +0 +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +N/A +T} +.TE +.sp 1 +.SS "ZMQ_IDENTITY: Retrieve socket identity" +.sp +The \fIZMQ_IDENTITY\fR option shall retrieve the identity of the specified \fIsocket\fR\&. Socket identity determines if existing 0MQ infastructure (\fImessage queues\fR, \fIforwarding devices\fR) shall be identified with a specific application and persist across multiple runs of the application\&. +.sp +If the socket has no identity, each run of an application is completely separate from other runs\&. However, with identity set the socket shall re\-use any existing 0MQ infrastructure configured by the previous run(s)\&. Thus the application may receive messages that were sent in the meantime, \fImessage queue\fR limits shall be shared with previous run(s) and so on\&. +.sp +Identity can be at least one byte and at most 255 bytes long\&. Identities starting with binary zero are reserved for use by 0MQ infrastructure\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +binary data +T} +T{ +.sp +Option value unit +T}:T{ +.sp +N/A +T} +T{ +.sp +Default value +T}:T{ +.sp +NULL +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +all +T} +.TE +.sp 1 +.SS "ZMQ_RATE: Retrieve multicast data rate" +.sp +The \fIZMQ_RATE\fR option shall retrieve the maximum send or receive data rate for multicast transports using the specified \fIsocket\fR\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +uint64_t +T} +T{ +.sp +Option value unit +T}:T{ +.sp +kilobits per second +T} +T{ +.sp +Default value +T}:T{ +.sp +100 +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +all, when using multicast transports +T} +.TE +.sp 1 +.SS "ZMQ_RECOVERY_IVL: Get multicast recovery interval" +.sp +The \fIZMQ_RECOVERY_IVL\fR option shall retrieve the recovery interval for multicast transports using the specified \fIsocket\fR\&. The recovery interval determines the maximum time in seconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +uint64_t +T} +T{ +.sp +Option value unit +T}:T{ +.sp +seconds +T} +T{ +.sp +Default value +T}:T{ +.sp +10 +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +all, when using multicast transports +T} +.TE +.sp 1 +.SS "ZMQ_MCAST_LOOP: Control multicast loopback" +.sp +The \fIZMQ_MCAST_LOOP\fR option controls whether data sent via multicast transports can also be received by the sending host via loopback\&. A value of zero indicates that the loopback functionality is disabled, while the default value of 1 indicates that the loopback functionality is enabled\&. Leaving multicast loopback enabled when it is not required can have a negative impact on performance\&. Where possible, disable \fIZMQ_MCAST_LOOP\fR in production environments\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +uint64_t +T} +T{ +.sp +Option value unit +T}:T{ +.sp +boolean +T} +T{ +.sp +Default value +T}:T{ +.sp +1 +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +all, when using multicast transports +T} +.TE +.sp 1 +.SS "ZMQ_SNDBUF: Retrieve kernel transmit buffer size" +.sp +The \fIZMQ_SNDBUF\fR option shall retrieve the underlying kernel transmit buffer size for the specified \fIsocket\fR\&. A value of zero means that the OS default is in effect\&. For details refer to your operating system documentation for the \fISO_SNDBUF\fR socket option\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +uint64_t +T} +T{ +.sp +Option value unit +T}:T{ +.sp +bytes +T} +T{ +.sp +Default value +T}:T{ +.sp +0 +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +all +T} +.TE +.sp 1 +.SS "ZMQ_RCVBUF: Retrieve kernel receive buffer size" +.sp +The \fIZMQ_RCVBUF\fR option shall retrieve the underlying kernel receive buffer size for the specified \fIsocket\fR\&. A value of zero means that the OS default is in effect\&. For details refer to your operating system documentation for the \fISO_RCVBUF\fR socket option\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +uint64_t +T} +T{ +.sp +Option value unit +T}:T{ +.sp +bytes +T} +T{ +.sp +Default value +T}:T{ +.sp +0 +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +all +T} +.TE +.sp 1 +.SH "RETURN VALUE" +.sp +The \fIzmq_getsockopt()\fR function shall return zero if successful\&. Otherwise it shall return \-1 and set \fIerrno\fR to one of the values defined below\&. +.SH "ERRORS" +.PP +\fBEINVAL\fR +.RS 4 +The requested option +\fIoption_name\fR +is unknown, or the requested +\fIoption_len\fR +or +\fIoption_value\fR +is invalid, or the size of the buffer pointed to by +\fIoption_value\fR, as specified by +\fIoption_len\fR, is insufficient for storing the option value\&. +.RE +.PP +\fBETERM\fR +.RS 4 +The 0MQ +\fIcontext\fR +associated with the specified +\fIsocket\fR +was terminated\&. +.RE +.SH "EXAMPLE" +.PP +\fBRetrieving the high water mark\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +/* Retrieve high water mark into hwm */ +int64_t hwm; +rc = zmq_getsockopt (socket, ZMQ_HWM, &hwm, sizeof hwm); +assert (rc == 0); +.fi +.if n \{\ +.RE +.\} +.sp +.SH "SEE ALSO" +.sp +\fBzmq_setsockopt\fR(3) \fBzmq_socket\fR(3) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_getsockopt.html b/doc/zmq_getsockopt.html new file mode 100644 index 0000000..1c4dda1 --- /dev/null +++ b/doc/zmq_getsockopt.html @@ -0,0 +1,1192 @@ + + + + + +zmq_getsockopt(3) + + + + + +
+

SYNOPSIS

+
+

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

+
+

DESCRIPTION

+
+

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

+

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

+

ZMQ_RCVMORE: More message parts to follow

+

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

+

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

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

+int64_t +

+
+Option value unit +
+		 +

+boolean +

+
+Default value +
+		 +

+N/A +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_HWM: Retrieve high water mark

+

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

+

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

+

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

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

+int64_t +

+
+Option value unit +
+		 +

+messages +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_SWAP: Retrieve disk offload size

+

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

+

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

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

+int64_t +

+
+Option value unit +
+		 +

+bytes +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_AFFINITY: Retrieve I/O thread affinity

+

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

+

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

+

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

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

+int64_t +

+
+Option value unit +
+		 +

+N/A (bitmap) +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+N/A +

+
+

ZMQ_IDENTITY: Retrieve socket identity

+

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

+

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

+

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

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

+binary data +

+
+Option value unit +
+		 +

+N/A +

+
+Default value +
+		 +

+NULL +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_RATE: Retrieve multicast data rate

+

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

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

+uint64_t +

+
+Option value unit +
+		 +

+kilobits per second +

+
+Default value +
+		 +

+100 +

+
+Applicable socket types +
+		 +

+all, when using multicast transports +

+
+

ZMQ_RECOVERY_IVL: Get multicast recovery interval

+

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

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

+uint64_t +

+
+Option value unit +
+		 +

+seconds +

+
+Default value +
+		 +

+10 +

+
+Applicable socket types +
+		 +

+all, when using multicast transports +

+
+

ZMQ_MCAST_LOOP: Control multicast loopback

+

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

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

+uint64_t +

+
+Option value unit +
+		 +

+boolean +

+
+Default value +
+		 +

+1 +

+
+Applicable socket types +
+		 +

+all, when using multicast transports +

+
+

ZMQ_SNDBUF: Retrieve kernel transmit buffer size

+

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

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

+uint64_t +

+
+Option value unit +
+		 +

+bytes +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_RCVBUF: Retrieve kernel receive buffer size

+

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

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

+uint64_t +

+
+Option value unit +
+		 +

+bytes +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+all +

+
+
+

RETURN VALUE

+
+

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

+
+

ERRORS

+
+
+
+EINVAL +
+
+

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

+
+
+ETERM +
+
+

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

+
+
+
+

EXAMPLE

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

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt new file mode 100644 index 0000000..7886eaf --- /dev/null +++ b/doc/zmq_getsockopt.txt @@ -0,0 +1,240 @@ +zmq_getsockopt(3) +================= + + +NAME +---- + +zmq_getsockopt - get 0MQ socket options + + +SYNOPSIS +-------- +*int zmq_getsockopt (void '*socket', int 'option_name', void '*option_value', size_t '*option_len');* + + +DESCRIPTION +----------- +The _zmq_getsockopt()_ function shall retrieve the value for the option +specified by the 'option_name' argument for the 0MQ socket pointed to by the +'socket' argument, and store it in the buffer pointed to by the 'option_value' +argument. The 'option_len' argument is the size in bytes of the buffer pointed +to by 'option_value'; upon successful completion _zmq_getsockopt()_ shall +modify the 'option_value' argument to indicate the actual size of the option +value stored in the buffer. + +The following options can be retrieved with the _zmq_getsockopt()_ function: + + +ZMQ_RCVMORE: More message parts to follow +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RCVMORE' option shall return a boolean value indicating if the +multi-part message currently being read from the specified 'socket' has more +message parts to follow. If there are no message parts to follow or if the +message currently being read is not a multi-part message a value of zero shall +be returned. Otherwise, a value of 1 shall be returned. + +Refer to linkzmq:zmq_send[3] and linkzmq:zmq_recv[3] for a detailed description +of sending/receiving multi-part messages. + +[horizontal] +Option value type:: int64_t +Option value unit:: boolean +Default value:: N/A +Applicable socket types:: all + + +ZMQ_HWM: Retrieve high water mark +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_HWM' option shall retrieve the high water mark for the specified +'socket'. The high water mark is a hard limit on the maximum number of +outstanding messages 0MQ shall queue in memory for any single peer that the +specified 'socket' is communicating with. + +If this limit has been reached the socket shall enter an exceptional state and +depending on the socket type, 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 +type. + +The default 'ZMQ_HWM' value of zero means "no limit". + +[horizontal] +Option value type:: int64_t +Option value unit:: messages +Default value:: 0 +Applicable socket types:: all + + +ZMQ_SWAP: Retrieve disk offload size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_SWAP' option shall retrieve the disk offload (swap) size for the +specified 'socket'. A socket which has 'ZMQ_SWAP' set to a non-zero value may +exceed it's high water mark; in this case outstanding messages shall be +offloaded to storage on disk rather than held in memory. + +The value of 'ZMQ_SWAP' defines the maximum size of the swap space in bytes. + +[horizontal] +Option value type:: int64_t +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +ZMQ_AFFINITY: Retrieve I/O thread affinity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_AFFINITY' option shall retrieve the I/O thread affinity for newly +created connections on the specified 'socket'. + +Affinity determines which threads from the 0MQ I/O thread pool associated with +the socket's _context_ shall handle newly created connections. A value of zero +specifies no affinity, meaning that work shall be distributed fairly among all +0MQ I/O threads in the thread pool. For non-zero values, the lowest bit +corresponds to thread 1, second lowest bit to thread 2 and so on. For example, +a value of 3 specifies that subsequent connections on 'socket' shall be handled +exclusively by I/O threads 1 and 2. + +See also linkzmq:zmq_init[3] for details on allocating the number of I/O +threads for a specific _context_. + +[horizontal] +Option value type:: int64_t +Option value unit:: N/A (bitmap) +Default value:: 0 +Applicable socket types:: N/A + + +ZMQ_IDENTITY: Retrieve socket identity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_IDENTITY' option shall retrieve the identity of the specified +'socket'. Socket identity determines if existing 0MQ infastructure (_message +queues_, _forwarding devices_) shall be identified with a specific application +and persist across multiple runs of the application. + +If the socket has no identity, each run of an application is completely +separate from other runs. However, with identity set the socket shall re-use +any existing 0MQ infrastructure configured by the previous run(s). Thus the +application may receive messages that were sent in the meantime, _message +queue_ limits shall be shared with previous run(s) and so on. + +Identity can be at least one byte and at most 255 bytes long. Identities +starting with binary zero are reserved for use by 0MQ infrastructure. + +[horizontal] +Option value type:: binary data +Option value unit:: N/A +Default value:: NULL +Applicable socket types:: all + + +ZMQ_RATE: Retrieve multicast data rate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RATE' option shall retrieve the maximum send or receive data rate for +multicast transports using the specified 'socket'. + +[horizontal] +Option value type:: uint64_t +Option value unit:: kilobits per second +Default value:: 100 +Applicable socket types:: all, when using multicast transports + + +ZMQ_RECOVERY_IVL: Get multicast recovery interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RECOVERY_IVL' option shall retrieve the recovery interval for +multicast transports using the specified 'socket'. The recovery interval +determines the maximum time in seconds that a receiver can be absent from a +multicast group before unrecoverable data loss will occur. + +[horizontal] +Option value type:: uint64_t +Option value unit:: seconds +Default value:: 10 +Applicable socket types:: all, when using multicast transports + + +ZMQ_MCAST_LOOP: Control multicast loopback +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_MCAST_LOOP' option controls whether data sent via multicast +transports can also be received by the sending host via loopback. A value of +zero indicates that the loopback functionality is disabled, while the default +value of 1 indicates that the loopback functionality is enabled. Leaving +multicast loopback enabled when it is not required can have a negative impact +on performance. Where possible, disable 'ZMQ_MCAST_LOOP' in production +environments. + +[horizontal] +Option value type:: uint64_t +Option value unit:: boolean +Default value:: 1 +Applicable socket types:: all, when using multicast transports + + +ZMQ_SNDBUF: Retrieve kernel transmit buffer size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_SNDBUF' option shall retrieve the underlying kernel transmit buffer +size for the specified 'socket'. A value of zero means that the OS default is +in effect. For details refer to your operating system documentation for the +'SO_SNDBUF' socket option. + +[horizontal] +Option value type:: uint64_t +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +ZMQ_RCVBUF: Retrieve kernel receive buffer size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RCVBUF' option shall retrieve the underlying kernel receive buffer +size for the specified 'socket'. A value of zero means that the OS default is +in effect. For details refer to your operating system documentation for the +'SO_RCVBUF' socket option. + +[horizontal] +Option value type:: uint64_t +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +RETURN VALUE +------------ +The _zmq_getsockopt()_ function shall return zero if successful. Otherwise it +shall return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +*EINVAL*:: +The requested option _option_name_ is unknown, or the requested _option_len_ or +_option_value_ is invalid, or the size of the buffer pointed to by +_option_value_, as specified by _option_len_, is insufficient for storing the +option value. +*ETERM*:: +The 0MQ 'context' associated with the specified 'socket' was terminated. + + +EXAMPLE +------- +.Retrieving the high water mark +---- +/* Retrieve high water mark into hwm */ +int64_t hwm; +rc = zmq_getsockopt (socket, ZMQ_HWM, &hwm, sizeof hwm); +assert (rc == 0); +---- + + +SEE ALSO +-------- +linkzmq:zmq_setsockopt[3] +linkzmq:zmq_socket[3] +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_init.3 b/doc/zmq_init.3 new file mode 100644 index 0000000..9e0be97 --- /dev/null +++ b/doc/zmq_init.3 @@ -0,0 +1,67 @@ +'\" t +.\" Title: zmq_init +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_INIT" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_init \- initialise 0MQ context +.SH "SYNOPSIS" +.sp +\fBvoid *zmq_init (int \fR\fB\fIio_threads\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_init()\fR function initialises a 0MQ \fIcontext\fR\&. +.sp +The \fIio_threads\fR argument specifies the size of the 0MQ thread pool to handle I/O operations\&. If your application is using only the \fIinproc\fR transport for messaging you may set this to zero, otherwise set it to at least one\&. +.SH "RETURN VALUE" +.sp +The \fIzmq_init()\fR function shall return an opaque handle to the initialised \fIcontext\fR if successful\&. Otherwise it shall return NULL and set \fIerrno\fR to one of the values defined below\&. +.SH "ERRORS" +.PP +\fBEINVAL\fR +.RS 4 +An invalid number of +\fIio_threads\fR +was requested\&. +.RE +.SH "SEE ALSO" +.sp +\fBzmq\fR(7) \fBzmq_term\fR(3) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_init.html b/doc/zmq_init.html new file mode 100644 index 0000000..a9f2986 --- /dev/null +++ b/doc/zmq_init.html @@ -0,0 +1,631 @@ + + + + + +zmq_init(3) + + + + + +
+

SYNOPSIS

+
+

void *zmq_init (int io_threads);

+
+

DESCRIPTION

+
+

The zmq_init() function initialises a ØMQ context.

+

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

+
+

RETURN VALUE

+
+

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

+
+

ERRORS

+
+
+
+EINVAL +
+
+

+An invalid number of io_threads was requested. +

+
+
+
+

SEE ALSO

+
+

zmq(7) +zmq_term(3)

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_init.txt b/doc/zmq_init.txt new file mode 100644 index 0000000..04bbbc8 --- /dev/null +++ b/doc/zmq_init.txt @@ -0,0 +1,46 @@ +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. + + +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_term[3] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_inproc.7 b/doc/zmq_inproc.7 new file mode 100644 index 0000000..c5d9307 --- /dev/null +++ b/doc/zmq_inproc.7 @@ -0,0 +1,115 @@ +'\" t +.\" Title: zmq_inproc +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_INPROC" "7" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_inproc \- 0MQ local in\-process (inter\-thread) communication transport +.SH "SYNOPSIS" +.sp +The in\-process transport passes messages via memory directly between threads sharing a single 0MQ \fIcontext\fR\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.sp +No I/O threads are involved in passing messages using the \fIinproc\fR transport\&. Therefore, if you are using a 0MQ \fIcontext\fR for in\-process messaging only you can initialise the \fIcontext\fR with zero I/O threads\&. See \fBzmq_init\fR(3) for details\&. +.sp .5v +.RE +.SH "ADDRESSING" +.sp +A 0MQ address string consists of two parts as follows: \fItransport\fR://\fIendpoint\fR\&. The \fItransport\fR part specifies the underlying transport protocol to use, and for the in\-process transport shall be set to inproc\&. The meaning of the \fIendpoint\fR part for the in\-process transport is defined below\&. +.SS "Assigning a local address to a socket" +.sp +When assigning a local address to a \fIsocket\fR using \fIzmq_bind()\fR with the \fIinproc\fR transport, the \fIendpoint\fR shall be interpreted as an arbitrary string identifying the \fIname\fR to create\&. The \fIname\fR must be unique within the 0MQ \fIcontext\fR associated with the \fIsocket\fR and may be up to 256 characters in length\&. No other restrictions are placed on the format of the \fIname\fR\&. +.SS "Connecting a socket" +.sp +When connecting a \fIsocket\fR to a peer address using \fIzmq_connect()\fR with the \fIinproc\fR transport, the \fIendpoint\fR shall be interpreted as an arbitrary string identifying the \fIname\fR to connect to\&. The \fIname\fR must have been previously created by assigning it to at least one \fIsocket\fR within the same 0MQ \fIcontext\fR as the \fIsocket\fR being connected\&. +.SH "WIRE FORMAT" +.sp +Not applicable\&. +.SH "EXAMPLES" +.PP +\fBAssigning a local address to a socket\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +/* Assign the in\-process name "#1" */ +rc = zmq_bind(socket, "inproc://#1"); +assert (rc == 0); +/* Assign the in\-process name "my\-endpoint" */ +rc = zmq_bind(socket, "inproc://my\-endpoint"); +assert (rc == 0); +.fi +.if n \{\ +.RE +.\} +.PP +\fBConnecting a socket\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +/* Connect to the in\-process name "#1" */ +rc = zmq_connect(socket, "inproc://#1"); +assert (rc == 0); +/* Connect to the in\-process name "my\-endpoint" */ +rc = zmq_connect(socket, "inproc://my\-endpoint"); +assert (rc == 0); +.fi +.if n \{\ +.RE +.\} +.sp +.SH "SEE ALSO" +.sp +\fBzmq_bind\fR(3) \fBzmq_connect\fR(3) \fBzmq_ipc\fR(7) \fBzmq_tcp\fR(7) \fBzmq_pgm\fR(7) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_inproc.html b/doc/zmq_inproc.html new file mode 100644 index 0000000..468a196 --- /dev/null +++ b/doc/zmq_inproc.html @@ -0,0 +1,668 @@ + + + + + +zmq_inproc(7) + + + + + +
+

SYNOPSIS

+
+

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

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

ADDRESSING

+
+

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

+

Assigning a local address to a socket

+

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

+

Connecting a socket

+

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

+
+

WIRE FORMAT

+
+

Not applicable.

+
+

EXAMPLES

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

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_inproc.txt b/doc/zmq_inproc.txt new file mode 100644 index 0000000..2805f71 --- /dev/null +++ b/doc/zmq_inproc.txt @@ -0,0 +1,89 @@ +zmq_inproc(7) +============= + + +NAME +---- +zmq_inproc - 0MQ local in-process (inter-thread) communication transport + + +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. + + +ADDRESSING +---------- +A 0MQ address string consists of two parts as follows: +'transport'`://`'endpoint'. The 'transport' part specifies the underlying +transport protocol to use, and for the in-process transport shall be set to +`inproc`. The meaning of the 'endpoint' part for the in-process transport is +defined below. + + +Assigning a local address to a socket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +When assigning a local address to a 'socket' using _zmq_bind()_ with the +'inproc' transport, the 'endpoint' shall be interpreted as an arbitrary string +identifying the 'name' to create. The 'name' must be unique within the 0MQ +'context' associated with the 'socket' and may be up to 256 characters in +length. No other restrictions are placed on the format of the 'name'. + + +Connecting a socket +~~~~~~~~~~~~~~~~~~~ +When connecting a 'socket' to a peer address using _zmq_connect()_ with the +'inproc' transport, the 'endpoint' shall be interpreted as an arbitrary string +identifying the 'name' to connect to. The 'name' must have been previously +created by assigning it to at least one 'socket' within the same 0MQ 'context' +as the 'socket' being connected. + + +WIRE FORMAT +----------- +Not applicable. + + +EXAMPLES +-------- +.Assigning a local address to a socket +---- +/* Assign the in-process name "#1" */ +rc = zmq_bind(socket, "inproc://#1"); +assert (rc == 0); +/* Assign the in-process name "my-endpoint" */ +rc = zmq_bind(socket, "inproc://my-endpoint"); +assert (rc == 0); +---- + +.Connecting a socket +---- +/* Connect to the in-process name "#1" */ +rc = zmq_connect(socket, "inproc://#1"); +assert (rc == 0); +/* Connect to the in-process name "my-endpoint" */ +rc = zmq_connect(socket, "inproc://my-endpoint"); +assert (rc == 0); +---- + + +SEE ALSO +-------- +linkzmq:zmq_bind[3] +linkzmq:zmq_connect[3] +linkzmq:zmq_ipc[7] +linkzmq:zmq_tcp[7] +linkzmq:zmq_pgm[7] +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_ipc.7 b/doc/zmq_ipc.7 new file mode 100644 index 0000000..619b352 --- /dev/null +++ b/doc/zmq_ipc.7 @@ -0,0 +1,109 @@ +'\" t +.\" Title: zmq_ipc +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_IPC" "7" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_ipc \- 0MQ local inter\-process communication transport +.SH "SYNOPSIS" +.sp +The inter\-process transport passes messages between local processes using a system\-dependent IPC mechanism\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.sp +The inter\-process transport is currently only implemented on operating systems that provide UNIX domain sockets\&. +.sp .5v +.RE +.SH "ADDRESSING" +.sp +A 0MQ address string consists of two parts as follows: \fItransport\fR://\fIendpoint\fR\&. The \fItransport\fR part specifies the underlying transport protocol to use, and for the inter\-process transport shall be set to ipc\&. The meaning of the \fIendpoint\fR part for the inter\-process transport is defined below\&. +.SS "Assigning a local address to a socket" +.sp +When assigning a local address to a \fIsocket\fR using \fIzmq_bind()\fR with the \fIipc\fR transport, the \fIendpoint\fR shall be interpreted as an arbitrary string identifying the \fIpathname\fR to create\&. The \fIpathname\fR must be unique within the operating system namespace used by the \fIipc\fR implementation, and must fulfill any restrictions placed by the operating system on the format and length of a \fIpathname\fR\&. +.SS "Connecting a socket" +.sp +When connecting a \fIsocket\fR to a peer address using \fIzmq_connect()\fR with the \fIipc\fR transport, the \fIendpoint\fR shall be interpreted as an arbitrary string identifying the \fIpathname\fR to connect to\&. The \fIpathname\fR must have been previously created within the operating system namespace by assigning it to a \fIsocket\fR with \fIzmq_bind()\fR\&. +.SH "WIRE FORMAT" +.sp +Not applicable\&. +.SH "EXAMPLES" +.PP +\fBAssigning a local address to a socket\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +/* Assign the pathname "/tmp/feeds/0" */ +rc = zmq_bind(socket, "ipc:///tmp/feeds/0"); +assert (rc == 0); +.fi +.if n \{\ +.RE +.\} +.PP +\fBConnecting a socket\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +/* Connect to the pathname "/tmp/feeds/0" */ +rc = zmq_connect(socket, "ipc:///tmp/feeds/0"); +assert (rc == 0); +.fi +.if n \{\ +.RE +.\} +.sp +.SH "SEE ALSO" +.sp +\fBzmq_bind\fR(3) \fBzmq_connect\fR(3) \fBzmq_inproc\fR(7) \fBzmq_tcp\fR(7) \fBzmq_pgm\fR(7) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_ipc.html b/doc/zmq_ipc.html new file mode 100644 index 0000000..ec5ac70 --- /dev/null +++ b/doc/zmq_ipc.html @@ -0,0 +1,661 @@ + + + + + +zmq_ipc(7) + + + + + +
+

SYNOPSIS

+
+

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

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

ADDRESSING

+
+

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

+

Assigning a local address to a socket

+

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

+

Connecting a socket

+

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

+
+

WIRE FORMAT

+
+

Not applicable.

+
+

EXAMPLES

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

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_ipc.txt b/doc/zmq_ipc.txt new file mode 100644 index 0000000..81f6747 --- /dev/null +++ b/doc/zmq_ipc.txt @@ -0,0 +1,80 @@ +zmq_ipc(7) +========== + + +NAME +---- +zmq_ipc - 0MQ local inter-process communication transport + + +SYNOPSIS +-------- +The inter-process transport passes messages between local processes using a +system-dependent IPC mechanism. + +NOTE: The inter-process transport is currently only implemented on operating +systems that provide UNIX domain sockets. + + +ADDRESSING +---------- +A 0MQ address string consists of two parts as follows: +'transport'`://`'endpoint'. The 'transport' part specifies the underlying +transport protocol to use, and for the inter-process transport shall be set to +`ipc`. The meaning of the 'endpoint' part for the inter-process transport is +defined below. + + +Assigning a local address to a socket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +When assigning a local address to a 'socket' using _zmq_bind()_ with the 'ipc' +transport, the 'endpoint' shall be interpreted as an arbitrary string +identifying the 'pathname' to create. The 'pathname' must be unique within the +operating system namespace used by the 'ipc' implementation, and must fulfill +any restrictions placed by the operating system on the format and length of a +'pathname'. + +Connecting a socket +~~~~~~~~~~~~~~~~~~~ +When connecting a 'socket' to a peer address using _zmq_connect()_ with the +'ipc' transport, the 'endpoint' shall be interpreted as an arbitrary string +identifying the 'pathname' to connect to. The 'pathname' must have been +previously created within the operating system namespace by assigning it to a +'socket' with _zmq_bind()_. + + +WIRE FORMAT +----------- +Not applicable. + + +EXAMPLES +-------- +.Assigning a local address to a socket +---- +/* Assign the pathname "/tmp/feeds/0" */ +rc = zmq_bind(socket, "ipc:///tmp/feeds/0"); +assert (rc == 0); +---- + +.Connecting a socket +---- +/* Connect to the pathname "/tmp/feeds/0" */ +rc = zmq_connect(socket, "ipc:///tmp/feeds/0"); +assert (rc == 0); +---- + +SEE ALSO +-------- +linkzmq:zmq_bind[3] +linkzmq:zmq_connect[3] +linkzmq:zmq_inproc[7] +linkzmq:zmq_tcp[7] +linkzmq:zmq_pgm[7] +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_msg_close.3 b/doc/zmq_msg_close.3 new file mode 100644 index 0000000..0a4ebdf --- /dev/null +++ b/doc/zmq_msg_close.3 @@ -0,0 +1,78 @@ +'\" t +.\" Title: zmq_msg_close +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_MSG_CLOSE" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_msg_close \- release 0MQ message +.SH "SYNOPSIS" +.sp +\fBint zmq_msg_close (zmq_msg_t \fR\fB\fI*msg\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_msg_close()\fR function shall inform the 0MQ infrastructure that any resources associated with the message object referenced by \fImsg\fR are no longer required and may be released\&. Actual release of resources associated with the message object shall be postponed by 0MQ until all users of the message or underlying data buffer have indicated it is no longer required\&. +.sp +Applications should ensure that \fIzmq_msg_close()\fR is called once a message is no longer required, otherwise memory leaks may occur\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.sp +Never access \fIzmq_msg_t\fR members directly, instead always use the \fIzmq_msg\fR family of functions\&. +.sp .5v +.RE +.SH "RETURN VALUE" +.sp +The \fIzmq_msg_close()\fR function shall return zero if successful\&. Otherwise it shall return \-1 and set \fIerrno\fR to one of the values defined below\&. +.SH "ERRORS" +.sp +No errors are defined\&. +.SH "SEE ALSO" +.sp +\fBzmq_msg_init\fR(3) \fBzmq_msg_init_size\fR(3) \fBzmq_msg_init_data\fR(3) \fBzmq_msg_data\fR(3) \fBzmq_msg_size\fR(3) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_msg_close.html b/doc/zmq_msg_close.html new file mode 100644 index 0000000..23b7a1c --- /dev/null +++ b/doc/zmq_msg_close.html @@ -0,0 +1,637 @@ + + + + + +zmq_msg_close(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_msg_close (zmq_msg_t *msg);

+
+

DESCRIPTION

+
+

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

+

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

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

RETURN VALUE

+
+

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

+
+

ERRORS

+
+

No errors are defined.

+
+

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_msg_close.txt b/doc/zmq_msg_close.txt new file mode 100644 index 0000000..1da353b --- /dev/null +++ b/doc/zmq_msg_close.txt @@ -0,0 +1,54 @@ +zmq_msg_close(3) +================ + + +NAME +---- +zmq_msg_close - release 0MQ message + + +SYNOPSIS +-------- +*int zmq_msg_close (zmq_msg_t '*msg');* + + +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 +message object shall be postponed by 0MQ until all users of the message or +underlying data buffer have indicated it is no longer required. + +Applications should ensure that _zmq_msg_close()_ is called once a message is +no longer required, otherwise memory leaks may occur. + +CAUTION: Never access 'zmq_msg_t' members directly, instead always use the +_zmq_msg_ family of functions. + + +RETURN VALUE +------------ +The _zmq_msg_close()_ function shall return zero if successful. Otherwise +it shall return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +No errors are defined. + + +SEE ALSO +-------- +linkzmq:zmq_msg_init[3] +linkzmq:zmq_msg_init_size[3] +linkzmq:zmq_msg_init_data[3] +linkzmq:zmq_msg_data[3] +linkzmq:zmq_msg_size[3] +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_msg_copy.3 b/doc/zmq_msg_copy.3 new file mode 100644 index 0000000..259ebd4 --- /dev/null +++ b/doc/zmq_msg_copy.3 @@ -0,0 +1,92 @@ +'\" t +.\" Title: zmq_msg_copy +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_MSG_COPY" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_msg_copy \- copy content of a message to another message +.SH "SYNOPSIS" +.sp +\fBint zmq_msg_copy (zmq_msg_t \fR\fB\fI*dest\fR\fR\fB, zmq_msg_t \fR\fB\fI*src\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_msg_copy()\fR function shall copy the message object referenced by \fIsrc\fR to the message object referenced by \fIdest\fR\&. The original content of \fIdest\fR, if any, shall be released\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.sp +The implementation may choose not to physically copy the message content, rather to share the underlying buffer between \fIsrc\fR and \fIdest\fR\&. Avoid modifying message content after a message has been copied with \fIzmq_msg_copy()\fR, doing so can result in undefined behaviour\&. If what you need is an actual hard copy, allocate a new message using \fIzmq_msg_init_size()\fR and copy the message content using \fImemcpy()\fR\&. +.sp .5v +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.sp +Never access \fIzmq_msg_t\fR members directly, instead always use the \fIzmq_msg\fR family of functions\&. +.sp .5v +.RE +.SH "RETURN VALUE" +.sp +The \fIzmq_msg_copy()\fR function shall return zero if successful\&. Otherwise it shall return \-1 and set \fIerrno\fR to one of the values defined below\&. +.SH "ERRORS" +.sp +No errors are defined\&. +.SH "SEE ALSO" +.sp +\fBzmq_msg_move\fR(3) \fBzmq_msg_init\fR(3) \fBzmq_msg_init_size\fR(3) \fBzmq_msg_init_data\fR(3) \fBzmq_msg_close\fR(3) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_msg_copy.html b/doc/zmq_msg_copy.html new file mode 100644 index 0000000..dbc2c57 --- /dev/null +++ b/doc/zmq_msg_copy.html @@ -0,0 +1,646 @@ + + + + + +zmq_msg_copy(3) + + + + + +
+

SYNOPSIS

+
+

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

+
+

DESCRIPTION

+
+

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

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

RETURN VALUE

+
+

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

+
+

ERRORS

+
+

No errors are defined.

+
+

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_msg_copy.txt b/doc/zmq_msg_copy.txt new file mode 100644 index 0000000..f41a42e --- /dev/null +++ b/doc/zmq_msg_copy.txt @@ -0,0 +1,56 @@ +zmq_msg_copy(3) +=============== + + +NAME +---- +zmq_msg_copy - copy content of a message to another message + + +SYNOPSIS +-------- +*int zmq_msg_copy (zmq_msg_t '*dest', zmq_msg_t '*src');* + + +DESCRIPTION +----------- +The _zmq_msg_copy()_ function shall copy the message object referenced by 'src' +to the message object referenced by 'dest'. The original content of 'dest', if +any, shall be released. + +CAUTION: The implementation may choose not to physically copy the message +content, rather to share the underlying buffer between 'src' and 'dest'. Avoid +modifying message content after a message has been copied with +_zmq_msg_copy()_, doing so can result in undefined behaviour. If what you need +is an actual hard copy, allocate a new message using _zmq_msg_init_size()_ and +copy the message content using _memcpy()_. + +CAUTION: Never access 'zmq_msg_t' members directly, instead always use the +_zmq_msg_ family of functions. + + +RETURN VALUE +------------ +The _zmq_msg_copy()_ function shall return zero if successful. Otherwise it +shall return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +No errors are defined. + + +SEE ALSO +-------- +linkzmq:zmq_msg_move[3] +linkzmq:zmq_msg_init[3] +linkzmq:zmq_msg_init_size[3] +linkzmq:zmq_msg_init_data[3] +linkzmq:zmq_msg_close[3] +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_msg_data.3 b/doc/zmq_msg_data.3 new file mode 100644 index 0000000..0dec4d2 --- /dev/null +++ b/doc/zmq_msg_data.3 @@ -0,0 +1,76 @@ +'\" t +.\" Title: zmq_msg_data +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_MSG_DATA" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_msg_data \- retrieve pointer to message content +.SH "SYNOPSIS" +.sp +\fBvoid *zmq_msg_data (zmq_msg_t \fR\fB\fI*msg\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_msg_data()\fR function shall return a pointer to the message content of the message object referenced by \fImsg\fR\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.sp +Never access \fIzmq_msg_t\fR members directly, instead always use the \fIzmq_msg\fR family of functions\&. +.sp .5v +.RE +.SH "RETURN VALUE" +.sp +Upon successful completion, \fIzmq_msg_data()\fR shall return a pointer to the message content\&. +.SH "ERRORS" +.sp +No errors are defined\&. +.SH "SEE ALSO" +.sp +\fBzmq_msg_size\fR(3) \fBzmq_msg_init\fR(3) \fBzmq_msg_init_size\fR(3) \fBzmq_msg_init_data\fR(3) \fBzmq_msg_close\fR(3) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_msg_data.html b/doc/zmq_msg_data.html new file mode 100644 index 0000000..78df0fc --- /dev/null +++ b/doc/zmq_msg_data.html @@ -0,0 +1,632 @@ + + + + + +zmq_msg_data(3) + + + + + +
+

SYNOPSIS

+
+

void *zmq_msg_data (zmq_msg_t *msg);

+
+

DESCRIPTION

+
+

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

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

RETURN VALUE

+
+

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

+
+

ERRORS

+
+

No errors are defined.

+
+

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_msg_data.txt b/doc/zmq_msg_data.txt new file mode 100644 index 0000000..dbf6612 --- /dev/null +++ b/doc/zmq_msg_data.txt @@ -0,0 +1,48 @@ +zmq_msg_data(3) +=============== + + +NAME +---- +zmq_msg_data - retrieve pointer to message content + + +SYNOPSIS +-------- +*void *zmq_msg_data (zmq_msg_t '*msg');* + + +DESCRIPTION +----------- +The _zmq_msg_data()_ function shall return a pointer to the message content of +the message object referenced by 'msg'. + +CAUTION: Never access 'zmq_msg_t' members directly, instead always use the +_zmq_msg_ family of functions. + + +RETURN VALUE +------------ +Upon successful completion, _zmq_msg_data()_ shall return a pointer to the +message content. + + +ERRORS +------ +No errors are defined. + + +SEE ALSO +-------- +linkzmq:zmq_msg_size[3] +linkzmq:zmq_msg_init[3] +linkzmq:zmq_msg_init_size[3] +linkzmq:zmq_msg_init_data[3] +linkzmq:zmq_msg_close[3] +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_msg_init.3 b/doc/zmq_msg_init.3 new file mode 100644 index 0000000..823118f --- /dev/null +++ b/doc/zmq_msg_init.3 @@ -0,0 +1,110 @@ +'\" t +.\" Title: zmq_msg_init +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_MSG_INIT" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_msg_init \- initialise empty 0MQ message +.SH "SYNOPSIS" +.sp +\fBint zmq_msg_init (zmq_msg_t \fR\fB\fI*msg\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_msg_init()\fR function shall initialise the message object referenced by \fImsg\fR to represent an empty message\&. This function is most useful when called before receiving a message with \fIzmq_recv()\fR\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.sp +Never access \fIzmq_msg_t\fR members directly, instead always use the \fIzmq_msg\fR family of functions\&. +.sp .5v +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.sp +The functions \fIzmq_msg_init()\fR, \fIzmq_msg_init_data()\fR and \fIzmq_msg_init_size()\fR are mutually exclusive\&. Never initialize the same \fIzmq_msg_t\fR twice\&. +.sp .5v +.RE +.SH "RETURN VALUE" +.sp +The \fIzmq_msg_init()\fR function shall return zero if successful\&. Otherwise it shall return \-1 and set \fIerrno\fR to one of the values defined below\&. +.SH "ERRORS" +.sp +No errors are defined\&. +.SH "EXAMPLE" +.PP +\fBReceiving a message from a socket\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +zmq_msg_t msg; +rc = zmq_msg_init (&msg); +assert (rc == 0); +rc = zmq_recv (socket, &msg, 0); +assert (rc == 0); +.fi +.if n \{\ +.RE +.\} +.sp +.SH "SEE ALSO" +.sp +\fBzmq_msg_init_size\fR(3) \fBzmq_msg_init_data\fR(3) \fBzmq_msg_close\fR(3) \fBzmq_msg_data\fR(3) \fBzmq_msg_size\fR(3) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_msg_init.html b/doc/zmq_msg_init.html new file mode 100644 index 0000000..83e2234 --- /dev/null +++ b/doc/zmq_msg_init.html @@ -0,0 +1,655 @@ + + + + + +zmq_msg_init(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_msg_init (zmq_msg_t *msg);

+
+

DESCRIPTION

+
+

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

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

RETURN VALUE

+
+

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

+
+

ERRORS

+
+

No errors are defined.

+
+

EXAMPLE

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

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_msg_init.txt b/doc/zmq_msg_init.txt new file mode 100644 index 0000000..d31dbae --- /dev/null +++ b/doc/zmq_msg_init.txt @@ -0,0 +1,65 @@ +zmq_msg_init(3) +=============== + + +NAME +---- +zmq_msg_init - initialise empty 0MQ message + + +SYNOPSIS +-------- +*int zmq_msg_init (zmq_msg_t '*msg');* + + +DESCRIPTION +----------- +The _zmq_msg_init()_ function shall initialise the message object referenced by +'msg' to represent an empty message. This function is most useful when called +before receiving a message with _zmq_recv()_. + +CAUTION: Never access 'zmq_msg_t' members directly, instead always use the +_zmq_msg_ family of functions. + +CAUTION: The functions _zmq_msg_init()_, _zmq_msg_init_data()_ and +_zmq_msg_init_size()_ are mutually exclusive. Never initialize the same +'zmq_msg_t' twice. + + +RETURN VALUE +------------ +The _zmq_msg_init()_ function shall return zero if successful. Otherwise it +shall return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +No errors are defined. + + +EXAMPLE +------- +.Receiving a message from a socket +---- +zmq_msg_t msg; +rc = zmq_msg_init (&msg); +assert (rc == 0); +rc = zmq_recv (socket, &msg, 0); +assert (rc == 0); +---- + + +SEE ALSO +-------- +linkzmq:zmq_msg_init_size[3] +linkzmq:zmq_msg_init_data[3] +linkzmq:zmq_msg_close[3] +linkzmq:zmq_msg_data[3] +linkzmq:zmq_msg_size[3] +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_msg_init_data.3 b/doc/zmq_msg_init_data.3 new file mode 100644 index 0000000..6893236 --- /dev/null +++ b/doc/zmq_msg_init_data.3 @@ -0,0 +1,122 @@ +'\" t +.\" Title: zmq_msg_init_data +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_MSG_INIT_DATA" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_msg_init_data \- initialise 0MQ message from a supplied buffer +.SH "SYNOPSIS" +.sp +\fBtypedef void (zmq_free_fn) (void \fR\fB\fI*data\fR\fR\fB, void \fR\fB\fI*hint\fR\fR\fB);\fR +.sp +\fBint zmq_msg_init_data (zmq_msg_t \fR\fB\fI*msg\fR\fR\fB, void \fR\fB\fI*data\fR\fR\fB, size_t \fR\fB\fIsize\fR\fR\fB, zmq_free_fn \fR\fB\fI*ffn\fR\fR\fB, void \fR\fB\fI*hint\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_msg_init_data()\fR function shall initialise the message object referenced by \fImsg\fR to represent the content referenced by the buffer located at address \fIdata\fR, \fIsize\fR bytes long\&. No copy of \fIdata\fR shall be performed and 0MQ shall take ownership of the supplied buffer\&. +.sp +If provided, the deallocation function \fIffn\fR shall be called once the data buffer is no longer required by 0MQ, with the \fIdata\fR and \fIhint\fR arguments supplied to \fIzmq_msg_init_data()\fR\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.sp +Never access \fIzmq_msg_t\fR members directly, instead always use the \fIzmq_msg\fR family of functions\&. +.sp .5v +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.sp +The functions \fIzmq_msg_init()\fR, \fIzmq_msg_init_data()\fR and \fIzmq_msg_init_size()\fR are mutually exclusive\&. Never initialize the same \fIzmq_msg_t\fR twice\&. +.sp .5v +.RE +.SH "RETURN VALUE" +.sp +The \fIzmq_msg_init_data()\fR function shall return zero if successful\&. Otherwise it shall return \-1 and set \fIerrno\fR to one of the values defined below\&. +.SH "ERRORS" +.sp +No errors are defined\&. +.SH "EXAMPLE" +.PP +\fBInitialising a message from a supplied buffer\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +void my_free (void *data, void *hint) +{ + free (data); +} + + /* \&.\&.\&. */ + +void *data = malloc (6); +assert (data); +memcpy (data, "ABCDEF", 6); +zmq_msg_t msg; +rc = zmq_msg_init_data (&msg, data, 6, my_free, NULL); +assert (rc == 0); +.fi +.if n \{\ +.RE +.\} +.sp +.SH "SEE ALSO" +.sp +\fBzmq_msg_init_size\fR(3) \fBzmq_msg_init\fR(3) \fBzmq_msg_close\fR(3) \fBzmq_msg_data\fR(3) \fBzmq_msg_size\fR(3) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_msg_init_data.html b/doc/zmq_msg_init_data.html new file mode 100644 index 0000000..11f8014 --- /dev/null +++ b/doc/zmq_msg_init_data.html @@ -0,0 +1,668 @@ + + + + + +zmq_msg_init_data(3) + + + + + +
+

SYNOPSIS

+
+

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

+

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

+
+

DESCRIPTION

+
+

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

+

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

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

RETURN VALUE

+
+

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

+
+

ERRORS

+
+

No errors are defined.

+
+

EXAMPLE

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

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_msg_init_data.txt b/doc/zmq_msg_init_data.txt new file mode 100644 index 0000000..8378757 --- /dev/null +++ b/doc/zmq_msg_init_data.txt @@ -0,0 +1,80 @@ +zmq_msg_init_data(3) +==================== + + +NAME +---- +zmq_msg_init_data - initialise 0MQ message from a supplied buffer + + +SYNOPSIS +-------- +*typedef void (zmq_free_fn) (void '*data', void '*hint');* + +*int zmq_msg_init_data (zmq_msg_t '*msg', void '*data', size_t 'size', zmq_free_fn '*ffn', void '*hint');* + + +DESCRIPTION +----------- +The _zmq_msg_init_data()_ function shall initialise the message object +referenced by 'msg' to represent the content referenced by the buffer located +at address 'data', 'size' bytes long. No copy of 'data' shall be performed and +0MQ shall take ownership of the supplied buffer. + +If provided, the deallocation function 'ffn' shall be called once the data +buffer is no longer required by 0MQ, with the 'data' and 'hint' arguments +supplied to _zmq_msg_init_data()_. + +CAUTION: Never access 'zmq_msg_t' members directly, instead always use the +_zmq_msg_ family of functions. + +CAUTION: The functions _zmq_msg_init()_, _zmq_msg_init_data()_ and +_zmq_msg_init_size()_ are mutually exclusive. Never initialize the same +'zmq_msg_t' twice. + + +RETURN VALUE +------------ +The _zmq_msg_init_data()_ function shall return zero if successful. Otherwise +it shall return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +No errors are defined. + + +EXAMPLE +------- +.Initialising a message from a supplied buffer +---- +void my_free (void *data, void *hint) +{ + free (data); +} + + /* ... */ + +void *data = malloc (6); +assert (data); +memcpy (data, "ABCDEF", 6); +zmq_msg_t msg; +rc = zmq_msg_init_data (&msg, data, 6, my_free, NULL); +assert (rc == 0); +---- + + +SEE ALSO +-------- +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] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_msg_init_size.3 b/doc/zmq_msg_init_size.3 new file mode 100644 index 0000000..6934ffd --- /dev/null +++ b/doc/zmq_msg_init_size.3 @@ -0,0 +1,97 @@ +'\" t +.\" Title: zmq_msg_init_size +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_MSG_INIT_SIZE" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_msg_init_size \- initialise 0MQ message of a specified size +.SH "SYNOPSIS" +.sp +\fBint zmq_msg_init_size (zmq_msg_t \fR\fB\fI*msg\fR\fR\fB, size_t \fR\fB\fIsize\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_msg_init_size()\fR function shall allocate any resources required to store a message \fIsize\fR bytes long and initialise the message object referenced by \fImsg\fR to represent the newly allocated message\&. +.sp +The implementation shall choose whether to store message content on the stack (small messages) or on the heap (large messages)\&. For performance reasons \fIzmq_msg_init_size()\fR shall not clear the message data\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.sp +Never access \fIzmq_msg_t\fR members directly, instead always use the \fIzmq_msg\fR family of functions\&. +.sp .5v +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.sp +The functions \fIzmq_msg_init()\fR, \fIzmq_msg_init_data()\fR and \fIzmq_msg_init_size()\fR are mutually exclusive\&. Never initialize the same \fIzmq_msg_t\fR twice\&. +.sp .5v +.RE +.SH "RETURN VALUE" +.sp +The \fIzmq_msg_init_size()\fR function shall return zero if successful\&. Otherwise it shall return \-1 and set \fIerrno\fR to one of the values defined below\&. +.SH "ERRORS" +.PP +\fBENOMEM\fR +.RS 4 +Insufficient storage space is available\&. +.RE +.SH "SEE ALSO" +.sp +\fBzmq_msg_init_data\fR(3) \fBzmq_msg_init\fR(3) \fBzmq_msg_close\fR(3) \fBzmq_msg_data\fR(3) \fBzmq_msg_size\fR(3) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_msg_init_size.html b/doc/zmq_msg_init_size.html new file mode 100644 index 0000000..87812ce --- /dev/null +++ b/doc/zmq_msg_init_size.html @@ -0,0 +1,655 @@ + + + + + +zmq_msg_init_size(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_msg_init_size (zmq_msg_t *msg, size_t size);

+
+

DESCRIPTION

+
+

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

+

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

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

RETURN VALUE

+
+

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

+
+

ERRORS

+
+
+
+ENOMEM +
+
+

+Insufficient storage space is available. +

+
+
+
+

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_msg_init_size.txt b/doc/zmq_msg_init_size.txt new file mode 100644 index 0000000..b4ef393 --- /dev/null +++ b/doc/zmq_msg_init_size.txt @@ -0,0 +1,58 @@ +zmq_msg_init_size(3) +==================== + + +NAME +---- +zmq_msg_init_size - initialise 0MQ message of a specified size + + +SYNOPSIS +-------- +*int zmq_msg_init_size (zmq_msg_t '*msg', size_t 'size');* + + +DESCRIPTION +----------- +The _zmq_msg_init_size()_ function shall allocate any resources required to +store a message 'size' bytes long and initialise the message object referenced +by 'msg' to represent the newly allocated message. + +The implementation shall choose whether to store message content on the stack +(small messages) or on the heap (large messages). For performance reasons +_zmq_msg_init_size()_ shall not clear the message data. + +CAUTION: Never access 'zmq_msg_t' members directly, instead always use the +_zmq_msg_ family of functions. + +CAUTION: The functions _zmq_msg_init()_, _zmq_msg_init_data()_ and +_zmq_msg_init_size()_ are mutually exclusive. Never initialize the same +'zmq_msg_t' twice. + + +RETURN VALUE +------------ +The _zmq_msg_init_size()_ function shall return zero if successful. Otherwise +it shall return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +*ENOMEM*:: +Insufficient storage space is available. + + +SEE ALSO +-------- +linkzmq:zmq_msg_init_data[3] +linkzmq:zmq_msg_init[3] +linkzmq:zmq_msg_close[3] +linkzmq:zmq_msg_data[3] +linkzmq:zmq_msg_size[3] +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_msg_move.3 b/doc/zmq_msg_move.3 new file mode 100644 index 0000000..24815cc --- /dev/null +++ b/doc/zmq_msg_move.3 @@ -0,0 +1,76 @@ +'\" t +.\" Title: zmq_msg_move +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_MSG_MOVE" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_msg_move \- move content of a message to another message +.SH "SYNOPSIS" +.sp +\fBint zmq_msg_move (zmq_msg_t \fR\fB\fI*dest\fR\fR\fB, zmq_msg_t \fR\fB\fI*src\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_msg_move()\fR function shall move the content of the message object referenced by \fIsrc\fR to the message object referenced by \fIdest\fR\&. No actual copying of message content is performed, \fIdest\fR is simply updated to reference the new content\&. \fIsrc\fR becomes an empty message after calling \fIzmq_msg_move()\fR\&. The original content of \fIdest\fR, if any, shall be released\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.sp +Never access \fIzmq_msg_t\fR members directly, instead always use the \fIzmq_msg\fR family of functions\&. +.sp .5v +.RE +.SH "RETURN VALUE" +.sp +The \fIzmq_msg_move()\fR function shall return zero if successful\&. Otherwise it shall return \-1 and set \fIerrno\fR to one of the values defined below\&. +.SH "ERRORS" +.sp +No errors are defined\&. +.SH "SEE ALSO" +.sp +\fBzmq_msg_copy\fR(3) \fBzmq_msg_init\fR(3) \fBzmq_msg_init_size\fR(3) \fBzmq_msg_init_data\fR(3) \fBzmq_msg_close\fR(3) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_msg_move.html b/doc/zmq_msg_move.html new file mode 100644 index 0000000..46e2fd1 --- /dev/null +++ b/doc/zmq_msg_move.html @@ -0,0 +1,635 @@ + + + + + +zmq_msg_move(3) + + + + + +
+

SYNOPSIS

+
+

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

+
+

DESCRIPTION

+
+

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

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

RETURN VALUE

+
+

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

+
+

ERRORS

+
+

No errors are defined.

+
+

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_msg_move.txt b/doc/zmq_msg_move.txt new file mode 100644 index 0000000..75c8e74 --- /dev/null +++ b/doc/zmq_msg_move.txt @@ -0,0 +1,51 @@ +zmq_msg_move(3) +=============== + + +NAME +---- +zmq_msg_move - move content of a message to another message + + +SYNOPSIS +-------- +*int zmq_msg_move (zmq_msg_t '*dest', zmq_msg_t '*src');* + + +DESCRIPTION +----------- +The _zmq_msg_move()_ function shall move the content of the message object +referenced by 'src' to the message object referenced by 'dest'. No actual +copying of message content is performed, 'dest' is simply updated to reference +the new content. 'src' becomes an empty message after calling _zmq_msg_move()_. +The original content of 'dest', if any, shall be released. + +CAUTION: Never access 'zmq_msg_t' members directly, instead always use the +_zmq_msg_ family of functions. + + +RETURN VALUE +------------ +The _zmq_msg_move()_ function shall return zero if successful. Otherwise it +shall return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +No errors are defined. + + +SEE ALSO +-------- +linkzmq:zmq_msg_copy[3] +linkzmq:zmq_msg_init[3] +linkzmq:zmq_msg_init_size[3] +linkzmq:zmq_msg_init_data[3] +linkzmq:zmq_msg_close[3] +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_msg_size.3 b/doc/zmq_msg_size.3 new file mode 100644 index 0000000..71337e3 --- /dev/null +++ b/doc/zmq_msg_size.3 @@ -0,0 +1,76 @@ +'\" t +.\" Title: zmq_msg_size +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_MSG_SIZE" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_msg_size \- retrieve message content size in bytes +.SH "SYNOPSIS" +.sp +\fBsize_t zmq_msg_size (zmq_msg_t \fR\fB\fI*msg\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_msg_size()\fR function shall return the size in bytes of the content of the message object referenced by \fImsg\fR\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.sp +Never access \fIzmq_msg_t\fR members directly, instead always use the \fIzmq_msg\fR family of functions\&. +.sp .5v +.RE +.SH "RETURN VALUE" +.sp +Upon successful completion, \fIzmq_msg_data()\fR shall return the size of the message content in bytes\&. +.SH "ERRORS" +.sp +No errors are defined\&. +.SH "SEE ALSO" +.sp +\fBzmq_msg_data\fR(3) \fBzmq_msg_init\fR(3) \fBzmq_msg_init_size\fR(3) \fBzmq_msg_init_data\fR(3) \fBzmq_msg_close\fR(3) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_msg_size.html b/doc/zmq_msg_size.html new file mode 100644 index 0000000..6e3e9ac --- /dev/null +++ b/doc/zmq_msg_size.html @@ -0,0 +1,632 @@ + + + + + +zmq_msg_size(3) + + + + + +
+

SYNOPSIS

+
+

size_t zmq_msg_size (zmq_msg_t *msg);

+
+

DESCRIPTION

+
+

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

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

RETURN VALUE

+
+

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

+
+

ERRORS

+
+

No errors are defined.

+
+

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_msg_size.txt b/doc/zmq_msg_size.txt new file mode 100644 index 0000000..05abfa6 --- /dev/null +++ b/doc/zmq_msg_size.txt @@ -0,0 +1,48 @@ +zmq_msg_size(3) +=============== + + +NAME +---- +zmq_msg_size - retrieve message content size in bytes + + +SYNOPSIS +-------- +*size_t zmq_msg_size (zmq_msg_t '*msg');* + + +DESCRIPTION +----------- +The _zmq_msg_size()_ function shall return the size in bytes of the content of +the message object referenced by 'msg'. + +CAUTION: Never access 'zmq_msg_t' members directly, instead always use the +_zmq_msg_ family of functions. + + +RETURN VALUE +------------ +Upon successful completion, _zmq_msg_data()_ shall return the size of the +message content in bytes. + + +ERRORS +------ +No errors are defined. + + +SEE ALSO +-------- +linkzmq:zmq_msg_data[3] +linkzmq:zmq_msg_init[3] +linkzmq:zmq_msg_init_size[3] +linkzmq:zmq_msg_init_data[3] +linkzmq:zmq_msg_close[3] +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_pgm.7 b/doc/zmq_pgm.7 new file mode 100644 index 0000000..98318ad --- /dev/null +++ b/doc/zmq_pgm.7 @@ -0,0 +1,207 @@ +'\" t +.\" Title: zmq_pgm +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_PGM" "7" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_pgm \- 0MQ reliable multicast transport using PGM +.SH "SYNOPSIS" +.sp +PGM (Pragmatic General Multicast) is a protocol for reliable multicast transport of data over IP networks\&. +.SH "DESCRIPTION" +.sp +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 \fIpgm\fR transport) and "Encapsulated PGM" where PGM datagrams are encapsulated inside UDP datagrams (the \fIepgm\fR transport)\&. +.sp +The \fIpgm\fR and \fIepgm\fR transports can only be used with the \fIZMQ_PUB\fR and \fIZMQ_SUB\fR socket types\&. +.sp +Further, PGM sockets are rate limited by default and incur a performance penalty when used over a loopback interface\&. For details, refer to the \fIZMQ_RATE\fR, \fIZMQ_RECOVERY_IVL\fR and \fIZMQ_MCAST_LOOP\fR options documented in \fBzmq_setsockopt\fR(3)\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.sp +The \fIpgm\fR transport implementation requires access to raw IP sockets\&. Additional privileges may be required on some operating systems for this operation\&. Applications not requiring direct interoperability with other PGM implementations are encouraged to use the \fIepgm\fR transport instead which does not require any special privileges\&. +.sp .5v +.RE +.SH "ADDRESSING" +.sp +A 0MQ address string consists of two parts as follows: \fItransport\fR://\fIendpoint\fR\&. The \fItransport\fR part specifies the underlying transport protocol to use\&. For the standard PGM protocol, \fItransport\fR shall be set to pgm\&. For the "Encapsulated PGM" protocol \fItransport\fR shall be set to epgm\&. The meaning of the \fIendpoint\fR part for both the \fIpgm\fR and \fIepgm\fR transport is defined below\&. +.SS "Connecting a socket" +.sp +When connecting a socket to a peer address using \fIzmq_connect()\fR with the \fIpgm\fR or \fIepgm\fR transport, the \fIendpoint\fR shall be interpreted as an \fIinterface\fR followed by a semicolon, followed by a \fImulticast address\fR, followed by a colon and a port number\&. +.sp +An \fIinterface\fR may be specified by either of the following: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The interface name as defined by the operating system\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The primary IPv4 address assigned to the interface, in it\(cqs numeric representation\&. +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.sp +Interface names are not standardised in any way and should be assumed to be arbitrary and platform dependent\&. On Win32 platforms no short interface names exist, thus only the primary IPv4 address may be used to specify an \fIinterface\fR\&. +.sp .5v +.RE +.sp +A \fImulticast address\fR is specified by an IPv4 multicast address in it\(cqs numeric representation\&. +.SH "WIRE FORMAT" +.sp +Consecutive PGM datagrams are interpreted by 0MQ as a single continous 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 \fIframes\fR as described in \fBzmq_tcp\fR(7)\&. +.SS "PGM datagram payload" +.sp +The following ABNF grammar represents the payload of a single PGM datagram as used by 0MQ: +.sp +.if n \{\ +.RS 4 +.\} +.nf +datagram = (offset data) +offset = 2OCTET +data = *OCTET +.fi +.if n \{\ +.RE +.\} +.sp +In order for late joining consumers to be able to identify message boundaries, each PGM datagram payload starts with a 16\-bit unsigned integer in network byte order specifying either the offset of the first message \fIframe\fR in the datagram or containing the value 0xFFFF if the datagram contains solely an intermediate part of a larger message\&. +.sp +The following diagram illustrates the layout of a single PGM datagram payload: +.sp +.if n \{\ +.RS 4 +.\} +.nf ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +| offset (16 bits) | data | ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +.fi +.if n \{\ +.RE +.\} +.sp +The following diagram further illustrates how three example 0MQ frames are laid out in consecutive PGM datagram payloads: +.sp +.if n \{\ +.RS 4 +.\} +.nf +First datagram payload ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +| Frame offset | Frame 1 | Frame 2, part 1 | +| 0x0000 | (Message 1) | (Message 2, part 1) | ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ + +Second datagram payload ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +| Frame offset | Frame 2, part 2 | +| 0xFFFF | (Message 2, part 2) | ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ + +Third datagram payload ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+ +| Frame offset | Frame 2, final 8 bytes | Frame 3 | +| 0x0008 | (Message 2, final 8 bytes) | (Message 3) | ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+ +.fi +.if n \{\ +.RE +.\} +.SH "EXAMPLE" +.PP +\fBConnecting a socket\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +/* Connecting to the multicast address 239\&.192\&.1\&.1, port 5555, */ +/* using the first ethernet network interface on Linux */ +/* and the Encapsulated PGM protocol */ +rc = zmq_connect(socket, "epgm://eth0;239\&.192\&.1\&.1:5555"); +assert (rc == 0); +/* Connecting to the multicast address 239\&.192\&.1\&.1, port 5555, */ +/* using the network interface with the address 192\&.168\&.1\&.1 */ +/* and the standard PGM protocol */ +rc = zmq_connect(socket, "pgm://192\&.168\&.1\&.1;239\&.192\&.1\&.1:5555"); +assert (rc == 0); +.fi +.if n \{\ +.RE +.\} +.sp +.SH "SEE ALSO" +.sp +\fBzmq_connect\fR(3) \fBzmq_setsockopt\fR(3) \fBzmq_tcp\fR(7) \fBzmq_ipc\fR(7) \fBzmq_inproc\fR(7) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_pgm.html b/doc/zmq_pgm.html new file mode 100644 index 0000000..456fcdf --- /dev/null +++ b/doc/zmq_pgm.html @@ -0,0 +1,744 @@ + + + + + +zmq_pgm(7) + + + + + +
+

SYNOPSIS

+
+

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

+
+

DESCRIPTION

+
+

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

+

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

+

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

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

ADDRESSING

+
+

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

+

Connecting a socket

+

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

+

An interface may be specified by either of the following:

+
    +
  • +

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

    +
    • +
  • +

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

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

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

+
+

WIRE FORMAT

+
+

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

+

PGM datagram payload

+

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

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

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

+

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

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

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

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

EXAMPLE

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

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_pgm.txt b/doc/zmq_pgm.txt new file mode 100644 index 0000000..4017db2 --- /dev/null +++ b/doc/zmq_pgm.txt @@ -0,0 +1,157 @@ +zmq_pgm(7) +========== + + +NAME +---- +zmq_pgm - 0MQ reliable multicast transport using PGM + + +SYNOPSIS +-------- +PGM (Pragmatic General Multicast) is a protocol for reliable multicast +transport of data over IP networks. + + +DESCRIPTION +----------- +0MQ implements two variants of PGM, the standard protocol where PGM datagrams +are layered directly on top of IP datagrams as defined by RFC 3208 (the 'pgm' +transport) and "Encapsulated PGM" where PGM datagrams are encapsulated inside +UDP datagrams (the 'epgm' transport). + +The 'pgm' and 'epgm' transports can only be used with the 'ZMQ_PUB' and +'ZMQ_SUB' socket types. + +Further, PGM sockets are rate limited by default and incur a performance +penalty when used over a loopback interface. For details, refer to the +'ZMQ_RATE', 'ZMQ_RECOVERY_IVL' and 'ZMQ_MCAST_LOOP' options documented in +linkzmq:zmq_setsockopt[3]. + +CAUTION: The 'pgm' transport implementation requires access to raw IP sockets. +Additional privileges may be required on some operating systems for this +operation. Applications not requiring direct interoperability with other PGM +implementations are encouraged to use the 'epgm' transport instead which does +not require any special privileges. + + +ADDRESSING +---------- +A 0MQ address string consists of two parts as follows: +'transport'`://`'endpoint'. The 'transport' part specifies the underlying +transport protocol to use. For the standard PGM protocol, 'transport' shall be +set to `pgm`. For the "Encapsulated PGM" protocol 'transport' shall be set to +`epgm`. The meaning of the 'endpoint' part for both the 'pgm' and 'epgm' +transport is defined below. + + +Connecting a socket +~~~~~~~~~~~~~~~~~~~ +When connecting a socket to a peer address using _zmq_connect()_ with the 'pgm' +or 'epgm' transport, the 'endpoint' shall be interpreted as an 'interface' +followed by a semicolon, followed by a 'multicast address', followed by a colon +and a port number. + +An 'interface' may be specified by either of the following: + +* The interface name as defined by the operating system. +* The primary IPv4 address assigned to the interface, in it's numeric + representation. + +NOTE: Interface names are not standardised in any way and should be assumed to +be arbitrary and platform dependent. On Win32 platforms no short interface +names exist, thus only the primary IPv4 address may be used to specify an +'interface'. + +A 'multicast address' is specified by an IPv4 multicast address in it's numeric +representation. + + +WIRE FORMAT +----------- +Consecutive PGM datagrams are interpreted by 0MQ as a single continous 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]. + + +PGM datagram payload +~~~~~~~~~~~~~~~~~~~~ +The following ABNF grammar represents the payload of a single PGM datagram as +used by 0MQ: + +.... +datagram = (offset data) +offset = 2OCTET +data = *OCTET +.... + +In order for late joining consumers to be able to identify message boundaries, +each PGM datagram payload starts with a 16-bit unsigned integer in network byte +order specifying either the offset of the first message 'frame' in the datagram +or containing the value `0xFFFF` if the datagram contains solely an +intermediate part of a larger message. + +The following diagram illustrates the layout of a single PGM datagram payload: + +.... ++------------------+----------------------+ +| offset (16 bits) | data | ++------------------+----------------------+ +.... + +The following diagram further illustrates how three example 0MQ frames are laid +out in consecutive PGM datagram payloads: + +.... +First datagram payload ++--------------+-------------+---------------------+ +| Frame offset | Frame 1 | Frame 2, part 1 | +| 0x0000 | (Message 1) | (Message 2, part 1) | ++--------------+-------------+---------------------+ + +Second datagram payload ++--------------+---------------------+ +| Frame offset | Frame 2, part 2 | +| 0xFFFF | (Message 2, part 2) | ++--------------+---------------------+ + +Third datagram payload ++--------------+----------------------------+-------------+ +| Frame offset | Frame 2, final 8 bytes | Frame 3 | +| 0x0008 | (Message 2, final 8 bytes) | (Message 3) | ++--------------+----------------------------+-------------+ +.... + + +EXAMPLE +------- +.Connecting a socket +---- +/* Connecting to the multicast address 239.192.1.1, port 5555, */ +/* using the first ethernet network interface on Linux */ +/* and the Encapsulated PGM protocol */ +rc = zmq_connect(socket, "epgm://eth0;239.192.1.1:5555"); +assert (rc == 0); +/* Connecting to the multicast address 239.192.1.1, port 5555, */ +/* using the network interface with the address 192.168.1.1 */ +/* and the standard PGM protocol */ +rc = zmq_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555"); +assert (rc == 0); +---- + + +SEE ALSO +-------- +linkzmq:zmq_connect[3] +linkzmq:zmq_setsockopt[3] +linkzmq:zmq_tcp[7] +linkzmq:zmq_ipc[7] +linkzmq:zmq_inproc[7] +linkzmq:zmq[7] + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_poll.3 b/doc/zmq_poll.3 new file mode 100644 index 0000000..96408c6 --- /dev/null +++ b/doc/zmq_poll.3 @@ -0,0 +1,217 @@ +'\" t +.\" Title: zmq_poll +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_POLL" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_poll \- input/output multiplexing +.SH "SYNOPSIS" +.sp +\fBint zmq_poll (zmq_pollitem_t \fR\fB\fI*items\fR\fR\fB, int \fR\fB\fInitems\fR\fR\fB, long \fR\fB\fItimeout\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_poll()\fR 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 \fIitems\fR argument is a \fBzmq_pollitem_t\fR structure\&. The \fInitems\fR argument specifies the number of items in the \fIitems\fR array\&. The \fBzmq_pollitem_t\fR structure is defined as follows: +.sp +.if n \{\ +.RS 4 +.\} +.nf +typedef struct +{ + void \fI*socket\fR; + int \fIfd\fR; + short \fIevents\fR; + short \fIrevents\fR; +} zmq_pollitem_t; +.fi +.if n \{\ +.RE +.\} +.sp +For each \fBzmq_pollitem_t\fR item, \fIzmq_poll()\fR shall examine either the 0MQ socket referenced by \fIsocket\fR \fBor\fR the standard socket specified by the file descriptor \fIfd\fR, for the event(s) specified in \fIevents\fR\&. If both \fIsocket\fR and \fIfd\fR are set in a single \fBzmq_pollitem_t\fR, the 0MQ socket referenced by \fIsocket\fR shall take precedence and the value of \fIfd\fR shall be ignored\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.sp +All 0MQ sockets passed to the \fIzmq_poll()\fR function must share the same 0MQ \fIcontext\fR and must belong to the thread calling \fIzmq_poll()\fR\&. +.sp .5v +.RE +.sp +For each \fBzmq_pollitem_t\fR item, \fIzmq_poll()\fR shall first clear the \fIrevents\fR member, and then indicate any requested events that have occured by setting the bit corresponding to the event condition in the \fIrevents\fR member\&. +.sp +If none of the requested events have occured on any \fBzmq_pollitem_t\fR item, \fIzmq_poll()\fR shall wait up to \fItimeout\fR microseconds for an event to occur on any of the requested items\&. If the value of \fItimeout\fR is 0, \fIzmq_poll()\fR shall return immediately\&. If the value of \fItimeout\fR is \-1, \fIzmq_poll()\fR shall block indefinitely until a requested event has occured on at least one \fBzmq_pollitem_t\fR\&. +.sp +The \fIevents\fR and \fIrevents\fR members of \fBzmq_pollitem_t\fR are bitmasks constructed by OR\(cqing a combination of the following event flags: +.PP +\fBZMQ_POLLIN\fR +.RS 4 +For 0MQ sockets, at least one message may be received from the +\fIsocket\fR +without blocking\&. For standard sockets this is equivalent to the +\fIPOLLIN\fR +flag of the +\fIpoll()\fR +system call and generally means that at least one byte of data may be read from +\fIfd\fR +without blocking\&. +.RE +.PP +\fBZMQ_POLLOUT\fR +.RS 4 +For 0MQ sockets, at least one message may be sent to the +\fIsocket\fR +without blocking\&. For standard sockets this is equivalent to the +\fIPOLLOUT\fR +flag of the +\fIpoll()\fR +system call and generally means that at least one byte of data may be written to +\fIfd\fR +without blocking\&. +.RE +.PP +\fBZMQ_POLLERR\fR +.RS 4 +For standard sockets, this flag is passed through +\fIzmq_poll()\fR +to the underlying +\fIpoll()\fR +system call and generally means that some sort of error condition is present on the socket specified by +\fIfd\fR\&. For 0MQ sockets this flag has no effect if set in +\fIevents\fR, and shall never be returned in +\fIrevents\fR +by +\fIzmq_poll()\fR\&. +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.sp +The \fIzmq_poll()\fR function may be implemented or emulated using operating system interfaces other than \fIpoll()\fR, and as such may be subject to the limits of those interfaces in ways not defined in this documentation\&. +.sp .5v +.RE +.SH "RETURN VALUE" +.sp +Upon successful completion, the \fIzmq_poll()\fR function shall return the number of \fBzmq_pollitem_t\fR structures with events signaled in \fIrevents\fR or 0 if no events have been signaled\&. Upon failure, \fIzmq_poll()\fR shall return \-1 and set \fIerrno\fR to one of the values defined below\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBImportant\fR +.ps -1 +.br +.sp +The \fIzmq_poll()\fR function may return \fBbefore\fR the \fItimeout\fR period has expired even if no events have been signaled\&. +.sp .5v +.RE +.SH "ERRORS" +.PP +\fBEFAULT\fR +.RS 4 +At least one of the members of the +\fIitems\fR +array refers to a +\fIsocket\fR +belonging to a different application thread\&. +.RE +.PP +\fBETERM\fR +.RS 4 +At least one of the members of the +\fIitems\fR +array refers to a +\fIsocket\fR +whose associated 0MQ +\fIcontext\fR +was terminated\&. +.RE +.SH "EXAMPLE" +.PP +\fBPolling indefinitely for input events on both a 0MQ socket and a standard socket.\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +zmq_pollitem_t items [2]; +/* First item refers to 0MQ socket \*(Aqsocket\*(Aq */ +items[0]\&.socket = socket; +items[0]\&.events = ZMQ_POLLIN; +/* Second item refers to standard socket \*(Aqfd\*(Aq */ +items[1]\&.socket = NULL; +items[1]\&.fd = fd; +items[1]\&.events = ZMQ_POLLIN; +/* Poll for events indefinitely */ +int rc = zmq_poll (items, 2, \-1); +assert (rc >= 0); +/* Returned events will be stored in items[]\&.revents */ +.fi +.if n \{\ +.RE +.\} +.sp +.SH "SEE ALSO" +.sp +\fBzmq_socket\fR(3) \fBzmq_send\fR(3) \fBzmq_recv\fR(3) \fBzmq\fR(7) +.sp +Your operating system documentation for the \fIpoll()\fR system call\&. +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_poll.html b/doc/zmq_poll.html new file mode 100644 index 0000000..fe38ead --- /dev/null +++ b/doc/zmq_poll.html @@ -0,0 +1,755 @@ + + + + + +zmq_poll(3) + + + + + +
+

SYNOPSIS

+
+

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

+
+

DESCRIPTION

+
+

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

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

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

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

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

+

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

+

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

+
+
+ZMQ_POLLIN +
+
+

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

+
+
+ZMQ_POLLOUT +
+
+

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

+
+
+ZMQ_POLLERR +
+
+

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

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

RETURN VALUE

+
+

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

+
+ + + +
+
Important
+		The zmq_poll() function may return before the timeout period +has expired even if no events have been signaled.
+
+
+

ERRORS

+
+
+
+EFAULT +
+
+

+At least one of the members of the items array refers to a socket belonging +to a different application thread. +

+
+
+ETERM +
+
+

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

+
+
+
+

EXAMPLE

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

SEE ALSO

+
+

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

+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_poll.txt b/doc/zmq_poll.txt new file mode 100644 index 0000000..d96af3e --- /dev/null +++ b/doc/zmq_poll.txt @@ -0,0 +1,133 @@ +zmq_poll(3) +=========== + + +NAME +---- +zmq_poll - input/output multiplexing + + +SYNOPSIS +-------- + +*int zmq_poll (zmq_pollitem_t '*items', int 'nitems', long 'timeout');* + + +DESCRIPTION +----------- +The _zmq_poll()_ function provides a mechanism for applications to multiplex +input/output events in a level-triggered fashion over a set of sockets. Each +member of the array pointed to by the 'items' argument is a *zmq_pollitem_t* +structure. The 'nitems' argument specifies the number of items in the 'items' +array. The *zmq_pollitem_t* structure is defined as follows: + +["literal", subs="quotes"] +typedef struct +{ + void '*socket'; + int 'fd'; + short 'events'; + short 'revents'; +} zmq_pollitem_t; + +For each *zmq_pollitem_t* item, _zmq_poll()_ shall examine either the 0MQ +socket referenced by 'socket' *or* the standard socket specified by the file +descriptor 'fd', for the event(s) specified in 'events'. If both 'socket' and +'fd' are set in a single *zmq_pollitem_t*, the 0MQ socket referenced by +'socket' shall take precedence and the value of 'fd' shall be ignored. + +NOTE: All 0MQ sockets passed to the _zmq_poll()_ function must share the +same 0MQ 'context' and must belong to the thread calling _zmq_poll()_. + +For each *zmq_pollitem_t* item, _zmq_poll()_ shall first clear the 'revents' +member, and then indicate any requested events that have occured by setting the +bit corresponding to the event condition in the 'revents' member. + +If none of the requested events have occured on any *zmq_pollitem_t* item, +_zmq_poll()_ shall wait up to 'timeout' microseconds for an event to occur on +any of the requested items. If the value of 'timeout' is `0`, _zmq_poll()_ +shall return immediately. If the value of 'timeout' is `-1`, _zmq_poll()_ shall +block indefinitely until a requested event has occured on at least one +*zmq_pollitem_t*. + +The 'events' and 'revents' members of *zmq_pollitem_t* are bitmasks constructed +by OR'ing a combination of the following event flags: + +*ZMQ_POLLIN*:: +For 0MQ sockets, at least one message may be received from the 'socket' without +blocking. For standard sockets this is equivalent to the 'POLLIN' flag of the +_poll()_ system call and generally means that at least one byte of data may be +read from 'fd' without blocking. + +*ZMQ_POLLOUT*:: +For 0MQ sockets, at least one message may be sent to the 'socket' without +blocking. For standard sockets this is equivalent to the 'POLLOUT' flag of the +_poll()_ system call and generally means that at least one byte of data may be +written to 'fd' without blocking. + +*ZMQ_POLLERR*:: +For standard sockets, this flag is passed through _zmq_poll()_ to the +underlying _poll()_ system call and generally means that some sort of error +condition is present on the socket specified by 'fd'. For 0MQ sockets this flag +has no effect if set in 'events', and shall never be returned in 'revents' by +_zmq_poll()_. + +NOTE: The _zmq_poll()_ function may be implemented or emulated using operating +system interfaces other than _poll()_, and as such may be subject to the limits +of those interfaces in ways not defined in this documentation. + + +RETURN VALUE +------------ +Upon successful completion, the _zmq_poll()_ function shall return the number +of *zmq_pollitem_t* structures with events signaled in 'revents' or `0` if no +events have been signaled. Upon failure, _zmq_poll()_ shall return `-1` and set +'errno' to one of the values defined below. + +IMPORTANT: The _zmq_poll()_ function may return *before* the 'timeout' period +has expired even if no events have been signaled. + + +ERRORS +------ +*EFAULT*:: +At least one of the members of the 'items' array refers to a 'socket' belonging +to a different application thread. +*ETERM*:: +At least one of the members of the 'items' array refers to a 'socket' whose +associated 0MQ 'context' was terminated. + + +EXAMPLE +------- +.Polling indefinitely for input events on both a 0MQ socket and a standard socket. +---- +zmq_pollitem_t items [2]; +/* First item refers to 0MQ socket 'socket' */ +items[0].socket = socket; +items[0].events = ZMQ_POLLIN; +/* Second item refers to standard socket 'fd' */ +items[1].socket = NULL; +items[1].fd = fd; +items[1].events = ZMQ_POLLIN; +/* Poll for events indefinitely */ +int rc = zmq_poll (items, 2, -1); +assert (rc >= 0); +/* Returned events will be stored in items[].revents */ +---- + + +SEE ALSO +-------- +linkzmq:zmq_socket[3] +linkzmq:zmq_send[3] +linkzmq:zmq_recv[3] +linkzmq:zmq[7] + +Your operating system documentation for the _poll()_ system call. + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_queue.1 b/doc/zmq_queue.1 new file mode 100644 index 0000000..bd085ee --- /dev/null +++ b/doc/zmq_queue.1 @@ -0,0 +1,57 @@ +'\" t +.\" Title: zmq_queue +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_QUEUE" "1" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_queue \- forwarding device for request\-reply messaging +.SH "SYNOPSIS" +.sp +To be written\&. +.SH "DESCRIPTION" +.sp +To be written\&. +.SH "OPTIONS" +.sp +To be written\&. +.SH "SEE ALSO" +.sp +\fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_queue.html b/doc/zmq_queue.html new file mode 100644 index 0000000..074b90a --- /dev/null +++ b/doc/zmq_queue.html @@ -0,0 +1,612 @@ + + + + + +zmq_queue(1) + + + + + +
+

SYNOPSIS

+
+

To be written.

+
+

DESCRIPTION

+
+

To be written.

+
+

OPTIONS

+
+

To be written.

+
+

SEE ALSO

+
+

zmq(7)

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_queue.txt b/doc/zmq_queue.txt new file mode 100644 index 0000000..a3f84f2 --- /dev/null +++ b/doc/zmq_queue.txt @@ -0,0 +1,33 @@ +zmq_queue(1) +============ + + +NAME +---- +zmq_queue - forwarding device for request-reply messaging + + +SYNOPSIS +-------- +To be written. + + +DESCRIPTION +----------- +To be written. + + +OPTIONS +------- +To be written. + + +SEE ALSO +-------- +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_recv.3 b/doc/zmq_recv.3 new file mode 100644 index 0000000..8e9720e --- /dev/null +++ b/doc/zmq_recv.3 @@ -0,0 +1,152 @@ +'\" t +.\" Title: zmq_recv +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_RECV" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_recv \- receive a message from a socket +.SH "SYNOPSIS" +.sp +\fBint zmq_recv (void \fR\fB\fI*socket\fR\fR\fB, zmq_msg_t \fR\fB\fI*msg\fR\fR\fB, int \fR\fB\fIflags\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_recv()\fR function shall receive a message from the socket referenced by the \fIsocket\fR argument and store it in the message referenced by the \fImsg\fR argument\&. Any content previously stored in \fImsg\fR shall be properly deallocated\&. If there are no messages available on the specified \fIsocket\fR the \fIzmq_recv()\fR function shall block until the request can be satisfied\&. The \fIflags\fR argument is a combination of the flags defined below: +.PP +\fBZMQ_NOBLOCK\fR +.RS 4 +Specifies that the operation should be performed in non\-blocking mode\&. If there are no messages available on the specified +\fIsocket\fR, the +\fIzmq_recv()\fR +function shall fail with +\fIerrno\fR +set to EAGAIN\&. +.RE +.SS "Multi\-part messages" +.sp +A 0MQ message is composed of 1 or more message parts; each message part is an independent \fIzmq_msg_t\fR in its own right\&. 0MQ ensures atomic delivery of messages; peers shall receive either all \fImessage parts\fR of a message or none at all\&. +.sp +The total number of message parts is unlimited\&. +.sp +An application wishing to determine if a message is composed of multiple parts does so by retrieving the value of the \fIZMQ_RCVMORE\fR socket option on the \fIsocket\fR it is receiving the message from\&. If there are no message parts to follow, or if the message is not composed of multiple parts, \fIZMQ_RCVMORE\fR shall report a value of zero\&. Otherwise, \fIZMQ_RCVMORE\fR shall report a value of 1, indicating that more message parts are to follow\&. +.SH "RETURN VALUE" +.sp +The \fIzmq_recv()\fR function shall return zero if successful\&. Otherwise it shall return \-1 and set \fIerrno\fR to one of the values defined below\&. +.SH "ERRORS" +.PP +\fBEAGAIN\fR +.RS 4 +Non\-blocking mode was requested and no messages are available at the moment\&. +.RE +.PP +\fBENOTSUP\fR +.RS 4 +The +\fIzmq_recv()\fR +operation is not supported by this socket type\&. +.RE +.PP +\fBEFSM\fR +.RS 4 +The +\fIzmq_recv()\fR +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 +\fImessaging patterns\fR +section of +\fBzmq_socket\fR(3) +for more information\&. +.RE +.PP +\fBETERM\fR +.RS 4 +The 0MQ +\fIcontext\fR +associated with the specified +\fIsocket\fR +was terminated\&. +.RE +.SH "EXAMPLE" +.PP +\fBReceiving a message from a socket\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +/* Create an empty 0MQ message */ +zmq_msg_t msg; +int rc = zmq_msg_init (&msg); +assert (rc == 0); +/* Block until a message is available to be received from socket */ +rc = zmq_recv (socket, &msg, 0); +assert (rc == 0); +.fi +.if n \{\ +.RE +.\} +.PP +\fBReceiving a multi-part message\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +int64_t more; +int64_t more_size = sizeof more; +do { + /* Create an empty 0MQ message to hold the message part */ + zmq_msg_t part; + int rc = zmq_msg_init (&part); + assert (rc == 0); + /* Block until a message is available to be received from socket */ + rc = zmq_recv (socket, &part, 0); + assert (rc == 0); + /* Determine if more message parts are to follow */ + rc = zmq_getsockopt (socket, ZMQ_RCVMORE, &more, &more_size); + assert (rc == 0); +} while (more); +.fi +.if n \{\ +.RE +.\} +.sp +.SH "SEE ALSO" +.sp +\fBzmq_send\fR(3) \fBzmq_getsockopt\fR(3) \fBzmq_socket\fR(7) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_recv.html b/doc/zmq_recv.html new file mode 100644 index 0000000..218892d --- /dev/null +++ b/doc/zmq_recv.html @@ -0,0 +1,717 @@ + + + + + +zmq_recv(3) + + + + + +
+

SYNOPSIS

+
+

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

+
+

DESCRIPTION

+
+

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

+
+
+ZMQ_NOBLOCK +
+
+

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

+
+
+

Multi-part messages

+

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

+

The total number of message parts is unlimited.

+

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

+
+

RETURN VALUE

+
+

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

+
+

ERRORS

+
+
+
+EAGAIN +
+
+

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

+
+
+ENOTSUP +
+
+

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

+
+
+EFSM +
+
+

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

+
+
+ETERM +
+
+

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

+
+
+
+

EXAMPLE

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

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_recv.txt b/doc/zmq_recv.txt new file mode 100644 index 0000000..79d3dc1 --- /dev/null +++ b/doc/zmq_recv.txt @@ -0,0 +1,111 @@ +zmq_recv(3) +=========== + + +NAME +---- +zmq_recv - receive a message from a socket + + +SYNOPSIS +-------- +*int zmq_recv (void '*socket', zmq_msg_t '*msg', int 'flags');* + + +DESCRIPTION +----------- +The _zmq_recv()_ function shall receive a message from the socket referenced by +the 'socket' argument and store it in the message referenced by the 'msg' +argument. Any content previously stored in 'msg' shall be properly deallocated. +If there are no messages available on the specified 'socket' the _zmq_recv()_ +function shall block until the request can be satisfied. The 'flags' argument +is a combination of the flags defined below: + +*ZMQ_NOBLOCK*:: +Specifies that the operation should be performed in non-blocking mode. If there +are no messages available on the specified 'socket', the _zmq_recv()_ function +shall fail with 'errno' set to EAGAIN. + + +Multi-part messages +~~~~~~~~~~~~~~~~~~~ +A 0MQ message is composed of 1 or more message parts; each message part is an +independent 'zmq_msg_t' in its own right. 0MQ ensures atomic delivery of +messages; peers shall receive either all _message parts_ of a message or none +at all. + +The total number of message parts is unlimited. + +An application wishing to determine if a message is composed of multiple parts +does so by retrieving the value of the _ZMQ_RCVMORE_ socket option on the +'socket' it is receiving the message from. If there are no message parts to +follow, or if the message is not composed of multiple parts, _ZMQ_RCVMORE_ +shall report a value of zero. Otherwise, _ZMQ_RCVMORE_ shall report a value of +1, indicating that more message parts are to follow. + + +RETURN VALUE +------------ +The _zmq_recv()_ function shall return zero if successful. Otherwise it shall +return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +*EAGAIN*:: +Non-blocking mode was requested and no messages are available at the moment. +*ENOTSUP*:: +The _zmq_recv()_ operation is not supported by this socket type. +*EFSM*:: +The _zmq_recv()_ operation cannot be performed on this socket at the moment due +to the socket not being in the appropriate state. This error may occur with +socket types that switch between several states, such as ZMQ_REP. See the +_messaging patterns_ section of linkzmq:zmq_socket[3] for more information. +*ETERM*:: +The 0MQ 'context' associated with the specified 'socket' was terminated. + + +EXAMPLE +------- +.Receiving a message from a socket +---- +/* Create an empty 0MQ message */ +zmq_msg_t msg; +int rc = zmq_msg_init (&msg); +assert (rc == 0); +/* Block until a message is available to be received from socket */ +rc = zmq_recv (socket, &msg, 0); +assert (rc == 0); +---- + +.Receiving a multi-part message +---- +int64_t more; +int64_t more_size = sizeof more; +do { + /* Create an empty 0MQ message to hold the message part */ + zmq_msg_t part; + int rc = zmq_msg_init (&part); + assert (rc == 0); + /* Block until a message is available to be received from socket */ + rc = zmq_recv (socket, &part, 0); + assert (rc == 0); + /* Determine if more message parts are to follow */ + rc = zmq_getsockopt (socket, ZMQ_RCVMORE, &more, &more_size); + assert (rc == 0); +} while (more); +---- + + +SEE ALSO +-------- +linkzmq:zmq_send[3] +linkzmq:zmq_getsockopt[3] +linkzmq:zmq_socket[7] +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_send.3 b/doc/zmq_send.3 new file mode 100644 index 0000000..5161d4e --- /dev/null +++ b/doc/zmq_send.3 @@ -0,0 +1,166 @@ +'\" t +.\" Title: zmq_send +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_SEND" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_send \- send a message on a socket +.SH "SYNOPSIS" +.sp +\fBint zmq_send (void \fR\fB\fI*socket\fR\fR\fB, zmq_msg_t \fR\fB\fI*msg\fR\fR\fB, int \fR\fB\fIflags\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_send()\fR function shall queue the message referenced by the \fImsg\fR argument to be sent to the socket referenced by the \fIsocket\fR argument\&. The \fIflags\fR argument is a combination of the flags defined below: +.PP +\fBZMQ_NOBLOCK\fR +.RS 4 +Specifies that the operation should be performed in non\-blocking mode\&. If the message cannot be queued on the +\fIsocket\fR, the +\fIzmq_send()\fR +function shall fail with +\fIerrno\fR +set to EAGAIN\&. +.RE +.PP +\fBZMQ_SNDMORE\fR +.RS 4 +Specifies that the message being sent is a multi\-part message, and that further message parts are to follow\&. Refer to the section regarding multi\-part messages below for a detailed description\&. +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.sp +A successful invocation of \fIzmq_send()\fR does not indicate that the message has been transmitted to the network, only that it has been queued on the \fIsocket\fR and 0MQ has assumed responsibility for the message\&. +.sp .5v +.RE +.SS "Multi\-part messages" +.sp +A 0MQ message is composed of 1 or more message parts; each message part is an independent \fIzmq_msg_t\fR in its own right\&. 0MQ ensures atomic delivery of messages; peers shall receive either all \fImessage parts\fR of a message or none at all\&. +.sp +The total number of message parts is unlimited\&. +.sp +An application wishing to send a multi\-part message does so by specifying the \fIZMQ_SNDMORE\fR flag to \fIzmq_send()\fR\&. The presence of this flag indicates to 0MQ that the message being sent is a multi\-part message and that more message parts are to follow\&. When the application wishes to send the final message part it does so by calling \fIzmq_send()\fR without the \fIZMQ_SNDMORE\fR flag; this indicates that no more message parts are to follow\&. +.SH "RETURN VALUE" +.sp +The \fIzmq_send()\fR function shall return zero if successful\&. Otherwise it shall return \-1 and set \fIerrno\fR to one of the values defined below\&. +.SH "ERRORS" +.PP +\fBEAGAIN\fR +.RS 4 +Non\-blocking mode was requested and the message cannot be sent at the moment\&. +.RE +.PP +\fBENOTSUP\fR +.RS 4 +The +\fIzmq_send()\fR +operation is not supported by this socket type\&. +.RE +.PP +\fBEFSM\fR +.RS 4 +The +\fIzmq_send()\fR +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 +\fImessaging patterns\fR +section of +\fBzmq_socket\fR(3) +for more information\&. +.RE +.PP +\fBETERM\fR +.RS 4 +The 0MQ +\fIcontext\fR +associated with the specified +\fIsocket\fR +was terminated\&. +.RE +.SH "EXAMPLE" +.PP +\fBFilling in a message and sending it to a socket\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +/* Create a new message, allocating 6 bytes for message content */ +zmq_msg_t msg; +int rc = zmq_msg_init_size (&msg, 6); +assert (rc == 0); +/* Fill in message content with \*(AqAAAAAA\*(Aq */ +memset (zmq_msg_data (&msg), \*(AqA\*(Aq, 6); +/* Send the message to the socket */ +rc = zmq_send (socket, &msg, 0); +assert (rc == 0); +.fi +.if n \{\ +.RE +.\} +.PP +\fBSending a multi-part message\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +/* Send a multi\-part message consisting of three parts to socket */ +rc = zmq_send (socket, &part1, ZMQ_SNDMORE); +rc = zmq_send (socket, &part2, ZMQ_SNDMORE); +/* Final part; no more parts to follow */ +rc = zmq_send (socket, &part3, 0); +.fi +.if n \{\ +.RE +.\} +.sp +.SH "SEE ALSO" +.sp +\fBzmq_recv\fR(3) \fBzmq_socket\fR(7) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_send.html b/doc/zmq_send.html new file mode 100644 index 0000000..22bd55a --- /dev/null +++ b/doc/zmq_send.html @@ -0,0 +1,726 @@ + + + + + +zmq_send(3) + + + + + +
+

SYNOPSIS

+
+

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

+
+

DESCRIPTION

+
+

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

+
+
+ZMQ_NOBLOCK +
+
+

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

+
+
+ZMQ_SNDMORE +
+
+

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

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

Multi-part messages

+

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

+

The total number of message parts is unlimited.

+

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

+
+

RETURN VALUE

+
+

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

+
+

ERRORS

+
+
+
+EAGAIN +
+
+

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

+
+
+ENOTSUP +
+
+

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

+
+
+EFSM +
+
+

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

+
+
+ETERM +
+
+

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

+
+
+
+

EXAMPLE

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

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_send.txt b/doc/zmq_send.txt new file mode 100644 index 0000000..419e386 --- /dev/null +++ b/doc/zmq_send.txt @@ -0,0 +1,109 @@ +zmq_send(3) +=========== + + +NAME +---- +zmq_send - send a message on a socket + + +SYNOPSIS +-------- +*int zmq_send (void '*socket', zmq_msg_t '*msg', int 'flags');* + + +DESCRIPTION +----------- +The _zmq_send()_ function shall queue the message referenced by the 'msg' +argument to be sent to the socket referenced by the 'socket' argument. The +'flags' argument is a combination of the flags defined below: + +*ZMQ_NOBLOCK*:: +Specifies that the operation should be performed in non-blocking mode. If the +message cannot be queued on the 'socket', the _zmq_send()_ function shall fail +with 'errno' set to EAGAIN. + +*ZMQ_SNDMORE*:: +Specifies that the message being sent is a multi-part message, and that further +message parts are to follow. Refer to the section regarding multi-part messages +below for a detailed description. + +NOTE: A successful invocation of _zmq_send()_ does not indicate that the +message has been transmitted to the network, only that it has been queued on +the 'socket' and 0MQ has assumed responsibility for the message. + + +Multi-part messages +~~~~~~~~~~~~~~~~~~~ +A 0MQ message is composed of 1 or more message parts; each message part is an +independent 'zmq_msg_t' in its own right. 0MQ ensures atomic delivery of +messages; peers shall receive either all _message parts_ of a message or none +at all. + +The total number of message parts is unlimited. + +An application wishing to send a multi-part message does so by specifying the +'ZMQ_SNDMORE' flag to _zmq_send()_. The presence of this flag indicates to 0MQ +that the message being sent is a multi-part message and that more message parts +are to follow. When the application wishes to send the final message part it +does so by calling _zmq_send()_ without the 'ZMQ_SNDMORE' flag; this indicates +that no more message parts are to follow. + + +RETURN VALUE +------------ +The _zmq_send()_ function shall return zero if successful. Otherwise it shall +return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +*EAGAIN*:: +Non-blocking mode was requested and the message cannot be sent at the moment. +*ENOTSUP*:: +The _zmq_send()_ operation is not supported by this socket type. +*EFSM*:: +The _zmq_send()_ operation cannot be performed on this socket at the moment due +to the socket not being in the appropriate state. This error may occur with +socket types that switch between several states, such as ZMQ_REP. See the +_messaging patterns_ section of linkzmq:zmq_socket[3] for more information. +*ETERM*:: +The 0MQ 'context' associated with the specified 'socket' was terminated. + + +EXAMPLE +------- +.Filling in a message and sending it to a socket +---- +/* Create a new message, allocating 6 bytes for message content */ +zmq_msg_t msg; +int rc = zmq_msg_init_size (&msg, 6); +assert (rc == 0); +/* Fill in message content with 'AAAAAA' */ +memset (zmq_msg_data (&msg), 'A', 6); +/* Send the message to the socket */ +rc = zmq_send (socket, &msg, 0); +assert (rc == 0); +---- + +.Sending a multi-part message +---- +/* Send a multi-part message consisting of three parts to socket */ +rc = zmq_send (socket, &part1, ZMQ_SNDMORE); +rc = zmq_send (socket, &part2, ZMQ_SNDMORE); +/* Final part; no more parts to follow */ +rc = zmq_send (socket, &part3, 0); +---- + + +SEE ALSO +-------- +linkzmq:zmq_recv[3] +linkzmq:zmq_socket[7] +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_setsockopt.3 b/doc/zmq_setsockopt.3 new file mode 100644 index 0000000..8ed1e59 --- /dev/null +++ b/doc/zmq_setsockopt.3 @@ -0,0 +1,583 @@ +'\" t +.\" Title: zmq_setsockopt +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_SETSOCKOPT" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_setsockopt \- set 0MQ socket options +.SH "SYNOPSIS" +.sp +\fBint zmq_setsockopt (void \fR\fB\fI*socket\fR\fR\fB, int \fR\fB\fIoption_name\fR\fR\fB, const void \fR\fB\fI*option_value\fR\fR\fB, size_t \fR\fB\fIoption_len\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_setsockopt()\fR function shall set the option specified by the \fIoption_name\fR argument to the value pointed to by the \fIoption_value\fR argument for the 0MQ socket pointed to by the \fIsocket\fR argument\&. The \fIoption_len\fR argument is the size of the option value in bytes\&. +.sp +The following socket options can be set with the \fIzmq_setsockopt()\fR function: +.SS "ZMQ_HWM: Set high water mark" +.sp +The \fIZMQ_HWM\fR option shall set the high water mark for the specified \fIsocket\fR\&. The high water mark is a hard limit on the maximum number of outstanding messages 0MQ shall queue in memory for any single peer that the specified \fIsocket\fR is communicating with\&. +.sp +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 \fBzmq_socket\fR(3) for details on the exact action taken for each socket type\&. +.sp +The default \fIZMQ_HWM\fR value of zero means "no limit"\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +int64_t +T} +T{ +.sp +Option value unit +T}:T{ +.sp +messages +T} +T{ +.sp +Default value +T}:T{ +.sp +0 +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +all +T} +.TE +.sp 1 +.SS "ZMQ_SWAP: Set disk offload size" +.sp +The \fIZMQ_SWAP\fR option shall set the disk offload (swap) size for the specified \fIsocket\fR\&. A socket which has \fIZMQ_SWAP\fR set to a non\-zero value may exceed it\(cqs high water mark; in this case outstanding messages shall be offloaded to storage on disk rather than held in memory\&. +.sp +The value of \fIZMQ_SWAP\fR defines the maximum size of the swap space in bytes\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +int64_t +T} +T{ +.sp +Option value unit +T}:T{ +.sp +bytes +T} +T{ +.sp +Default value +T}:T{ +.sp +0 +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +all +T} +.TE +.sp 1 +.SS "ZMQ_AFFINITY: Set I/O thread affinity" +.sp +The \fIZMQ_AFFINITY\fR option shall set the I/O thread affinity for newly created connections on the specified \fIsocket\fR\&. +.sp +Affinity determines which threads from the 0MQ I/O thread pool associated with the socket\(cqs \fIcontext\fR shall handle newly created connections\&. A value of zero specifies no affinity, meaning that work shall be distributed fairly among all 0MQ I/O threads in the thread pool\&. For non\-zero values, the lowest bit corresponds to thread 1, second lowest bit to thread 2 and so on\&. For example, a value of 3 specifies that subsequent connections on \fIsocket\fR shall be handled exclusively by I/O threads 1 and 2\&. +.sp +See also \fBzmq_init\fR(3) for details on allocating the number of I/O threads for a specific \fIcontext\fR\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +int64_t +T} +T{ +.sp +Option value unit +T}:T{ +.sp +N/A (bitmap) +T} +T{ +.sp +Default value +T}:T{ +.sp +0 +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +N/A +T} +.TE +.sp 1 +.SS "ZMQ_IDENTITY: Set socket identity" +.sp +The \fIZMQ_IDENTITY\fR option shall set the identity of the specified \fIsocket\fR\&. Socket identity determines if existing 0MQ infastructure (\fImessage queues\fR, \fIforwarding devices\fR) shall be identified with a specific application and persist across multiple runs of the application\&. +.sp +If the socket has no identity, each run of an application is completely separate from other runs\&. However, with identity set the socket shall re\-use any existing 0MQ infrastructure configured by the previous run(s)\&. Thus the application may receive messages that were sent in the meantime, \fImessage queue\fR limits shall be shared with previous run(s) and so on\&. +.sp +Identity should be at least one byte and at most 255 bytes long\&. Identities starting with binary zero are reserved for use by 0MQ infrastructure\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +binary data +T} +T{ +.sp +Option value unit +T}:T{ +.sp +N/A +T} +T{ +.sp +Default value +T}:T{ +.sp +NULL +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +all +T} +.TE +.sp 1 +.SS "ZMQ_SUBSCRIBE: Establish message filter" +.sp +The \fIZMQ_SUBSCRIBE\fR option shall establish a new message filter on a \fIZMQ_SUB\fR socket\&. Newly created \fIZMQ_SUB\fR sockets shall filter out all incoming messages, therefore you should call this option to establish an initial message filter\&. +.sp +An empty \fIoption_value\fR of length zero shall subscribe to all incoming messages\&. A non\-empty \fIoption_value\fR shall subscribe to all messages beginning with the specified prefix\&. Mutiple filters may be attached to a single \fIZMQ_SUB\fR socket, in which case a message shall be accepted if it matches at least one filter\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +binary data +T} +T{ +.sp +Option value unit +T}:T{ +.sp +N/A +T} +T{ +.sp +Default value +T}:T{ +.sp +N/A +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +ZMQ_SUB +T} +.TE +.sp 1 +.SS "ZMQ_UNSUBSCRIBE: Remove message filter" +.sp +The \fIZMQ_UNSUBSCRIBE\fR option shall remove an existing message filter on a \fIZMQ_SUB\fR socket\&. The filter specified must match an existing filter previously established with the \fIZMQ_SUBSCRIBE\fR option\&. If the socket has several instances of the same filter attached the \fIZMQ_UNSUBSCRIBE\fR option shall remove only one instance, leaving the rest in place and functional\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +binary data +T} +T{ +.sp +Option value unit +T}:T{ +.sp +N/A +T} +T{ +.sp +Default value +T}:T{ +.sp +N/A +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +ZMQ_SUB +T} +.TE +.sp 1 +.SS "ZMQ_RATE: Set multicast data rate" +.sp +The \fIZMQ_RATE\fR option shall set the maximum send or receive data rate for multicast transports such as \fBzmq_pgm\fR(7) using the specified \fIsocket\fR\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +uint64_t +T} +T{ +.sp +Option value unit +T}:T{ +.sp +kilobits per second +T} +T{ +.sp +Default value +T}:T{ +.sp +100 +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +all, when using multicast transports +T} +.TE +.sp 1 +.SS "ZMQ_RECOVERY_IVL: Set multicast recovery interval" +.sp +The \fIZMQ_RECOVERY_IVL\fR option shall set the recovery interval for multicast transports using the specified \fIsocket\fR\&. The recovery interval determines the maximum time in seconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.sp +Excersize care when setting large recovery intervals as the data needed for recovery will be held in memory\&. For example, a 1 minute recovery interval at a data rate of 1Gbps requires a 7GB in\-memory buffer\&. +.sp .5v +.RE +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +uint64_t +T} +T{ +.sp +Option value unit +T}:T{ +.sp +seconds +T} +T{ +.sp +Default value +T}:T{ +.sp +10 +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +all, when using multicast transports +T} +.TE +.sp 1 +.SS "ZMQ_MCAST_LOOP: Control multicast loopback" +.sp +The \fIZMQ_MCAST_LOOP\fR option shall control whether data sent via multicast transports using the specified \fIsocket\fR can also be received by the sending host via loopback\&. A value of zero disables the loopback functionality, while the default value of 1 enables the loopback functionality\&. Leaving multicast loopback enabled when it is not required can have a negative impact on performance\&. Where possible, disable \fIZMQ_MCAST_LOOP\fR in production environments\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +uint64_t +T} +T{ +.sp +Option value unit +T}:T{ +.sp +boolean +T} +T{ +.sp +Default value +T}:T{ +.sp +1 +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +all, when using multicast transports +T} +.TE +.sp 1 +.SS "ZMQ_SNDBUF: Set kernel transmit buffer size" +.sp +The \fIZMQ_SNDBUF\fR option shall set the underlying kernel transmit buffer size for the \fIsocket\fR to the specified size in bytes\&. A value of zero means leave the OS default unchanged\&. For details please refer to your operating system documentation for the \fISO_SNDBUF\fR socket option\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +uint64_t +T} +T{ +.sp +Option value unit +T}:T{ +.sp +bytes +T} +T{ +.sp +Default value +T}:T{ +.sp +0 +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +all +T} +.TE +.sp 1 +.SS "ZMQ_RCVBUF: Set kernel receive buffer size" +.sp +The \fIZMQ_RCVBUF\fR option shall set the underlying kernel receive buffer size for the \fIsocket\fR to the specified size in bytes\&. A value of zero means leave the OS default unchanged\&. For details refer to your operating system documentation for the \fISO_RCVBUF\fR socket option\&. +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Option value type +T}:T{ +.sp +uint64_t +T} +T{ +.sp +Option value unit +T}:T{ +.sp +bytes +T} +T{ +.sp +Default value +T}:T{ +.sp +0 +T} +T{ +.sp +Applicable socket types +T}:T{ +.sp +all +T} +.TE +.sp 1 +.SH "RETURN VALUE" +.sp +The \fIzmq_setsockopt()\fR function shall return zero if successful\&. Otherwise it shall return \-1 and set \fIerrno\fR to one of the values defined below\&. +.SH "ERRORS" +.PP +\fBEINVAL\fR +.RS 4 +The requested option +\fIoption_name\fR +is unknown, or the requested +\fIoption_len\fR +or +\fIoption_value\fR +is invalid\&. +.RE +.PP +\fBETERM\fR +.RS 4 +The 0MQ +\fIcontext\fR +associated with the specified +\fIsocket\fR +was terminated\&. +.RE +.SH "EXAMPLE" +.PP +\fBSubscribing to messages on a ZMQ_SUB socket\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +/* Subscribe to all messages */ +rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "", 0); +assert (rc == 0); +/* Subscribe to messages prefixed with "ANIMALS\&.CATS" */ +rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "ANIMALS\&.CATS", 12); +.fi +.if n \{\ +.RE +.\} +.PP +\fBSetting I/O thread affinity\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +int64_t affinity; +/* Incoming connections on TCP port 5555 shall be handled by I/O thread 1 */ +affinity = 1; +rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof affinity); +assert (rc); +rc = zmq_bind (socket, "tcp://lo:5555"); +assert (rc); +/* Incoming connections on TCP port 5556 shall be handled by I/O thread 2 */ +affinity = 2; +rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof affinity); +assert (rc); +rc = zmq_bind (socket, "tcp://lo:5556"); +assert (rc); +.fi +.if n \{\ +.RE +.\} +.sp +.SH "SEE ALSO" +.sp +\fBzmq_getsockopt\fR(3) \fBzmq_socket\fR(3) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_setsockopt.html b/doc/zmq_setsockopt.html new file mode 100644 index 0000000..2bccca9 --- /dev/null +++ b/doc/zmq_setsockopt.html @@ -0,0 +1,1268 @@ + + + + + +zmq_setsockopt(3) + + + + + +
+

SYNOPSIS

+
+

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

+
+

DESCRIPTION

+
+

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

+

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

+

ZMQ_HWM: Set high water mark

+

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

+

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

+

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

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

+int64_t +

+
+Option value unit +
+		 +

+messages +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_SWAP: Set disk offload size

+

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

+

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

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

+int64_t +

+
+Option value unit +
+		 +

+bytes +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_AFFINITY: Set I/O thread affinity

+

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

+

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

+

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

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

+int64_t +

+
+Option value unit +
+		 +

+N/A (bitmap) +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+N/A +

+
+

ZMQ_IDENTITY: Set socket identity

+

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

+

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

+

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

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

+binary data +

+
+Option value unit +
+		 +

+N/A +

+
+Default value +
+		 +

+NULL +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_SUBSCRIBE: Establish message filter

+

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

+

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

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

+binary data +

+
+Option value unit +
+		 +

+N/A +

+
+Default value +
+		 +

+N/A +

+
+Applicable socket types +
+		 +

+ZMQ_SUB +

+
+

ZMQ_UNSUBSCRIBE: Remove message filter

+

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

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

+binary data +

+
+Option value unit +
+		 +

+N/A +

+
+Default value +
+		 +

+N/A +

+
+Applicable socket types +
+		 +

+ZMQ_SUB +

+
+

ZMQ_RATE: Set multicast data rate

+

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

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

+uint64_t +

+
+Option value unit +
+		 +

+kilobits per second +

+
+Default value +
+		 +

+100 +

+
+Applicable socket types +
+		 +

+all, when using multicast transports +

+
+

ZMQ_RECOVERY_IVL: Set multicast recovery interval

+

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

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

+uint64_t +

+
+Option value unit +
+		 +

+seconds +

+
+Default value +
+		 +

+10 +

+
+Applicable socket types +
+		 +

+all, when using multicast transports +

+
+

ZMQ_MCAST_LOOP: Control multicast loopback

+

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

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

+uint64_t +

+
+Option value unit +
+		 +

+boolean +

+
+Default value +
+		 +

+1 +

+
+Applicable socket types +
+		 +

+all, when using multicast transports +

+
+

ZMQ_SNDBUF: Set kernel transmit buffer size

+

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

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

+uint64_t +

+
+Option value unit +
+		 +

+bytes +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+all +

+
+

ZMQ_RCVBUF: Set kernel receive buffer size

+

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

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

+uint64_t +

+
+Option value unit +
+		 +

+bytes +

+
+Default value +
+		 +

+0 +

+
+Applicable socket types +
+		 +

+all +

+
+
+

RETURN VALUE

+
+

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

+
+

ERRORS

+
+
+
+EINVAL +
+
+

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

+
+
+ETERM +
+
+

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

+
+
+
+

EXAMPLE

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

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt new file mode 100644 index 0000000..a5a2601 --- /dev/null +++ b/doc/zmq_setsockopt.txt @@ -0,0 +1,273 @@ +zmq_setsockopt(3) +================= + + +NAME +---- + +zmq_setsockopt - set 0MQ socket options + + +SYNOPSIS +-------- +*int zmq_setsockopt (void '*socket', int 'option_name', const void '*option_value', size_t 'option_len');* + + +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' +argument is the size of the option value in bytes. + +The following socket options can be set with the _zmq_setsockopt()_ function: + + +ZMQ_HWM: Set high water mark +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_HWM' option shall set the high water mark for the specified 'socket'. +The high water mark is a hard limit on the maximum number of outstanding +messages 0MQ shall queue in memory for any single peer that the specified +'socket' is communicating with. + +If this limit has been reached the socket shall enter an exceptional state and +depending on the socket type, 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 +type. + +The default 'ZMQ_HWM' value of zero means "no limit". + +[horizontal] +Option value type:: int64_t +Option value unit:: messages +Default value:: 0 +Applicable socket types:: all + + +ZMQ_SWAP: Set disk offload size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_SWAP' option shall set the disk offload (swap) size for the specified +'socket'. A socket which has 'ZMQ_SWAP' set to a non-zero value may exceed it's +high water mark; in this case outstanding messages shall be offloaded to +storage on disk rather than held in memory. + +The value of 'ZMQ_SWAP' defines the maximum size of the swap space in bytes. + +[horizontal] +Option value type:: int64_t +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +ZMQ_AFFINITY: Set I/O thread affinity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_AFFINITY' option shall set the I/O thread affinity for newly created +connections on the specified 'socket'. + +Affinity determines which threads from the 0MQ I/O thread pool associated with +the socket's _context_ shall handle newly created connections. A value of zero +specifies no affinity, meaning that work shall be distributed fairly among all +0MQ I/O threads in the thread pool. For non-zero values, the lowest bit +corresponds to thread 1, second lowest bit to thread 2 and so on. For example, +a value of 3 specifies that subsequent connections on 'socket' shall be handled +exclusively by I/O threads 1 and 2. + +See also linkzmq:zmq_init[3] for details on allocating the number of I/O +threads for a specific _context_. + +[horizontal] +Option value type:: int64_t +Option value unit:: N/A (bitmap) +Default value:: 0 +Applicable socket types:: N/A + + +ZMQ_IDENTITY: Set socket identity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_IDENTITY' option shall set the identity of the specified 'socket'. +Socket identity determines if existing 0MQ infastructure (_message queues_, +_forwarding devices_) shall be identified with a specific application and +persist across multiple runs of the application. + +If the socket has no identity, each run of an application is completely +separate from other runs. However, with identity set the socket shall re-use +any existing 0MQ infrastructure configured by the previous run(s). Thus the +application may receive messages that were sent in the meantime, _message +queue_ limits shall be shared with previous run(s) and so on. + +Identity should be at least one byte and at most 255 bytes long. Identities +starting with binary zero are reserved for use by 0MQ infrastructure. + +[horizontal] +Option value type:: binary data +Option value unit:: N/A +Default value:: NULL +Applicable socket types:: all + + +ZMQ_SUBSCRIBE: Establish message filter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_SUBSCRIBE' option shall establish a new message filter on a 'ZMQ_SUB' +socket. Newly created 'ZMQ_SUB' sockets shall filter out all incoming messages, +therefore you should call this option to establish an initial message filter. + +An empty 'option_value' of length zero shall subscribe to all incoming +messages. A non-empty 'option_value' shall subscribe to all messages beginning +with the specified prefix. Mutiple filters may be attached to a single +'ZMQ_SUB' socket, in which case a message shall be accepted if it matches at +least one filter. + +[horizontal] +Option value type:: binary data +Option value unit:: N/A +Default value:: N/A +Applicable socket types:: ZMQ_SUB + + +ZMQ_UNSUBSCRIBE: Remove message filter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_UNSUBSCRIBE' option shall remove an existing message filter on a +'ZMQ_SUB' socket. The filter specified must match an existing filter previously +established with the 'ZMQ_SUBSCRIBE' option. If the socket has several +instances of the same filter attached the 'ZMQ_UNSUBSCRIBE' option shall remove +only one instance, leaving the rest in place and functional. + +[horizontal] +Option value type:: binary data +Option value unit:: N/A +Default value:: N/A +Applicable socket types:: ZMQ_SUB + + +ZMQ_RATE: Set multicast data rate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RATE' option shall set the maximum send or receive data rate for +multicast transports such as linkzmq:zmq_pgm[7] using the specified 'socket'. + +[horizontal] +Option value type:: uint64_t +Option value unit:: kilobits per second +Default value:: 100 +Applicable socket types:: all, when using multicast transports + + +ZMQ_RECOVERY_IVL: Set multicast recovery interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RECOVERY_IVL' option shall set the recovery interval for multicast +transports using the specified 'socket'. The recovery interval determines the +maximum time in seconds that a receiver can be absent from a multicast group +before unrecoverable data loss will occur. + +CAUTION: Excersize care when setting large recovery intervals as the data +needed for recovery will be held in memory. For example, a 1 minute recovery +interval at a data rate of 1Gbps requires a 7GB in-memory buffer. + +[horizontal] +Option value type:: uint64_t +Option value unit:: seconds +Default value:: 10 +Applicable socket types:: all, when using multicast transports + + +ZMQ_MCAST_LOOP: Control multicast loopback +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_MCAST_LOOP' option shall control whether data sent via multicast +transports using the specified 'socket' can also be received by the sending +host via loopback. A value of zero disables the loopback functionality, while +the default value of 1 enables the loopback functionality. Leaving multicast +loopback enabled when it is not required can have a negative impact on +performance. Where possible, disable 'ZMQ_MCAST_LOOP' in production +environments. + +[horizontal] +Option value type:: uint64_t +Option value unit:: boolean +Default value:: 1 +Applicable socket types:: all, when using multicast transports + + +ZMQ_SNDBUF: Set kernel transmit buffer size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_SNDBUF' option shall set the underlying kernel transmit buffer size +for the 'socket' to the specified size in bytes. A value of zero means leave +the OS default unchanged. For details please refer to your operating system +documentation for the 'SO_SNDBUF' socket option. + +[horizontal] +Option value type:: uint64_t +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +ZMQ_RCVBUF: Set kernel receive buffer size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RCVBUF' option shall set the underlying kernel receive buffer size for +the 'socket' to the specified size in bytes. A value of zero means leave the +OS default unchanged. For details refer to your operating system documentation +for the 'SO_RCVBUF' socket option. + +[horizontal] +Option value type:: uint64_t +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +RETURN VALUE +------------ +The _zmq_setsockopt()_ function shall return zero if successful. Otherwise it +shall return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +*EINVAL*:: +The requested option _option_name_ is unknown, or the requested _option_len_ or +_option_value_ is invalid. +*ETERM*:: +The 0MQ 'context' associated with the specified 'socket' was terminated. + + +EXAMPLE +------- +.Subscribing to messages on a 'ZMQ_SUB' socket +---- +/* Subscribe to all messages */ +rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "", 0); +assert (rc == 0); +/* Subscribe to messages prefixed with "ANIMALS.CATS" */ +rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "ANIMALS.CATS", 12); +---- + +.Setting I/O thread affinity +---- +int64_t affinity; +/* Incoming connections on TCP port 5555 shall be handled by I/O thread 1 */ +affinity = 1; +rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof affinity); +assert (rc); +rc = zmq_bind (socket, "tcp://lo:5555"); +assert (rc); +/* Incoming connections on TCP port 5556 shall be handled by I/O thread 2 */ +affinity = 2; +rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof affinity); +assert (rc); +rc = zmq_bind (socket, "tcp://lo:5556"); +assert (rc); +---- + + +SEE ALSO +-------- +linkzmq:zmq_getsockopt[3] +linkzmq:zmq_socket[3] +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_socket.3 b/doc/zmq_socket.3 new file mode 100644 index 0000000..3e4ebd1 --- /dev/null +++ b/doc/zmq_socket.3 @@ -0,0 +1,609 @@ +'\" t +.\" Title: zmq_socket +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_SOCKET" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_socket \- create 0MQ socket +.SH "SYNOPSIS" +.sp +\fBvoid *zmq_socket (void \fR\fB\fI*context\fR\fR\fB, int \fR\fB\fItype\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_socket()\fR function shall create a 0MQ socket within the specified \fIcontext\fR and return an opaque handle to the newly created socket\&. The \fItype\fR argument specifies the socket type, which determines the semantics of communication over the socket\&. +.sp +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 \fBzmq_connect\fR(3), or at least one endpoint must be created for accepting incoming connections with \fBzmq_bind\fR(3)\&. +.PP +\fBKey differences to conventional sockets\fR. Generally speaking, conventional sockets present a +\fIsynchronous\fR +interface to either connection\-oriented reliable byte streams (SOCK_STREAM), or connection\-less unreliable datagrams (SOCK_DGRAM)\&. In comparison, 0MQ sockets present an abstraction of an asynchronous +\fImessage queue\fR, with the exact queueing semantics depending on the socket type in use\&. Where conventional sockets transfer streams of bytes or discrete datagrams, 0MQ sockets transfer discrete +\fImessages\fR\&. +.sp +0MQ sockets being \fIasynchronous\fR means that the timings of the physical connection setup and teardown, reconnect and effective delivery are transparent to the user and organized by 0MQ itself\&. Further, messages may be \fIqueued\fR in the event that a peer is unavailable to receive them\&. +.sp +Conventional sockets allow only strict one\-to\-one (two peers), many\-to\-one (many clients, one server), or in some cases one\-to\-many (multicast) relationships\&. With the exception of \fIZMQ_PAIR\fR, 0MQ sockets may be connected \fBto multiple endpoints\fR using \fIzmq_connect()\fR, while simultaneously accepting incoming connections \fBfrom multiple endpoints\fR bound to the socket using \fIzmq_bind()\fR, thus allowing many\-to\-many relationships\&. +.PP +\fBSocket types\fR. The following sections present the socket types defined by 0MQ, grouped by the general +\fImessaging pattern\fR +which is built from related socket types\&. +.SS "Request\-reply pattern" +.sp +The request\-reply pattern is used for sending requests from a \fIclient\fR to one or more instances of a \fIservice\fR, and receiving subsequent replies to each request sent\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBZMQ_REQ\fR +.RS 4 +.sp +A socket of type \fIZMQ_REQ\fR is used by a \fIclient\fR to send requests to and receive replies from a \fIservice\fR\&. This socket type allows only an alternating sequence of \fIzmq_send(request)\fR and subsequent \fIzmq_recv(reply)\fR calls\&. Each request sent is load\-balanced among all \fIservices\fR, and each reply received is matched with the last issued request\&. +.sp +When a \fIZMQ_REQ\fR socket enters an exceptional state due to having reached the high water mark for all \fIservices\fR, or if there are no \fIservices\fR at all, then any \fBzmq_send\fR(3) operations on the socket shall block until the exceptional state ends or at least one \fIservice\fR becomes available for sending; messages are not discarded\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&Summary of ZMQ_REQ characteristics +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Compatible peer sockets +T}:T{ +.sp +\fIZMQ_REP\fR +T} +T{ +.sp +Direction +T}:T{ +.sp +Bidirectional +T} +T{ +.sp +Send/receive pattern +T}:T{ +.sp +Send, Receive, Send, Receive, \&... +T} +T{ +.sp +Outgoing routing strategy +T}:T{ +.sp +Load\-balanced +T} +T{ +.sp +Incoming routing strategy +T}:T{ +.sp +Last peer +T} +T{ +.sp +ZMQ_HWM option action +T}:T{ +.sp +Block +T} +.TE +.sp 1 +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBZMQ_REP\fR +.RS 4 +.sp +A socket of type \fIZMQ_REP\fR is used by a \fIservice\fR to receive requests from and send replies to a \fIclient\fR\&. This socket type allows only an alternating sequence of \fIzmq_recv(request)\fR and subsequent \fIzmq_send(reply)\fR calls\&. Each request received is fair\-queued from among all \fIclients\fR, and each reply sent is routed to the \fIclient\fR that issued the last request\&. +.sp +When a \fIZMQ_REP\fR socket enters an exceptional state due to having reached the high water mark for a \fIclient\fR, then any replies sent to the \fIclient\fR in question shall be dropped until the exceptional state ends\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&2.\ \&Summary of ZMQ_REP characteristics +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Compatible peer sockets +T}:T{ +.sp +\fIZMQ_REQ\fR +T} +T{ +.sp +Direction +T}:T{ +.sp +Bidirectional +T} +T{ +.sp +Send/receive pattern +T}:T{ +.sp +Receive, Send, Receive, Send, \&... +T} +T{ +.sp +Incoming routing strategy +T}:T{ +.sp +Fair\-queued +T} +T{ +.sp +Outgoing routing stratagy +T}:T{ +.sp +Last peer +T} +T{ +.sp +ZMQ_HWM option action +T}:T{ +.sp +Drop +T} +.TE +.sp 1 +.RE +.SS "Publish\-subscribe pattern" +.sp +The publish\-subscribe pattern is used for one\-to\-many distribution of data from a single \fIpublisher\fR to multiple \fIsubscribers\fR in a fanout fashion\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBZMQ_PUB\fR +.RS 4 +.sp +A socket of type \fIZMQ_PUB\fR is used by a \fIpublisher\fR to distribute data\&. Messages sent are distributed in a fanout fashion to all connected peers\&. The \fBzmq_recv\fR(3) function is not implemented for this socket type\&. +.sp +When a \fIZMQ_PUB\fR socket enters an exceptional state due to having reached the high water mark for a \fIsubscriber\fR, then any messages that would be sent to the \fIsubscriber\fR in question shall instead be dropped until the exceptional state ends\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&3.\ \&Summary of ZMQ_PUB characteristics +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Compatible peer sockets +T}:T{ +.sp +\fIZMQ_SUB\fR +T} +T{ +.sp +Direction +T}:T{ +.sp +Unidirectional +T} +T{ +.sp +Send/receive pattern +T}:T{ +.sp +Send only +T} +T{ +.sp +Incoming routing strategy +T}:T{ +.sp +N/A +T} +T{ +.sp +Outgoing routing strategy +T}:T{ +.sp +Fanout +T} +T{ +.sp +ZMQ_HWM option action +T}:T{ +.sp +Drop +T} +.TE +.sp 1 +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBZMQ_SUB\fR +.RS 4 +.sp +A socket of type \fIZMQ_SUB\fR is used by a \fIsubscriber\fR to subscribe to data distributed by a \fIpublisher\fR\&. Initially a \fIZMQ_SUB\fR socket is not subscribed to any messages, use the \fIZMQ_SUBSCRIBE\fR option of \fBzmq_setsockopt\fR(3) to specify which messages to subscribe to\&. The \fIzmq_send()\fR function is not implemented for this socket type\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&4.\ \&Summary of ZMQ_SUB characteristics +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Compatible peer sockets +T}:T{ +.sp +\fIZMQ_PUB\fR +T} +T{ +.sp +Direction +T}:T{ +.sp +Unidirectional +T} +T{ +.sp +Send/receive pattern +T}:T{ +.sp +Receive only +T} +T{ +.sp +Incoming routing strategy +T}:T{ +.sp +Fair\-queued +T} +T{ +.sp +Outgoing routing strategy +T}:T{ +.sp +N/A +T} +T{ +.sp +ZMQ_HWM option action +T}:T{ +.sp +N/A +T} +.TE +.sp 1 +.RE +.SS "Pipeline pattern" +.sp +The pipeline pattern is used for distributing data to \fInodes\fR arranged in a pipeline\&. Data always flows down the pipeline, and each stage of the pipeline is connected to at least one \fInode\fR\&. When a pipeline stage is connected to multiple \fInodes\fR data is load\-balanced among all connected \fInodes\fR\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBZMQ_DOWNSTREAM\fR +.RS 4 +.sp +A socket of type \fIZMQ_DOWNSTREAM\fR is used by a pipeline \fInode\fR to send messages to downstream pipeline \fInodes\fR\&. Messages are load\-balanced to all connected downstream \fInodes\fR\&. The \fIzmq_recv()\fR function is not implemented for this socket type\&. +.sp +When a \fIZMQ_DOWNSTREAM\fR socket enters an exceptional state due to having reached the high water mark for all downstream \fInodes\fR, or if there are no downstream \fInodes\fR at all, then any \fBzmq_send\fR(3) operations on the socket shall block until the exceptional state ends or at least one downstream \fInode\fR becomes available for sending; messages are not discarded\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&5.\ \&Summary of ZMQ_DOWNSTREAM characteristics +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Compatible peer sockets +T}:T{ +.sp +\fIZMQ_UPSTREAM\fR +T} +T{ +.sp +Direction +T}:T{ +.sp +Unidirectional +T} +T{ +.sp +Send/receive pattern +T}:T{ +.sp +Send only +T} +T{ +.sp +Incoming routing strategy +T}:T{ +.sp +N/A +T} +T{ +.sp +Outgoing routing strategy +T}:T{ +.sp +Load\-balanced +T} +T{ +.sp +ZMQ_HWM option action +T}:T{ +.sp +Block +T} +.TE +.sp 1 +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBZMQ_UPSTREAM\fR +.RS 4 +.sp +A socket of type \fIZMQ_UPSTREAM\fR is used by a pipeline \fInode\fR to receive messages from upstream pipeline \fInodes\fR\&. Messages are fair\-queued from among all connected upstream \fInodes\fR\&. The \fIzmq_send()\fR function is not implemented for this socket type\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&6.\ \&Summary of ZMQ_UPSTREAM characteristics +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Compatible peer sockets +T}:T{ +.sp +\fIZMQ_DOWNSTREAM\fR +T} +T{ +.sp +Direction +T}:T{ +.sp +Unidirectional +T} +T{ +.sp +Send/receive pattern +T}:T{ +.sp +Receive only +T} +T{ +.sp +Incoming routing strategy +T}:T{ +.sp +Fair\-queued +T} +T{ +.sp +Outgoing routing strategy +T}:T{ +.sp +N/A +T} +T{ +.sp +ZMQ_HWM option action +T}:T{ +.sp +N/A +T} +.TE +.sp 1 +.RE +.SS "Exclusive pair pattern" +.sp +The exclusive pair is an advanced pattern used for communicating exclusively between two peers\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBZMQ_PAIR\fR +.RS 4 +.sp +A socket of type \fIZMQ_PAIR\fR can only be connected to a single peer at any one time\&. No message routing or filtering is performed on messages sent over a \fIZMQ_PAIR\fR socket\&. +.sp +When a \fIZMQ_PAIR\fR socket enters an exceptional state due to having reached the high water mark for the connected peer, or if no peer is connected, then any \fBzmq_send\fR(3) operations on the socket shall block until the peer becomes available for sending; messages are not discarded\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.sp +\fIZMQ_PAIR\fR sockets are experimental, and are currently missing several features such as auto\-reconnection\&. +.sp .5v +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&7.\ \&Summary of ZMQ_PAIR characteristics +.TS +tab(:); +lt lt +lt lt +lt lt +lt lt +lt lt +lt lt. +T{ +.sp +Compatible peer sockets +T}:T{ +.sp +\fIZMQ_PAIR\fR +T} +T{ +.sp +Direction +T}:T{ +.sp +Bidirectional +T} +T{ +.sp +Send/receive pattern +T}:T{ +.sp +Unrestricted +T} +T{ +.sp +Incoming routing strategy +T}:T{ +.sp +N/A +T} +T{ +.sp +Outgoing routing strategy +T}:T{ +.sp +N/A +T} +T{ +.sp +ZMQ_HWM option action +T}:T{ +.sp +Block +T} +.TE +.sp 1 +.RE +.SH "RETURN VALUE" +.sp +The \fIzmq_socket()\fR function shall return an opaque handle to the newly created socket if successful\&. Otherwise, it shall return NULL and set \fIerrno\fR to one of the values defined below\&. +.SH "ERRORS" +.PP +\fBEINVAL\fR +.RS 4 +The requested socket +\fItype\fR +is invalid\&. +.RE +.PP +\fBEMTHREAD\fR +.RS 4 +The maximum number of sockets within this +\fIcontext\fR +has been exceeded\&. +.RE +.SH "SEE ALSO" +.sp +\fBzmq_init\fR(3) \fBzmq_setsockopt\fR(3) \fBzmq_bind\fR(3) \fBzmq_connect\fR(3) \fBzmq_send\fR(3) \fBzmq_recv\fR(3) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_socket.html b/doc/zmq_socket.html new file mode 100644 index 0000000..ddab7e1 --- /dev/null +++ b/doc/zmq_socket.html @@ -0,0 +1,1225 @@ + + + + + +zmq_socket(3) + + + + + +
+

SYNOPSIS

+
+

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

+
+

DESCRIPTION

+
+

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

+

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

+
Key differences to conventional sockets

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

+

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

+

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

+
Socket types

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

+

Request-reply pattern

+

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

+

ZMQ_REQ

+

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

+

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

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

+ZMQ_REP +

+
+Direction +
+		 +

+Bidirectional +

+
+Send/receive pattern +
+		 +

+Send, Receive, Send, Receive, … +

+
+Outgoing routing strategy +
+		 +

+Load-balanced +

+
+Incoming routing strategy +
+		 +

+Last peer +

+
+ZMQ_HWM option action +
+		 +

+Block +

+
+

ZMQ_REP

+

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

+

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

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

+ZMQ_REQ +

+
+Direction +
+		 +

+Bidirectional +

+
+Send/receive pattern +
+		 +

+Receive, Send, Receive, Send, … +

+
+Incoming routing strategy +
+		 +

+Fair-queued +

+
+Outgoing routing stratagy +
+		 +

+Last peer +

+
+ZMQ_HWM option action +
+		 +

+Drop +

+
+

Publish-subscribe pattern

+

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

+

ZMQ_PUB

+

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

+

When a ZMQ_PUB socket enters an exceptional state due to having reached the +high water mark for a subscriber, then any messages that would be sent to the +subscriber in question shall instead be dropped until the exceptional state +ends.

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

+ZMQ_SUB +

+
+Direction +
+		 +

+Unidirectional +

+
+Send/receive pattern +
+		 +

+Send only +

+
+Incoming routing strategy +
+		 +

+N/A +

+
+Outgoing routing strategy +
+		 +

+Fanout +

+
+ZMQ_HWM option action +
+		 +

+Drop +

+
+

ZMQ_SUB

+

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

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

+ZMQ_PUB +

+
+Direction +
+		 +

+Unidirectional +

+
+Send/receive pattern +
+		 +

+Receive only +

+
+Incoming routing strategy +
+		 +

+Fair-queued +

+
+Outgoing routing strategy +
+		 +

+N/A +

+
+ZMQ_HWM option action +
+		 +

+N/A +

+
+

Pipeline pattern

+

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

+

ZMQ_DOWNSTREAM

+

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

+

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

+
Summary of ZMQ_DOWNSTREAM characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + +
+Compatible peer sockets +
+		 +

+ZMQ_UPSTREAM +

+
+Direction +
+		 +

+Unidirectional +

+
+Send/receive pattern +
+		 +

+Send only +

+
+Incoming routing strategy +
+		 +

+N/A +

+
+Outgoing routing strategy +
+		 +

+Load-balanced +

+
+ZMQ_HWM option action +
+		 +

+Block +

+
+

ZMQ_UPSTREAM

+

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

+
Summary of ZMQ_UPSTREAM characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + +
+Compatible peer sockets +
+		 +

+ZMQ_DOWNSTREAM +

+
+Direction +
+		 +

+Unidirectional +

+
+Send/receive pattern +
+		 +

+Receive only +

+
+Incoming routing strategy +
+		 +

+Fair-queued +

+
+Outgoing routing strategy +
+		 +

+N/A +

+
+ZMQ_HWM option action +
+		 +

+N/A +

+
+

Exclusive pair pattern

+

The exclusive pair is an advanced pattern used for communicating exclusively +between two peers.

+

ZMQ_PAIR

+

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

+

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

+
+ + + +
+
Note
+		ZMQ_PAIR sockets are experimental, and are currently missing several +features such as auto-reconnection.
+
+
Summary of ZMQ_PAIR characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + +
+Compatible peer sockets +
+		 +

+ZMQ_PAIR +

+
+Direction +
+		 +

+Bidirectional +

+
+Send/receive pattern +
+		 +

+Unrestricted +

+
+Incoming routing strategy +
+		 +

+N/A +

+
+Outgoing routing strategy +
+		 +

+N/A +

+
+ZMQ_HWM option action +
+		 +

+Block +

+
+
+

RETURN VALUE

+
+

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

+
+

ERRORS

+
+
+
+EINVAL +
+
+

+The requested socket type is invalid. +

+
+
+EMTHREAD +
+
+

+The maximum number of sockets within this context has been exceeded. +

+
+
+
+

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt new file mode 100644 index 0000000..23cc317 --- /dev/null +++ b/doc/zmq_socket.txt @@ -0,0 +1,260 @@ +zmq_socket(3) +============= + + +NAME +---- +zmq_socket - create 0MQ socket + + +SYNOPSIS +-------- +*void *zmq_socket (void '*context', int 'type');* + + +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 +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 +endpoint must be created for accepting incoming connections with +linkzmq:zmq_bind[3]. + +.Key differences to conventional sockets +Generally speaking, conventional sockets present a _synchronous_ interface to +either connection-oriented reliable byte streams (SOCK_STREAM), or +connection-less unreliable datagrams (SOCK_DGRAM). In comparison, 0MQ sockets +present an abstraction of an asynchronous _message queue_, with the exact +queueing semantics depending on the socket type in use. Where conventional +sockets transfer streams of bytes or discrete datagrams, 0MQ sockets transfer +discrete _messages_. + +0MQ sockets being _asynchronous_ means that the timings of the physical +connection setup and teardown, reconnect and effective delivery are transparent +to the user and organized by 0MQ itself. Further, messages may be _queued_ in +the event that a peer is unavailable to receive them. + +Conventional sockets allow only strict one-to-one (two peers), many-to-one +(many clients, one server), or in some cases one-to-many (multicast) +relationships. With the exception of 'ZMQ_PAIR', 0MQ sockets may be connected +*to multiple endpoints* using _zmq_connect()_, while simultaneously accepting +incoming connections *from multiple endpoints* bound to the socket using +_zmq_bind()_, thus allowing many-to-many relationships. + +.Socket types +The following sections present the socket types defined by 0MQ, grouped by the +general _messaging pattern_ which is built from related socket types. + + +Request-reply pattern +~~~~~~~~~~~~~~~~~~~~~ +The request-reply pattern is used for sending requests from a _client_ to one +or more instances of a _service_, and receiving subsequent replies to each +request sent. + + +ZMQ_REQ +^^^^^^^ +A socket of type 'ZMQ_REQ' is used by a _client_ to send requests to and +receive replies from a _service_. This socket type allows only an alternating +sequence of _zmq_send(request)_ and subsequent _zmq_recv(reply)_ calls. Each +request sent is load-balanced among all _services_, and each reply received is +matched with the last issued request. + +When a 'ZMQ_REQ' socket enters an exceptional state due to having reached the +high water mark for all _services_, or if there are no _services_ at all, then +any linkzmq:zmq_send[3] operations on the socket shall block until the +exceptional state ends or at least one _service_ becomes available for sending; +messages are not discarded. + +[horizontal] +.Summary of ZMQ_REQ characteristics +Compatible peer sockets:: 'ZMQ_REP' +Direction:: Bidirectional +Send/receive pattern:: Send, Receive, Send, Receive, ... +Outgoing routing strategy:: Load-balanced +Incoming routing strategy:: Last peer +ZMQ_HWM option action:: Block + + +ZMQ_REP +^^^^^^^ +A socket of type 'ZMQ_REP' is used by a _service_ to receive requests from and +send replies to a _client_. This socket type allows only an alternating +sequence of _zmq_recv(request)_ and subsequent _zmq_send(reply)_ calls. Each +request received is fair-queued from among all _clients_, and each reply sent +is routed to the _client_ that issued the last request. + +When a 'ZMQ_REP' socket enters an exceptional state due to having reached the +high water mark for a _client_, then any replies sent to the _client_ in +question shall be dropped until the exceptional state ends. + +[horizontal] +.Summary of ZMQ_REP characteristics +Compatible peer sockets:: 'ZMQ_REQ' +Direction:: Bidirectional +Send/receive pattern:: Receive, Send, Receive, Send, ... +Incoming routing strategy:: Fair-queued +Outgoing routing stratagy:: Last peer +ZMQ_HWM option action:: Drop + + +Publish-subscribe pattern +~~~~~~~~~~~~~~~~~~~~~~~~~ +The publish-subscribe pattern is used for one-to-many distribution of data from +a single _publisher_ to multiple _subscribers_ in a fanout fashion. + + +ZMQ_PUB +^^^^^^^ +A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data. +Messages sent are distributed in a fanout fashion to all connected peers. +The linkzmq:zmq_recv[3] function is not implemented for this socket type. + +When a 'ZMQ_PUB' socket enters an exceptional state due to having reached the +high water mark for a _subscriber_, then any messages that would be sent to the +_subscriber_ in question shall instead be dropped until the exceptional state +ends. + +[horizontal] +.Summary of ZMQ_PUB characteristics +Compatible peer sockets:: 'ZMQ_SUB' +Direction:: Unidirectional +Send/receive pattern:: Send only +Incoming routing strategy:: N/A +Outgoing routing strategy:: Fanout +ZMQ_HWM option action:: Drop + + +ZMQ_SUB +^^^^^^^ +A socket of type 'ZMQ_SUB' is used by a _subscriber_ to subscribe to data +distributed by a _publisher_. Initially a 'ZMQ_SUB' socket is not subscribed to +any messages, use the 'ZMQ_SUBSCRIBE' option of linkzmq:zmq_setsockopt[3] to +specify which messages to subscribe to. The _zmq_send()_ function is not +implemented for this socket type. + +[horizontal] +.Summary of ZMQ_SUB characteristics +Compatible peer sockets:: 'ZMQ_PUB' +Direction:: Unidirectional +Send/receive pattern:: Receive only +Incoming routing strategy:: Fair-queued +Outgoing routing strategy:: N/A +ZMQ_HWM option action:: N/A + + +Pipeline pattern +~~~~~~~~~~~~~~~~ +The pipeline pattern is used for distributing data to _nodes_ arranged in +a pipeline. Data always flows down the pipeline, and each stage of the pipeline +is connected to at least one _node_. When a pipeline stage is connected to +multiple _nodes_ data is load-balanced among all connected _nodes_. + + +ZMQ_DOWNSTREAM +^^^^^^^^^^^^^^ +A socket of type 'ZMQ_DOWNSTREAM' is used by a pipeline _node_ to send messages +to downstream pipeline _nodes_. Messages are load-balanced to all connected +downstream _nodes_. The _zmq_recv()_ function is not implemented for this +socket type. + +When a 'ZMQ_DOWNSTREAM' socket enters an exceptional state due to having +reached the high water mark for all downstream _nodes_, or if there are no +downstream _nodes_ at all, then any linkzmq:zmq_send[3] operations on the +socket shall block until the exceptional state ends or at least one downstream +_node_ becomes available for sending; messages are not discarded. + +[horizontal] +.Summary of ZMQ_DOWNSTREAM characteristics +Compatible peer sockets:: 'ZMQ_UPSTREAM' +Direction:: Unidirectional +Send/receive pattern:: Send only +Incoming routing strategy:: N/A +Outgoing routing strategy:: Load-balanced +ZMQ_HWM option action:: Block + + +ZMQ_UPSTREAM +^^^^^^^^^^^^ +A socket of type 'ZMQ_UPSTREAM' is used by a pipeline _node_ to receive +messages from upstream pipeline _nodes_. Messages are fair-queued from among +all connected upstream _nodes_. The _zmq_send()_ function is not implemented +for this socket type. + +[horizontal] +.Summary of ZMQ_UPSTREAM characteristics +Compatible peer sockets:: 'ZMQ_DOWNSTREAM' +Direction:: Unidirectional +Send/receive pattern:: Receive only +Incoming routing strategy:: Fair-queued +Outgoing routing strategy:: N/A +ZMQ_HWM option action:: N/A + + +Exclusive pair pattern +~~~~~~~~~~~~~~~~~~~~~~ +The exclusive pair is an advanced pattern used for communicating exclusively +between two peers. + + +ZMQ_PAIR +^^^^^^^^ +A socket of type 'ZMQ_PAIR' can only be connected to a single peer at any one +time. No message routing or filtering is performed on messages sent over a +'ZMQ_PAIR' socket. + +When a 'ZMQ_PAIR' socket enters an exceptional state due to having reached the +high water mark for the connected peer, or if no peer is connected, then +any linkzmq:zmq_send[3] operations on the socket shall block until the peer +becomes available for sending; messages are not discarded. + +NOTE: 'ZMQ_PAIR' sockets are experimental, and are currently missing several +features such as auto-reconnection. + +[horizontal] +.Summary of ZMQ_PAIR characteristics +Compatible peer sockets:: 'ZMQ_PAIR' +Direction:: Bidirectional +Send/receive pattern:: Unrestricted +Incoming routing strategy:: N/A +Outgoing routing strategy:: N/A +ZMQ_HWM option action:: Block + + +RETURN VALUE +------------ +The _zmq_socket()_ function shall return an opaque handle to the newly created +socket if successful. Otherwise, it shall return NULL and set 'errno' to one of +the values defined below. + + +ERRORS +------ +*EINVAL*:: +The requested socket 'type' is invalid. + +*EMTHREAD*:: +The maximum number of sockets within this 'context' has been exceeded. + + +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[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_streamer.1 b/doc/zmq_streamer.1 new file mode 100644 index 0000000..d8af2e5 --- /dev/null +++ b/doc/zmq_streamer.1 @@ -0,0 +1,57 @@ +'\" t +.\" Title: zmq_streamer +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_STREAMER" "1" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_streamer \- streamer device for parallelized pipeline messaging +.SH "SYNOPSIS" +.sp +To be written\&. +.SH "DESCRIPTION" +.sp +To be written\&. +.SH "OPTIONS" +.sp +To be written\&. +.SH "SEE ALSO" +.sp +\fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_streamer.html b/doc/zmq_streamer.html new file mode 100644 index 0000000..389c146 --- /dev/null +++ b/doc/zmq_streamer.html @@ -0,0 +1,612 @@ + + + + + +zmq_streamer(1) + + + + + +
+

SYNOPSIS

+
+

To be written.

+
+

DESCRIPTION

+
+

To be written.

+
+

OPTIONS

+
+

To be written.

+
+

SEE ALSO

+
+

zmq(7)

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_streamer.txt b/doc/zmq_streamer.txt new file mode 100644 index 0000000..c8d517b --- /dev/null +++ b/doc/zmq_streamer.txt @@ -0,0 +1,33 @@ +zmq_streamer(1) +=============== + + +NAME +---- +zmq_streamer - streamer device for parallelized pipeline messaging + + +SYNOPSIS +-------- +To be written. + + +DESCRIPTION +----------- +To be written. + + +OPTIONS +------- +To be written. + + +SEE ALSO +-------- +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_strerror.3 b/doc/zmq_strerror.3 new file mode 100644 index 0000000..3045e41 --- /dev/null +++ b/doc/zmq_strerror.3 @@ -0,0 +1,78 @@ +'\" t +.\" Title: zmq_strerror +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_STRERROR" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_strerror \- get 0MQ error message string +.SH "SYNOPSIS" +.sp +\fBconst char *zmq_strerror (int \fR\fB\fIerrnum\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_strerror()\fR function shall return a pointer to an error message string corresponding to the error number specified by the \fIerrnum\fR argument\&. As 0MQ defines additional error numbers over and above those defined by the operating system, applications should use \fIzmq_strerror()\fR in preference to the standard \fIstrerror()\fR function\&. +.SH "RETURN VALUE" +.sp +The \fIzmq_strerror()\fR function shall return a pointer to an error message string\&. +.SH "ERRORS" +.sp +No errors are defined\&. +.SH "EXAMPLE" +.PP +\fBDisplaying an error message when a 0MQ context cannot be initialised\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +void *ctx = zmq_init (1, 1, 0); +if (!ctx) { + printf ("Error occurred during zmq_init(): %s\en", zmq_strerror (errno)); + abort (); +} +.fi +.if n \{\ +.RE +.\} +.sp +.SH "SEE ALSO" +.sp +\fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_strerror.html b/doc/zmq_strerror.html new file mode 100644 index 0000000..a57b380 --- /dev/null +++ b/doc/zmq_strerror.html @@ -0,0 +1,633 @@ + + + + + +zmq_strerror(3) + + + + + +
+

SYNOPSIS

+
+

const char *zmq_strerror (int errnum);

+
+

DESCRIPTION

+
+

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

+
+

RETURN VALUE

+
+

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

+
+

ERRORS

+
+

No errors are defined.

+
+

EXAMPLE

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

SEE ALSO

+
+

zmq(7)

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_strerror.txt b/doc/zmq_strerror.txt new file mode 100644 index 0000000..61f30e3 --- /dev/null +++ b/doc/zmq_strerror.txt @@ -0,0 +1,55 @@ +zmq_strerror(3) +=============== + + +NAME +---- +zmq_strerror - get 0MQ error message string + + +SYNOPSIS +-------- +*const char *zmq_strerror (int 'errnum');* + + +DESCRIPTION +----------- +The _zmq_strerror()_ function shall return a pointer to an error message string +corresponding to the error number specified by the 'errnum' argument. As 0MQ +defines additional error numbers over and above those defined by the operating +system, applications should use _zmq_strerror()_ in preference to the standard +_strerror()_ function. + + +RETURN VALUE +------------ +The _zmq_strerror()_ function shall return a pointer to an error message +string. + + +ERRORS +------ +No errors are defined. + + +EXAMPLE +------- +.Displaying an error message when a 0MQ context cannot be initialised +---- +void *ctx = zmq_init (1, 1, 0); +if (!ctx) { + printf ("Error occurred during zmq_init(): %s\n", zmq_strerror (errno)); + abort (); +} +---- + + +SEE ALSO +-------- +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_tcp.7 b/doc/zmq_tcp.7 new file mode 100644 index 0000000..3d4129b --- /dev/null +++ b/doc/zmq_tcp.7 @@ -0,0 +1,244 @@ +'\" t +.\" Title: zmq_tcp +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_TCP" "7" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_tcp \- 0MQ unicast transport using TCP +.SH "SYNOPSIS" +.sp +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\&. +.SH "ADDRESSING" +.sp +A 0MQ address string consists of two parts as follows: \fItransport\fR://\fIendpoint\fR\&. The \fItransport\fR part specifies the underlying transport protocol to use, and for the TCP transport shall be set to tcp\&. The meaning of the \fIendpoint\fR part for the TCP transport is defined below\&. +.SS "Assigning a local address to a socket" +.sp +When assigning a local address to a socket using \fIzmq_bind()\fR with the \fItcp\fR transport, the \fIendpoint\fR shall be interpreted as an \fIinterface\fR followed by a colon and the TCP port number to use\&. +.sp +An \fIinterface\fR may be specified by either of the following: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The interface name as defined by the operating system\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The primary IPv4 address assigned to the interface, in it\(cqs numeric representation\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The wildcard +*, meaning that the interface address is unspecified\&. +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.sp +Interface names are not standardised in any way and should be assumed to be arbitrary and platform dependent\&. On Win32 platforms no short interface names exist, thus only the primary IPv4 address may be used to specify an \fIinterface\fR\&. +.sp .5v +.RE +.SS "Connecting a socket" +.sp +When connecting a socket to a peer address using \fIzmq_connect()\fR with the \fItcp\fR transport, the \fIendpoint\fR shall be interpreted as a \fIpeer address\fR followed by a colon and the TCP port number to use\&. +.sp +A \fIpeer address\fR may be specified by either of the following: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The DNS name of the peer\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The IPv4 address of the peer, in it\(cqs numeric representation\&. +.RE +.SH "WIRE FORMAT" +.sp +0MQ messages are transmitted over TCP in frames consisting of an encoded \fIpayload length\fR, followed by a \fIflags\fR field and the message body\&. The \fIpayload length\fR is defined as the combined length in octets of the message body and the \fIflags\fR field\&. +.sp +For frames with a \fIpayload length\fR not exceeding 254 octets, the \fIpayload length\fR shall be encoded as a single octet\&. The minimum valid \fIpayload length\fR of a frame is 1 octet, thus a \fIpayload length\fR of 0 octets is invalid and such frames SHOULD be ignored\&. +.sp +For frames with a \fIpayload length\fR exceeding 254 octets, the \fIpayload length\fR shall be encoded as a single octet with the value 255 followed by the \fIpayload length\fR represented as a 64\-bit unsigned integer in network byte order\&. +.sp +The \fIflags\fR field consists of a single octet containing various control flags: +.sp +Bit 0 (MORE): \fIMore message parts to follow\fR\&. A value of 0 indicates that there are no more message parts to follow; or that the message being sent is not a multi\-part message\&. A value of 1 indicates that the message being sent is a multi\-part message and more message parts are to follow\&. +.sp +Bits 1\-7: \fIReserved\fR\&. Bits 1\-7 are reserved for future expansion and MUST be set to zero\&. +.sp +The following ABNF grammar represents a single \fIframe\fR: +.sp +.if n \{\ +.RS 4 +.\} +.nf + frame = (length flags data) + length = OCTET / (escape 8OCTET) + flags = OCTET + escape = %xFF + data = *OCTET +.fi +.if n \{\ +.RE +.\} +.sp +The following diagram illustrates the layout of a frame with a \fIpayload length\fR not exceeding 254 octets: +.sp +.if n \{\ +.RS 4 +.\} +.nf +0 1 2 3 +0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +| Payload length| Flags | Message body \&.\&.\&. | ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +| Message body \&.\&.\&. ++\-+\-+\-+\-+\-+\-+\- \&.\&.\&. +.fi +.if n \{\ +.RE +.\} +.sp +The following diagram illustrates the layout of a frame with a \fIpayload length\fR exceeding 254 octets: +.sp +.if n \{\ +.RS 4 +.\} +.nf +0 1 2 3 +0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +| 0xff | Payload length \&.\&.\&. | ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +| Payload length \&.\&.\&. | ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +| Payload length| Flags | Message body \&.\&.\&. | ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +| Message body \&.\&.\&. ++\-+\-+\-+\-+\-+\-+\-+ \&.\&.\&. +.fi +.if n \{\ +.RE +.\} +.SH "EXAMPLES" +.PP +\fBAssigning a local address to a socket\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +/* TCP port 5555 on the local loopback interface on all platforms */ +rc = zmq_bind(socket, "tcp://127\&.0\&.0\&.1:5555"); +assert (rc == 0); +/* TCP port 5555 on the first ethernet network interface on Linux */ +rc = zmq_bind(socket, "tcp://eth0:5555"); +assert (rc == 0); +/* TCP port 5555 with an unspecified interface */ +rc = zmq_bind(socket, "tcp://*:5555"); +assert (rc == 0); +.fi +.if n \{\ +.RE +.\} +.PP +\fBConnecting a socket\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +/* Connecting using an IP address */ +rc = zmq_connect(socket, "tcp://192\&.168\&.1\&.1:5555"); +assert (rc == 0); +/* Connecting using a DNS name */ +rc = zmq_connect(socket, "tcp://server1:5555"); +assert (rc == 0); +.fi +.if n \{\ +.RE +.\} +.sp +.SH "SEE ALSO" +.sp +\fBzmq_bind\fR(3) \fBzmq_connect\fR(3) \fBzmq_pgm\fR(7) \fBzmq_ipc\fR(7) \fBzmq_inproc\fR(7) \fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_tcp.html b/doc/zmq_tcp.html new file mode 100644 index 0000000..6a7ca72 --- /dev/null +++ b/doc/zmq_tcp.html @@ -0,0 +1,753 @@ + + + + + +zmq_tcp(7) + + + + + +
+

SYNOPSIS

+
+

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

+
+

ADDRESSING

+
+

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

+

Assigning a local address to a socket

+

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

+

An interface may be specified by either of the following:

+
    +
  • +

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

    +
    • +
  • +

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

    +
    • +
  • +

    +The wildcard *, meaning that the interface address is unspecified. +

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

Connecting a socket

+

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

+

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

+
    +
  • +

    +The DNS name of the peer. +

    +
    • +
  • +

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

    +
    • +
+
+

WIRE FORMAT

+
+

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

+

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

+

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

+

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

+

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

+

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

+

The following ABNF grammar represents a single frame:

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

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

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

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

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

EXAMPLES

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

SEE ALSO

+
+

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

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_tcp.txt b/doc/zmq_tcp.txt new file mode 100644 index 0000000..a845f62 --- /dev/null +++ b/doc/zmq_tcp.txt @@ -0,0 +1,161 @@ +zmq_tcp(7) +========== + + +NAME +---- +zmq_tcp - 0MQ unicast transport using TCP + + +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 +---------- +A 0MQ address string consists of two parts as follows: +'transport'`://`'endpoint'. The 'transport' part specifies the underlying +transport protocol to use, and for the TCP transport shall be set to `tcp`. +The meaning of the 'endpoint' part for the TCP transport is defined below. + + +Assigning a local address to a socket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +When assigning a local address to a socket using _zmq_bind()_ with the 'tcp' +transport, the 'endpoint' shall be interpreted as an 'interface' followed by a +colon and the TCP port number to use. + +An 'interface' may be specified by either of the following: + +* The interface name as defined by the operating system. +* The primary IPv4 address assigned to the interface, in it's numeric representation. +* The wildcard `*`, meaning that the interface address is unspecified. + +NOTE: Interface names are not standardised in any way and should be assumed to +be arbitrary and platform dependent. On Win32 platforms no short interface +names exist, thus only the primary IPv4 address may be used to specify an +'interface'. + +Connecting a socket +~~~~~~~~~~~~~~~~~~~ +When connecting a socket to a peer address using _zmq_connect()_ with the 'tcp' +transport, the 'endpoint' shall be interpreted as a 'peer address' followed by +a colon and the TCP port number to use. + +A 'peer address' may be specified by either of the following: + +* The DNS name of the peer. +* The IPv4 address of the peer, in it's numeric representation. + + +WIRE FORMAT +----------- +0MQ messages are transmitted over TCP in frames consisting of an encoded +'payload length', followed by a 'flags' field and the message body. The 'payload +length' is defined as the combined length in octets of the message body and the +'flags' field. + +For frames with a 'payload length' not exceeding 254 octets, the 'payload +length' shall be encoded as a single octet. The minimum valid 'payload length' +of a frame is 1 octet, thus a 'payload length' of 0 octets is invalid and such +frames SHOULD be ignored. + +For frames with a 'payload length' exceeding 254 octets, the 'payload length' +shall be encoded as a single octet with the value `255` followed by the +'payload length' represented as a 64-bit unsigned integer in network byte +order. + +The 'flags' field consists of a single octet containing various control flags: + +Bit 0 (MORE): _More message parts to follow_. A value of 0 indicates that there +are no more message parts to follow; or that the message being sent is not a +multi-part message. A value of 1 indicates that the message being sent is a +multi-part message and more message parts are to follow. + +Bits 1-7: _Reserved_. Bits 1-7 are reserved for future expansion and MUST be +set to zero. + +The following ABNF grammar represents a single 'frame': + +.... + frame = (length flags data) + length = OCTET / (escape 8OCTET) + flags = OCTET + escape = %xFF + data = *OCTET +.... + +The following diagram illustrates the layout of a frame with a 'payload length' +not exceeding 254 octets: + +.... +0 1 2 3 +0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Payload length| Flags | Message body ... | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Message body ... ++-+-+-+-+-+-+- ... +.... + +The following diagram illustrates the layout of a frame with a 'payload length' +exceeding 254 octets: + +.... +0 1 2 3 +0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| 0xff | Payload length ... | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Payload length ... | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Payload length| Flags | Message body ... | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Message body ... ++-+-+-+-+-+-+-+ ... +.... + + +EXAMPLES +-------- +.Assigning a local address to a socket +---- +/* TCP port 5555 on the local loopback interface on all platforms */ +rc = zmq_bind(socket, "tcp://127.0.0.1:5555"); +assert (rc == 0); +/* TCP port 5555 on the first ethernet network interface on Linux */ +rc = zmq_bind(socket, "tcp://eth0:5555"); +assert (rc == 0); +/* TCP port 5555 with an unspecified interface */ +rc = zmq_bind(socket, "tcp://*:5555"); +assert (rc == 0); +---- + +.Connecting a socket +---- +/* Connecting using an IP address */ +rc = zmq_connect(socket, "tcp://192.168.1.1:5555"); +assert (rc == 0); +/* Connecting using a DNS name */ +rc = zmq_connect(socket, "tcp://server1:5555"); +assert (rc == 0); +---- + + +SEE ALSO +-------- +linkzmq:zmq_bind[3] +linkzmq:zmq_connect[3] +linkzmq:zmq_pgm[7] +linkzmq:zmq_ipc[7] +linkzmq:zmq_inproc[7] +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_term.3 b/doc/zmq_term.3 new file mode 100644 index 0000000..bfb533d --- /dev/null +++ b/doc/zmq_term.3 @@ -0,0 +1,119 @@ +'\" t +.\" Title: zmq_term +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_TERM" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_term \- terminate 0MQ context +.SH "SYNOPSIS" +.sp +\fBint zmq_term (void \fR\fB\fI*context\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_term()\fR function terminates the 0MQ context \fIcontext\fR\&. +.sp +If there are no longer any sockets open within \fIcontext\fR at the time \fIzmq_term()\fR is called then \fIcontext\fR shall be shut down and all associated resources shall be released immediately\&. +.sp +Otherwise, the following applies: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The +\fIzmq_term()\fR +function shall return immediately\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Any blocking operations currently in progress on sockets open within +\fIcontext\fR +shall return immediately with an error code of ETERM\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +With the exception of +\fIzmq_close()\fR, any further operations on sockets open within +\fIcontext\fR +shall fail with an error code of ETERM\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The actual shutdown of +\fIcontext\fR, and release of any associated resources, +\fBshall be delayed\fR +until the last socket within it is closed with +\fIzmq_close()\fR\&. +.RE +.SH "RETURN VALUE" +.sp +The \fIzmq_term()\fR function shall return zero if successful\&. Otherwise it shall return \-1 and set \fIerrno\fR to one of the values defined below\&. +.SH "ERRORS" +.sp +No errors are defined\&. +.SH "SEE ALSO" +.sp +\fBzmq\fR(7) \fBzmq_init\fR(3) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_term.html b/doc/zmq_term.html new file mode 100644 index 0000000..847abf5 --- /dev/null +++ b/doc/zmq_term.html @@ -0,0 +1,648 @@ + + + + + +zmq_term(3) + + + + + +
+

SYNOPSIS

+
+

int zmq_term (void *context);

+
+

DESCRIPTION

+
+

The zmq_term() function terminates the ØMQ context context.

+

If there are no longer any sockets open within context at the time +zmq_term() is called then context shall be shut down and all associated +resources shall be released immediately.

+

Otherwise, the following applies:

+
    +
  • +

    +The zmq_term() function shall return immediately. +

    +
    • +
  • +

    +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. +

    +
    • +
  • +

    +The actual shutdown of context, and release of any associated resources, + shall be delayed until the last socket within it is closed with + zmq_close(). +

    +
    • +
+
+

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

+
+

No errors are defined.

+
+

SEE ALSO

+
+

zmq(7) +zmq_init(3)

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_term.txt b/doc/zmq_term.txt new file mode 100644 index 0000000..820fa30 --- /dev/null +++ b/doc/zmq_term.txt @@ -0,0 +1,58 @@ +zmq_term(3) +=========== + + +NAME +---- +zmq_term - terminate 0MQ context + + +SYNOPSIS +-------- +*int zmq_term (void '*context');* + + +DESCRIPTION +----------- +The _zmq_term()_ function terminates the 0MQ context 'context'. + +If there are no longer any sockets open within 'context' at the time +_zmq_term()_ is called then 'context' shall be shut down and all associated +resources shall be released immediately. + +Otherwise, the following applies: + +* The _zmq_term()_ function shall return immediately. + +* 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. + +* The actual shutdown of 'context', and release of any associated resources, + *shall be delayed* until the last socket within it is closed with + _zmq_close()_. + + +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 +------ +No errors are defined. + + +SEE ALSO +-------- +linkzmq:zmq[7] +linkzmq:zmq_init[3] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . diff --git a/doc/zmq_version.3 b/doc/zmq_version.3 new file mode 100644 index 0000000..37d2aaa --- /dev/null +++ b/doc/zmq_version.3 @@ -0,0 +1,78 @@ +'\" t +.\" Title: zmq_version +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 06/04/2010 +.\" Manual: 0MQ Manual +.\" Source: 0MQ 2.0.7 +.\" Language: English +.\" +.TH "ZMQ_VERSION" "3" "06/04/2010" "0MQ 2\&.0\&.7" "0MQ Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +zmq_version \- report 0MQ library version +.SH "SYNOPSIS" +.sp +\fBvoid zmq_version (int \fR\fB\fI*major\fR\fR\fB, int \fR\fB\fI*minor\fR\fR\fB, int \fR\fB\fI*patch\fR\fR\fB);\fR +.SH "DESCRIPTION" +.sp +The \fIzmq_version()\fR function shall fill in the integer variables pointed to by the \fImajor\fR, \fIminor\fR and \fIpatch\fR arguments with the major, minor and patchlevel components of the 0MQ library version\&. +.sp +This functionality is intended for applications or language bindings dynamically linking to the 0MQ library that wish to determine the actual version of the 0MQ library they are using\&. +.SH "RETURN VALUE" +.sp +There is no return value\&. +.SH "ERRORS" +.sp +No errors are defined\&. +.SH "EXAMPLE" +.PP +\fBPrinting out the version of the 0MQ library\fR. +.sp +.if n \{\ +.RS 4 +.\} +.nf +int major, minor, patch; +zmq_version (&major, &minor, &patch); +printf ("Current 0MQ version is %d\&.%d\&.%d\en", major, minor, patch); +.fi +.if n \{\ +.RE +.\} +.sp +.SH "SEE ALSO" +.sp +\fBzmq\fR(7) +.SH "AUTHORS" +.sp +The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\fR\m[]\&\s-2\u[2]\d\s+2>\&. +.SH "NOTES" +.IP " 1." 4 +sustrik@250bpm.com +.RS 4 +\%mailto:sustrik@250bpm.com +.RE +.IP " 2." 4 +mato@kotelna.sk +.RS 4 +\%mailto:mato@kotelna.sk +.RE diff --git a/doc/zmq_version.html b/doc/zmq_version.html new file mode 100644 index 0000000..7be9aa2 --- /dev/null +++ b/doc/zmq_version.html @@ -0,0 +1,631 @@ + + + + + +zmq_version(3) + + + + + +
+

SYNOPSIS

+
+

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

+
+

DESCRIPTION

+
+

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

+

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

+
+

RETURN VALUE

+
+

There is no return value.

+
+

ERRORS

+
+

No errors are defined.

+
+

EXAMPLE

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

SEE ALSO

+
+

zmq(7)

+
+

AUTHORS

+
+

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

+
+
+
+ + + diff --git a/doc/zmq_version.txt b/doc/zmq_version.txt new file mode 100644 index 0000000..0ad3a55 --- /dev/null +++ b/doc/zmq_version.txt @@ -0,0 +1,53 @@ +zmq_version(3) +============== + + +NAME +---- +zmq_version - report 0MQ library version + + +SYNOPSIS +-------- +*void zmq_version (int '*major', int '*minor', int '*patch');* + + +DESCRIPTION +----------- +The _zmq_version()_ function shall fill in the integer variables pointed to by +the 'major', 'minor' and 'patch' arguments with the major, minor and patchlevel +components of the 0MQ library version. + +This functionality is intended for applications or language bindings +dynamically linking to the 0MQ library that wish to determine the actual +version of the 0MQ library they are using. + + +RETURN VALUE +------------ +There is no return value. + + +ERRORS +------ +No errors are defined. + + +EXAMPLE +------- +.Printing out the version of the 0MQ library +---- +int major, minor, patch; +zmq_version (&major, &minor, &patch); +printf ("Current 0MQ version is %d.%d.%d\n", major, minor, patch); +---- + + +SEE ALSO +-------- +linkzmq:zmq[7] + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . -- cgit v1.2.3