Fix potential pointer use err in SI95

In SIconnect it was possible for a freed struct to be used
if the session didn't connect.

This change also picks up whitespace changes to the docs.

Issue-ID: RIC-626

Signed-off-by: E. Scott Daniels <daniels@research.att.com>
Change-Id: Ie23f4925c6a29b301f0143e938c11f57f0ed5631

diff --git a/CHANGES_CORE.txt b/CHANGES_CORE.txt
index 1acf21c..27e05cd 100644 (file)
--- a/CHANGES_CORE.txt
+++ b/CHANGES_CORE.txt
@@ -5,6 +5,9 @@
 # API and build change  and fix summaries. Doc correctsions
 # and/or changes are not mentioned here; see the commit messages.
 
 # API and build change  and fix summaries. Doc correctsions
 # and/or changes are not mentioned here; see the commit messages.
 

+2020 July 21; Version 4.2.4
+       Fix bug in SI95 -- possible use of pointer after free (RIC-626).
+

 2020 July 9; version 4.1.3
        Allow RTS messages to be sent before the arrival of the initial
        route table. Calls to RTS (heart beat responses) prior to the
 2020 July 9; version 4.1.3
        Allow RTS messages to be sent before the arrival of the initial
        route table. Calls to RTS (heart beat responses) prior to the

diff --git a/CMakeLists.txt b/CMakeLists.txt
index ed345f4..65226cf 100644 (file)
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -41,7 +41,7 @@ cmake_minimum_required( VERSION 3.5 )
 
 set( major_version "4" )               # should be automatically populated from git tag later, but until CI process sets a tag we use this
 set( minor_version "1" )
 
 set( major_version "4" )               # should be automatically populated from git tag later, but until CI process sets a tag we use this
 set( minor_version "1" )

-set( patch_level "3" )
+set( patch_level "4" )

 
 set( install_root "${CMAKE_INSTALL_PREFIX}" )
 set( install_inc "include/rmr" )
 
 set( install_root "${CMAKE_INSTALL_PREFIX}" )
 set( install_inc "include/rmr" )

diff --git a/doc/src/library/Makefile b/doc/src/library/Makefile
index 7108614..60404c9 100644 (file)
--- a/doc/src/library/Makefile
+++ b/doc/src/library/Makefile
@@ -33,7 +33,7 @@ P2 = $(XP) XFM_PASS=2
 
 %.rst: %.xfm
        $(P1) OUTPUT_TYPE=rst tfm $< /dev/null
 
 %.rst: %.xfm
        $(P1) OUTPUT_TYPE=rst tfm $< /dev/null

-       $(P2) OUTPUT_TYPE=rst tfm $< stdout | sed 's/^ //' >$@
+       $(P2) OUTPUT_TYPE=rst tfm $< stdout | sed 's/^ //; s/ *$$//' >$@

 
 %.txt: %.xfm
        $(P1) OUTPUT_TYPE=txt tfm  $< /dev/null
 
 %.txt: %.xfm
        $(P1) OUTPUT_TYPE=txt tfm  $< /dev/null

diff --git a/doc/src/library/setup.im b/doc/src/library/setup.im
index 9ad6ece..3a96aca 100644 (file)
--- a/doc/src/library/setup.im
+++ b/doc/src/library/setup.im
@@ -158,9 +158,4 @@
        .pn on noline center f=%d 0
 .fi
 
        .pn on noline center f=%d 0
 .fi
 

-.** work around bug until change made (RouxWare issue #4)
-.if tfm
-       .in 7p
-.fi
-

 .dv _setup_im
 .dv _setup_im

diff --git a/doc/src/rtd/Makefile b/doc/src/rtd/Makefile
index dc8f4be..6ef1743 100644 (file)
--- a/doc/src/rtd/Makefile
+++ b/doc/src/rtd/Makefile
@@ -23,7 +23,7 @@
 
 
 %.rst:: %.xfm
 
 
 %.rst:: %.xfm

-       OUTPUT_TYPE=rst tfm $< | sed 's/^ //' >$@
+       OUTPUT_TYPE=rst tfm $< | sed 's/^ //;  s/ *$$//' >$@

 
 %.ps:: %.xfm
        OUTPUT_TYPE=ps pfm $< $@
 
 %.ps:: %.xfm
        OUTPUT_TYPE=ps pfm $< $@

diff --git a/doc/src/rtd/publish_man.sh b/doc/src/rtd/publish_man.sh
index 1bbfc7f..1563f62 100755 (executable)
--- a/doc/src/rtd/publish_man.sh
+++ b/doc/src/rtd/publish_man.sh
@@ -39,7 +39,7 @@ do
                out=stuff/${x%.*}.rst
                target=${sdir}/${out##*/}
 
                out=stuff/${x%.*}.rst
                target=${sdir}/${out##*/}
 

-               INPUT_FILE=${x%%.*} GEN_TITLE=1 LIB=".." OUTPUT_TYPE=rst tfm ../man/$x stdout 2>/dev/null | sed 's/^ //' >$out
+               INPUT_FILE=${x%%.*} GEN_TITLE=1 LIB=".." OUTPUT_TYPE=rst tfm ../man/$x stdout 2>/dev/null | sed 's/^ //;  s/ *$//' >$out

                new_m5=$( md5sum $out | sed 's/ .*//' )
                if [[ ! -f $target || $new_m5 != $( md5sum $target | sed 's/ .*//' ) ]]
                then
                new_m5=$( md5sum $out | sed 's/ .*//' )
                if [[ ! -f $target || $new_m5 != $( md5sum $target | sed 's/ .*//' ) ]]
                then

diff --git a/docs/config-deploy.rst b/docs/config-deploy.rst
index 58fff4b..16e64f5 100644 (file)
--- a/docs/config-deploy.rst
+++ b/docs/config-deploy.rst
@@ -1,222 +1,222 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Configuration and Deployment 
-============================================================================================ 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Configuration and Deployment
+============================================================================================

 
 
 OVERVIEW
 ========
 
 
 
 OVERVIEW
 ========
 

-The RIC Message Router (RMR) is a library for peer-to-peer 
-communication. Applications use the library to send and 
-receive messages where the message routing and endpoint 
-selection is based on the message type rather than DNS host 
-name-IP port combinations. 
- 
-This document contains information regarding the 
-configuration of RMR when it is embedded by a *user 
-application* . RMR itself is a library, not a deployable 
-entity. 
+The RIC Message Router (RMR) is a library for peer-to-peer
+communication. Applications use the library to send and
+receive messages where the message routing and endpoint
+selection is based on the message type rather than DNS host
+name-IP port combinations.
+
+This document contains information regarding the
+configuration of RMR when it is embedded by a *user
+application* . RMR itself is a library, not a deployable
+entity.

 
 
 Configuration
 -------------
 
 
 
 Configuration
 -------------
 

-Many aspects of RMR behavior are controlled via environment 
-variables. These values are read when a user application 
-invokes the RMR initialization function. This allows these 
-variables to be set before the application is started as a 
-function of the true environment, or set by the application 
-as a means for the application to influence RMR's behaviour. 
-The following is a list of environment variables which RMR 
-recognizes. Also see the main RMR manual page in the 
-development package for more details. 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **RMR_ASYNC_CONN** 
-       - 
-         Allows the async connection mode to be turned off (by setting 
-         the value to 0). When set to 1, or missing from the 
-         environment, RMR will invoke the connection interface in the 
-         transport mechanism using the non-blocking (async) mode. This 
-         will likely result in many "soft failures" (retry) until the 
-         connection is established, but allows the application to 
-         continue unimpeded should the connection be slow to set up. 
-      
-     * - **RMR_BIND_IF** 
-       - 
-         This provides the interface that RMR will bind listen ports 
-         to, allowing for a single interface to be used rather than 
-         listening across all interfaces. This should be the IP 
-         address assigned to the interface that RMR should listen on, 
-         and if not defined RMR will listen on all interfaces. 
-      
-     * - **RMR_CTL_PORT** 
-       - 
-         This variable defines the port that RMR should open for 
-         communications with Route Manager, and other RMR control 
-         applications. If not defined, the port 4561 is assumed. 
-          
-         Previously, the ``RMR_RTG_SVC`` (route table generator 
-         service port) was used to define this port. However, a future 
-         version of Route Manager will require RMR to connect and 
-         request tables, thus that variable is now used to supply the 
-         Route Manager's well-known address and port. 
-          
-         To maintain backwards compatibility with the older Route 
-         Manager versions, the presence of this variable in the 
-         environment will shift RMR's behaviour with respect to the 
-         default value used when ``RMR_RTG_SVC`` is **not** defined. 
-          
-         When ``RMR_CTL_PORT`` is **defined:** RMR assumes that Route 
-         Manager requires RMR to connect and request table updates is 
-         made, and the default well-known address for Route manager is 
-         used (routemgr:4561). 
-          
-         When ``RMR_CTL_PORT`` is **undefined:** RMR assumes that 
-         Route Manager will connect and push table updates, thus the 
-         default listen port (4561) is used. 
-          
-         To avoid any possible misinterpretation and/or incorrect 
-         assumptions on the part of RMR, it is recommended that both 
-         the ``RMR_CTL_PORT`` and ``RMR_RTG_SVC`` be defined. In the 
-         case where both variables are defined, RMR will behave 
-         exactly as is communicated with the variable's values. 
-      
-     * - **RMR_RTG_SVC** 
-       - 
-         The value of this variable depends on the Route Manager in 
-         use. 
-          
-         When the Route Manager is expecting to connect to an xAPP and 
-         push route tables, this variable must indicate the 
-         ``port`` which RMR should use to listen for these 
-         connections. 
-          
-         When the Route Manager is expecting RMR to connect and 
-         request a table update during initialisation, the variable 
-         should be the ``host`` of the Route Manager process. 
-          
-         The ``RMR_CTL_PORT`` variable (added with the support of 
-         sending table update requests to Route manager), controls the 
-         behaviour if this variable is not set. See the description of 
-         that variable for details. 
-      
-     * - **RMR_HR_LOG** 
-       - 
-         By default RMR writes messages to standard error (incorrectly 
-         referred to as log messages) in human readable format. If 
-         this environment variable is set to 0, the format of standard 
-         error messages might be written in some format not easily 
-         read by humans. If missing, a value of 1 is assumed. 
-      
-     * - **RMR_LOG_VLEVEL** 
-       - 
-         This is a numeric value which corresponds to the verbosity 
-         level used to limit messages written to standard error. The 
-         lower the number the less chatty RMR functions are during 
-         execution. The following is the current relationship between 
-         the value set on this variable and the messages written: 
-          
-          
-             .. list-table:: 
-               :widths: auto 
-               :header-rows: 0 
-               :class: borderless 
-                
-               * - **0** 
-                 - 
-                   Off; no messages of any sort are written. 
-                
-               * - **1** 
-                 - 
-                   Only critical messages are written (default if this variable 
-                   does not exist) 
-                
-               * - **2** 
-                 - 
-                   Errors and all messages written with a lower value. 
-                
-               * - **3** 
-                 - 
-                   Warnings and all messages written with a lower value. 
-                
-               * - **4** 
-                 - 
-                   Informational and all messages written with a lower value. 
-                
-               * - **5** 
-                 - 
-                   Debugging mode -- all messages written, however this requires 
-                   RMR to have been compiled with debugging support enabled. 
-                    
-          
-      
-     * - **RMR_RTG_ISRAW** 
-       - 
-         **Deprecated.** Should be set to 1 if the route table 
-         generator is sending "plain" messages (not using RMR to send 
-         messages), 0 if the RTG is using RMR to send. The default is 
-         1 as we don't expect the RTG to use RMR. 
-          
-         This variable is only recognised when using the NNG transport 
-         library as it is not possible to support NNG "raw" 
-         communications with other transport libraries. It is also 
-         necessary to match the value of this variable with the 
-         capabilities of the Route Manager; at some point in the 
-         future RMR will assume that all Route Manager messages will 
-         arrive via an RMR connection and will ignore this variable. 
-      
-     * - **RMR_SEED_RT** 
-       - 
-         This is used to supply a static route table which can be used 
-         for debugging, testing, or if no route table generator 
-         process is being used to supply the route table. If not 
-         defined, no static table is used and RMR will not report 
-         *ready* until a table is received. The static route table may 
-         contain both the route table (between newrt start and end 
-         records), and the MEID map (between meid_map start and end 
-         records). 
-      
-     * - **RMR_SRC_ID** 
-       - 
-         This is either the name or IP address which is placed into 
-         outbound messages as the message source. This will used when 
-         an RMR based application uses the rmr_rts_msg() function to 
-         return a response to the sender. If not supplied RMR will use 
-         the hostname which in some container environments might not 
-         be routable. 
-          
-         The value of this variable is also used for Route Manager 
-         messages which are sent via an RMR connection. 
-      
-     * - **RMR_VCTL_FILE** 
-       - 
-         This supplies the name of a verbosity control file. The core 
-         RMR functions do not produce messages unless there is a 
-         critical failure. However, the route table collection thread, 
-         not a part of the main message processing component, can 
-         write additional messages to standard error. If this variable 
-         is set, RMR will extract the verbosity level for these 
-         messages (0 is silent) from the first line of the file. 
-         Changes to the file are detected and thus the level can be 
-         changed dynamically, however RMR will only suss out this 
-         variable during initialisation, so it is impossible to enable 
-         verbosity after startup. 
-      
-     * - **RMR_WARNINGS** 
-       - 
-         If set to 1, RMR will write some warnings which are 
-         non-performance impacting. If the variable is not defined, or 
-         set to 0, RMR will not write these additional warnings. 
-          
- 
+Many aspects of RMR behavior are controlled via environment
+variables. These values are read when a user application
+invokes the RMR initialization function. This allows these
+variables to be set before the application is started as a
+function of the true environment, or set by the application
+as a means for the application to influence RMR's behaviour.
+The following is a list of environment variables which RMR
+recognizes. Also see the main RMR manual page in the
+development package for more details.
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMR_ASYNC_CONN**
+        -
+          Allows the async connection mode to be turned off (by setting
+          the value to 0). When set to 1, or missing from the
+          environment, RMR will invoke the connection interface in the
+          transport mechanism using the non-blocking (async) mode. This
+          will likely result in many "soft failures" (retry) until the
+          connection is established, but allows the application to
+          continue unimpeded should the connection be slow to set up.
+
+      * - **RMR_BIND_IF**
+        -
+          This provides the interface that RMR will bind listen ports
+          to, allowing for a single interface to be used rather than
+          listening across all interfaces. This should be the IP
+          address assigned to the interface that RMR should listen on,
+          and if not defined RMR will listen on all interfaces.
+
+      * - **RMR_CTL_PORT**
+        -
+          This variable defines the port that RMR should open for
+          communications with Route Manager, and other RMR control
+          applications. If not defined, the port 4561 is assumed.
+
+          Previously, the ``RMR_RTG_SVC`` (route table generator
+          service port) was used to define this port. However, a future
+          version of Route Manager will require RMR to connect and
+          request tables, thus that variable is now used to supply the
+          Route Manager's well-known address and port.
+
+          To maintain backwards compatibility with the older Route
+          Manager versions, the presence of this variable in the
+          environment will shift RMR's behaviour with respect to the
+          default value used when ``RMR_RTG_SVC`` is **not** defined.
+
+          When ``RMR_CTL_PORT`` is **defined:** RMR assumes that Route
+          Manager requires RMR to connect and request table updates is
+          made, and the default well-known address for Route manager is
+          used (routemgr:4561).
+
+          When ``RMR_CTL_PORT`` is **undefined:** RMR assumes that
+          Route Manager will connect and push table updates, thus the
+          default listen port (4561) is used.
+
+          To avoid any possible misinterpretation and/or incorrect
+          assumptions on the part of RMR, it is recommended that both
+          the ``RMR_CTL_PORT`` and ``RMR_RTG_SVC`` be defined. In the
+          case where both variables are defined, RMR will behave
+          exactly as is communicated with the variable's values.
+
+      * - **RMR_RTG_SVC**
+        -
+          The value of this variable depends on the Route Manager in
+          use.
+
+          When the Route Manager is expecting to connect to an xAPP and
+          push route tables, this variable must indicate the
+          ``port`` which RMR should use to listen for these
+          connections.
+
+          When the Route Manager is expecting RMR to connect and
+          request a table update during initialisation, the variable
+          should be the ``host`` of the Route Manager process.
+
+          The ``RMR_CTL_PORT`` variable (added with the support of
+          sending table update requests to Route manager), controls the
+          behaviour if this variable is not set. See the description of
+          that variable for details.
+
+      * - **RMR_HR_LOG**
+        -
+          By default RMR writes messages to standard error (incorrectly
+          referred to as log messages) in human readable format. If
+          this environment variable is set to 0, the format of standard
+          error messages might be written in some format not easily
+          read by humans. If missing, a value of 1 is assumed.
+
+      * - **RMR_LOG_VLEVEL**
+        -
+          This is a numeric value which corresponds to the verbosity
+          level used to limit messages written to standard error. The
+          lower the number the less chatty RMR functions are during
+          execution. The following is the current relationship between
+          the value set on this variable and the messages written:
+
+
+              .. list-table::
+                :widths: auto
+                :header-rows: 0
+                :class: borderless
+
+                * - **0**
+                  -
+                    Off; no messages of any sort are written.
+
+                * - **1**
+                  -
+                    Only critical messages are written (default if this variable
+                    does not exist)
+
+                * - **2**
+                  -
+                    Errors and all messages written with a lower value.
+
+                * - **3**
+                  -
+                    Warnings and all messages written with a lower value.
+
+                * - **4**
+                  -
+                    Informational and all messages written with a lower value.
+
+                * - **5**
+                  -
+                    Debugging mode -- all messages written, however this requires
+                    RMR to have been compiled with debugging support enabled.
+
+
+
+      * - **RMR_RTG_ISRAW**
+        -
+          **Deprecated.** Should be set to 1 if the route table
+          generator is sending "plain" messages (not using RMR to send
+          messages), 0 if the RTG is using RMR to send. The default is
+          1 as we don't expect the RTG to use RMR.
+
+          This variable is only recognised when using the NNG transport
+          library as it is not possible to support NNG "raw"
+          communications with other transport libraries. It is also
+          necessary to match the value of this variable with the
+          capabilities of the Route Manager; at some point in the
+          future RMR will assume that all Route Manager messages will
+          arrive via an RMR connection and will ignore this variable.
+
+      * - **RMR_SEED_RT**
+        -
+          This is used to supply a static route table which can be used
+          for debugging, testing, or if no route table generator
+          process is being used to supply the route table. If not
+          defined, no static table is used and RMR will not report
+          *ready* until a table is received. The static route table may
+          contain both the route table (between newrt start and end
+          records), and the MEID map (between meid_map start and end
+          records).
+
+      * - **RMR_SRC_ID**
+        -
+          This is either the name or IP address which is placed into
+          outbound messages as the message source. This will used when
+          an RMR based application uses the rmr_rts_msg() function to
+          return a response to the sender. If not supplied RMR will use
+          the hostname which in some container environments might not
+          be routable.
+
+          The value of this variable is also used for Route Manager
+          messages which are sent via an RMR connection.
+
+      * - **RMR_VCTL_FILE**
+        -
+          This supplies the name of a verbosity control file. The core
+          RMR functions do not produce messages unless there is a
+          critical failure. However, the route table collection thread,
+          not a part of the main message processing component, can
+          write additional messages to standard error. If this variable
+          is set, RMR will extract the verbosity level for these
+          messages (0 is silent) from the first line of the file.
+          Changes to the file are detected and thus the level can be
+          changed dynamically, however RMR will only suss out this
+          variable during initialisation, so it is impossible to enable
+          verbosity after startup.
+
+      * - **RMR_WARNINGS**
+        -
+          If set to 1, RMR will write some warnings which are
+          non-performance impacting. If the variable is not defined, or
+          set to 0, RMR will not write these additional warnings.
+
+

diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst
index bdd8964..9bfeccc 100644 (file)
--- a/docs/developer-guide.rst
+++ b/docs/developer-guide.rst
@@ -1,122 +1,122 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Developer's Guide 
-============================================================================================ 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Developer's Guide
+============================================================================================

 
 
 OVERVIEW
 ========
 
 
 
 OVERVIEW
 ========
 

-The RIC Message Router (RMR) is a library for peer-to-peer 
-communication. Applications use the library to send and 
-receive messages where the message routing and endpoint 
-selection is based on the message type rather than DNS host 
-name-IP port combinations. 
- 
-This document contains information that developers need to 
-know to contribute to the RMR project. 
+The RIC Message Router (RMR) is a library for peer-to-peer
+communication. Applications use the library to send and
+receive messages where the message routing and endpoint
+selection is based on the message type rather than DNS host
+name-IP port combinations.
+
+This document contains information that developers need to
+know to contribute to the RMR project.

 
 
 Language
 --------
 
 
 
 Language
 --------
 

-RMR is written in C, and thus a contributing developer to the 
-core library should have an excellent working knowledge of C. 
-There currently is one set of cross-languages bindings 
-supporting Python, and a developer wishing to contribute to 
-the bindings source should be familiar with Python (version 
-3.7+) and with the Python *ctypes* library. 
+RMR is written in C, and thus a contributing developer to the
+core library should have an excellent working knowledge of C.
+There currently is one set of cross-languages bindings
+supporting Python, and a developer wishing to contribute to
+the bindings source should be familiar with Python (version
+3.7+) and with the Python *ctypes* library.

 
 
 Code Structure
 --------------
 
 
 
 Code Structure
 --------------
 

-RMR is designed to provide an insulation layer between user 
-applications and the actual transport mechanism. Initially 
-RMR was built on top of the third-party library Nanosmg, 
-shortly after was ported to the third-party library NNG 
-(Nanomsg Next Generation), and then was ported to an 
-internally developed socket library called SI95. RMR presents 
-the same API to the user application regardless of the 
-underlying transport library, but the resulting output when 
-compiling RMR is always a transport-specific library. As an 
-example, ``librmr_nng.a`` is the library generated for use 
-with the NNG transport. 
- 
-As such the library source is organised into multiple 
-components: 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **common** 
-       - 
-         Source in the common directory is agnostic to the underlying 
-         transport mechanism (Nanomsg, NNG, SI95, ..), and thus can be 
-         used when generating either library. 
-      
-     * - **nano** 
-       - 
-         Source which is tightly coupled with the underlying Nanomsg 
-         library. (Nanomsg has been deprecated, but the RMR source 
-         remains as an example.) 
-      
-     * - **nng** 
-       - 
-         Source which is tightly coupled with the underlying NNG 
-         library. (NNG has been deprecated, but the RMR source remains 
-         as an example.) 
-      
-     * - **si** 
-       - 
-         Source which is tightly coupled with the underlying SI95 
-         library. 
-          
- 
- 
+RMR is designed to provide an insulation layer between user
+applications and the actual transport mechanism. Initially
+RMR was built on top of the third-party library Nanosmg,
+shortly after was ported to the third-party library NNG
+(Nanomsg Next Generation), and then was ported to an
+internally developed socket library called SI95. RMR presents
+the same API to the user application regardless of the
+underlying transport library, but the resulting output when
+compiling RMR is always a transport-specific library. As an
+example, ``librmr_nng.a`` is the library generated for use
+with the NNG transport.
+
+As such the library source is organised into multiple
+components:
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **common**
+        -
+          Source in the common directory is agnostic to the underlying
+          transport mechanism (Nanomsg, NNG, SI95, ..), and thus can be
+          used when generating either library.
+
+      * - **nano**
+        -
+          Source which is tightly coupled with the underlying Nanomsg
+          library. (Nanomsg has been deprecated, but the RMR source
+          remains as an example.)
+
+      * - **nng**
+        -
+          Source which is tightly coupled with the underlying NNG
+          library. (NNG has been deprecated, but the RMR source remains
+          as an example.)
+
+      * - **si**
+        -
+          Source which is tightly coupled with the underlying SI95
+          library.
+
+
+

 
 
 Internal Function Exposure
 --------------------------
 
 
 
 Internal Function Exposure
 --------------------------
 

-The decision to limit as much as practical the exposure of 
-truly internal RMR functions was made, and as a result most 
-of the RMR functions carry a ``static`` label. In order to 
-modularise the code as much as possible, this means that the 
-primary module (e.g. rmr_nng.c) directly includes other RMR 
-modules, rather than depending on referencing the internal 
-functions during linking. While this is an infrequently used 
-approach, it does mean that there are very few functions 
-visible for the user application to reference, all of them 
-having the prefix ``rmr\$1_``. This allows internal functions 
-to have shorter names while still being meaningful. 
+The decision to limit as much as practical the exposure of
+truly internal RMR functions was made, and as a result most
+of the RMR functions carry a ``static`` label. In order to
+modularise the code as much as possible, this means that the
+primary module (e.g. rmr_nng.c) directly includes other RMR
+modules, rather than depending on referencing the internal
+functions during linking. While this is an infrequently used
+approach, it does mean that there are very few functions
+visible for the user application to reference, all of them
+having the prefix ``rmr\$1_``. This allows internal functions
+to have shorter names while still being meaningful.

 
 
 Coding Style
 ------------
 
 
 
 Coding Style
 ------------
 

-There is a list of coding style guidelines in the top level 
-directory, and as such they are not expanded upon here. The 
-general practice is to follow the style when editing an 
-existing module, respect the author's choice where style 
-alternatives are not frowned upon. When creating new modules, 
-select a style that fits the guidelines and is easy for you 
-to work with. There are a few things that the RMR maintainers 
-insist on, but for the most part style is up to the creator 
-of a module. 
+There is a list of coding style guidelines in the top level
+directory, and as such they are not expanded upon here. The
+general practice is to follow the style when editing an
+existing module, respect the author's choice where style
+alternatives are not frowned upon. When creating new modules,
+select a style that fits the guidelines and is easy for you
+to work with. There are a few things that the RMR maintainers
+insist on, but for the most part style is up to the creator
+of a module.

 
 
 Building
 --------
 
 
 
 Building
 --------
 

-RMR is constructed using CMake. While CMake's project 
-description can be more cumbersome than most typical 
-Makefiles, the tool provides convenience especially when it 
-comes to creating DEB/RPM packages. 
+RMR is constructed using CMake. While CMake's project
+description can be more cumbersome than most typical
+Makefiles, the tool provides convenience especially when it
+comes to creating DEB/RPM packages.

diff --git a/docs/msg_types.rst b/docs/msg_types.rst
index f2e6a99..090d112 100644 (file)
--- a/docs/msg_types.rst
+++ b/docs/msg_types.rst
@@ -29,15 +29,15 @@ These message types are not routable and a message passed to
 an RMR function with any of these constants set will not be
 sent.
 
 an RMR function with any of these constants set will not be
 sent.
 

-   .. list-table::
-     :widths: 30,70
-     :header-rows: 0
-     :class: borderless
+    .. list-table::
+      :widths: 30,70
+      :header-rows: 0
+      :class: borderless

 
 

-     * - **RIC_UNDEFINED**
-       -
-         Message type is unset or undefined. Newly allocated messages
-         have the type value set to this constant.
+      * - **RIC_UNDEFINED**
+        -
+          Message type is unset or undefined. Newly allocated messages
+          have the type value set to this constant.

 
 
 
 
 
 


@@ -48,25 +48,25 @@ RMR Reserved Message Types
 These message types are reserved for RMR communications (e.g.
 with Route Manager).
 
 These message types are reserved for RMR communications (e.g.
 with Route Manager).
 

-   .. list-table::
-     :widths: 30,70
-     :header-rows: 0
-     :class: borderless
+    .. list-table::
+      :widths: 30,70
+      :header-rows: 0
+      :class: borderless

 
 

-     * - **RMRRM_TABLE_DATA**
-       -
-         Table data from route manger. Route manager sends all route
-         mse, etc.) with this type.
+      * - **RMRRM_TABLE_DATA**
+        -
+          Table data from route manger. Route manager sends all route
+          mse, etc.) with this type.

 
 

-     * - **RMRRM_REQ_TABLE**
-       -
-         Request for table update. RMR will send a message with this a
-         table update from route manger.
+      * - **RMRRM_REQ_TABLE**
+        -
+          Request for table update. RMR will send a message with this a
+          table update from route manger.

 
 

-     * - **RMRRM_TABLE_STATE**
-       -
-         This message type conveys the state of the route table to the
-         end of a table is noticed.
+      * - **RMRRM_TABLE_STATE**
+        -
+          This message type conveys the state of the route table to the
+          end of a table is noticed.

 
 
 
 
 
 


@@ -77,33 +77,33 @@ System Support Message Types
 These message types are used for systems level communications
 such as health checks, alarms and probes.
 
 These message types are used for systems level communications
 such as health checks, alarms and probes.
 

-   .. list-table::
-     :widths: 30,70
-     :header-rows: 0
-     :class: borderless
+    .. list-table::
+      :widths: 30,70
+      :header-rows: 0
+      :class: borderless

 
 

-     * - **RIC_HEALTH_CHECK_REQ**
-       -
-         When received the application is expected to return a
-         response to the current "health" of the application.
+      * - **RIC_HEALTH_CHECK_REQ**
+        -
+          When received the application is expected to return a
+          response to the current "health" of the application.

 
 

-     * - **RIC_HEALTH_CHECK_RESP**
-       -
-         Health responses are sent with a message of this type.
+      * - **RIC_HEALTH_CHECK_RESP**
+        -
+          Health responses are sent with a message of this type.

 
 

-     * - **RIC_ALARM**
-       -
-         Alarm messages with this type are routed to the alarm
-         collection process.
+      * - **RIC_ALARM**
+        -
+          Alarm messages with this type are routed to the alarm
+          collection process.

 
 

-     * - **RIC_ALARM_QUERY**
-       -
-         Unknown meaning
+      * - **RIC_ALARM_QUERY**
+        -
+          Unknown meaning

 
 

-     * - **RIC_METRICS**
-       -
-         This message type causes the message to be routed to the xAPP
-         responsible redistributing metrics.
+      * - **RIC_METRICS**
+        -
+          This message type causes the message to be routed to the xAPP
+          responsible redistributing metrics.

 
 
 
 
 
 


@@ -114,385 +114,385 @@ Unclassified Message Types
 The following message types have not been clasified into a
 specific category.
 
 The following message types have not been clasified into a
 specific category.
 

-   .. list-table::
-     :widths: 30,70
-     :header-rows: 0
-     :class: borderless
+    .. list-table::
+      :widths: 30,70
+      :header-rows: 0
+      :class: borderless

 
 

-     * - **RIC_SCTP_CONNECTION_FAILURE**
-       -
-         |
+      * - **RIC_SCTP_CONNECTION_FAILURE**
+        -
+          |

 
 

-     * - **RIC_SCTP_CLEAR_ALL**
-       -
-         |
+      * - **RIC_SCTP_CLEAR_ALL**
+        -
+          |

 
 

-     * - **E2_TERM_INIT**
-       -
-         |
+      * - **E2_TERM_INIT**
+        -
+          |

 
 

-     * - **E2_TERM_KEEP_ALIVE_REQ**
-       -
-         |
+      * - **E2_TERM_KEEP_ALIVE_REQ**
+        -
+          |

 
 

-     * - **E2_TERM_KEEP_ALIVE_RESP**
-       -
-         |
+      * - **E2_TERM_KEEP_ALIVE_RESP**
+        -
+          |

 
 

-     * - **RAN_CONNECTED**
-       -
-         |
+      * - **RAN_CONNECTED**
+        -
+          |

 
 

-     * - **RAN_RESTARTED**
-       -
-         |
+      * - **RAN_RESTARTED**
+        -
+          |

 
 

-     * - **RAN_RECONFIGURED**
-       -
-         |
+      * - **RAN_RECONFIGURED**
+        -
+          |

 
 

-     * - **RIC_ENB_LOAD_INFORMATION**
-       -
-         |
+      * - **RIC_ENB_LOAD_INFORMATION**
+        -
+          |

 
 

-     * - **RIC_ERROR_INDICATION**
-       -
-         |
+      * - **RIC_ERROR_INDICATION**
+        -
+          |

 
 

-     * - **RIC_SN_STATUS_TRANSFER**
-       -
-         |
+      * - **RIC_SN_STATUS_TRANSFER**
+        -
+          |

 
 

-     * - **RIC_UE_CONTEXT_RELEASE**
-       -
-         |
+      * - **RIC_UE_CONTEXT_RELEASE**
+        -
+          |

 
 

-     * - **RIC_X2_SETUP_REQ**
-       -
-         |
+      * - **RIC_X2_SETUP_REQ**
+        -
+          |

 
 

-     * - **RIC_X2_SETUP_RESP**
-       -
-         |
+      * - **RIC_X2_SETUP_RESP**
+        -
+          |

 
 

-     * - **RIC_X2_SETUP_FAILURE**
-       -
-         |
+      * - **RIC_X2_SETUP_FAILURE**
+        -
+          |

 
 

-     * - **RIC_X2_RESET**
-       -
-         |
+      * - **RIC_X2_RESET**
+        -
+          |

 
 

-     * - **RIC_X2_RESET_RESP**
-       -
-         |
+      * - **RIC_X2_RESET_RESP**
+        -
+          |

 
 

-     * - **RIC_ENB_CONF_UPDATE**
-       -
-         |
+      * - **RIC_ENB_CONF_UPDATE**
+        -
+          |

 
 

-     * - **RIC_ENB_CONF_UPDATE_ACK**
-       -
-         |
+      * - **RIC_ENB_CONF_UPDATE_ACK**
+        -
+          |

 
 

-     * - **RIC_ENB_CONF_UPDATE_FAILURE**
-       -
-         |
+      * - **RIC_ENB_CONF_UPDATE_FAILURE**
+        -
+          |

 
 

-     * - **RIC_RES_STATUS_REQ**
-       -
-         |
+      * - **RIC_RES_STATUS_REQ**
+        -
+          |

 
 

-     * - **RIC_RES_STATUS_RESP**
-       -
-         |
+      * - **RIC_RES_STATUS_RESP**
+        -
+          |

 
 

-     * - **RIC_RES_STATUS_FAILURE**
-       -
-         |
+      * - **RIC_RES_STATUS_FAILURE**
+        -
+          |

 
 

-     * - **RIC_RESOURCE_STATUS_UPDATE**
-       -
-         |
+      * - **RIC_RESOURCE_STATUS_UPDATE**
+        -
+          |

 
 

-     * - **RIC_SGNB_ADDITION_REQ**
-       -
-         |
+      * - **RIC_SGNB_ADDITION_REQ**
+        -
+          |

 
 

-     * - **RIC_SGNB_ADDITION_ACK**
-       -
-         |
+      * - **RIC_SGNB_ADDITION_ACK**
+        -
+          |

 
 

-     * - **RIC_SGNB_ADDITION_REJECT**
-       -
-         |
+      * - **RIC_SGNB_ADDITION_REJECT**
+        -
+          |

 
 

-     * - **RIC_SGNB_RECONF_COMPLETE**
-       -
-         |
+      * - **RIC_SGNB_RECONF_COMPLETE**
+        -
+          |

 
 

-     * - **RIC_SGNB_MOD_REQUEST**
-       -
-         |
+      * - **RIC_SGNB_MOD_REQUEST**
+        -
+          |

 
 

-     * - **RIC_SGNB_MOD_REQUEST_ACK**
-       -
-         |
+      * - **RIC_SGNB_MOD_REQUEST_ACK**
+        -
+          |

 
 

-     * - **RIC_SGNB_MOD_REQUEST_REJ**
-       -
-         |
+      * - **RIC_SGNB_MOD_REQUEST_REJ**
+        -
+          |

 
 

-     * - **RIC_SGNB_MOD_REQUIRED**
-       -
-         |
+      * - **RIC_SGNB_MOD_REQUIRED**
+        -
+          |

 
 

-     * - **RIC_SGNB_MOD_CONFIRM**
-       -
-         |
+      * - **RIC_SGNB_MOD_CONFIRM**
+        -
+          |

 
 

-     * - **RIC_SGNB_MOD_REFUSE**
-       -
-         |
+      * - **RIC_SGNB_MOD_REFUSE**
+        -
+          |

 
 

-     * - **RIC_SGNB_RELEASE_REQUEST**
-       -
-         |
+      * - **RIC_SGNB_RELEASE_REQUEST**
+        -
+          |

 
 

-     * - **RIC_SGNB_RELEASE_REQUEST_ACK**
-       -
-         |
+      * - **RIC_SGNB_RELEASE_REQUEST_ACK**
+        -
+          |

 
 

-     * - **RIC_SGNB_RELEASE_REQUIRED**
-       -
-         |
+      * - **RIC_SGNB_RELEASE_REQUIRED**
+        -
+          |

 
 

-     * - **RIC_SGNB_RELEASE_CONFIRM**
-       -
-         |
+      * - **RIC_SGNB_RELEASE_CONFIRM**
+        -
+          |

 
 

-     * - **RIC_RRC_TRANSFER**
-       -
-         |
+      * - **RIC_RRC_TRANSFER**
+        -
+          |

 
 

-     * - **RIC_ENDC_X2_SETUP_REQ**
-       -
-         |
+      * - **RIC_ENDC_X2_SETUP_REQ**
+        -
+          |

 
 

-     * - **RIC_ENDC_X2_SETUP_RESP**
-       -
-         |
+      * - **RIC_ENDC_X2_SETUP_RESP**
+        -
+          |

 
 

-     * - **RIC_ENDC_X2_SETUP_FAILURE**
-       -
-         |
+      * - **RIC_ENDC_X2_SETUP_FAILURE**
+        -
+          |

 
 

-     * - **RIC_ENDC_CONF_UPDATE**
-       -
-         |
+      * - **RIC_ENDC_CONF_UPDATE**
+        -
+          |

 
 

-     * - **RIC_ENDC_CONF_UPDATE_ACK**
-       -
-         |
+      * - **RIC_ENDC_CONF_UPDATE_ACK**
+        -
+          |

 
 

-     * - **RIC_ENDC_CONF_UPDATE_FAILURE**
-       -
-         |
+      * - **RIC_ENDC_CONF_UPDATE_FAILURE**
+        -
+          |

 
 

-     * - **RIC_SECONDARY_RAT_DATA_USAGE_REPORT**
-       -
-         |
+      * - **RIC_SECONDARY_RAT_DATA_USAGE_REPORT**
+        -
+          |

 
 

-     * - **RIC_GNB_STATUS_INDICATION**
-       -
-         |
+      * - **RIC_GNB_STATUS_INDICATION**
+        -
+          |

 
 

-     * - **RIC_E2_SETUP_REQ**
-       -
-         |
+      * - **RIC_E2_SETUP_REQ**
+        -
+          |

 
 

-     * - **RIC_E2_SETUP_RESP**
-       -
-         |
+      * - **RIC_E2_SETUP_RESP**
+        -
+          |

 
 

-     * - **RIC_E2_SETUP_FAILURE**
-       -
-         |
+      * - **RIC_E2_SETUP_FAILURE**
+        -
+          |

 
 

-     * - **RIC_E2_RESET_REQ**
-       -
-         |
+      * - **RIC_E2_RESET_REQ**
+        -
+          |

 
 

-     * - **RIC_E2_RESET_RESP**
-       -
-         |
+      * - **RIC_E2_RESET_RESP**
+        -
+          |

 
 

-     * - **RIC_E2_RAN_ERROR_INDICATION**
-       -
-         |
+      * - **RIC_E2_RAN_ERROR_INDICATION**
+        -
+          |

 
 

-     * - **RIC_E2_RIC_ERROR_INDICATION**
-       -
-         |
+      * - **RIC_E2_RIC_ERROR_INDICATION**
+        -
+          |

 
 

-     * - **RAN_E2_RESET_REQ**
-       -
-         |
+      * - **RAN_E2_RESET_REQ**
+        -
+          |

 
 

-     * - **RAN_E2_RESET_RESP**
-       -
-         |
+      * - **RAN_E2_RESET_RESP**
+        -
+          |

 
 

-     * - **RIC_SUB_REQ**
-       -
-         |
+      * - **RIC_SUB_REQ**
+        -
+          |

 
 

-     * - **RIC_SUB_RESP**
-       -
-         |
+      * - **RIC_SUB_RESP**
+        -
+          |

 
 

-     * - **RIC_SUB_FAILURE**
-       -
-         |
+      * - **RIC_SUB_FAILURE**
+        -
+          |

 
 

-     * - **RIC_SUB_DEL_REQ**
-       -
-         |
+      * - **RIC_SUB_DEL_REQ**
+        -
+          |

 
 

-     * - **RIC_SUB_DEL_RESP**
-       -
-         |
+      * - **RIC_SUB_DEL_RESP**
+        -
+          |

 
 

-     * - **RIC_SUB_DEL_FAILURE**
-       -
-         |
+      * - **RIC_SUB_DEL_FAILURE**
+        -
+          |

 
 

-     * - **RIC_SERVICE_UPDATE**
-       -
-         |
+      * - **RIC_SERVICE_UPDATE**
+        -
+          |

 
 

-     * - **RIC_SERVICE_UPDATE_ACK**
-       -
-         |
+      * - **RIC_SERVICE_UPDATE_ACK**
+        -
+          |

 
 

-     * - **RIC_SERVICE_UPDATE_FAILURE**
-       -
-         |
+      * - **RIC_SERVICE_UPDATE_FAILURE**
+        -
+          |

 
 

-     * - **RIC_CONTROL_REQ**
-       -
-         |
+      * - **RIC_CONTROL_REQ**
+        -
+          |

 
 

-     * - **RIC_CONTROL_ACK**
-       -
-         |
+      * - **RIC_CONTROL_ACK**
+        -
+          |

 
 

-     * - **RIC_CONTROL_FAILURE**
-       -
-         |
+      * - **RIC_CONTROL_FAILURE**
+        -
+          |

 
 

-     * - **RIC_INDICATION**
-       -
-         |
+      * - **RIC_INDICATION**
+        -
+          |

 
 

-     * - **RIC_SERVICE_QUERY**
-       -
-         |
+      * - **RIC_SERVICE_QUERY**
+        -
+          |

 
 

-     * - **DC_ADM_INT_CONTROL**
-       -
-         |
+      * - **DC_ADM_INT_CONTROL**
+        -
+          |

 
 

-     * - **DC_ADM_INT_CONTROL_ACK**
-       -
-         |
+      * - **DC_ADM_INT_CONTROL_ACK**
+        -
+          |

 
 

-     * - **DC_ADM_GET_POLICY**
-       -
-         |
+      * - **DC_ADM_GET_POLICY**
+        -
+          |

 
 

-     * - **DC_ADM_GET_POLICY_ACK**
-       -
-         |
+      * - **DC_ADM_GET_POLICY_ACK**
+        -
+          |

 
 

-     * - **A1_POLICY_REQ**
-       -
-         |
+      * - **A1_POLICY_REQ**
+        -
+          |

 
 

-     * - **A1_POLICY_RESP**
-       -
-         |
+      * - **A1_POLICY_RESP**
+        -
+          |

 
 

-     * - **A1_POLICY_QUERY**
-       -
-         |
+      * - **A1_POLICY_QUERY**
+        -
+          |

 
 

-     * - **TS_UE_LIST**
-       -
-         |
+      * - **TS_UE_LIST**
+        -
+          |

 
 

-     * - **TS_QOE_PRED_REQ**
-       -
-         |
+      * - **TS_QOE_PRED_REQ**
+        -
+          |

 
 

-     * - **TS_QOE_PREDICTION**
-       -
-         |
+      * - **TS_QOE_PREDICTION**
+        -
+          |

 
 

-     * - **MC_REPORT**
-       -
-         |
+      * - **MC_REPORT**
+        -
+          |

 
 

-     * - **DCAPTERM_RTPM_RMR_MSGTYPE**
-       -
-         |
+      * - **DCAPTERM_RTPM_RMR_MSGTYPE**
+        -
+          |

 
 

-     * - **DCAPTERM_GEO_RMR_MSGTYPE**
-       -
-         |
+      * - **DCAPTERM_GEO_RMR_MSGTYPE**
+        -
+          |

 
 

-     * - **RIC_X2_SETUP**
-       -
-         deprecated
+      * - **RIC_X2_SETUP**
+        -
+          deprecated

 
 

-     * - **RIC_X2_RESPONSE**
-       -
-         deprecated
+      * - **RIC_X2_RESPONSE**
+        -
+          deprecated

 
 

-     * - **RIC_X2_RESOURCE_STATUS_REQUEST**
-       -
-         deprecated
+      * - **RIC_X2_RESOURCE_STATUS_REQUEST**
+        -
+          deprecated

 
 

-     * - **RIC_X2_RESOURCE_STATUS_RESPONSE**
-       -
-         deprecated
+      * - **RIC_X2_RESOURCE_STATUS_RESPONSE**
+        -
+          deprecated

 
 

-     * - **RIC_X2_LOAD_INFORMATION**
-       -
-         deprecated
+      * - **RIC_X2_LOAD_INFORMATION**
+        -
+          deprecated

 
 

-     * - **RIC_E2_TERMINATION_HC_REQUEST**
-       -
-         deprecated
+      * - **RIC_E2_TERMINATION_HC_REQUEST**
+        -
+          deprecated

 
 

-     * - **RIC_E2_TERMINATION_HC_RESPONSE**
-       -
-         deprecated
+      * - **RIC_E2_TERMINATION_HC_RESPONSE**
+        -
+          deprecated

 
 

-     * - **RIC_E2_MANAGER_HC_REQUEST**
-       -
-         deprecated
+      * - **RIC_E2_MANAGER_HC_REQUEST**
+        -
+          deprecated

 
 

-     * - **RIC_E2_MANAGER_HC_RESPONSE**
-       -
-         deprecated
+      * - **RIC_E2_MANAGER_HC_RESPONSE**
+        -
+          deprecated

 
 

-     * - **RIC_CONTROL_XAPP_CONFIG_REQUEST**
-       -
-         deprecated
+      * - **RIC_CONTROL_XAPP_CONFIG_REQUEST**
+        -
+          deprecated

 
 

-     * - **RIC_CONTROL_XAPP_CONFIG_RESPONSE**
-       -
-         deprecated
+      * - **RIC_CONTROL_XAPP_CONFIG_RESPONSE**
+        -
+          deprecated

 
 
 
 

diff --git a/docs/rel-notes.rst b/docs/rel-notes.rst
index 43a100b..f740768 100644 (file)
--- a/docs/rel-notes.rst
+++ b/docs/rel-notes.rst
@@ -22,6 +22,14 @@ the need to leap frog versions ceased, and beginning with
 version 4.0.0, the RMR versions should no longer skip.
 
 
 version 4.0.0, the RMR versions should no longer skip.
 
 

+2020 July 21; Version 4.2.4
+---------------------------
+
+Fix bug in SI95 -- possible use of pointer after free
+(RIC-626).
+
+
+

 2020 July 9; version 4.1.3
 --------------------------
 
 2020 July 9; version 4.1.3
 --------------------------
 

diff --git a/docs/rmr.7.rst b/docs/rmr.7.rst
index e3df91c..05c1cd4 100644 (file)
--- a/docs/rmr.7.rst
+++ b/docs/rmr.7.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr
+============================================================================================
+
+

 
 
 RMR LIBRARY
 
 
 RMR LIBRARY


@@ -19,395 +19,395 @@ RMR LIBRARY
 NAME
 ----
 
 NAME
 ----
 

-RMR -- Ric Message Router Library 
+RMR -- Ric Message Router Library

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-RMR is a library which provides a user application with the 
-ability to send and receive messages to/from other RMR based 
-applications without having to understand the underlying 
-messaging transport environment (e.g., SI95) and without 
-needing to know which other endpoint applications are 
-currently available and accepting messages. To do this, RMR 
-depends on a routing table generated by an external source. 
-This table is used to determine the destination endpoint of 
-each message sent by mapping the message type T (supplied by 
-the user application) to an endpoint entry. Once determined, 
-the message is sent directly to the endpoint. The user 
-application is unaware of which endpoint actually receives 
-the message, and in some cases whether that message was sent 
-to multiple applications. 
- 
-RMR functions do provide for the ability to respond to the 
-specific source instance of a message allowing for either a 
-request response, or call response relationship when needed. 
+RMR is a library which provides a user application with the
+ability to send and receive messages to/from other RMR based
+applications without having to understand the underlying
+messaging transport environment (e.g., SI95) and without
+needing to know which other endpoint applications are
+currently available and accepting messages. To do this, RMR
+depends on a routing table generated by an external source.
+This table is used to determine the destination endpoint of
+each message sent by mapping the message type T (supplied by
+the user application) to an endpoint entry. Once determined,
+the message is sent directly to the endpoint. The user
+application is unaware of which endpoint actually receives
+the message, and in some cases whether that message was sent
+to multiple applications.
+
+RMR functions do provide for the ability to respond to the
+specific source instance of a message allowing for either a
+request response, or call response relationship when needed.

 
 
 The Route Table
 ---------------
 
 
 
 The Route Table
 ---------------
 

-The library must be given a route table which maps message 
-types (integers) to endpoint groups such that each time a 
-message of type T is sent, the message is delivered to one 
-member of each group associated with T. For example, message 
-type 2 might route to two different groups where group A has 
-two members, worker1 and worker2, while group B has only one 
-member, logger1. 
- 
-The route table consists of a start record, one or more table 
-entry records, and an end record. All table records contain 
-fields separated with vertical bars (|), and allow for 
-trailing comments with the standard shell comment symbol 
-(hash, #) provided that the start of the comment is separated 
-from the last token on the record by one or more spaces. 
-Leading and trailing white space in each field is ignored. 
-The route table supports two entry types: *rte* and *mse*. 
- 
-A *rte* entry defines a message type, an optional sender 
-application, and the endpoint(s) which accept the indicated 
-message type. However, this format is deprecated and may be 
-removed in a future version. An example record appears next. 
- 
-:: 
- 
-     rte | 1 | app10:4560
- 
- 
-The second type of entry is *mse*. This entry defines a 
-message type, an optional sender application, a subscription 
-ID, and a collection of endpoints. An example record appears 
-next. 
- 
-:: 
- 
-     mse | 1000,forwarder:43086 | 10 | app2:43086
- 
- 
-It is the responsibility of the route table generator to know 
-which endpoints belong to which groups, and which groups 
-accept which message types. Once understood, the route table 
-generator publishes a table that is ingested by RMR and used 
-for mapping messages to end points. 
- 
-The following is a simple route table which causes message 
-types 0 through 9 to be routed to specific applications: 
- 
-:: 
- 
- newrt|start
-    mse|0|-1| %meid
-    mse|1|-1|app10:4560,app11:4560
-    mse|2|-1|app12:4560
-    mse|3|-1|app14:4560
-    mse|4|-1|app18:4560
-    mse|5|-1|app01:4560
-    mse|6|-1|app02:4560
-    mse|7|-1|app03:4560
-    mse|8|-1|app04:4560
-    mse|9|-1|app05:4560
- newrt|end
- 
- 
-The special endpoint "%meid" indicates that the message type 
-(0 in this case) is to be routed to the endpoint which has 
-been listed as the "owner" for the meid appearing in the 
-message. MEID ownership is communicated to RMR using the same 
-Route Table Manager interface and by supplying a "table" such 
-as the one below: 
- 
-:: 
- 
- meid_map | start
-    mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005
-    mme_ar | control2 | meid100 meid101 meid102 meid103
- meid_map | end | 2
- 
- 
-This table indicates that the application (endpoint) 
-*control1* "owns" 6 MEIDs and *control2* owns 4. When message 
-type 0 is sent, the MEID in the message will be used to 
-select the endpoint via this table. 
- 
-The MEID table will update the existing owner relationships, 
-and add new ones; it is necessary to send only the changes 
-with the add/replace (mme_ar) entries in the table. When 
-necessary, MEIDs can be deleted by adding an ``mme_del`` 
-record to the table. The following example illustrates how 
-this might look: 
- 
-:: 
- 
- meid_map | start
-    mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005
-    mme_ar | control2 | meid100 meid101 meid102 meid103
-    mme_del| meid200 meid401
- meid_map | end | 3
- 
+The library must be given a route table which maps message
+types (integers) to endpoint groups such that each time a
+message of type T is sent, the message is delivered to one
+member of each group associated with T. For example, message
+type 2 might route to two different groups where group A has
+two members, worker1 and worker2, while group B has only one
+member, logger1.
+
+The route table consists of a start record, one or more table
+entry records, and an end record. All table records contain
+fields separated with vertical bars (|), and allow for
+trailing comments with the standard shell comment symbol
+(hash, #) provided that the start of the comment is separated
+from the last token on the record by one or more spaces.
+Leading and trailing white space in each field is ignored.
+The route table supports two entry types: *rte* and *mse*.
+
+A *rte* entry defines a message type, an optional sender
+application, and the endpoint(s) which accept the indicated
+message type. However, this format is deprecated and may be
+removed in a future version. An example record appears next.
+
+::
+
+      rte | 1 | app10:4560
+
+
+The second type of entry is *mse*. This entry defines a
+message type, an optional sender application, a subscription
+ID, and a collection of endpoints. An example record appears
+next.
+
+::
+
+      mse | 1000,forwarder:43086 | 10 | app2:43086
+
+
+It is the responsibility of the route table generator to know
+which endpoints belong to which groups, and which groups
+accept which message types. Once understood, the route table
+generator publishes a table that is ingested by RMR and used
+for mapping messages to end points.
+
+The following is a simple route table which causes message
+types 0 through 9 to be routed to specific applications:
+
+::
+
+  newrt|start
+     mse|0|-1| %meid
+     mse|1|-1|app10:4560,app11:4560
+     mse|2|-1|app12:4560
+     mse|3|-1|app14:4560
+     mse|4|-1|app18:4560
+     mse|5|-1|app01:4560
+     mse|6|-1|app02:4560
+     mse|7|-1|app03:4560
+     mse|8|-1|app04:4560
+     mse|9|-1|app05:4560
+  newrt|end
+
+
+The special endpoint "%meid" indicates that the message type
+(0 in this case) is to be routed to the endpoint which has
+been listed as the "owner" for the meid appearing in the
+message. MEID ownership is communicated to RMR using the same
+Route Table Manager interface and by supplying a "table" such
+as the one below:
+
+::
+
+  meid_map | start
+     mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005
+     mme_ar | control2 | meid100 meid101 meid102 meid103
+  meid_map | end | 2
+
+
+This table indicates that the application (endpoint)
+*control1* "owns" 6 MEIDs and *control2* owns 4. When message
+type 0 is sent, the MEID in the message will be used to
+select the endpoint via this table.
+
+The MEID table will update the existing owner relationships,
+and add new ones; it is necessary to send only the changes
+with the add/replace (mme_ar) entries in the table. When
+necessary, MEIDs can be deleted by adding an ``mme_del``
+record to the table. The following example illustrates how
+this might look:
+
+::
+
+  meid_map | start
+     mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005
+     mme_ar | control2 | meid100 meid101 meid102 meid103
+     mme_del| meid200 meid401
+  meid_map | end | 3
+

 
 
 Route Table Syntax
 ------------------
 
 
 
 Route Table Syntax
 ------------------
 

-The following illustrates the syntax for both types of route 
-table entries. 
- 
- 
-:: 
- 
- newrt | start
- rte | <message-type>[,<sender-endpoint>] | <round-robin-grp>[;<round-robin-grp>]...
- mse | <message-type>[,<sender-endpoint>] | <sub-id> | <round-robin-grp>[;<round-robin-grp>]...
- newrt | end
- 
- 
-A round robin group is one or more endpoints from which one 
-will be selected to receive the message. When multiple 
-endpoints are given in a group, they must be separated with a 
-comma. An endpoint is an IP address and port (e.g. 
-192.158.4.30:8219), or DNS name and port, of the application 
-that should receive the message type. If multiple round-robin 
-groups are given, they must be separated by a semicolon. 
+The following illustrates the syntax for both types of route
+table entries.
+
+
+::
+
+  newrt | start
+  rte | <message-type>[,<sender-endpoint>] | <round-robin-grp>[;<round-robin-grp>]...
+  mse | <message-type>[,<sender-endpoint>] | <sub-id> | <round-robin-grp>[;<round-robin-grp>]...
+  newrt | end
+
+
+A round robin group is one or more endpoints from which one
+will be selected to receive the message. When multiple
+endpoints are given in a group, they must be separated with a
+comma. An endpoint is an IP address and port (e.g.
+192.158.4.30:8219), or DNS name and port, of the application
+that should receive the message type. If multiple round-robin
+groups are given, they must be separated by a semicolon.

 
 
 MEID Map Syntax
 ---------------
 
 
 
 MEID Map Syntax
 ---------------
 

-The MEID map is similar to the route table. Entries are used 
-to add or replace the ownership of one or more MEIDs (mme_ar) 
-or to delete one or more MEIDs (mme_del). The following is 
-the syntax for the MEID map. 
- 
- 
-:: 
- 
- meid_map | start
- mme_ar | <owner-endpoint> | <meid> [<meid>...]
- mme_del | <meid> [<meid>...]
- meid_map | end | <count> | <md5sum>
- 
- 
-The <count> on the end record indicates the number of mme_ar 
-and mme_del records which were sent; if the count does not 
-match the whole map is refused and dropped. The 
-<owner-endpoint> is the endpoint which should receive the 
-message when a message is routed based on the MEID it 
-contains. A MEID may be "owned" by only one endpoint, and if 
-supplied multiple times, the last observed relationship is 
-used. Each of the lists of MEIDs are blank separated. 
- 
-The optional <md5sum> on the *end* record should be the 
-computed MD5 hash for all records which appear between the 
-start and and records. This allows for a tighter verification 
-that all data was received exactly as the route manager 
-transmitted them. 
+The MEID map is similar to the route table. Entries are used
+to add or replace the ownership of one or more MEIDs (mme_ar)
+or to delete one or more MEIDs (mme_del). The following is
+the syntax for the MEID map.
+
+
+::
+
+  meid_map | start
+  mme_ar | <owner-endpoint> | <meid> [<meid>...]
+  mme_del | <meid> [<meid>...]
+  meid_map | end | <count> | <md5sum>
+
+
+The <count> on the end record indicates the number of mme_ar
+and mme_del records which were sent; if the count does not
+match the whole map is refused and dropped. The
+<owner-endpoint> is the endpoint which should receive the
+message when a message is routed based on the MEID it
+contains. A MEID may be "owned" by only one endpoint, and if
+supplied multiple times, the last observed relationship is
+used. Each of the lists of MEIDs are blank separated.
+
+The optional <md5sum> on the *end* record should be the
+computed MD5 hash for all records which appear between the
+start and and records. This allows for a tighter verification
+that all data was received exactly as the route manager
+transmitted them.

 
 
 Environment
 -----------
 
 
 
 Environment
 -----------
 

-To enable configuration of the library behaviour outside of 
-direct user application control, RMR supports a number of 
-environment variables which provide information to the 
-library. The following is a list of the various environment 
-variables, what they control and the defaults which RMR uses 
-if undefined. 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **RMR_ASYNC_CONN** 
-       - 
-         Allows the async connection mode to be turned off (by setting 
-         the value to 0). When set to 1, or missing from the 
-         environment, RMR will invoke the connection interface in the 
-         transport mechanism using the non-blocking (async) mode. This 
-         will likely result in many "soft failures" (retry) until the 
-         connection is established, but allows the application to 
-         continue unimpeded should the connection be slow to set up. 
-      
-     * - **RMR_BIND_IF** 
-       - 
-         This provides the interface that RMR will bind listen ports 
-         to, allowing for a single interface to be used rather than 
-         listening across all interfaces. This should be the IP 
-         address assigned to the interface that RMR should listen on, 
-         and if not defined RMR will listen on all interfaces. 
-      
-     * - **RMR_CTL_PORT** 
-       - 
-         This variable defines the port that RMR should open for 
-         communications with Route Manager, and other RMR control 
-         applications. If not defined, the port 4561 is assumed. 
-          
-         Previously, the ``RMR_RTG_SVC`` (route table generator 
-         service port) was used to define this port. However, a future 
-         version of Route Manager will require RMR to connect and 
-         request tables, thus that variable is now used to supply the 
-         Route Manager's well-known address and port. 
-          
-         To maintain backwards compatibility with the older Route 
-         Manager versions, the presence of this variable in the 
-         environment will shift RMR's behaviour with respect to the 
-         default value used when ``RMR_RTG_SVC`` is **not** defined. 
-          
-         When ``RMR_CTL_PORT`` is **defined:** RMR assumes that Route 
-         Manager requires RMR to connect and request table updates is 
-         made, and the default well-known address for Route manager is 
-         used (routemgr:4561). 
-          
-         When ``RMR_CTL_PORT`` is **undefined:** RMR assumes that 
-         Route Manager will connect and push table updates, thus the 
-         default listen port (4561) is used. 
-          
-         To avoid any possible misinterpretation and/or incorrect 
-         assumptions on the part of RMR, it is recommended that both 
-         the ``RMR_CTL_PORT`` and ``RMR_RTG_SVC`` be defined. In the 
-         case where both variables are defined, RMR will behave 
-         exactly as is communicated with the variable's values. 
-      
-     * - **RMR_RTG_SVC** 
-       - 
-         The value of this variable depends on the Route Manager in 
-         use. 
-          
-         When the Route Manager is expecting to connect to an xAPP and 
-         push route tables, this variable must indicate the 
-         ``port`` which RMR should use to listen for these 
-         connections. 
-          
-         When the Route Manager is expecting RMR to connect and 
-         request a table update during initialisation, the variable 
-         should be the ``host`` of the Route Manager process. 
-          
-         The ``RMR_CTL_PORT`` variable (added with the support of 
-         sending table update requests to Route manager), controls the 
-         behaviour if this variable is not set. See the description of 
-         that variable for details. 
-      
-     * - **RMR_HR_LOG** 
-       - 
-         By default RMR writes messages to standard error (incorrectly 
-         referred to as log messages) in human readable format. If 
-         this environment variable is set to 0, the format of standard 
-         error messages might be written in some format not easily 
-         read by humans. If missing, a value of 1 is assumed. 
-      
-     * - **RMR_LOG_VLEVEL** 
-       - 
-         This is a numeric value which corresponds to the verbosity 
-         level used to limit messages written to standard error. The 
-         lower the number the less chatty RMR functions are during 
-         execution. The following is the current relationship between 
-         the value set on this variable and the messages written: 
-          
-          
-             .. list-table:: 
-               :widths: auto 
-               :header-rows: 0 
-               :class: borderless 
-                
-               * - **0** 
-                 - 
-                   Off; no messages of any sort are written. 
-                
-               * - **1** 
-                 - 
-                   Only critical messages are written (default if this variable 
-                   does not exist) 
-                
-               * - **2** 
-                 - 
-                   Errors and all messages written with a lower value. 
-                
-               * - **3** 
-                 - 
-                   Warnings and all messages written with a lower value. 
-                
-               * - **4** 
-                 - 
-                   Informational and all messages written with a lower value. 
-                
-               * - **5** 
-                 - 
-                   Debugging mode -- all messages written, however this requires 
-                   RMR to have been compiled with debugging support enabled. 
-                    
-          
-      
-     * - **RMR_RTG_ISRAW** 
-       - 
-         **Deprecated.** Should be set to 1 if the route table 
-         generator is sending "plain" messages (not using RMR to send 
-         messages), 0 if the RTG is using RMR to send. The default is 
-         1 as we don't expect the RTG to use RMR. 
-          
-         This variable is only recognised when using the NNG transport 
-         library as it is not possible to support NNG "raw" 
-         communications with other transport libraries. It is also 
-         necessary to match the value of this variable with the 
-         capabilities of the Route Manager; at some point in the 
-         future RMR will assume that all Route Manager messages will 
-         arrive via an RMR connection and will ignore this variable. 
-      
-     * - **RMR_SEED_RT** 
-       - 
-         This is used to supply a static route table which can be used 
-         for debugging, testing, or if no route table generator 
-         process is being used to supply the route table. If not 
-         defined, no static table is used and RMR will not report 
-         *ready* until a table is received. The static route table may 
-         contain both the route table (between newrt start and end 
-         records), and the MEID map (between meid_map start and end 
-         records). 
-      
-     * - **RMR_SRC_ID** 
-       - 
-         This is either the name or IP address which is placed into 
-         outbound messages as the message source. This will used when 
-         an RMR based application uses the rmr_rts_msg() function to 
-         return a response to the sender. If not supplied RMR will use 
-         the hostname which in some container environments might not 
-         be routable. 
-          
-         The value of this variable is also used for Route Manager 
-         messages which are sent via an RMR connection. 
-      
-     * - **RMR_VCTL_FILE** 
-       - 
-         This supplies the name of a verbosity control file. The core 
-         RMR functions do not produce messages unless there is a 
-         critical failure. However, the route table collection thread, 
-         not a part of the main message processing component, can 
-         write additional messages to standard error. If this variable 
-         is set, RMR will extract the verbosity level for these 
-         messages (0 is silent) from the first line of the file. 
-         Changes to the file are detected and thus the level can be 
-         changed dynamically, however RMR will only suss out this 
-         variable during initialisation, so it is impossible to enable 
-         verbosity after startup. 
-      
-     * - **RMR_WARNINGS** 
-       - 
-         If set to 1, RMR will write some warnings which are 
-         non-performance impacting. If the variable is not defined, or 
-         set to 0, RMR will not write these additional warnings. 
-          
- 
+To enable configuration of the library behaviour outside of
+direct user application control, RMR supports a number of
+environment variables which provide information to the
+library. The following is a list of the various environment
+variables, what they control and the defaults which RMR uses
+if undefined.
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMR_ASYNC_CONN**
+        -
+          Allows the async connection mode to be turned off (by setting
+          the value to 0). When set to 1, or missing from the
+          environment, RMR will invoke the connection interface in the
+          transport mechanism using the non-blocking (async) mode. This
+          will likely result in many "soft failures" (retry) until the
+          connection is established, but allows the application to
+          continue unimpeded should the connection be slow to set up.
+
+      * - **RMR_BIND_IF**
+        -
+          This provides the interface that RMR will bind listen ports
+          to, allowing for a single interface to be used rather than
+          listening across all interfaces. This should be the IP
+          address assigned to the interface that RMR should listen on,
+          and if not defined RMR will listen on all interfaces.
+
+      * - **RMR_CTL_PORT**
+        -
+          This variable defines the port that RMR should open for
+          communications with Route Manager, and other RMR control
+          applications. If not defined, the port 4561 is assumed.
+
+          Previously, the ``RMR_RTG_SVC`` (route table generator
+          service port) was used to define this port. However, a future
+          version of Route Manager will require RMR to connect and
+          request tables, thus that variable is now used to supply the
+          Route Manager's well-known address and port.
+
+          To maintain backwards compatibility with the older Route
+          Manager versions, the presence of this variable in the
+          environment will shift RMR's behaviour with respect to the
+          default value used when ``RMR_RTG_SVC`` is **not** defined.
+
+          When ``RMR_CTL_PORT`` is **defined:** RMR assumes that Route
+          Manager requires RMR to connect and request table updates is
+          made, and the default well-known address for Route manager is
+          used (routemgr:4561).
+
+          When ``RMR_CTL_PORT`` is **undefined:** RMR assumes that
+          Route Manager will connect and push table updates, thus the
+          default listen port (4561) is used.
+
+          To avoid any possible misinterpretation and/or incorrect
+          assumptions on the part of RMR, it is recommended that both
+          the ``RMR_CTL_PORT`` and ``RMR_RTG_SVC`` be defined. In the
+          case where both variables are defined, RMR will behave
+          exactly as is communicated with the variable's values.
+
+      * - **RMR_RTG_SVC**
+        -
+          The value of this variable depends on the Route Manager in
+          use.
+
+          When the Route Manager is expecting to connect to an xAPP and
+          push route tables, this variable must indicate the
+          ``port`` which RMR should use to listen for these
+          connections.
+
+          When the Route Manager is expecting RMR to connect and
+          request a table update during initialisation, the variable
+          should be the ``host`` of the Route Manager process.
+
+          The ``RMR_CTL_PORT`` variable (added with the support of
+          sending table update requests to Route manager), controls the
+          behaviour if this variable is not set. See the description of
+          that variable for details.
+
+      * - **RMR_HR_LOG**
+        -
+          By default RMR writes messages to standard error (incorrectly
+          referred to as log messages) in human readable format. If
+          this environment variable is set to 0, the format of standard
+          error messages might be written in some format not easily
+          read by humans. If missing, a value of 1 is assumed.
+
+      * - **RMR_LOG_VLEVEL**
+        -
+          This is a numeric value which corresponds to the verbosity
+          level used to limit messages written to standard error. The
+          lower the number the less chatty RMR functions are during
+          execution. The following is the current relationship between
+          the value set on this variable and the messages written:
+
+
+              .. list-table::
+                :widths: auto
+                :header-rows: 0
+                :class: borderless
+
+                * - **0**
+                  -
+                    Off; no messages of any sort are written.
+
+                * - **1**
+                  -
+                    Only critical messages are written (default if this variable
+                    does not exist)
+
+                * - **2**
+                  -
+                    Errors and all messages written with a lower value.
+
+                * - **3**
+                  -
+                    Warnings and all messages written with a lower value.
+
+                * - **4**
+                  -
+                    Informational and all messages written with a lower value.
+
+                * - **5**
+                  -
+                    Debugging mode -- all messages written, however this requires
+                    RMR to have been compiled with debugging support enabled.
+
+
+
+      * - **RMR_RTG_ISRAW**
+        -
+          **Deprecated.** Should be set to 1 if the route table
+          generator is sending "plain" messages (not using RMR to send
+          messages), 0 if the RTG is using RMR to send. The default is
+          1 as we don't expect the RTG to use RMR.
+
+          This variable is only recognised when using the NNG transport
+          library as it is not possible to support NNG "raw"
+          communications with other transport libraries. It is also
+          necessary to match the value of this variable with the
+          capabilities of the Route Manager; at some point in the
+          future RMR will assume that all Route Manager messages will
+          arrive via an RMR connection and will ignore this variable.
+
+      * - **RMR_SEED_RT**
+        -
+          This is used to supply a static route table which can be used
+          for debugging, testing, or if no route table generator
+          process is being used to supply the route table. If not
+          defined, no static table is used and RMR will not report
+          *ready* until a table is received. The static route table may
+          contain both the route table (between newrt start and end
+          records), and the MEID map (between meid_map start and end
+          records).
+
+      * - **RMR_SRC_ID**
+        -
+          This is either the name or IP address which is placed into
+          outbound messages as the message source. This will used when
+          an RMR based application uses the rmr_rts_msg() function to
+          return a response to the sender. If not supplied RMR will use
+          the hostname which in some container environments might not
+          be routable.
+
+          The value of this variable is also used for Route Manager
+          messages which are sent via an RMR connection.
+
+      * - **RMR_VCTL_FILE**
+        -
+          This supplies the name of a verbosity control file. The core
+          RMR functions do not produce messages unless there is a
+          critical failure. However, the route table collection thread,
+          not a part of the main message processing component, can
+          write additional messages to standard error. If this variable
+          is set, RMR will extract the verbosity level for these
+          messages (0 is silent) from the first line of the file.
+          Changes to the file are detected and thus the level can be
+          changed dynamically, however RMR will only suss out this
+          variable during initialisation, so it is impossible to enable
+          verbosity after startup.
+
+      * - **RMR_WARNINGS**
+        -
+          If set to 1, RMR will write some warnings which are
+          non-performance impacting. If the variable is not defined, or
+          set to 0, RMR will not write these additional warnings.
+
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_call(3), 
-rmr_free_msg(3), rmr_init(3), rmr_init_trace(3), 
-rmr_get_meid(3), rmr_get_src(3), rmr_get_srcip(3), 
-rmr_get_trace(3), rmr_get_trlen(3), rmr_get_xact(3), 
-rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3), 
-rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), 
-rmr_tokenise(3), rmr_mk_ring(3), rmr_realloc_payload(3), 
-rmr_ring_free(3), rmr_set_trace(3), rmr_torcv_msg(3), 
-rmr_wh_open(3), rmr_wh_send_msg(3) 
+rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_call(3),
+rmr_free_msg(3), rmr_init(3), rmr_init_trace(3),
+rmr_get_meid(3), rmr_get_src(3), rmr_get_srcip(3),
+rmr_get_trace(3), rmr_get_trlen(3), rmr_get_xact(3),
+rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
+rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
+rmr_tokenise(3), rmr_mk_ring(3), rmr_realloc_payload(3),
+rmr_ring_free(3), rmr_set_trace(3), rmr_torcv_msg(3),
+rmr_wh_open(3), rmr_wh_send_msg(3)

diff --git a/docs/rmr_alloc_msg.3.rst b/docs/rmr_alloc_msg.3.rst
index cc15fbb..9c79c34 100644 (file)
--- a/docs/rmr_alloc_msg.3.rst
+++ b/docs/rmr_alloc_msg.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_alloc_msg 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_alloc_msg
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,172 +19,172 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_alloc_msg 
+rmr_alloc_msg

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size );
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size );
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_alloc_msg`` function is used to allocate a buffer 
-which the user programme can write into and then send through 
-the RMR library. The buffer is allocated such that sending it 
-requires no additional copying out of the buffer. If the 
-value passed in ``size`` is less than or equal to 0, then the 
-*normal maximum size* supplied on the *rmr_init* call will be 
-used. When *size* is greater than zero, the message allocated 
-will have at least the indicated number of bytes in the 
-payload. There is no maximum size imposed by RMR, however the 
-underlying system memory management (e.g. malloc) functions 
-may impose a limit. 
- 
-The *ctx* parameter is the void context pointer that was 
-returned by the *rmr_init* function. 
- 
-The pointer to the message buffer returned is a structure 
-which has some user application visible fields; the structure 
-is described in ``rmr.h,`` and is illustrated below. 
- 
- 
-:: 
- 
- typedef struct {
-     int state;
-     int mtype;
-     int len;
-     unsigned char* payload;
-     unsigned char* xaction;
-     int sub_id;
-     int tp_state;
- } rmr_mbuf_t;
- 
- 
-Where: 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **state** 
-       - 
-         Is the current buffer state. Following a call to 
-         ``rmr_send_msg`` the state indicates whether the buffer was 
-         successfully sent which determines exactly what the payload 
-         points to. If the send failed, the payload referenced by the 
-         buffer is the message that failed to send (allowing the 
-         application to attempt a retransmission). When the state is 
-         ``RMR_OK`` the buffer represents an empty buffer that the 
-         application may fill in in preparation to send. 
-      
-     * - **mtype** 
-       - 
-         When sending a message, the application is expected to set 
-         this field to the appropriate message type value (as 
-         determined by the user programme). Upon send this value 
-         determines how the RMR library will route the message. For a 
-         buffer which has been received, this field will contain the 
-         message type that was set by the sending application. 
-      
-     * - **len** 
-       - 
-         The application using a buffer to send a message is expected 
-         to set the length value to the actual number of bytes that it 
-         placed into the message. This is likely less than the total 
-         number of bytes that the message can carry. For a message 
-         buffer that is passed to the application as the result of a 
-         receive call, this will be the value that the sending 
-         application supplied and should indicate the number of bytes 
-         in the payload which are valid. 
-      
-     * - **payload** 
-       - 
-         The payload is a pointer to the actual received data. The 
-         user programme may read and write from/to the memory 
-         referenced by the payload up until the point in time that the 
-         buffer is used on a ``rmr_send, rmr_call`` or 
-         ``rmr_reply`` function call. Once the buffer has been passed 
-         back to a RMR library function the user programme should 
-         **NOT** make use of the payload pointer. 
-      
-     * - **xaction** 
-       - 
-         The *xaction* field is a pointer to a fixed sized area in the 
-         message into which the user may write a transaction ID. The 
-         ID is optional with the exception of when the user 
-         application uses the ``rmr_call`` function to send a message 
-         and wait for the reply; the underlying RMR processing expects 
-         that the matching reply message will also contain the same 
-         data in the *xaction* field. 
-      
-     * - **sub_id** 
-       - 
-         This value is the subscription ID. It, in combination with 
-         the message type is used by rmr to determine the target 
-         endpoint when sending a message. If the application to 
-         application protocol does not warrant the use of a 
-         subscription ID, the RMR constant RMR_VOID_SUBID should be 
-         placed in this field. When an application is forwarding or 
-         returning a buffer to the sender, it is the application's 
-         responsibility to set/reset this value. 
-      
-     * - **tp_state** 
-       - 
-         For C applications making use of RMR, the state of a 
-         transport based failure will often be available via 
-         ``errno.`` However, some wrapper environments may not have 
-         direct access to the C-lib ``errno`` value. RMR send and 
-         receive operations will place the current value of 
-         ``errno`` into this field which should make it available to 
-         wrapper functions. User applications are strongly cautioned 
-         against relying on the value of errno as some transport 
-         mechanisms may not set this value on all calls. This value 
-         should also be ignored any time the message status is 
-         ``RMR_OK.`` 
-          
- 
+The ``rmr_alloc_msg`` function is used to allocate a buffer
+which the user programme can write into and then send through
+the RMR library. The buffer is allocated such that sending it
+requires no additional copying out of the buffer. If the
+value passed in ``size`` is less than or equal to 0, then the
+*normal maximum size* supplied on the *rmr_init* call will be
+used. When *size* is greater than zero, the message allocated
+will have at least the indicated number of bytes in the
+payload. There is no maximum size imposed by RMR, however the
+underlying system memory management (e.g. malloc) functions
+may impose a limit.
+
+The *ctx* parameter is the void context pointer that was
+returned by the *rmr_init* function.
+
+The pointer to the message buffer returned is a structure
+which has some user application visible fields; the structure
+is described in ``rmr.h,`` and is illustrated below.
+
+
+::
+
+  typedef struct {
+      int state;
+      int mtype;
+      int len;
+      unsigned char* payload;
+      unsigned char* xaction;
+      int sub_id;
+      int tp_state;
+  } rmr_mbuf_t;
+
+
+Where:
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **state**
+        -
+          Is the current buffer state. Following a call to
+          ``rmr_send_msg`` the state indicates whether the buffer was
+          successfully sent which determines exactly what the payload
+          points to. If the send failed, the payload referenced by the
+          buffer is the message that failed to send (allowing the
+          application to attempt a retransmission). When the state is
+          ``RMR_OK`` the buffer represents an empty buffer that the
+          application may fill in in preparation to send.
+
+      * - **mtype**
+        -
+          When sending a message, the application is expected to set
+          this field to the appropriate message type value (as
+          determined by the user programme). Upon send this value
+          determines how the RMR library will route the message. For a
+          buffer which has been received, this field will contain the
+          message type that was set by the sending application.
+
+      * - **len**
+        -
+          The application using a buffer to send a message is expected
+          to set the length value to the actual number of bytes that it
+          placed into the message. This is likely less than the total
+          number of bytes that the message can carry. For a message
+          buffer that is passed to the application as the result of a
+          receive call, this will be the value that the sending
+          application supplied and should indicate the number of bytes
+          in the payload which are valid.
+
+      * - **payload**
+        -
+          The payload is a pointer to the actual received data. The
+          user programme may read and write from/to the memory
+          referenced by the payload up until the point in time that the
+          buffer is used on a ``rmr_send, rmr_call`` or
+          ``rmr_reply`` function call. Once the buffer has been passed
+          back to a RMR library function the user programme should
+          **NOT** make use of the payload pointer.
+
+      * - **xaction**
+        -
+          The *xaction* field is a pointer to a fixed sized area in the
+          message into which the user may write a transaction ID. The
+          ID is optional with the exception of when the user
+          application uses the ``rmr_call`` function to send a message
+          and wait for the reply; the underlying RMR processing expects
+          that the matching reply message will also contain the same
+          data in the *xaction* field.
+
+      * - **sub_id**
+        -
+          This value is the subscription ID. It, in combination with
+          the message type is used by rmr to determine the target
+          endpoint when sending a message. If the application to
+          application protocol does not warrant the use of a
+          subscription ID, the RMR constant RMR_VOID_SUBID should be
+          placed in this field. When an application is forwarding or
+          returning a buffer to the sender, it is the application's
+          responsibility to set/reset this value.
+
+      * - **tp_state**
+        -
+          For C applications making use of RMR, the state of a
+          transport based failure will often be available via
+          ``errno.`` However, some wrapper environments may not have
+          direct access to the C-lib ``errno`` value. RMR send and
+          receive operations will place the current value of
+          ``errno`` into this field which should make it available to
+          wrapper functions. User applications are strongly cautioned
+          against relying on the value of errno as some transport
+          mechanisms may not set this value on all calls. This value
+          should also be ignored any time the message status is
+          ``RMR_OK.``
+
+

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-The function returns a pointer to a ``rmr_mbuf`` structure, 
-or NULL on error. 
+The function returns a pointer to a ``rmr_mbuf`` structure,
+or NULL on error.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **ENOMEM** 
-       - 
-         Unable to allocate memory. 
-          
- 
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **ENOMEM**
+        -
+          Unable to allocate memory.
+
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_tralloc_msg(3), rmr_call(3), rmr_free_msg(3), 
-rmr_init(3), rmr_init_trace(3), rmr_get_trace(3), 
-rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3), 
-rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), 
-rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), 
-rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3) 
+rmr_tralloc_msg(3), rmr_call(3), rmr_free_msg(3),
+rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
+rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
+rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
+rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
+rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)

diff --git a/docs/rmr_bytes2meid.3.rst b/docs/rmr_bytes2meid.3.rst
index 3afe3dc..f9e1df6 100644 (file)
--- a/docs/rmr_bytes2meid.3.rst
+++ b/docs/rmr_bytes2meid.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_bytes2meid 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_bytes2meid
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,65 +19,65 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_bytes2meid 
+rmr_bytes2meid

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_bytes2meid`` function will copy up to *len* bytes 
-from *src* to the managed entity ID (meid) field in the 
-message. The field is a fixed length, gated by the constant 
-``RMR_MAX_MEID`` and if len is larger than this value, only 
-RMR_MAX_MEID bytes will actually be copied. 
+The ``rmr_bytes2meid`` function will copy up to *len* bytes
+from *src* to the managed entity ID (meid) field in the
+message. The field is a fixed length, gated by the constant
+``RMR_MAX_MEID`` and if len is larger than this value, only
+RMR_MAX_MEID bytes will actually be copied.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-On success, the actual number of bytes copied is returned, or 
--1 to indicate a hard error. If the length is less than 0, or 
-not the same as length passed in, ``errno`` is set to one of 
-the errors described in the *Errors* section. 
+On success, the actual number of bytes copied is returned, or
+-1 to indicate a hard error. If the length is less than 0, or
+not the same as length passed in, ``errno`` is set to one of
+the errors described in the *Errors* section.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-If the returned length does not match the length passed in, 
-``errno`` will be set to one of the following constants with 
-the meaning listed below. 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-      
-     * - **EINVAL** 
-       - 
-         The message, or an internal portion of the message, was 
-         corrupted or the pointer was invalid. 
-          
-      
-     * - **EOVERFLOW** 
-       - 
-         The length passed in was larger than the maximum length of 
-         the field; only a portion of the source bytes were copied. 
-          
- 
+If the returned length does not match the length passed in,
+``errno`` will be set to one of the following constants with
+the meaning listed below.
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+
+      * - **EINVAL**
+        -
+          The message, or an internal portion of the message, was
+          corrupted or the pointer was invalid.
+
+
+      * - **EOVERFLOW**
+        -
+          The length passed in was larger than the maximum length of
+          the field; only a portion of the source bytes were copied.
+
+

 
 
 EXAMPLE
 
 
 EXAMPLE


@@ -88,10 +88,10 @@ EXAMPLE
 SEE ALSO
 --------
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_call(3), 
-rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_meid(3), 
-rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), 
-rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), 
-rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), 
-rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3), 
-rmr_wh_open(3), rmr_wh_send_msg(3) 
+rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_call(3),
+rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_meid(3),
+rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
+rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
+rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
+rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3),
+rmr_wh_open(3), rmr_wh_send_msg(3)

diff --git a/docs/rmr_bytes2payload.3.rst b/docs/rmr_bytes2payload.3.rst
index f9dc183..43de0b5 100644 (file)
--- a/docs/rmr_bytes2payload.3.rst
+++ b/docs/rmr_bytes2payload.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_bytes2payload 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_bytes2payload
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,39 +19,39 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_bytes2payload 
+rmr_bytes2payload

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char* src, int len )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char* src, int len )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-This is a convenience function as some wrapper languages 
-might not have the ability to directly copy into the payload 
-buffer. The bytes from *src* for the length given are copied 
-to the payload. It is the caller's responsibility to ensure 
-that the payload is large enough. Upon successfully copy, the 
-``len`` field in the message buffer is updated to reflect the 
-number of bytes copied. 
- 
-There is little error checking, and no error reporting. 
+This is a convenience function as some wrapper languages
+might not have the ability to directly copy into the payload
+buffer. The bytes from *src* for the length given are copied
+to the payload. It is the caller's responsibility to ensure
+that the payload is large enough. Upon successfully copy, the
+``len`` field in the message buffer is updated to reflect the
+number of bytes copied.
+
+There is little error checking, and no error reporting.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-None. 
+None.

 
 
 EXAMPLE
 
 
 EXAMPLE


@@ -62,10 +62,10 @@ EXAMPLE
 SEE ALSO
 --------
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2payload(3), 
-rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3), 
-rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3), 
-rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), 
-rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), 
-rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), 
-rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3) 
+rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2payload(3),
+rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
+rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3),
+rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
+rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
+rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
+rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)

diff --git a/docs/rmr_bytes2xact.3.rst b/docs/rmr_bytes2xact.3.rst
index dd99f13..12f29f2 100644 (file)
--- a/docs/rmr_bytes2xact.3.rst
+++ b/docs/rmr_bytes2xact.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_bytes2xact 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_bytes2xact
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,63 +19,63 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_bytes2xact 
+rmr_bytes2xact

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_bytes2xact`` function will copy up to *len* bytes 
-from *src* to the transaction ID (xaction) field in the 
-message. The field is a fixed length, gated by the constant 
-``RMR_MAX_XID`` and if len is larger than this value, only 
-``RMR_MAX_XID`` bytes will actually be copied. 
+The ``rmr_bytes2xact`` function will copy up to *len* bytes
+from *src* to the transaction ID (xaction) field in the
+message. The field is a fixed length, gated by the constant
+``RMR_MAX_XID`` and if len is larger than this value, only
+``RMR_MAX_XID`` bytes will actually be copied.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-On success, the actual number of bytes copied is returned, or 
--1 to indicate a hard error. If the length is less than 0, or 
-not the same as length passed in, ``errno`` is set to one of 
-the errors described in the *Errors* section. 
+On success, the actual number of bytes copied is returned, or
+-1 to indicate a hard error. If the length is less than 0, or
+not the same as length passed in, ``errno`` is set to one of
+the errors described in the *Errors* section.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-If the returned length does not match the length passed in, 
-``errno`` will be set to one of the following constants with 
-the meaning listed below. 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **EINVAL** 
-       - 
-         The message, or an internal portion of the message, was 
-         corrupted or the pointer was invalid. 
-      
-     * - **EOVERFLOW** 
-       - 
-         The length passed in was larger than the maximum length of 
-         the field; only a portion of the source bytes were copied. 
-          
- 
+If the returned length does not match the length passed in,
+``errno`` will be set to one of the following constants with
+the meaning listed below.
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **EINVAL**
+        -
+          The message, or an internal portion of the message, was
+          corrupted or the pointer was invalid.
+
+      * - **EOVERFLOW**
+        -
+          The length passed in was larger than the maximum length of
+          the field; only a portion of the source bytes were copied.
+
+

 
 
 EXAMPLE
 
 
 EXAMPLE


@@ -86,10 +86,10 @@ EXAMPLE
 SEE ALSO
 --------
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_call(3), 
-rmr_free_msg(3), rmr_get_meid(3), rmr_get_rcvfd(3), 
-rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3), 
-rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), 
-rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), 
-rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), 
-rmr_wh_open(3), rmr_wh_send_msg(3) 
+rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_call(3),
+rmr_free_msg(3), rmr_get_meid(3), rmr_get_rcvfd(3),
+rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3),
+rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
+rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
+rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
+rmr_wh_open(3), rmr_wh_send_msg(3)

diff --git a/docs/rmr_call.3.rst b/docs/rmr_call.3.rst
index bb02415..a8e02e5 100644 (file)
--- a/docs/rmr_call.3.rst
+++ b/docs/rmr_call.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_call 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_call
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,227 +19,227 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_call 
+rmr_call

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- extern rmr_mbuf_t* rmr_call( void* vctx, rmr_mbuf_t* msg );
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  extern rmr_mbuf_t* rmr_call( void* vctx, rmr_mbuf_t* msg );
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_call`` function sends the user application message 
-to a remote endpoint, and waits for a corresponding response 
-message before returning control to the user application. The 
-user application supplies a completed message buffer, as it 
-would for a ``rmr_send`` call, but unlike with the send, the 
-buffer returned will have the response from the application 
-that received the message. 
- 
-Messages which are received while waiting for the response 
-are queued internally by RMR, and are returned to the user 
-application when ``rmr_rcv_msg`` is invoked. These messages 
-are returned in the order received, one per call to 
-``rmr_rcv_msg.`` 
+The ``rmr_call`` function sends the user application message
+to a remote endpoint, and waits for a corresponding response
+message before returning control to the user application. The
+user application supplies a completed message buffer, as it
+would for a ``rmr_send`` call, but unlike with the send, the
+buffer returned will have the response from the application
+that received the message.
+
+Messages which are received while waiting for the response
+are queued internally by RMR, and are returned to the user
+application when ``rmr_rcv_msg`` is invoked. These messages
+are returned in the order received, one per call to
+``rmr_rcv_msg.``

 
 
 Call Timeout
 ------------
 
 
 
 Call Timeout
 ------------
 

-The ``rmr_call`` function implements a timeout failsafe to 
-prevent, in most cases, the function from blocking forever. 
-The timeout period is **not** based on time (calls to clock 
-are deemed too expensive for a low latency system level 
-library), but instead the period is based on the number of 
-received messages which are not the response. Using a 
-mechanism which is not time based for *timeout* prevents the 
-async queue from filling (which would lead to message drops) 
-in an environment where there is heavy message traffic. 
- 
-When the threshold number of messages have been queued 
-without receiving a response message, control is returned to 
-the user application and a nil pointer is returned to 
-indicate that no message was received to process. Currently 
-the threshold is fixed at 20 messages, though in future 
-versions of the library this might be extended to be a 
-parameter which the user application may set. 
+The ``rmr_call`` function implements a timeout failsafe to
+prevent, in most cases, the function from blocking forever.
+The timeout period is **not** based on time (calls to clock
+are deemed too expensive for a low latency system level
+library), but instead the period is based on the number of
+received messages which are not the response. Using a
+mechanism which is not time based for *timeout* prevents the
+async queue from filling (which would lead to message drops)
+in an environment where there is heavy message traffic.
+
+When the threshold number of messages have been queued
+without receiving a response message, control is returned to
+the user application and a nil pointer is returned to
+indicate that no message was received to process. Currently
+the threshold is fixed at 20 messages, though in future
+versions of the library this might be extended to be a
+parameter which the user application may set.

 
 
 Retries
 -------
 
 
 
 Retries
 -------
 

-The send operations in RMR will retry *soft* send failures 
-until one of three conditions occurs: 
- 
- 
-* The message is sent without error 
-  
-* The underlying transport reports a *hard* failure 
-  
-* The maximum number of retry loops has been attempted 
- 
- 
-A retry loop consists of approximately 1000 send attempts 
-**without** any intervening calls to *sleep()* or *usleep().* 
-The number of retry loops defaults to 1, thus a maximum of 
-1000 send attempts is performed before returning to the user 
-application. This value can be set at any point after RMR 
-initialisation using the *rmr_set_stimeout()* function 
-allowing the user application to completely disable retires 
-(set to 0), or to increase the number of retry loops. 
+The send operations in RMR will retry *soft* send failures
+until one of three conditions occurs:
+
+
+* The message is sent without error
+
+* The underlying transport reports a *hard* failure
+
+* The maximum number of retry loops has been attempted
+
+
+A retry loop consists of approximately 1000 send attempts
+**without** any intervening calls to *sleep()* or *usleep().*
+The number of retry loops defaults to 1, thus a maximum of
+1000 send attempts is performed before returning to the user
+application. This value can be set at any point after RMR
+initialisation using the *rmr_set_stimeout()* function
+allowing the user application to completely disable retires
+(set to 0), or to increase the number of retry loops.

 
 
 Transport Level Blocking
 ------------------------
 
 
 
 Transport Level Blocking
 ------------------------
 

-The underlying transport mechanism used to send messages is 
-configured in *non-blocking* mode. This means that if a 
-message cannot be sent immediately the transport mechanism 
-will **not** pause with the assumption that the inability to 
-send will clear quickly (within a few milliseconds). This 
-means that when the retry loop is completely disabled (set to 
-0), that the failure to accept a message for sending by the 
-underlying mechanisms (software or hardware) will be reported 
-immediately to the user application. 
- 
-It should be noted that depending on the underlying transport 
-mechanism being used, it is extremely likely that retry 
-conditions will happen during normal operations. These are 
-completely out of RMR's control, and there is nothing that 
-RMR can do to avoid or mitigate these other than by allowing 
-RMR to retry the send operation, and even then it is possible 
-(e.g., during connection reattempts), that a single retry 
-loop is not enough to guarantee a successful send. 
+The underlying transport mechanism used to send messages is
+configured in *non-blocking* mode. This means that if a
+message cannot be sent immediately the transport mechanism
+will **not** pause with the assumption that the inability to
+send will clear quickly (within a few milliseconds). This
+means that when the retry loop is completely disabled (set to
+0), that the failure to accept a message for sending by the
+underlying mechanisms (software or hardware) will be reported
+immediately to the user application.
+
+It should be noted that depending on the underlying transport
+mechanism being used, it is extremely likely that retry
+conditions will happen during normal operations. These are
+completely out of RMR's control, and there is nothing that
+RMR can do to avoid or mitigate these other than by allowing
+RMR to retry the send operation, and even then it is possible
+(e.g., during connection reattempts), that a single retry
+loop is not enough to guarantee a successful send.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-The ``rmr_call`` function returns a pointer to a message 
-buffer with the state set to reflect the overall state of 
-call processing (see Errors below). In some cases a nil 
-pointer will be returned; when this is the case only *errno* 
-will be available to describe the reason for failure. 
+The ``rmr_call`` function returns a pointer to a message
+buffer with the state set to reflect the overall state of
+call processing (see Errors below). In some cases a nil
+pointer will be returned; when this is the case only *errno*
+will be available to describe the reason for failure.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-These values are reflected in the state field of the returned 
-message. 
- 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **RMR_OK** 
-       - 
-         The call was successful and the message buffer references the 
-         response message. 
-      
-     * - **RMR_ERR_CALLFAILED** 
-       - 
-         The call failed and the value of *errno,* as described below, 
-         should be checked for the specific reason. 
-          
- 
- 
-The global "variable" *errno* will be set to one of the 
-following values if the overall call processing was not 
-successful. 
- 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **ETIMEDOUT** 
-       - 
-         Too many messages were queued before receiving the expected 
-         response 
-      
-     * - **ENOBUFS** 
-       - 
-         The queued message ring is full, messages were dropped 
-      
-     * - **EINVAL** 
-       - 
-         A parameter was not valid 
-      
-     * - **EAGAIN** 
-       - 
-         The underlying message system was interrupted or the device 
-         was busy; the message was **not** sent, and the user 
-         application should call this function with the message again. 
-          
- 
+These values are reflected in the state field of the returned
+message.
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMR_OK**
+        -
+          The call was successful and the message buffer references the
+          response message.
+
+      * - **RMR_ERR_CALLFAILED**
+        -
+          The call failed and the value of *errno,* as described below,
+          should be checked for the specific reason.
+
+
+
+The global "variable" *errno* will be set to one of the
+following values if the overall call processing was not
+successful.
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **ETIMEDOUT**
+        -
+          Too many messages were queued before receiving the expected
+          response
+
+      * - **ENOBUFS**
+        -
+          The queued message ring is full, messages were dropped
+
+      * - **EINVAL**
+        -
+          A parameter was not valid
+
+      * - **EAGAIN**
+        -
+          The underlying message system was interrupted or the device
+          was busy; the message was **not** sent, and the user
+          application should call this function with the message again.
+
+

 
 
 EXAMPLE
 -------
 
 
 
 EXAMPLE
 -------
 

-The following code snippet shows one way of using the 
-``rmr_call`` function, and illustrates how the transaction ID 
-must be set. 
- 
- 
-:: 
- 
-     int retries_left = 5;               // max retries on dev not available
-     int retry_delay = 50000;            // retry delay (usec)
-     static rmr_mbuf_t*  mbuf = NULL;    // response msg
-     msg_t*  pm;                         // application struct for payload
-  
-     // get a send buffer and reference the payload
-     mbuf = rmr_alloc_msg( mr, sizeof( pm->req ) );
-     pm = (msg_t*) mbuf->payload;
-  
-     // generate an xaction ID and fill in payload with data and msg type
-     snprintf( mbuf->xaction, RMR_MAX_XID, "%s", gen_xaction() );
-     snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
-     mbuf->mtype = MT_REQ;
-  
-     msg = rmr_call( mr, msg );
-     if( ! msg ) {               // probably a timeout and no msg received
-         return NULL;            // let errno trickle up
-     }
-  
-     if( mbuf->state != RMR_OK ) {
-         while( retries_left-- > 0 &&             // loop as long as eagain
-                errno == EAGAIN &&
-                (msg = rmr_call( mr, msg )) != NULL &&
-                mbuf->state != RMR_OK ) {
-  
-             usleep( retry_delay );
-         }
-  
-         if( mbuf == NULL || mbuf->state != RMR_OK ) {
-             rmr_free_msg( mbuf );        // safe if nil
-             return NULL;
-         }
-     }
-  
-     // do something with mbuf
- 
+The following code snippet shows one way of using the
+``rmr_call`` function, and illustrates how the transaction ID
+must be set.
+
+
+::
+
+      int retries_left = 5;               // max retries on dev not available
+      int retry_delay = 50000;            // retry delay (usec)
+      static rmr_mbuf_t*  mbuf = NULL;    // response msg
+      msg_t*  pm;                         // application struct for payload
+
+      // get a send buffer and reference the payload
+      mbuf = rmr_alloc_msg( mr, sizeof( pm->req ) );
+      pm = (msg_t*) mbuf->payload;
+
+      // generate an xaction ID and fill in payload with data and msg type
+      snprintf( mbuf->xaction, RMR_MAX_XID, "%s", gen_xaction() );
+      snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
+      mbuf->mtype = MT_REQ;
+
+      msg = rmr_call( mr, msg );
+      if( ! msg ) {               // probably a timeout and no msg received
+          return NULL;            // let errno trickle up
+      }
+
+      if( mbuf->state != RMR_OK ) {
+          while( retries_left-- > 0 &&             // loop as long as eagain
+                 errno == EAGAIN &&
+                 (msg = rmr_call( mr, msg )) != NULL &&
+                 mbuf->state != RMR_OK ) {
+
+              usleep( retry_delay );
+          }
+
+          if( mbuf == NULL || mbuf->state != RMR_OK ) {
+              rmr_free_msg( mbuf );        // safe if nil
+              return NULL;
+          }
+      }
+
+      // do something with mbuf
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3), 
-rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), 
-rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), 
-rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3), 
-rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3) 
+rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
+rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
+rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
+rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3),
+rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)

diff --git a/docs/rmr_close.3.rst b/docs/rmr_close.3.rst
index ae0af1d..2ddc025 100644 (file)
--- a/docs/rmr_close.3.rst
+++ b/docs/rmr_close.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_close 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_close
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,38 +19,38 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_close 
+rmr_close

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- void rmr_close( void* vctx )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  void rmr_close( void* vctx )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_close`` function closes the listen socket 
-effectively cutting the application off. The route table 
-listener is also stopped. Calls to rmr_rcv_msg() will fail 
-with unpredictable error codes, and calls to rmr_send_msg(), 
-rmr_call(), and rmr_rts_msg() will have unknown results. 
- 
+The ``rmr_close`` function closes the listen socket
+effectively cutting the application off. The route table
+listener is also stopped. Calls to rmr_rcv_msg() will fail
+with unpredictable error codes, and calls to rmr_send_msg(),
+rmr_call(), and rmr_rts_msg() will have unknown results.
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), 
-rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3), 
-rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), 
-rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), 
-rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3), 
-rmr_wh_send_msg(3) 
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
+rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
+rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
+rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
+rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3),
+rmr_wh_send_msg(3)

diff --git a/docs/rmr_free_msg.3.rst b/docs/rmr_free_msg.3.rst
index b35905c..833dc28 100644 (file)
--- a/docs/rmr_free_msg.3.rst
+++ b/docs/rmr_free_msg.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_free_msg 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_free_msg
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,41 +19,41 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_free_msg 
+rmr_free_msg

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- void rmr_free_msg( rmr_mbuf_t* mbuf );
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  void rmr_free_msg( rmr_mbuf_t* mbuf );
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The message buffer is returned to the pool, or the associated 
-memory is released depending on the needs of the underlying 
-messaging system. This allows the user application to release 
-a buffer that is not going to be used. It is safe to pass a 
-nil pointer to this function, and doing so does not result in 
-a change to the value of ``errrno.`` 
- 
-After calling, the user application should **not** use any of 
-the pointers (transaction ID, or payload) which were 
-available. 
+The message buffer is returned to the pool, or the associated
+memory is released depending on the needs of the underlying
+messaging system. This allows the user application to release
+a buffer that is not going to be used. It is safe to pass a
+nil pointer to this function, and doing so does not result in
+a change to the value of ``errrno.``
+
+After calling, the user application should **not** use any of
+the pointers (transaction ID, or payload) which were
+available.

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_init(3), 
-rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), 
-rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), 
-rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), 
-rmr_ring_free(3) 
+rmr_alloc_msg(3), rmr_call(3), rmr_init(3),
+rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
+rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
+rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
+rmr_ring_free(3)

diff --git a/docs/rmr_get_const.3.rst b/docs/rmr_get_const.3.rst
index 83f91df..f39465c 100644 (file)
--- a/docs/rmr_get_const.3.rst
+++ b/docs/rmr_get_const.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_get_const 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_get_const
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,55 +19,55 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_get_const 
+rmr_get_const

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- unsigned char* rmr_get_const();
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  unsigned char* rmr_get_const();
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_get_const`` function is a convenience function for 
-wrappers which do not have the ability to "compile in" RMR 
-constants. The function will build a nil terminated string 
-containing JSON which defines the RMR constants that C and Go 
-applications have at compile time via the ``rmr.h`` header 
-file. 
- 
-All values are represented as strings and the JSON format is 
-illustrated in the following (partial) example: 
- 
- 
-:: 
- 
- {
-   "RMR_MAX_XID": "32",
-   "RMR_OK": "0",
-   "RMR_ERR_BADARG", "1",
-   "RMR_ERR_NOENDPT" "2"
- }
- 
+The ``rmr_get_const`` function is a convenience function for
+wrappers which do not have the ability to "compile in" RMR
+constants. The function will build a nil terminated string
+containing JSON which defines the RMR constants that C and Go
+applications have at compile time via the ``rmr.h`` header
+file.
+
+All values are represented as strings and the JSON format is
+illustrated in the following (partial) example:
+
+
+::
+
+  {
+    "RMR_MAX_XID": "32",
+    "RMR_OK": "0",
+    "RMR_ERR_BADARG", "1",
+    "RMR_ERR_NOENDPT" "2"
+  }
+

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-On success, a pointer to a string containing the JSON 
-defining constant and value pairs. On failure a nil pointer 
-is returned. 
+On success, a pointer to a string containing the JSON
+defining constant and value pairs. On failure a nil pointer
+is returned.

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr(7) 
+rmr(7)

diff --git a/docs/rmr_get_meid.3.rst b/docs/rmr_get_meid.3.rst
index d97cfd9..0f03d6e 100644 (file)
--- a/docs/rmr_get_meid.3.rst
+++ b/docs/rmr_get_meid.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_get_meid 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_get_meid
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,74 +19,74 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_get_meid 
+rmr_get_meid

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- char* rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  char* rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_get_meid`` function will copy the managed entity ID 
-(meid) field from the message into the *dest* buffer provided 
-by the user. The buffer referenced by *dest* is assumed to be 
-at least ``RMR_MAX_MEID`` bytes in length. If *dest* is NULL, 
-then a buffer is allocated (the calling application is 
-expected to free when the buffer is no longer needed). 
+The ``rmr_get_meid`` function will copy the managed entity ID
+(meid) field from the message into the *dest* buffer provided
+by the user. The buffer referenced by *dest* is assumed to be
+at least ``RMR_MAX_MEID`` bytes in length. If *dest* is NULL,
+then a buffer is allocated (the calling application is
+expected to free when the buffer is no longer needed).

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-On success, a pointer to the extracted string is returned. If 
-*dest* was supplied, then this is just a pointer to the 
-caller's buffer. If *dest* was NULL, this is a pointer to the 
-allocated buffer. If an error occurs, a nil pointer is 
-returned and errno is set as described below. 
+On success, a pointer to the extracted string is returned. If
+*dest* was supplied, then this is just a pointer to the
+caller's buffer. If *dest* was NULL, this is a pointer to the
+allocated buffer. If an error occurs, a nil pointer is
+returned and errno is set as described below.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-If an error occurs, the value of the global variable 
-``errno`` will be set to one of the following with the 
-indicated meaning. 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **EINVAL** 
-       - 
-         The message, or an internal portion of the message, was 
-         corrupted or the pointer was invalid. 
-      
-     * - **ENOMEM** 
-       - 
-         A nil pointer was passed for *dest,* however it was not 
-         possible to allocate a buffer using malloc(). 
-          
- 
+If an error occurs, the value of the global variable
+``errno`` will be set to one of the following with the
+indicated meaning.
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **EINVAL**
+        -
+          The message, or an internal portion of the message, was
+          corrupted or the pointer was invalid.
+
+      * - **ENOMEM**
+        -
+          A nil pointer was passed for *dest,* however it was not
+          possible to allocate a buffer using malloc().
+
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3), 
-rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3), 
-rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3), 
-rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), 
-rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), 
-rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), 
-rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3) 
+rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
+rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
+rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3),
+rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
+rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
+rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
+rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)

diff --git a/docs/rmr_get_rcvfd.3.rst b/docs/rmr_get_rcvfd.3.rst
index 8a6bcd2..3a3e270 100644 (file)
--- a/docs/rmr_get_rcvfd.3.rst
+++ b/docs/rmr_get_rcvfd.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_get_rcvfd 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_get_rcvfd
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,117 +19,117 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_get_rcvfd 
+rmr_get_rcvfd

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- void* rmr_get_rcvfd( void* ctx )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  void* rmr_get_rcvfd( void* ctx )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_get_rcvfd`` function returns a file descriptor 
-which may be given to epoll_wait() by an application that 
-wishes to use event poll in a single thread rather than block 
-on the arrival of a message via calls to rmr_rcv_msg(). When 
-epoll_wait() indicates that this file descriptor is ready, a 
-call to rmr_rcv_msg() will not block as at least one message 
-has been received. 
- 
-The context (ctx) pointer passed in is the pointer returned 
-by the call to rmr_init(). 
+The ``rmr_get_rcvfd`` function returns a file descriptor
+which may be given to epoll_wait() by an application that
+wishes to use event poll in a single thread rather than block
+on the arrival of a message via calls to rmr_rcv_msg(). When
+epoll_wait() indicates that this file descriptor is ready, a
+call to rmr_rcv_msg() will not block as at least one message
+has been received.
+
+The context (ctx) pointer passed in is the pointer returned
+by the call to rmr_init().

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-The ``rmr_get_rcvfd`` function returns a file descriptor 
-greater or equal to 0 on success and -1 on error. 
+The ``rmr_get_rcvfd`` function returns a file descriptor
+greater or equal to 0 on success and -1 on error.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-The following error values are specifically set by this RMR 
-function. In some cases the error message of a system call is 
-propagated up, and thus this list might be incomplete. 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **EINVAL** 
-       - 
-         The use of this function is invalid in this environment. 
-          
- 
+The following error values are specifically set by this RMR
+function. In some cases the error message of a system call is
+propagated up, and thus this list might be incomplete.
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **EINVAL**
+        -
+          The use of this function is invalid in this environment.
+
+

 
 
 EXAMPLE
 -------
 
 
 
 EXAMPLE
 -------
 

-The following short code bit illustrates the use of this 
-function. Error checking has been omitted for clarity. 
- 
- 
-:: 
- 
- #include <stdio.h>
- #include <stdlib.h>
- #include <sys/epoll.h>
- #include <rmr/rmr.h>
-  
- int main() {
-     int rcv_fd;     // pollable fd
-     void* mrc;      //msg router context
-     struct epoll_event events[10];          // support 10 events to poll
-     struct epoll_event epe;                 // event definition for event to listen to
-     int     ep_fd = -1;
-     rmr_mbuf_t* msg = NULL;
-     int nready;
-     int i;
-     int norm_msg_size = 1500;               // 95% messages are less than this
-  
-     mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE );
-     rcv_fd = rmr_get_rcvfd( mrc );
-  
-     ep_fd = epoll_create1( 0 );             // initialise epoll environment
-     epe.events = EPOLLIN;
-     epe.data.fd = rcv_fd;
-     epoll_ctl( ep_fd, EPOLL_CTL_ADD, rcv_fd, &epe );    // add our info to the mix
-  
-     while( 1 ) {
-         nready = epoll_wait( ep_fd, events, 10, -1 );   // -1 == block forever (no timeout)
-         for( i = 0; i < nready && i < 10; i++ ) {       // loop through to find what is ready
-             if( events[i].data.fd == rcv_fd ) {         // RMR has something
-                 msg = rmr_rcv_msg( mrc, msg );
-                 if( msg ) {
-                     // do something with msg
-                 }
-             }
-  
-             // check for other ready fds....
-         }
-     }
- }
- 
+The following short code bit illustrates the use of this
+function. Error checking has been omitted for clarity.
+
+
+::
+
+  #include <stdio.h>
+  #include <stdlib.h>
+  #include <sys/epoll.h>
+  #include <rmr/rmr.h>
+
+  int main() {
+      int rcv_fd;     // pollable fd
+      void* mrc;      //msg router context
+      struct epoll_event events[10];          // support 10 events to poll
+      struct epoll_event epe;                 // event definition for event to listen to
+      int     ep_fd = -1;
+      rmr_mbuf_t* msg = NULL;
+      int nready;
+      int i;
+      int norm_msg_size = 1500;               // 95% messages are less than this
+
+      mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE );
+      rcv_fd = rmr_get_rcvfd( mrc );
+
+      ep_fd = epoll_create1( 0 );             // initialise epoll environment
+      epe.events = EPOLLIN;
+      epe.data.fd = rcv_fd;
+      epoll_ctl( ep_fd, EPOLL_CTL_ADD, rcv_fd, &epe );    // add our info to the mix
+
+      while( 1 ) {
+          nready = epoll_wait( ep_fd, events, 10, -1 );   // -1 == block forever (no timeout)
+          for( i = 0; i < nready && i < 10; i++ ) {       // loop through to find what is ready
+              if( events[i].data.fd == rcv_fd ) {         // RMR has something
+                  msg = rmr_rcv_msg( mrc, msg );
+                  if( msg ) {
+                      // do something with msg
+                  }
+              }
+
+              // check for other ready fds....
+          }
+      }
+  }
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), 
-rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), 
-rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), 
-rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), 
-rmr_ring_free(3) 
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
+rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
+rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
+rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
+rmr_ring_free(3)

diff --git a/docs/rmr_get_src.3.rst b/docs/rmr_get_src.3.rst
index 37f9f74..936e570 100644 (file)
--- a/docs/rmr_get_src.3.rst
+++ b/docs/rmr_get_src.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_get_src 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_get_src
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,74 +19,74 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_get_src 
+rmr_get_src

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- unsigned char* rmr_get_src( rmr_mbuf_t* mbuf, unsigned char* dest )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  unsigned char* rmr_get_src( rmr_mbuf_t* mbuf, unsigned char* dest )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_get_src`` function will copy the *source* 
-information from the message to a buffer (dest) supplied by 
-the user. In an RMR message, the source is the sender's 
-information that is used for return to sender function calls, 
-and is generally the hostname and port in the form *name*. 
-The source might be an IP address port combination; the data 
-is populated by the sending process and the only requirement 
-is that it be capable of being used to start a TCP session 
-with the sender. 
- 
-The maximum size allowed by RMR is 64 bytes (including the 
-nil string terminator), so the user must ensure that the 
-destination buffer given is at least 64 bytes. 
+The ``rmr_get_src`` function will copy the *source*
+information from the message to a buffer (dest) supplied by
+the user. In an RMR message, the source is the sender's
+information that is used for return to sender function calls,
+and is generally the hostname and port in the form *name*.
+The source might be an IP address port combination; the data
+is populated by the sending process and the only requirement
+is that it be capable of being used to start a TCP session
+with the sender.
+
+The maximum size allowed by RMR is 64 bytes (including the
+nil string terminator), so the user must ensure that the
+destination buffer given is at least 64 bytes.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-On success, a pointer to the destination buffer is given as a 
-convenience to the user programme. On failure, a nil pointer 
-is returned and the value of errno is set. 
+On success, a pointer to the destination buffer is given as a
+convenience to the user programme. On failure, a nil pointer
+is returned and the value of errno is set.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-If an error occurs, the value of the global variable 
-``errno`` will be set to one of the following with the 
-indicated meaning. 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **EINVAL** 
-       - 
-         The message, or an internal portion of the message, was 
-         corrupted or the pointer was invalid. 
-          
- 
+If an error occurs, the value of the global variable
+``errno`` will be set to one of the following with the
+indicated meaning.
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **EINVAL**
+        -
+          The message, or an internal portion of the message, was
+          corrupted or the pointer was invalid.
+
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3), 
-rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3), 
-rmr_get_srcip(3), rmr_payload_size(3), rmr_send_msg(3), 
-rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), 
-rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), 
-rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), 
-rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3) 
+rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
+rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
+rmr_get_srcip(3), rmr_payload_size(3), rmr_send_msg(3),
+rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
+rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
+rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
+rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)

diff --git a/docs/rmr_get_srcip.3.rst b/docs/rmr_get_srcip.3.rst
index 88785ed..b47ac8b 100644 (file)
--- a/docs/rmr_get_srcip.3.rst
+++ b/docs/rmr_get_srcip.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_get_srcip 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_get_srcip
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,77 +19,77 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_get_srcip 
+rmr_get_srcip

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- unsigned char* rmr_get_srcip( rmr_mbuf_t* mbuf, unsigned char* dest )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  unsigned char* rmr_get_srcip( rmr_mbuf_t* mbuf, unsigned char* dest )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_get_srcip`` function will copy the *source IP 
-address* from the message to a buffer (dest) supplied by the 
-user. In an RMR message, the source IP address is the 
-sender's information that is used for return to sender 
-function calls; this function makes it available to the user 
-application. The address is maintained as IP:port where *IP* 
-could be either an IPv6 or IPv4 address depending on what was 
-provided by the sending application. 
- 
-The maximum size allowed by RMR is 64 bytes (including the 
-nil string terminator), so the user must ensure that the 
-destination buffer given is at least 64 bytes. The user 
-application should use the RMR constant RMR_MAX_SRC to ensure 
-that the buffer supplied is large enough, and to protect 
-against future RMR enhancements which might increase the 
-address buffer size requirement. 
+The ``rmr_get_srcip`` function will copy the *source IP
+address* from the message to a buffer (dest) supplied by the
+user. In an RMR message, the source IP address is the
+sender's information that is used for return to sender
+function calls; this function makes it available to the user
+application. The address is maintained as IP:port where *IP*
+could be either an IPv6 or IPv4 address depending on what was
+provided by the sending application.
+
+The maximum size allowed by RMR is 64 bytes (including the
+nil string terminator), so the user must ensure that the
+destination buffer given is at least 64 bytes. The user
+application should use the RMR constant RMR_MAX_SRC to ensure
+that the buffer supplied is large enough, and to protect
+against future RMR enhancements which might increase the
+address buffer size requirement.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-On success, a pointer to the destination buffer is given as a 
-convenience to the user programme. On failure, a nil pointer 
-is returned and the value of errno is set. 
+On success, a pointer to the destination buffer is given as a
+convenience to the user programme. On failure, a nil pointer
+is returned and the value of errno is set.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-If an error occurs, the value of the global variable 
-``errno`` will be set to one of the following with the 
-indicated meaning. 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **EINVAL** 
-       - 
-         The message, or an internal portion of the message, was 
-         corrupted or the pointer was invalid. 
-          
- 
+If an error occurs, the value of the global variable
+``errno`` will be set to one of the following with the
+indicated meaning.
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **EINVAL**
+        -
+          The message, or an internal portion of the message, was
+          corrupted or the pointer was invalid.
+
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3), 
-rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3), 
-rmr_get_src(3), rmr_payload_size(3), rmr_send_msg(3), 
-rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), 
-rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), 
-rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), 
-rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3) 
+rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
+rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
+rmr_get_src(3), rmr_payload_size(3), rmr_send_msg(3),
+rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
+rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
+rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
+rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)

diff --git a/docs/rmr_get_trace.3.rst b/docs/rmr_get_trace.3.rst
index 2c27b8d..0f1fc8b 100644 (file)
--- a/docs/rmr_get_trace.3.rst
+++ b/docs/rmr_get_trace.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_get_trace 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_get_trace
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,49 +19,49 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_get_trace 
+rmr_get_trace

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- int rmr_get_trace( rmr_mbuf_t* mbuf, unsigned char* dest, int size )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  int rmr_get_trace( rmr_mbuf_t* mbuf, unsigned char* dest, int size )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_get_trace`` function will copy the trace 
-information from the message into the user's allocated memory 
-referenced by ``dest.`` The ``size`` parameter is assumed to 
-be the maximum number of bytes which can be copied (size of 
-the destination buffer). 
+The ``rmr_get_trace`` function will copy the trace
+information from the message into the user's allocated memory
+referenced by ``dest.`` The ``size`` parameter is assumed to
+be the maximum number of bytes which can be copied (size of
+the destination buffer).

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-On success, the number of bytes actually copied is returned. 
-If the return value is 0, no bytes copied, then the reason 
-could be that the message pointer was nil, or the size 
-parameter was <= 0. 
+On success, the number of bytes actually copied is returned.
+If the return value is 0, no bytes copied, then the reason
+could be that the message pointer was nil, or the size
+parameter was <= 0.

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3), 
-rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3), 
-rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3), 
-rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3), 
-rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), 
-rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), 
-rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), 
-rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3), 
-rmr_set_trace(3), rmr_trace_ref(3) 
+rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
+rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3),
+rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3),
+rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3),
+rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
+rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
+rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
+rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3),
+rmr_set_trace(3), rmr_trace_ref(3)

diff --git a/docs/rmr_get_trlen.3.rst b/docs/rmr_get_trlen.3.rst
index c438157..81430ae 100644 (file)
--- a/docs/rmr_get_trlen.3.rst
+++ b/docs/rmr_get_trlen.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_get_trlen 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_get_trlen
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,58 +19,58 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_get_trlen 
+rmr_get_trlen

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- int rmr_get_trlen( rmr_mbuf_t* msg );
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  int rmr_get_trlen( rmr_mbuf_t* msg );
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-Given a message buffer, this function returns the amount of 
-space (bytes) that have been allocated for trace data. If no 
-trace data has been allocated, then 0 is returned. 
+Given a message buffer, this function returns the amount of
+space (bytes) that have been allocated for trace data. If no
+trace data has been allocated, then 0 is returned.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-The number of bytes allocated for trace information in the 
-given message. 
+The number of bytes allocated for trace information in the
+given message.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **INVAL** 
-       - 
-         Parameter(s) passed to the function were not valid. 
-          
- 
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **INVAL**
+        -
+          Parameter(s) passed to the function were not valid.
+
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), 
-rmr_get_trace(3), rmr_init(3), rmr_init_trace(3), 
-rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3), 
-rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), 
-rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3), 
-rmr_set_trace(3), rmr_tralloc_msg(3) 
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
+rmr_get_trace(3), rmr_init(3), rmr_init_trace(3),
+rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
+rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
+rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
+rmr_set_trace(3), rmr_tralloc_msg(3)

diff --git a/docs/rmr_get_xact.3.rst b/docs/rmr_get_xact.3.rst
index 887d654..409b158 100644 (file)
--- a/docs/rmr_get_xact.3.rst
+++ b/docs/rmr_get_xact.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_get_xact 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_get_xact
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,74 +19,74 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_get_xact 
+rmr_get_xact

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- char* rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  char* rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_get_xact`` function will copy the transaction field 
-from the message into the *dest* buffer provided by the user. 
-The buffer referenced by *dest* is assumed to be at least 
-``RMR_MAX_XID`` bytes in length. If *dest* is NULL, then a 
-buffer is allocated (the calling application is expected to 
-free when the buffer is no longer needed). 
+The ``rmr_get_xact`` function will copy the transaction field
+from the message into the *dest* buffer provided by the user.
+The buffer referenced by *dest* is assumed to be at least
+``RMR_MAX_XID`` bytes in length. If *dest* is NULL, then a
+buffer is allocated (the calling application is expected to
+free when the buffer is no longer needed).

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-On success, a pointer to the extracted string is returned. If 
-*dest* was supplied, then this is just a pointer to the 
-caller's buffer. If *dest* was NULL, this is a pointer to the 
-allocated buffer. If an error occurs, a nil pointer is 
-returned and errno is set as described below. 
+On success, a pointer to the extracted string is returned. If
+*dest* was supplied, then this is just a pointer to the
+caller's buffer. If *dest* was NULL, this is a pointer to the
+allocated buffer. If an error occurs, a nil pointer is
+returned and errno is set as described below.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-If an error occurs, the value of the global variable 
-``errno`` will be set to one of the following with the 
-indicated meaning. 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **EINVAL** 
-       - 
-         The message, or an internal portion of the message, was 
-         corrupted or the pointer was invalid. 
-      
-     * - **ENOMEM** 
-       - 
-         A nil pointer was passed for *dest,* however it was not 
-         possible to allocate a buffer using malloc(). 
-          
- 
+If an error occurs, the value of the global variable
+``errno`` will be set to one of the following with the
+indicated meaning.
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **EINVAL**
+        -
+          The message, or an internal portion of the message, was
+          corrupted or the pointer was invalid.
+
+      * - **ENOMEM**
+        -
+          A nil pointer was passed for *dest,* however it was not
+          possible to allocate a buffer using malloc().
+
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3), 
-rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3), 
-rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3), 
-rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), 
-rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), 
-rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), 
-rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3) 
+rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
+rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
+rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3),
+rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
+rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
+rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
+rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)

diff --git a/docs/rmr_init.3.rst b/docs/rmr_init.3.rst
index ef830f2..d229a2a 100644 (file)
--- a/docs/rmr_init.3.rst
+++ b/docs/rmr_init.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_init 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_init
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,364 +19,364 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_init 
+rmr_init

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- void* rmr_init( char* proto_port, int norm_msg_size, int flags );
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  void* rmr_init( char* proto_port, int norm_msg_size, int flags );
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_init`` function prepares the environment for 
-sending and receiving messages. It does so by establishing a 
-worker thread (pthread) which subscribes to a route table 
-generator which provides the necessary routing information 
-for the RMR library to send messages. 
- 
-*Port* is used to listen for connection requests from other 
-RMR based applications. The *norm_msg_size* parameter is used 
-to allocate receive buffers and should be set to what the 
-user application expects to be a size which will hold the 
-vast majority of expected messages. When computing the size, 
-the application should consider the usual payload size 
-**and** the maximum trace data size that will be used. This 
-value is also used as the default message size when 
-allocating message buffers (when a zero size is given to 
-rmr_alloc_msg(); see the rmr_alloc_msg() manual page). 
-Messages arriving which are longer than the given normal size 
-will cause RMR to allocate a new buffer which is large enough 
-for the arriving message. 
- 
-Starting with version 3.8.0 RMR no longer places a maximum 
-buffer size for received messages. The underlying system 
-memory manager might impose such a limit and the attempt to 
-allocate a buffer larger than that limit will likely result 
-in an application abort. Other than the potential performance 
-impact from extra memory allocation and release, there is no 
-penality to the user programme for specifyning a normal 
-buffer size which is usually smaller than received buffers. 
-Similarly, the only penality to the application for over 
-specifying the normal buffer size might be a larger memory 
-footprint. 
- 
-*Flags* allows for selection of some RMR options at the time 
-of initialisation. These are set by ORing ``RMRFL`` constants 
-from the RMR header file. Currently the following flags are 
-supported: 
- 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **RMRFL_NONE** 
-       - 
-         No flags are set. 
-          
-      
-     * - **RMRFL_NOTHREAD** 
-       - 
-         The route table collector thread is not to be started. This 
-         should only be used by the route table generator application 
-         if it is based on RMR. 
-          
-      
-     * - **RMRFL_MTCALL** 
-       - 
-         Enable multi-threaded call support. 
-          
-      
-     * - **RMRFL_NOLOCK** 
-       - 
-         Some underlying transport providers (e.g. SI95) enable 
-         locking to be turned off if the user application is single 
-         threaded, or otherwise can guarantee that RMR functions will 
-         not be invoked concurrently from different threads. Turning 
-         off locking can help make message receipt more efficient. If 
-         this flag is set when the underlying transport does not 
-         support disabling locks, it will be ignored. 
-          
- 
+The ``rmr_init`` function prepares the environment for
+sending and receiving messages. It does so by establishing a
+worker thread (pthread) which subscribes to a route table
+generator which provides the necessary routing information
+for the RMR library to send messages.
+
+*Port* is used to listen for connection requests from other
+RMR based applications. The *norm_msg_size* parameter is used
+to allocate receive buffers and should be set to what the
+user application expects to be a size which will hold the
+vast majority of expected messages. When computing the size,
+the application should consider the usual payload size
+**and** the maximum trace data size that will be used. This
+value is also used as the default message size when
+allocating message buffers (when a zero size is given to
+rmr_alloc_msg(); see the rmr_alloc_msg() manual page).
+Messages arriving which are longer than the given normal size
+will cause RMR to allocate a new buffer which is large enough
+for the arriving message.
+
+Starting with version 3.8.0 RMR no longer places a maximum
+buffer size for received messages. The underlying system
+memory manager might impose such a limit and the attempt to
+allocate a buffer larger than that limit will likely result
+in an application abort. Other than the potential performance
+impact from extra memory allocation and release, there is no
+penality to the user programme for specifyning a normal
+buffer size which is usually smaller than received buffers.
+Similarly, the only penality to the application for over
+specifying the normal buffer size might be a larger memory
+footprint.
+
+*Flags* allows for selection of some RMR options at the time
+of initialisation. These are set by ORing ``RMRFL`` constants
+from the RMR header file. Currently the following flags are
+supported:
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMRFL_NONE**
+        -
+          No flags are set.
+
+
+      * - **RMRFL_NOTHREAD**
+        -
+          The route table collector thread is not to be started. This
+          should only be used by the route table generator application
+          if it is based on RMR.
+
+
+      * - **RMRFL_MTCALL**
+        -
+          Enable multi-threaded call support.
+
+
+      * - **RMRFL_NOLOCK**
+        -
+          Some underlying transport providers (e.g. SI95) enable
+          locking to be turned off if the user application is single
+          threaded, or otherwise can guarantee that RMR functions will
+          not be invoked concurrently from different threads. Turning
+          off locking can help make message receipt more efficient. If
+          this flag is set when the underlying transport does not
+          support disabling locks, it will be ignored.
+
+

 
 
 Multi-threaded Calling
 ----------------------
 
 
 
 Multi-threaded Calling
 ----------------------
 

-The support for an application to issue a *blocking call* by 
-the ``rmr_call()`` function was limited such that only user 
-applications which were operating in a single thread could 
-safely use the function. Further, timeouts were message count 
-based and not time unit based. Multi-threaded call support 
-adds the ability for a user application with multiple threads 
-to invoke a blocking call function with the guarantee that 
-the correct response message is delivered to the thread. The 
-additional support is implemented with the *rmr_mt_call()* 
-and *rmr_mt_rcv()* function calls. 
- 
-Multi-threaded call support requires the user application to 
-specifically enable it when RMR is initialised. This is 
-necessary because a second, dedicated, receiver thread must 
-be started, and requires all messages to be examined and 
-queued by this thread. The additional overhead is minimal, 
-queuing information is all in the RMR message header, but as 
-an additional process is necessary the user application must 
-"opt in" to this approach. 
- 
+The support for an application to issue a *blocking call* by
+the ``rmr_call()`` function was limited such that only user
+applications which were operating in a single thread could
+safely use the function. Further, timeouts were message count
+based and not time unit based. Multi-threaded call support
+adds the ability for a user application with multiple threads
+to invoke a blocking call function with the guarantee that
+the correct response message is delivered to the thread. The
+additional support is implemented with the *rmr_mt_call()*
+and *rmr_mt_rcv()* function calls.
+
+Multi-threaded call support requires the user application to
+specifically enable it when RMR is initialised. This is
+necessary because a second, dedicated, receiver thread must
+be started, and requires all messages to be examined and
+queued by this thread. The additional overhead is minimal,
+queuing information is all in the RMR message header, but as
+an additional process is necessary the user application must
+"opt in" to this approach.
+

 
 
 ENVIRONMENT
 -----------
 
 
 
 ENVIRONMENT
 -----------
 

-As a part of the initialisation process ``rmr_init`` reads 
-environment variables to configure itself. The following 
-variables are used if found. 
- 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **RMR_ASYNC_CONN** 
-       - 
-         Allows the async connection mode to be turned off (by setting 
-         the value to 0). When set to 1, or missing from the 
-         environment, RMR will invoke the connection interface in the 
-         transport mechanism using the non-blocking (async) mode. This 
-         will likely result in many "soft failures" (retry) until the 
-         connection is established, but allows the application to 
-         continue unimpeded should the connection be slow to set up. 
-      
-     * - **RMR_BIND_IF** 
-       - 
-         This provides the interface that RMR will bind listen ports 
-         to, allowing for a single interface to be used rather than 
-         listening across all interfaces. This should be the IP 
-         address assigned to the interface that RMR should listen on, 
-         and if not defined RMR will listen on all interfaces. 
-      
-     * - **RMR_CTL_PORT** 
-       - 
-         This variable defines the port that RMR should open for 
-         communications with Route Manager, and other RMR control 
-         applications. If not defined, the port 4561 is assumed. 
-          
-         Previously, the ``RMR_RTG_SVC`` (route table generator 
-         service port) was used to define this port. However, a future 
-         version of Route Manager will require RMR to connect and 
-         request tables, thus that variable is now used to supply the 
-         Route Manager's well-known address and port. 
-          
-         To maintain backwards compatibility with the older Route 
-         Manager versions, the presence of this variable in the 
-         environment will shift RMR's behaviour with respect to the 
-         default value used when ``RMR_RTG_SVC`` is **not** defined. 
-          
-         When ``RMR_CTL_PORT`` is **defined:** RMR assumes that Route 
-         Manager requires RMR to connect and request table updates is 
-         made, and the default well-known address for Route manager is 
-         used (routemgr:4561). 
-          
-         When ``RMR_CTL_PORT`` is **undefined:** RMR assumes that 
-         Route Manager will connect and push table updates, thus the 
-         default listen port (4561) is used. 
-          
-         To avoid any possible misinterpretation and/or incorrect 
-         assumptions on the part of RMR, it is recommended that both 
-         the ``RMR_CTL_PORT`` and ``RMR_RTG_SVC`` be defined. In the 
-         case where both variables are defined, RMR will behave 
-         exactly as is communicated with the variable's values. 
-      
-     * - **RMR_RTG_SVC** 
-       - 
-         The value of this variable depends on the Route Manager in 
-         use. 
-          
-         When the Route Manager is expecting to connect to an xAPP and 
-         push route tables, this variable must indicate the 
-         ``port`` which RMR should use to listen for these 
-         connections. 
-          
-         When the Route Manager is expecting RMR to connect and 
-         request a table update during initialisation, the variable 
-         should be the ``host`` of the Route Manager process. 
-          
-         The ``RMR_CTL_PORT`` variable (added with the support of 
-         sending table update requests to Route manager), controls the 
-         behaviour if this variable is not set. See the description of 
-         that variable for details. 
-      
-     * - **RMR_HR_LOG** 
-       - 
-         By default RMR writes messages to standard error (incorrectly 
-         referred to as log messages) in human readable format. If 
-         this environment variable is set to 0, the format of standard 
-         error messages might be written in some format not easily 
-         read by humans. If missing, a value of 1 is assumed. 
-      
-     * - **RMR_LOG_VLEVEL** 
-       - 
-         This is a numeric value which corresponds to the verbosity 
-         level used to limit messages written to standard error. The 
-         lower the number the less chatty RMR functions are during 
-         execution. The following is the current relationship between 
-         the value set on this variable and the messages written: 
-          
-          
-             .. list-table:: 
-               :widths: auto 
-               :header-rows: 0 
-               :class: borderless 
-                
-               * - **0** 
-                 - 
-                   Off; no messages of any sort are written. 
-                
-               * - **1** 
-                 - 
-                   Only critical messages are written (default if this variable 
-                   does not exist) 
-                
-               * - **2** 
-                 - 
-                   Errors and all messages written with a lower value. 
-                
-               * - **3** 
-                 - 
-                   Warnings and all messages written with a lower value. 
-                
-               * - **4** 
-                 - 
-                   Informational and all messages written with a lower value. 
-                
-               * - **5** 
-                 - 
-                   Debugging mode -- all messages written, however this requires 
-                   RMR to have been compiled with debugging support enabled. 
-                    
-          
-      
-     * - **RMR_RTG_ISRAW** 
-       - 
-         **Deprecated.** Should be set to 1 if the route table 
-         generator is sending "plain" messages (not using RMR to send 
-         messages), 0 if the RTG is using RMR to send. The default is 
-         1 as we don't expect the RTG to use RMR. 
-          
-         This variable is only recognised when using the NNG transport 
-         library as it is not possible to support NNG "raw" 
-         communications with other transport libraries. It is also 
-         necessary to match the value of this variable with the 
-         capabilities of the Route Manager; at some point in the 
-         future RMR will assume that all Route Manager messages will 
-         arrive via an RMR connection and will ignore this variable. 
-      
-     * - **RMR_SEED_RT** 
-       - 
-         This is used to supply a static route table which can be used 
-         for debugging, testing, or if no route table generator 
-         process is being used to supply the route table. If not 
-         defined, no static table is used and RMR will not report 
-         *ready* until a table is received. The static route table may 
-         contain both the route table (between newrt start and end 
-         records), and the MEID map (between meid_map start and end 
-         records). 
-      
-     * - **RMR_SRC_ID** 
-       - 
-         This is either the name or IP address which is placed into 
-         outbound messages as the message source. This will used when 
-         an RMR based application uses the rmr_rts_msg() function to 
-         return a response to the sender. If not supplied RMR will use 
-         the hostname which in some container environments might not 
-         be routable. 
-          
-         The value of this variable is also used for Route Manager 
-         messages which are sent via an RMR connection. 
-      
-     * - **RMR_VCTL_FILE** 
-       - 
-         This supplies the name of a verbosity control file. The core 
-         RMR functions do not produce messages unless there is a 
-         critical failure. However, the route table collection thread, 
-         not a part of the main message processing component, can 
-         write additional messages to standard error. If this variable 
-         is set, RMR will extract the verbosity level for these 
-         messages (0 is silent) from the first line of the file. 
-         Changes to the file are detected and thus the level can be 
-         changed dynamically, however RMR will only suss out this 
-         variable during initialisation, so it is impossible to enable 
-         verbosity after startup. 
-      
-     * - **RMR_WARNINGS** 
-       - 
-         If set to 1, RMR will write some warnings which are 
-         non-performance impacting. If the variable is not defined, or 
-         set to 0, RMR will not write these additional warnings. 
-          
- 
+As a part of the initialisation process ``rmr_init`` reads
+environment variables to configure itself. The following
+variables are used if found.
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMR_ASYNC_CONN**
+        -
+          Allows the async connection mode to be turned off (by setting
+          the value to 0). When set to 1, or missing from the
+          environment, RMR will invoke the connection interface in the
+          transport mechanism using the non-blocking (async) mode. This
+          will likely result in many "soft failures" (retry) until the
+          connection is established, but allows the application to
+          continue unimpeded should the connection be slow to set up.
+
+      * - **RMR_BIND_IF**
+        -
+          This provides the interface that RMR will bind listen ports
+          to, allowing for a single interface to be used rather than
+          listening across all interfaces. This should be the IP
+          address assigned to the interface that RMR should listen on,
+          and if not defined RMR will listen on all interfaces.
+
+      * - **RMR_CTL_PORT**
+        -
+          This variable defines the port that RMR should open for
+          communications with Route Manager, and other RMR control
+          applications. If not defined, the port 4561 is assumed.
+
+          Previously, the ``RMR_RTG_SVC`` (route table generator
+          service port) was used to define this port. However, a future
+          version of Route Manager will require RMR to connect and
+          request tables, thus that variable is now used to supply the
+          Route Manager's well-known address and port.
+
+          To maintain backwards compatibility with the older Route
+          Manager versions, the presence of this variable in the
+          environment will shift RMR's behaviour with respect to the
+          default value used when ``RMR_RTG_SVC`` is **not** defined.
+
+          When ``RMR_CTL_PORT`` is **defined:** RMR assumes that Route
+          Manager requires RMR to connect and request table updates is
+          made, and the default well-known address for Route manager is
+          used (routemgr:4561).
+
+          When ``RMR_CTL_PORT`` is **undefined:** RMR assumes that
+          Route Manager will connect and push table updates, thus the
+          default listen port (4561) is used.
+
+          To avoid any possible misinterpretation and/or incorrect
+          assumptions on the part of RMR, it is recommended that both
+          the ``RMR_CTL_PORT`` and ``RMR_RTG_SVC`` be defined. In the
+          case where both variables are defined, RMR will behave
+          exactly as is communicated with the variable's values.
+
+      * - **RMR_RTG_SVC**
+        -
+          The value of this variable depends on the Route Manager in
+          use.
+
+          When the Route Manager is expecting to connect to an xAPP and
+          push route tables, this variable must indicate the
+          ``port`` which RMR should use to listen for these
+          connections.
+
+          When the Route Manager is expecting RMR to connect and
+          request a table update during initialisation, the variable
+          should be the ``host`` of the Route Manager process.
+
+          The ``RMR_CTL_PORT`` variable (added with the support of
+          sending table update requests to Route manager), controls the
+          behaviour if this variable is not set. See the description of
+          that variable for details.
+
+      * - **RMR_HR_LOG**
+        -
+          By default RMR writes messages to standard error (incorrectly
+          referred to as log messages) in human readable format. If
+          this environment variable is set to 0, the format of standard
+          error messages might be written in some format not easily
+          read by humans. If missing, a value of 1 is assumed.
+
+      * - **RMR_LOG_VLEVEL**
+        -
+          This is a numeric value which corresponds to the verbosity
+          level used to limit messages written to standard error. The
+          lower the number the less chatty RMR functions are during
+          execution. The following is the current relationship between
+          the value set on this variable and the messages written:
+
+
+              .. list-table::
+                :widths: auto
+                :header-rows: 0
+                :class: borderless
+
+                * - **0**
+                  -
+                    Off; no messages of any sort are written.
+
+                * - **1**
+                  -
+                    Only critical messages are written (default if this variable
+                    does not exist)
+
+                * - **2**
+                  -
+                    Errors and all messages written with a lower value.
+
+                * - **3**
+                  -
+                    Warnings and all messages written with a lower value.
+
+                * - **4**
+                  -
+                    Informational and all messages written with a lower value.
+
+                * - **5**
+                  -
+                    Debugging mode -- all messages written, however this requires
+                    RMR to have been compiled with debugging support enabled.
+
+
+
+      * - **RMR_RTG_ISRAW**
+        -
+          **Deprecated.** Should be set to 1 if the route table
+          generator is sending "plain" messages (not using RMR to send
+          messages), 0 if the RTG is using RMR to send. The default is
+          1 as we don't expect the RTG to use RMR.
+
+          This variable is only recognised when using the NNG transport
+          library as it is not possible to support NNG "raw"
+          communications with other transport libraries. It is also
+          necessary to match the value of this variable with the
+          capabilities of the Route Manager; at some point in the
+          future RMR will assume that all Route Manager messages will
+          arrive via an RMR connection and will ignore this variable.
+
+      * - **RMR_SEED_RT**
+        -
+          This is used to supply a static route table which can be used
+          for debugging, testing, or if no route table generator
+          process is being used to supply the route table. If not
+          defined, no static table is used and RMR will not report
+          *ready* until a table is received. The static route table may
+          contain both the route table (between newrt start and end
+          records), and the MEID map (between meid_map start and end
+          records).
+
+      * - **RMR_SRC_ID**
+        -
+          This is either the name or IP address which is placed into
+          outbound messages as the message source. This will used when
+          an RMR based application uses the rmr_rts_msg() function to
+          return a response to the sender. If not supplied RMR will use
+          the hostname which in some container environments might not
+          be routable.
+
+          The value of this variable is also used for Route Manager
+          messages which are sent via an RMR connection.
+
+      * - **RMR_VCTL_FILE**
+        -
+          This supplies the name of a verbosity control file. The core
+          RMR functions do not produce messages unless there is a
+          critical failure. However, the route table collection thread,
+          not a part of the main message processing component, can
+          write additional messages to standard error. If this variable
+          is set, RMR will extract the verbosity level for these
+          messages (0 is silent) from the first line of the file.
+          Changes to the file are detected and thus the level can be
+          changed dynamically, however RMR will only suss out this
+          variable during initialisation, so it is impossible to enable
+          verbosity after startup.
+
+      * - **RMR_WARNINGS**
+        -
+          If set to 1, RMR will write some warnings which are
+          non-performance impacting. If the variable is not defined, or
+          set to 0, RMR will not write these additional warnings.
+
+

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-The ``rmr_init`` function returns a void pointer (a context 
-if you will) that is passed as the first parameter to nearly 
-all other RMR functions. If ``rmr_init`` is unable to 
-properly initialise the environment, NULL is returned and 
-errno is set to an appropriate value. 
+The ``rmr_init`` function returns a void pointer (a context
+if you will) that is passed as the first parameter to nearly
+all other RMR functions. If ``rmr_init`` is unable to
+properly initialise the environment, NULL is returned and
+errno is set to an appropriate value.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-The following error values are specifically set by this RMR 
-function. In some cases the error message of a system call is 
-propagated up, and thus this list might be incomplete. 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **ENOMEM** 
-       - 
-         Unable to allocate memory. 
-          
- 
+The following error values are specifically set by this RMR
+function. In some cases the error message of a system call is
+propagated up, and thus this list might be incomplete.
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **ENOMEM**
+        -
+          Unable to allocate memory.
+
+

 
 
 EXAMPLE
 -------
 
 
 
 EXAMPLE
 -------
 

- 
-:: 
- 
-    void*  uh;
-    rmr_mbuf* buf = NULL;
-  
-    uh = rmr_init( "43086", 4096, 0 );
-    buf = rmr_rcv_msg( uh, buf );
- 
+
+::
+
+     void*  uh;
+     rmr_mbuf* buf = NULL;
+
+     uh = rmr_init( "43086", 4096, 0 );
+     buf = rmr_rcv_msg( uh, buf );
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), 
-rmr_get_rcvfd(3), rmr_mt_call(3), rmr_mt_rcv(3), 
-rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), 
-rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), 
-rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), 
-rmr_ring_free(3) 
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
+rmr_get_rcvfd(3), rmr_mt_call(3), rmr_mt_rcv(3),
+rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
+rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
+rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
+rmr_ring_free(3)

diff --git a/docs/rmr_init_trace.3.rst b/docs/rmr_init_trace.3.rst
index 52875a9..2f9774d 100644 (file)
--- a/docs/rmr_init_trace.3.rst
+++ b/docs/rmr_init_trace.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_init_trace 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_init_trace
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,61 +19,61 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_init_trace 
+rmr_init_trace

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- void* rmr_init_trace( void* ctx )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  void* rmr_init_trace( void* ctx )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_init_trace`` function establishes the default trace 
-space placed in each message buffer allocated with 
-``rmr_alloc_msg().`` If this function is never called, then 
-no trace space is allocated by default into any message 
-buffer. 
- 
-Trace space allows the user application to pass some trace 
-token, or other data with the message, but outside of the 
-payload. Trace data may be added to any message with 
-``rmr_set_trace(),`` and may be extracted from a message with 
-``rmr_get_trace().`` The number of bytes that a message 
-contains for/with trace data can be determined by invoking 
-``rmr_get_trlen().`` 
- 
-This function may be safely called at any time during the 
-life of the user programme to (re)set the default trace space 
-reserved. If the user programme needs to allocate a message 
-with trace space of a different size than is allocated by 
-default, without fear of extra overhead of reallocating a 
-message later, the ``rmr_tralloc_msg()`` function can be 
-used. 
+The ``rmr_init_trace`` function establishes the default trace
+space placed in each message buffer allocated with
+``rmr_alloc_msg().`` If this function is never called, then
+no trace space is allocated by default into any message
+buffer.
+
+Trace space allows the user application to pass some trace
+token, or other data with the message, but outside of the
+payload. Trace data may be added to any message with
+``rmr_set_trace(),`` and may be extracted from a message with
+``rmr_get_trace().`` The number of bytes that a message
+contains for/with trace data can be determined by invoking
+``rmr_get_trlen().``
+
+This function may be safely called at any time during the
+life of the user programme to (re)set the default trace space
+reserved. If the user programme needs to allocate a message
+with trace space of a different size than is allocated by
+default, without fear of extra overhead of reallocating a
+message later, the ``rmr_tralloc_msg()`` function can be
+used.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-A value of 1 is returned on success, and 0 on failure. A 
-failure indicates that the RMR context (a void pointer passed 
-to this function was not valid. 
+A value of 1 is returned on success, and 0 on failure. A
+failure indicates that the RMR context (a void pointer passed
+to this function was not valid.

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_tr_alloc_msg(3), rmr_call(3), 
-rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_trace(3), 
-rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3), 
-rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), 
-rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), 
-rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3) 
+rmr_alloc_msg(3), rmr_tr_alloc_msg(3), rmr_call(3),
+rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_trace(3),
+rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
+rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
+rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
+rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)

diff --git a/docs/rmr_mt_call.3.rst b/docs/rmr_mt_call.3.rst
index f8b295b..985e9d7 100644 (file)
--- a/docs/rmr_mt_call.3.rst
+++ b/docs/rmr_mt_call.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_mt_call 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_mt_call
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,252 +19,252 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_mt_call 
+rmr_mt_call

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- extern rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* msg, int id, int timeout );
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  extern rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* msg, int id, int timeout );
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_mt_call`` function sends the user application 
-message to a remote endpoint, and waits for a corresponding 
-response message before returning control to the user 
-application. The user application supplies a completed 
-message buffer, as it would for a ``rmr_send_msg`` call, but 
-unlike with a send, the buffer returned will have the 
-response from the application that received the message. The 
-thread invoking the *rmr_mt_call()* will block until a 
-message arrives or until *timeout* milliseconds has passed; 
-which ever comes first. Using a timeout value of zero (0) 
-will cause the thread to block without a timeout. 
- 
-The *id* supplied as the third parameter is an integer in the 
-range of 2 through 255 inclusive. This is a caller defined 
-"thread number" and is used to match the response message 
-with the correct user application thread. If the ID value is 
-not in the proper range, the attempt to make the call will 
-fail. 
- 
-Messages which are received while waiting for the response 
-are queued on a *normal* receive queue and will be delivered 
-to the user application with the next invocation of 
-*rmr_mt_rcv()* or *rmr_rvv_msg().* by RMR, and are returned 
-to the user application when ``rmr_rcv_msg`` is invoked. 
-These messages are returned in the order received, one per 
-call to ``rmr_rcv_msg.`` 
+The ``rmr_mt_call`` function sends the user application
+message to a remote endpoint, and waits for a corresponding
+response message before returning control to the user
+application. The user application supplies a completed
+message buffer, as it would for a ``rmr_send_msg`` call, but
+unlike with a send, the buffer returned will have the
+response from the application that received the message. The
+thread invoking the *rmr_mt_call()* will block until a
+message arrives or until *timeout* milliseconds has passed;
+which ever comes first. Using a timeout value of zero (0)
+will cause the thread to block without a timeout.
+
+The *id* supplied as the third parameter is an integer in the
+range of 2 through 255 inclusive. This is a caller defined
+"thread number" and is used to match the response message
+with the correct user application thread. If the ID value is
+not in the proper range, the attempt to make the call will
+fail.
+
+Messages which are received while waiting for the response
+are queued on a *normal* receive queue and will be delivered
+to the user application with the next invocation of
+*rmr_mt_rcv()* or *rmr_rvv_msg().* by RMR, and are returned
+to the user application when ``rmr_rcv_msg`` is invoked.
+These messages are returned in the order received, one per
+call to ``rmr_rcv_msg.``

 
 
 The Transaction ID
 ------------------
 
 
 
 The Transaction ID
 ------------------
 

-The user application is responsible for setting the value of 
-the transaction ID field before invoking *rmr_mt_call.* The 
-transaction ID is a ``RMR_MAX_XID`` byte field that is used 
-to match the response message when it arrives. RMR will 
-compare **all** of the bytes in the field, so the caller must 
-ensure that they are set correctly to avoid missing the 
-response message. The application which returns the response 
-message is also expected to ensure that the return buffer has 
-the matching transaction ID. This can be done transparently 
-if the application uses the *rmr_rts_msg()* function and does 
-not adjust the transaction ID. 
+The user application is responsible for setting the value of
+the transaction ID field before invoking *rmr_mt_call.* The
+transaction ID is a ``RMR_MAX_XID`` byte field that is used
+to match the response message when it arrives. RMR will
+compare **all** of the bytes in the field, so the caller must
+ensure that they are set correctly to avoid missing the
+response message. The application which returns the response
+message is also expected to ensure that the return buffer has
+the matching transaction ID. This can be done transparently
+if the application uses the *rmr_rts_msg()* function and does
+not adjust the transaction ID.

 
 
 Retries
 -------
 
 
 
 Retries
 -------
 

-The send operations in RMR will retry *soft* send failures 
-until one of three conditions occurs: 
- 
- 
-* The message is sent without error 
-  
-* The underlying transport reports a *hard* failure 
-  
-* The maximum number of retry loops has been attempted 
- 
- 
-A retry loop consists of approximately 1000 send attempts 
-**without** any intervening calls to *sleep()* or *usleep().* 
-The number of retry loops defaults to 1, thus a maximum of 
-1000 send attempts is performed before returning to the user 
-application. This value can be set at any point after RMR 
-initialisation using the *rmr_set_stimeout()* function 
-allowing the user application to completely disable retires 
-(set to 0), or to increase the number of retry loops. 
+The send operations in RMR will retry *soft* send failures
+until one of three conditions occurs:
+
+
+* The message is sent without error
+
+* The underlying transport reports a *hard* failure
+
+* The maximum number of retry loops has been attempted
+
+
+A retry loop consists of approximately 1000 send attempts
+**without** any intervening calls to *sleep()* or *usleep().*
+The number of retry loops defaults to 1, thus a maximum of
+1000 send attempts is performed before returning to the user
+application. This value can be set at any point after RMR
+initialisation using the *rmr_set_stimeout()* function
+allowing the user application to completely disable retires
+(set to 0), or to increase the number of retry loops.

 
 
 Transport Level Blocking
 ------------------------
 
 
 
 Transport Level Blocking
 ------------------------
 

-The underlying transport mechanism used to send messages is 
-configured in *non-blocking* mode. This means that if a 
-message cannot be sent immediately the transport mechanism 
-will **not** pause with the assumption that the inability to 
-send will clear quickly (within a few milliseconds). This 
-means that when the retry loop is completely disabled (set to 
-0), that the failure to accept a message for sending by the 
-underlying mechanisms (software or hardware) will be reported 
-immediately to the user application. 
- 
-It should be noted that depending on the underlying transport 
-mechanism being used, it is extremely likely that retry 
-conditions will happen during normal operations. These are 
-completely out of RMR's control, and there is nothing that 
-RMR can do to avoid or mitigate these other than by allowing 
-RMR to retry the send operation, and even then it is possible 
-(e.g., during connection reattempts), that a single retry 
-loop is not enough to guarantee a successful send. 
+The underlying transport mechanism used to send messages is
+configured in *non-blocking* mode. This means that if a
+message cannot be sent immediately the transport mechanism
+will **not** pause with the assumption that the inability to
+send will clear quickly (within a few milliseconds). This
+means that when the retry loop is completely disabled (set to
+0), that the failure to accept a message for sending by the
+underlying mechanisms (software or hardware) will be reported
+immediately to the user application.
+
+It should be noted that depending on the underlying transport
+mechanism being used, it is extremely likely that retry
+conditions will happen during normal operations. These are
+completely out of RMR's control, and there is nothing that
+RMR can do to avoid or mitigate these other than by allowing
+RMR to retry the send operation, and even then it is possible
+(e.g., during connection reattempts), that a single retry
+loop is not enough to guarantee a successful send.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-The ``rmr_mt_call`` function returns a pointer to a message 
-buffer with the state set to reflect the overall state of 
-call processing. If the state is ``RMR_OK`` then the buffer 
-contains the response message; otherwise the state indicates 
-the error encountered while attempting to send the message. 
- 
-If no response message is received when the timeout period 
-has expired, a nil pointer will be returned (NULL). 
+The ``rmr_mt_call`` function returns a pointer to a message
+buffer with the state set to reflect the overall state of
+call processing. If the state is ``RMR_OK`` then the buffer
+contains the response message; otherwise the state indicates
+the error encountered while attempting to send the message.
+
+If no response message is received when the timeout period
+has expired, a nil pointer will be returned (NULL).

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-These values are reflected in the state field of the returned 
-message. 
- 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **RMR_OK** 
-       - 
-         The call was successful and the message buffer references the 
-         response message. 
-      
-     * - **RMR_ERR_BADARG** 
-       - 
-         An argument passed to the function was invalid. 
-      
-     * - **RMR_ERR_CALLFAILED** 
-       - 
-         The call failed and the value of *errno,* as described below, 
-         should be checked for the specific reason. 
-      
-     * - **RMR_ERR_NOENDPT** 
-       - 
-         An endpoint associated with the message type could not be 
-         found in the route table. 
-      
-     * - **RMR_ERR_RETRY** 
-       - 
-         The underlying transport mechanism was unable to accept the 
-         message for sending. The user application can retry the call 
-         operation if appropriate to do so. 
-          
- 
- 
-The global "variable" *errno* will be set to one of the 
-following values if the overall call processing was not 
-successful. 
- 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **ETIMEDOUT** 
-       - 
-         Too many messages were queued before receiving the expected 
-         response 
-      
-     * - **ENOBUFS** 
-       - 
-         The queued message ring is full, messages were dropped 
-      
-     * - **EINVAL** 
-       - 
-         A parameter was not valid 
-      
-     * - **EAGAIN** 
-       - 
-         The underlying message system wsa interrupted or the device 
-         was busy; the message was **not** sent, and user application 
-         should call this function with the message again. 
-          
- 
+These values are reflected in the state field of the returned
+message.
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMR_OK**
+        -
+          The call was successful and the message buffer references the
+          response message.
+
+      * - **RMR_ERR_BADARG**
+        -
+          An argument passed to the function was invalid.
+
+      * - **RMR_ERR_CALLFAILED**
+        -
+          The call failed and the value of *errno,* as described below,
+          should be checked for the specific reason.
+
+      * - **RMR_ERR_NOENDPT**
+        -
+          An endpoint associated with the message type could not be
+          found in the route table.
+
+      * - **RMR_ERR_RETRY**
+        -
+          The underlying transport mechanism was unable to accept the
+          message for sending. The user application can retry the call
+          operation if appropriate to do so.
+
+
+
+The global "variable" *errno* will be set to one of the
+following values if the overall call processing was not
+successful.
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **ETIMEDOUT**
+        -
+          Too many messages were queued before receiving the expected
+          response
+
+      * - **ENOBUFS**
+        -
+          The queued message ring is full, messages were dropped
+
+      * - **EINVAL**
+        -
+          A parameter was not valid
+
+      * - **EAGAIN**
+        -
+          The underlying message system wsa interrupted or the device
+          was busy; the message was **not** sent, and user application
+          should call this function with the message again.
+
+

 
 
 EXAMPLE
 -------
 
 
 
 EXAMPLE
 -------
 

-The following code bit shows one way of using the 
-``rmr_mt_call`` function, and illustrates how the transaction 
-ID must be set. 
- 
- 
-:: 
- 
-     int retries_left = 5;               // max retries on dev not available
-     static rmr_mbuf_t*  mbuf = NULL;    // response msg
-     msg_t*  pm;                         // appl message struct (payload)
-  
-     // get a send buffer and reference the payload
-     mbuf = rmr_alloc_msg( mr, sizeof( pm->req ) );
-     pm = (msg_t*) mbuf->payload;
-  
-     // generate an xaction ID and fill in payload with data and msg type
-     rmr_bytes2xact( mbuf, xid, RMR_MAX_XID );
-     snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
-     mbuf->mtype = MT_USR_RESP;
-  
-     msg = rmr_mt_call( mr, msg, my_id, 100 );        // wait up to 100ms
-     if( ! msg ) {               // probably a timeout and no msg received
-         return NULL;            // let errno trickle up
-     }
-  
-     if( mbuf->state != RMR_OK ) {
-         while( retries_left-- > 0 &&             // loop as long as eagain
-                mbuf->state == RMR_ERR_RETRY &&
-                (msg = rmr_mt_call( mr, msg )) != NULL &&
-                mbuf->state != RMR_OK ) {
-  
-             usleep( retry_delay );
-         }
-  
-         if( mbuf == NULL || mbuf->state != RMR_OK ) {
-             rmr_free_msg( mbuf );        // safe if nil
-             return NULL;
-         }
-     }
-  
-     // do something with mbuf
- 
+The following code bit shows one way of using the
+``rmr_mt_call`` function, and illustrates how the transaction
+ID must be set.
+
+
+::
+
+      int retries_left = 5;               // max retries on dev not available
+      static rmr_mbuf_t*  mbuf = NULL;    // response msg
+      msg_t*  pm;                         // appl message struct (payload)
+
+      // get a send buffer and reference the payload
+      mbuf = rmr_alloc_msg( mr, sizeof( pm->req ) );
+      pm = (msg_t*) mbuf->payload;
+
+      // generate an xaction ID and fill in payload with data and msg type
+      rmr_bytes2xact( mbuf, xid, RMR_MAX_XID );
+      snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
+      mbuf->mtype = MT_USR_RESP;
+
+      msg = rmr_mt_call( mr, msg, my_id, 100 );        // wait up to 100ms
+      if( ! msg ) {               // probably a timeout and no msg received
+          return NULL;            // let errno trickle up
+      }
+
+      if( mbuf->state != RMR_OK ) {
+          while( retries_left-- > 0 &&             // loop as long as eagain
+                 mbuf->state == RMR_ERR_RETRY &&
+                 (msg = rmr_mt_call( mr, msg )) != NULL &&
+                 mbuf->state != RMR_OK ) {
+
+              usleep( retry_delay );
+          }
+
+          if( mbuf == NULL || mbuf->state != RMR_OK ) {
+              rmr_free_msg( mbuf );        // safe if nil
+              return NULL;
+          }
+      }
+
+      // do something with mbuf
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3), 
-rmr_mt_rcv(3), rmr_payload_size(3), rmr_send_msg(3), 
-rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), 
-rmr_ready(3), rmr_fib(3), rmr_has_str(3), 
-rmr_set_stimeout(3), rmr_tokenise(3), rmr_mk_ring(3), 
-rmr_ring_free(3) 
+rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
+rmr_mt_rcv(3), rmr_payload_size(3), rmr_send_msg(3),
+rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
+rmr_ready(3), rmr_fib(3), rmr_has_str(3),
+rmr_set_stimeout(3), rmr_tokenise(3), rmr_mk_ring(3),
+rmr_ring_free(3)

diff --git a/docs/rmr_mt_rcv.3.rst b/docs/rmr_mt_rcv.3.rst
index d772774..087d417 100644 (file)
--- a/docs/rmr_mt_rcv.3.rst
+++ b/docs/rmr_mt_rcv.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_mt_rcv 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_mt_rcv
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,201 +19,201 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_mt_rcv 
+rmr_mt_rcv

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout );
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout );
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_mt_rcv`` function blocks until a message is 
-received, or the timeout period (milliseconds) has passed. 
-The result is an RMR message buffer which references a 
-received message. In the case of a timeout the state will be 
-reflected in an "empty buffer" (if old_msg was not nil, or 
-simply with the return of a nil pointer. If a timeout value 
-of zero (0) is given, then the function will block until the 
-next message received. 
- 
-The *vctx* pointer is the pointer returned by the 
-``rmr_init`` function. *Old_msg* is a pointer to a previously 
-used message buffer or NULL. The ability to reuse message 
-buffers helps to avoid alloc/free cycles in the user 
-application. When no buffer is available to supply, the 
-receive function will allocate one. 
- 
-The *old_msg* parameter allows the user to pass a previously 
-generated RMR message back to RMR for reuse. Optionally, the 
-user application may pass a nil pointer if no reusable 
-message is available. When a timeout occurs, and old_msg was 
-not nil, the state will be returned by returning a pointer to 
-the old message with the state set. 
- 
-It is possible to use the *rmr_rcv_msg()* function instead of 
-this function. Doing so might be advantageous if the user 
-programme does not always start the multi-threaded mode and 
-the use of *rmr_rcv_msg()* would make the flow of the code 
-more simple. The advantages of using this function are the 
-ability to set a timeout without using epoll, and a small 
-performance gain (if multi-threaded mode is enabled, and the 
-*rmr_rcv_msg()* function is used, it simply invokes this 
-function without a timeout value, thus there is the small 
-cost of a second call that results). Similarly, the 
-*rmr_torcv_msg()* call can be used when in multi-threaded 
-mode with the same "pass through" overhead to using this 
-function directly. 
+The ``rmr_mt_rcv`` function blocks until a message is
+received, or the timeout period (milliseconds) has passed.
+The result is an RMR message buffer which references a
+received message. In the case of a timeout the state will be
+reflected in an "empty buffer" (if old_msg was not nil, or
+simply with the return of a nil pointer. If a timeout value
+of zero (0) is given, then the function will block until the
+next message received.
+
+The *vctx* pointer is the pointer returned by the
+``rmr_init`` function. *Old_msg* is a pointer to a previously
+used message buffer or NULL. The ability to reuse message
+buffers helps to avoid alloc/free cycles in the user
+application. When no buffer is available to supply, the
+receive function will allocate one.
+
+The *old_msg* parameter allows the user to pass a previously
+generated RMR message back to RMR for reuse. Optionally, the
+user application may pass a nil pointer if no reusable
+message is available. When a timeout occurs, and old_msg was
+not nil, the state will be returned by returning a pointer to
+the old message with the state set.
+
+It is possible to use the *rmr_rcv_msg()* function instead of
+this function. Doing so might be advantageous if the user
+programme does not always start the multi-threaded mode and
+the use of *rmr_rcv_msg()* would make the flow of the code
+more simple. The advantages of using this function are the
+ability to set a timeout without using epoll, and a small
+performance gain (if multi-threaded mode is enabled, and the
+*rmr_rcv_msg()* function is used, it simply invokes this
+function without a timeout value, thus there is the small
+cost of a second call that results). Similarly, the
+*rmr_torcv_msg()* call can be used when in multi-threaded
+mode with the same "pass through" overhead to using this
+function directly.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-When a message is received before the timeout period expires, 
-a pointer to the RMR message buffer which describes the 
-message is returned. This will, with a high probability, be a 
-different message buffer than *old_msg;* the user application 
-should not continue to use *old_msg* after it is passed to 
-this function. 
- 
-In the event of a timeout the return value will be the old 
-msg with the state set, or a nil pointer if no old message 
-was provided. 
+When a message is received before the timeout period expires,
+a pointer to the RMR message buffer which describes the
+message is returned. This will, with a high probability, be a
+different message buffer than *old_msg;* the user application
+should not continue to use *old_msg* after it is passed to
+this function.
+
+In the event of a timeout the return value will be the old
+msg with the state set, or a nil pointer if no old message
+was provided.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-The *state* field in the message buffer will be set to one of 
-the following values: 
- 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **RMR_OK** 
-       - 
-         The message was received without error. 
-      
-     * - **RMR_ERR_BADARG** 
-       - 
-         A parameter passed to the function was not valid (e.g. a nil 
-         pointer). indicate either ``RMR_OK`` or ``RMR_ERR_EMPTY`` if 
-         an empty message was received. 
-      
-     * - **RMR_ERR_EMPTY** 
-       - 
-         The message received had no associated data. The length of 
-         the message will be 0. 
-      
-     * - **RMR_ERR_NOTSUPP** 
-       - 
-         The multi-threaded option was not enabled when RMR was 
-         initialised. See the man page for *rmr_init()* for details. 
-      
-     * - **RMR_ERR_RCVFAILED** 
-       - 
-         A hard error occurred preventing the receive from completing. 
-          
- 
-When a nil pointer is returned, or any other state value was 
-set in the message buffer, ``errno`` will be set to one of 
-the following: 
- 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **INVAL** 
-       - 
-         Parameter(s) passed to the function were not valid. 
-      
-     * - **EBADF** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-      
-     * - **ENOTSUP** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-      
-     * - **EFSM** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-      
-     * - **EAGAIN** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-      
-     * - **EINTR** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-      
-     * - **ETIMEDOUT** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-      
-     * - **ETERM** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-          
- 
+The *state* field in the message buffer will be set to one of
+the following values:
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMR_OK**
+        -
+          The message was received without error.
+
+      * - **RMR_ERR_BADARG**
+        -
+          A parameter passed to the function was not valid (e.g. a nil
+          pointer). indicate either ``RMR_OK`` or ``RMR_ERR_EMPTY`` if
+          an empty message was received.
+
+      * - **RMR_ERR_EMPTY**
+        -
+          The message received had no associated data. The length of
+          the message will be 0.
+
+      * - **RMR_ERR_NOTSUPP**
+        -
+          The multi-threaded option was not enabled when RMR was
+          initialised. See the man page for *rmr_init()* for details.
+
+      * - **RMR_ERR_RCVFAILED**
+        -
+          A hard error occurred preventing the receive from completing.
+
+
+When a nil pointer is returned, or any other state value was
+set in the message buffer, ``errno`` will be set to one of
+the following:
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **INVAL**
+        -
+          Parameter(s) passed to the function were not valid.
+
+      * - **EBADF**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+      * - **ENOTSUP**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+      * - **EFSM**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+      * - **EAGAIN**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+      * - **EINTR**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+      * - **ETIMEDOUT**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+      * - **ETERM**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+

 
 
 EXAMPLE
 -------
 
 
 
 EXAMPLE
 -------
 

- 
- 
-:: 
- 
-     rmr_mbuf_t*  mbuf = NULL;   // received msg
-  
-     msg = rmr_mt_recv( mr, mbuf, 100 );     // wait up to 100ms
-     if( msg != NULL ) {
-         switch( msg->state ) {
-             case RMR_OK:
-                 printf( "got a good message\\n" );
-                 break;
-  
-             case RMR_ERR_EMPTY:
-                 printf( "received timed out\\n" );
-                 break;
-  
-             default:
-                 printf( "receive error: %d\\n", mbuf->state );
-                 break;
-         }
-     } else {
-         printf( "receive timeout (nil)\\n" );
-     }
- 
+
+
+::
+
+      rmr_mbuf_t*  mbuf = NULL;   // received msg
+
+      msg = rmr_mt_recv( mr, mbuf, 100 );     // wait up to 100ms
+      if( msg != NULL ) {
+          switch( msg->state ) {
+              case RMR_OK:
+                  printf( "got a good message\\n" );
+                  break;
+
+              case RMR_ERR_EMPTY:
+                  printf( "received timed out\\n" );
+                  break;
+
+              default:
+                  printf( "receive error: %d\\n", mbuf->state );
+                  break;
+          }
+      } else {
+          printf( "receive timeout (nil)\\n" );
+      }
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), 
-rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3), 
-rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3), 
-rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), 
-rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3) 
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
+rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
+rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3),
+rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
+rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3)

diff --git a/docs/rmr_payload_size.3.rst b/docs/rmr_payload_size.3.rst
index 58b674f..a0c4bd3 100644 (file)
--- a/docs/rmr_payload_size.3.rst
+++ b/docs/rmr_payload_size.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_payload_size 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_payload_size
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,56 +19,56 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_payload_size 
+rmr_payload_size

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- int rmr_payload_size( rmr_mbuf_t* msg );
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  int rmr_payload_size( rmr_mbuf_t* msg );
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-Given a message buffer, this function returns the amount of 
-space (bytes) available for the user application to consume 
-in the message payload. This is different than the message 
-length available as a field in the message buffer. 
+Given a message buffer, this function returns the amount of
+space (bytes) available for the user application to consume
+in the message payload. This is different than the message
+length available as a field in the message buffer.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-The number of bytes available in the payload. 
+The number of bytes available in the payload.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **INVAL** 
-       - 
-         Parameter(s) passed to the function were not valid. 
-          
- 
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **INVAL**
+        -
+          Parameter(s) passed to the function were not valid.
+
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), 
-rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3), 
-rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), 
-rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3) 
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
+rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
+rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
+rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)

diff --git a/docs/rmr_rcv_msg.3.rst b/docs/rmr_rcv_msg.3.rst
index aa7f2fd..9faa3a3 100644 (file)
--- a/docs/rmr_rcv_msg.3.rst
+++ b/docs/rmr_rcv_msg.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_rcv_msg 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_rcv_msg
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,135 +19,135 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_rcv_msg 
+rmr_rcv_msg

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_rcv_msg`` function blocks until a message is 
-received, returning the message to the caller via a pointer 
-to a ``rmr_mbuf_t`` structure type. If messages were queued 
-while waiting for the response to a previous invocation of 
-``rmr_call,`` the oldest message is removed from the queue 
-and returned without delay. 
- 
-The *vctx* pointer is the pointer returned by the 
-``rmr_init`` function. *Old_msg* is a pointer to a previously 
-used message buffer or NULL. The ability to reuse message 
-buffers helps to avoid alloc/free cycles in the user 
-application. When no buffer is available to supply, the 
-receive function will allocate one. 
+The ``rmr_rcv_msg`` function blocks until a message is
+received, returning the message to the caller via a pointer
+to a ``rmr_mbuf_t`` structure type. If messages were queued
+while waiting for the response to a previous invocation of
+``rmr_call,`` the oldest message is removed from the queue
+and returned without delay.
+
+The *vctx* pointer is the pointer returned by the
+``rmr_init`` function. *Old_msg* is a pointer to a previously
+used message buffer or NULL. The ability to reuse message
+buffers helps to avoid alloc/free cycles in the user
+application. When no buffer is available to supply, the
+receive function will allocate one.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-The function returns a pointer to the ``rmr_mbuf_t`` 
-structure which references the message information (state, 
-length, payload), or a nil pointer in the case of an extreme 
-error. 
+The function returns a pointer to the ``rmr_mbuf_t``
+structure which references the message information (state,
+length, payload), or a nil pointer in the case of an extreme
+error.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-The *state* field in the message buffer will indicate 
-``RMR_OK`` when the message receive process was successful 
-and the message can be used by the caller. Depending on the 
-underlying transport mechanism, one of the following RMR 
-error stats may be returned: 
- 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **RMR_ERR_EMPTY** 
-       - 
-         The message received had no payload, or was completely empty. 
-          
-      
-     * - **RMR_ERR_TIMEOUT** 
-       - 
-         For some transport mechanisms, or if reading the receive 
-         queue from multiple threads, it is possible for one thread to 
-         find no data waiting when it queries the queue. When this 
-         state is reported, the message buffer does not contain 
-         message data and the user application should reinvoke the 
-         receive function. 
-          
- 
- 
-When an RMR error state is reported, the underlying 
-``errno`` value might provide more information. The following 
-is a list of possible values that might accompany the states 
-listed above: 
- 
-``RMR_ERR_EMPTY`` if an empty message was received. If a nil 
-pointer is returned, or any other state value was set in the 
-message buffer, ``errno`` will be set to one of the 
-following: 
- 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **INVAL** 
-       - 
-         Parameter(s) passed to the function were not valid. 
-      
-     * - **EBADF** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-      
-     * - **ENOTSUP** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-      
-     * - **EFSM** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-      
-     * - **EAGAIN** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-      
-     * - **EINTR** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-      
-     * - **ETIMEDOUT** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-      
-     * - **ETERM** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-          
- 
+The *state* field in the message buffer will indicate
+``RMR_OK`` when the message receive process was successful
+and the message can be used by the caller. Depending on the
+underlying transport mechanism, one of the following RMR
+error stats may be returned:
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMR_ERR_EMPTY**
+        -
+          The message received had no payload, or was completely empty.
+
+
+      * - **RMR_ERR_TIMEOUT**
+        -
+          For some transport mechanisms, or if reading the receive
+          queue from multiple threads, it is possible for one thread to
+          find no data waiting when it queries the queue. When this
+          state is reported, the message buffer does not contain
+          message data and the user application should reinvoke the
+          receive function.
+
+
+
+When an RMR error state is reported, the underlying
+``errno`` value might provide more information. The following
+is a list of possible values that might accompany the states
+listed above:
+
+``RMR_ERR_EMPTY`` if an empty message was received. If a nil
+pointer is returned, or any other state value was set in the
+message buffer, ``errno`` will be set to one of the
+following:
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **INVAL**
+        -
+          Parameter(s) passed to the function were not valid.
+
+      * - **EBADF**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+      * - **ENOTSUP**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+      * - **EFSM**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+      * - **EAGAIN**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+      * - **EINTR**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+      * - **ETIMEDOUT**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+      * - **ETERM**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+

 
 
 EXAMPLE
 
 
 EXAMPLE


@@ -158,8 +158,8 @@ EXAMPLE
 SEE ALSO
 --------
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), 
-rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3), 
-rmr_payload_size(3), rmr_send_msg(3), rmr_torcv_msg(3), 
-rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), 
-rmr_ring_free(3), rmr_torcv_msg(3) 
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
+rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
+rmr_payload_size(3), rmr_send_msg(3), rmr_torcv_msg(3),
+rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
+rmr_ring_free(3), rmr_torcv_msg(3)

diff --git a/docs/rmr_ready.3.rst b/docs/rmr_ready.3.rst
index e7843b4..b6b8b0f 100644 (file)
--- a/docs/rmr_ready.3.rst
+++ b/docs/rmr_ready.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_ready 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_ready
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,44 +19,44 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_ready 
+rmr_ready

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- int rmr_ready( void* vctx );
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  int rmr_ready( void* vctx );
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_ready`` function checks to see if a routing table 
-has been successfully received and installed. The return 
-value indicates the state of readiness. 
+The ``rmr_ready`` function checks to see if a routing table
+has been successfully received and installed. The return
+value indicates the state of readiness.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-A return value of 1 (true) indicates that the routing table 
-is in place and attempts to send messages can be made. When 0 
-is returned (false) the routing table has not been received 
-and thus attempts to send messages will fail with *no 
-endpoint* errors. 
+A return value of 1 (true) indicates that the routing table
+is in place and attempts to send messages can be made. When 0
+is returned (false) the routing table has not been received
+and thus attempts to send messages will fail with *no
+endpoint* errors.

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), 
-rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), 
-rmr_rcv_specific(3), rmr_rts_msg(3), rmr_fib(3), 
-rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), 
-rmr_ring_free(3) 
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
+rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
+rmr_rcv_specific(3), rmr_rts_msg(3), rmr_fib(3),
+rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
+rmr_ring_free(3)

diff --git a/docs/rmr_realloc_payload.3.rst b/docs/rmr_realloc_payload.3.rst
index 3d5f013..9397017 100644 (file)
--- a/docs/rmr_realloc_payload.3.rst
+++ b/docs/rmr_realloc_payload.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_realloc_payload 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_realloc_payload
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,126 +19,126 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_realloc_payload 
+rmr_realloc_payload

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* msg, int new_len, int copy, int clone );
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* msg, int new_len, int copy, int clone );
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_realloc_payload`` function will return a pointer to 
-an RMR message buffer struct (rmr_mbuf_t) which has a payload 
-large enough to accomodate *new_len* bytes. If necessary, the 
-underlying payload is reallocated, and the bytes from the 
-original payload are copied if the *copy* parameter is true 
-(1). If the message passed in has a payload large enough, 
-there is no additional memory allocation and copying. 
+The ``rmr_realloc_payload`` function will return a pointer to
+an RMR message buffer struct (rmr_mbuf_t) which has a payload
+large enough to accomodate *new_len* bytes. If necessary, the
+underlying payload is reallocated, and the bytes from the
+original payload are copied if the *copy* parameter is true
+(1). If the message passed in has a payload large enough,
+there is no additional memory allocation and copying.

 
 
 Cloning The Message Buffer
 --------------------------
 
 
 
 Cloning The Message Buffer
 --------------------------
 

-This function can also be used to generate a separate copy of 
-the original message, with the desired payload size, without 
-destroying the original message buffer or the original 
-payload. A standalone copy is made only when the *clone* 
-parameter is true (1). When cloning, the payload is copied to 
-the cloned message **only** if the *copy* parameter is true. 
+This function can also be used to generate a separate copy of
+the original message, with the desired payload size, without
+destroying the original message buffer or the original
+payload. A standalone copy is made only when the *clone*
+parameter is true (1). When cloning, the payload is copied to
+the cloned message **only** if the *copy* parameter is true.

 
 
 Message Buffer Metadata
 -----------------------
 
 
 
 Message Buffer Metadata
 -----------------------
 

-The metadata in the original message buffer (message type, 
-subscription ID, and payload length) will be preserved if the 
-*copy* parameter is true. When this parameter is not true 
-(0), then these values are set to the uninitialised value 
-(-1) for type and ID, and the length is set to 0. 
+The metadata in the original message buffer (message type,
+subscription ID, and payload length) will be preserved if the
+*copy* parameter is true. When this parameter is not true
+(0), then these values are set to the uninitialised value
+(-1) for type and ID, and the length is set to 0.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-The ``rmr_realloc_payload`` function returns a pointer to the 
-message buffer with the payload which is large enough to hold 
-*new_len* bytes. If the *clone* option is true, this will be 
-a pointer to the newly cloned message buffer; the original 
-message buffer pointer may still be used to reference that 
-message. It is the calling application's responsibility to 
-free the memory associateed with both messages using the 
-rmr_free_msg() function. 
- 
-When the *clone* option is not used, it is still good 
-practice by the calling application to capture and use this 
-reference as it is possible that the message buffer, and not 
-just the payload buffer, was reallocated. In the event of an 
-error, a nil pointer will be returned and the value of 
-*errno* will be set to reflect the problem. 
+The ``rmr_realloc_payload`` function returns a pointer to the
+message buffer with the payload which is large enough to hold
+*new_len* bytes. If the *clone* option is true, this will be
+a pointer to the newly cloned message buffer; the original
+message buffer pointer may still be used to reference that
+message. It is the calling application's responsibility to
+free the memory associateed with both messages using the
+rmr_free_msg() function.
+
+When the *clone* option is not used, it is still good
+practice by the calling application to capture and use this
+reference as it is possible that the message buffer, and not
+just the payload buffer, was reallocated. In the event of an
+error, a nil pointer will be returned and the value of
+*errno* will be set to reflect the problem.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-These value of *errno* will reflect the error condition if a 
-nil pointer is returned: 
- 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **ENOMEM** 
-       - 
-         Memory allocation of the new payload failed. 
-      
-     * - **EINVAL** 
-       - 
-         The pointer passed in was nil, or referenced an invalid 
-         message, or the required length was not valid. 
-          
- 
+These value of *errno* will reflect the error condition if a
+nil pointer is returned:
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **ENOMEM**
+        -
+          Memory allocation of the new payload failed.
+
+      * - **EINVAL**
+        -
+          The pointer passed in was nil, or referenced an invalid
+          message, or the required length was not valid.
+
+

 
 
 EXAMPLE
 -------
 
 
 
 EXAMPLE
 -------
 

-The following code bit illustrates how this function can be 
-used to reallocate a buffer for a return to sender 
-acknowledgement message which is larger than the message 
-received. 
- 
- 
-:: 
- 
-   if( rmr_payload_size( msg ) < ack_sz ) {              // received message too small for ack
-     msg = rmr_realloc_payload( msg, ack_sz, 0, 0 );     // reallocate the message with a payload big enough
-     if( msg == NULL ) {
-       fprintf( stderr, "[ERR] realloc returned a nil pointer: %s\\n", strerror( errno ) );
-     } else {
-       // populate and send ack message
-     }
- }
-  
- 
+The following code bit illustrates how this function can be
+used to reallocate a buffer for a return to sender
+acknowledgement message which is larger than the message
+received.
+
+
+::
+
+    if( rmr_payload_size( msg ) < ack_sz ) {              // received message too small for ack
+      msg = rmr_realloc_payload( msg, ack_sz, 0, 0 );     // reallocate the message with a payload big enough
+      if( msg == NULL ) {
+        fprintf( stderr, "[ERR] realloc returned a nil pointer: %s\\n", strerror( errno ) );
+      } else {
+        // populate and send ack message
+      }
+  }
+
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3), 
-rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), 
-rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), 
-rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3), 
-rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3) 
+rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
+rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
+rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
+rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3),
+rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)

diff --git a/docs/rmr_rts_msg.3.rst b/docs/rmr_rts_msg.3.rst
index b0637cc..1ebbd84 100644 (file)
--- a/docs/rmr_rts_msg.3.rst
+++ b/docs/rmr_rts_msg.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_rts_msg 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_rts_msg
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,213 +19,213 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_rts_msg 
+rmr_rts_msg

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- rmr_mbuf_t*  rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  rmr_mbuf_t*  rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_rts_msg`` function sends a message returning it to 
-the endpoint which sent the message rather than selecting an 
-endpoint based on the message type and routing table. Other 
-than this small difference, the behaviour is exactly the same 
-as ``rmr_send_msg.`` 
+The ``rmr_rts_msg`` function sends a message returning it to
+the endpoint which sent the message rather than selecting an
+endpoint based on the message type and routing table. Other
+than this small difference, the behaviour is exactly the same
+as ``rmr_send_msg.``

 
 
 Retries
 -------
 
 
 
 Retries
 -------
 

-The send operations in RMR will retry *soft* send failures 
-until one of three conditions occurs: 
- 
- 
-* The message is sent without error 
-  
-* The underlying transport reports a *hard* failure 
-  
-* The maximum number of retry loops has been attempted 
- 
- 
-A retry loop consists of approximately 1000 send attempts 
-**without** any intervening calls to *sleep()* or *usleep().* 
-The number of retry loops defaults to 1, thus a maximum of 
-1000 send attempts is performed before returning to the user 
-application. This value can be set at any point after RMR 
-initialisation using the *rmr_set_stimeout()* function 
-allowing the user application to completely disable retires 
-(set to 0), or to increase the number of retry loops. 
+The send operations in RMR will retry *soft* send failures
+until one of three conditions occurs:
+
+
+* The message is sent without error
+
+* The underlying transport reports a *hard* failure
+
+* The maximum number of retry loops has been attempted
+
+
+A retry loop consists of approximately 1000 send attempts
+**without** any intervening calls to *sleep()* or *usleep().*
+The number of retry loops defaults to 1, thus a maximum of
+1000 send attempts is performed before returning to the user
+application. This value can be set at any point after RMR
+initialisation using the *rmr_set_stimeout()* function
+allowing the user application to completely disable retires
+(set to 0), or to increase the number of retry loops.

 
 
 Transport Level Blocking
 ------------------------
 
 
 
 Transport Level Blocking
 ------------------------
 

-The underlying transport mechanism used to send messages is 
-configured in *non-blocking* mode. This means that if a 
-message cannot be sent immediately the transport mechanism 
-will **not** pause with the assumption that the inability to 
-send will clear quickly (within a few milliseconds). This 
-means that when the retry loop is completely disabled (set to 
-0), that the failure to accept a message for sending by the 
-underlying mechanisms (software or hardware) will be reported 
-immediately to the user application. 
- 
-It should be noted that depending on the underlying transport 
-mechanism being used, it is extremely likely that retry 
-conditions will happen during normal operations. These are 
-completely out of RMR's control, and there is nothing that 
-RMR can do to avoid or mitigate these other than by allowing 
-RMR to retry the send operation, and even then it is possible 
-(e.g., during connection reattempts), that a single retry 
-loop is not enough to guarantee a successful send. 
+The underlying transport mechanism used to send messages is
+configured in *non-blocking* mode. This means that if a
+message cannot be sent immediately the transport mechanism
+will **not** pause with the assumption that the inability to
+send will clear quickly (within a few milliseconds). This
+means that when the retry loop is completely disabled (set to
+0), that the failure to accept a message for sending by the
+underlying mechanisms (software or hardware) will be reported
+immediately to the user application.
+
+It should be noted that depending on the underlying transport
+mechanism being used, it is extremely likely that retry
+conditions will happen during normal operations. These are
+completely out of RMR's control, and there is nothing that
+RMR can do to avoid or mitigate these other than by allowing
+RMR to retry the send operation, and even then it is possible
+(e.g., during connection reattempts), that a single retry
+loop is not enough to guarantee a successful send.

 
 
 PAYLOAD SIZE
 ------------
 
 
 
 PAYLOAD SIZE
 ------------
 

-When crafting a response based on a received message, the 
-user application must take care not to write more bytes to 
-the message payload than the allocated message has. In the 
-case of a received message, it is possible that the response 
-needs to be larger than the payload associated with the 
-inbound message. In order to use the return to sender 
-function, the source information in the original message must 
-be present in the response; information which cannot be added 
-to a message buffer allocated through the standard RMR 
-allocation function. To allocate a buffer with a larger 
-payload, and which retains the necessary sender data needed 
-by this function, the *rmr_realloc_payload()* function must 
-be used to extend the payload to a size suitable for the 
-response. 
+When crafting a response based on a received message, the
+user application must take care not to write more bytes to
+the message payload than the allocated message has. In the
+case of a received message, it is possible that the response
+needs to be larger than the payload associated with the
+inbound message. In order to use the return to sender
+function, the source information in the original message must
+be present in the response; information which cannot be added
+to a message buffer allocated through the standard RMR
+allocation function. To allocate a buffer with a larger
+payload, and which retains the necessary sender data needed
+by this function, the *rmr_realloc_payload()* function must
+be used to extend the payload to a size suitable for the
+response.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-On success, a new message buffer, with an empty payload, is 
-returned for the application to use for the next send. The 
-state in this buffer will reflect the overall send operation 
-state and should be ``RMR_OK.`` 
- 
-If the state in the returned buffer is anything other than 
-``RMR_OK,`` the user application may need to attempt a 
-retransmission of the message, or take other action depending 
-on the setting of ``errno`` as described below. 
- 
-In the event of extreme failure, a nil pointer is returned. 
-In this case the value of ``errno`` might be of some use, for 
-documentation, but there will be little that the user 
-application can do other than to move on. 
+On success, a new message buffer, with an empty payload, is
+returned for the application to use for the next send. The
+state in this buffer will reflect the overall send operation
+state and should be ``RMR_OK.``
+
+If the state in the returned buffer is anything other than
+``RMR_OK,`` the user application may need to attempt a
+retransmission of the message, or take other action depending
+on the setting of ``errno`` as described below.
+
+In the event of extreme failure, a nil pointer is returned.
+In this case the value of ``errno`` might be of some use, for
+documentation, but there will be little that the user
+application can do other than to move on.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-The following values may be passed back in the *state* field 
-of the returned message buffer. 
- 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **RMR_ERR_BADARG** 
-       - 
-         The message buffer pointer did not refer to a valid message. 
-      
-     * - **RMR_ERR_NOHDR** 
-       - 
-         The header in the message buffer was not valid or corrupted. 
-      
-     * - **RMR_ERR_NOENDPT** 
-       - 
-         The message type in the message buffer did not map to a known 
-         endpoint. 
-      
-     * - **RMR_ERR_SENDFAILED** 
-       - 
-         The send failed; ``errno`` has the possible reason. 
-          
- 
- 
-The following values may be assigned to ``errno`` on failure. 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **INVAL** 
-       - 
-         Parameter(s) passed to the function were not valid, or the 
-         underlying message processing environment was unable to 
-         interpret the message. 
-      
-     * - **ENOKEY** 
-       - 
-         The header information in the message buffer was invalid. 
-      
-     * - **ENXIO** 
-       - 
-         No known endpoint for the message could be found. 
-      
-     * - **EMSGSIZE** 
-       - 
-         The underlying transport refused to accept the message 
-         because of a size value issue (message was not attempted to 
-         be sent). 
-      
-     * - **EFAULT** 
-       - 
-         The message referenced by the message buffer is corrupt (nil 
-         pointer or bad internal length). 
-      
-     * - **EBADF** 
-       - 
-         Internal RMR error; information provided to the message 
-         transport environment was not valid. 
-      
-     * - **ENOTSUP** 
-       - 
-         Sending was not supported by the underlying message 
-         transport. 
-      
-     * - **EFSM** 
-       - 
-         The device is not in a state that can accept the message. 
-      
-     * - **EAGAIN** 
-       - 
-         The device is not able to accept a message for sending. The 
-         user application should attempt to resend. 
-      
-     * - **EINTR** 
-       - 
-         The operation was interrupted by delivery of a signal before 
-         the message was sent. 
-      
-     * - **ETIMEDOUT** 
-       - 
-         The underlying message environment timed out during the send 
-         process. 
-      
-     * - **ETERM** 
-       - 
-         The underlying message environment is in a shutdown state. 
-          
- 
+The following values may be passed back in the *state* field
+of the returned message buffer.
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMR_ERR_BADARG**
+        -
+          The message buffer pointer did not refer to a valid message.
+
+      * - **RMR_ERR_NOHDR**
+        -
+          The header in the message buffer was not valid or corrupted.
+
+      * - **RMR_ERR_NOENDPT**
+        -
+          The message type in the message buffer did not map to a known
+          endpoint.
+
+      * - **RMR_ERR_SENDFAILED**
+        -
+          The send failed; ``errno`` has the possible reason.
+
+
+
+The following values may be assigned to ``errno`` on failure.
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **INVAL**
+        -
+          Parameter(s) passed to the function were not valid, or the
+          underlying message processing environment was unable to
+          interpret the message.
+
+      * - **ENOKEY**
+        -
+          The header information in the message buffer was invalid.
+
+      * - **ENXIO**
+        -
+          No known endpoint for the message could be found.
+
+      * - **EMSGSIZE**
+        -
+          The underlying transport refused to accept the message
+          because of a size value issue (message was not attempted to
+          be sent).
+
+      * - **EFAULT**
+        -
+          The message referenced by the message buffer is corrupt (nil
+          pointer or bad internal length).
+
+      * - **EBADF**
+        -
+          Internal RMR error; information provided to the message
+          transport environment was not valid.
+
+      * - **ENOTSUP**
+        -
+          Sending was not supported by the underlying message
+          transport.
+
+      * - **EFSM**
+        -
+          The device is not in a state that can accept the message.
+
+      * - **EAGAIN**
+        -
+          The device is not able to accept a message for sending. The
+          user application should attempt to resend.
+
+      * - **EINTR**
+        -
+          The operation was interrupted by delivery of a signal before
+          the message was sent.
+
+      * - **ETIMEDOUT**
+        -
+          The underlying message environment timed out during the send
+          process.
+
+      * - **ETERM**
+        -
+          The underlying message environment is in a shutdown state.
+
+

 
 
 EXAMPLE
 
 
 EXAMPLE


@@ -236,8 +236,8 @@ EXAMPLE
 SEE ALSO
 --------
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), 
-rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), 
-rmr_rcv_specific(3), rmr_ready(3), rmr_fib(3), 
-rmr_has_str(3), rmr_set_stimeout(3), rmr_tokenise(3), 
-rmr_mk_ring(3), rmr_ring_free(3) 
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
+rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
+rmr_rcv_specific(3), rmr_ready(3), rmr_fib(3),
+rmr_has_str(3), rmr_set_stimeout(3), rmr_tokenise(3),
+rmr_mk_ring(3), rmr_ring_free(3)

diff --git a/docs/rmr_send_msg.3.rst b/docs/rmr_send_msg.3.rst
index 33fd9cf..9d214fe 100644 (file)
--- a/docs/rmr_send_msg.3.rst
+++ b/docs/rmr_send_msg.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_send_msg 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_send_msg
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,263 +19,263 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_send_msg 
+rmr_send_msg

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg );
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg );
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_send_msg`` function accepts a message buffer from 
-the user application and attempts to send it. The destination 
-of the message is selected based on the message type 
-specified in the message buffer, and the matching information 
-in the routing tables which are currently in use by the RMR 
-library. This may actually result in the sending of the 
-message to multiple destinations which could degrade expected 
-overall performance of the user application. (Limiting 
-excessive sending of messages is the responsibility of the 
-application(s) responsible for building the routing table 
-used by the RMR library, and not the responsibility of the 
-library.) 
+The ``rmr_send_msg`` function accepts a message buffer from
+the user application and attempts to send it. The destination
+of the message is selected based on the message type
+specified in the message buffer, and the matching information
+in the routing tables which are currently in use by the RMR
+library. This may actually result in the sending of the
+message to multiple destinations which could degrade expected
+overall performance of the user application. (Limiting
+excessive sending of messages is the responsibility of the
+application(s) responsible for building the routing table
+used by the RMR library, and not the responsibility of the
+library.)

 
 
 Retries
 -------
 
 
 
 Retries
 -------
 

-The send operations in RMR will retry *soft* send failures 
-until one of three conditions occurs: 
- 
- 
-* The message is sent without error 
-  
-* The underlying transport reports a *hard* failure 
-  
-* The maximum number of retry loops has been attempted 
- 
- 
-A retry loop consists of approximately 1000 send attempts 
-**without** any intervening calls to *sleep()* or *usleep().* 
-The number of retry loops defaults to 1, thus a maximum of 
-1000 send attempts is performed before returning to the user 
-application. This value can be set at any point after RMR 
-initialisation using the *rmr_set_stimeout()* function 
-allowing the user application to completely disable retires 
-(set to 0), or to increase the number of retry loops. 
+The send operations in RMR will retry *soft* send failures
+until one of three conditions occurs:
+
+
+* The message is sent without error
+
+* The underlying transport reports a *hard* failure
+
+* The maximum number of retry loops has been attempted
+
+
+A retry loop consists of approximately 1000 send attempts
+**without** any intervening calls to *sleep()* or *usleep().*
+The number of retry loops defaults to 1, thus a maximum of
+1000 send attempts is performed before returning to the user
+application. This value can be set at any point after RMR
+initialisation using the *rmr_set_stimeout()* function
+allowing the user application to completely disable retires
+(set to 0), or to increase the number of retry loops.

 
 
 Transport Level Blocking
 ------------------------
 
 
 
 Transport Level Blocking
 ------------------------
 

-The underlying transport mechanism used to send messages is 
-configured in *non-blocking* mode. This means that if a 
-message cannot be sent immediately the transport mechanism 
-will **not** pause with the assumption that the inability to 
-send will clear quickly (within a few milliseconds). This 
-means that when the retry loop is completely disabled (set to 
-0), that the failure to accept a message for sending by the 
-underlying mechanisms (software or hardware) will be reported 
-immediately to the user application. 
- 
-It should be noted that depending on the underlying transport 
-mechanism being used, it is extremely likely that retry 
-conditions will happen during normal operations. These are 
-completely out of RMR's control, and there is nothing that 
-RMR can do to avoid or mitigate these other than by allowing 
-RMR to retry the send operation, and even then it is possible 
-(e.g., during connection reattempts), that a single retry 
-loop is not enough to guarantee a successful send. 
+The underlying transport mechanism used to send messages is
+configured in *non-blocking* mode. This means that if a
+message cannot be sent immediately the transport mechanism
+will **not** pause with the assumption that the inability to
+send will clear quickly (within a few milliseconds). This
+means that when the retry loop is completely disabled (set to
+0), that the failure to accept a message for sending by the
+underlying mechanisms (software or hardware) will be reported
+immediately to the user application.
+
+It should be noted that depending on the underlying transport
+mechanism being used, it is extremely likely that retry
+conditions will happen during normal operations. These are
+completely out of RMR's control, and there is nothing that
+RMR can do to avoid or mitigate these other than by allowing
+RMR to retry the send operation, and even then it is possible
+(e.g., during connection reattempts), that a single retry
+loop is not enough to guarantee a successful send.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-On success, a new message buffer, with an empty payload, is 
-returned for the application to use for the next send. The 
-state in this buffer will reflect the overall send operation 
-state and will be ``RMR_OK`` when the send was successful. 
- 
-When the message cannot be successfully sent this function 
-will return the unsent (original) message buffer with the 
-state set to indicate the reason for failure. The value of 
-*errno* may also be set to reflect a more detailed failure 
-reason if it is known. 
- 
-In the event of extreme failure, a nil pointer is returned. 
-In this case the value of ``errno`` might be of some use, for 
-documentation, but there will be little that the user 
-application can do other than to move on. 
- 
-**CAUTION:** In some cases it is extremely likely that the 
-message returned by the send function does **not** reference 
-the same memory structure. Thus is important for the user 
-programme to capture the new pointer for future use or to be 
-passed to ``rmr_free().`` If you are experiencing either 
-double free errors or segment faults in either 
-``rmr_free()`` or ``rmr_send_msg(),`` ensure that the return 
-value from this function is being captured and used. 
+On success, a new message buffer, with an empty payload, is
+returned for the application to use for the next send. The
+state in this buffer will reflect the overall send operation
+state and will be ``RMR_OK`` when the send was successful.
+
+When the message cannot be successfully sent this function
+will return the unsent (original) message buffer with the
+state set to indicate the reason for failure. The value of
+*errno* may also be set to reflect a more detailed failure
+reason if it is known.
+
+In the event of extreme failure, a nil pointer is returned.
+In this case the value of ``errno`` might be of some use, for
+documentation, but there will be little that the user
+application can do other than to move on.
+
+**CAUTION:** In some cases it is extremely likely that the
+message returned by the send function does **not** reference
+the same memory structure. Thus is important for the user
+programme to capture the new pointer for future use or to be
+passed to ``rmr_free().`` If you are experiencing either
+double free errors or segment faults in either
+``rmr_free()`` or ``rmr_send_msg(),`` ensure that the return
+value from this function is being captured and used.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-The following values may be passed back in the *state* field 
-of the returned message buffer. 
- 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **RMR_RETRY** 
-       - 
-         The message could not be sent, but the underlying transport 
-         mechanism indicates that the failure is temporary. If the 
-         send operation is tried again it might be successful. 
-      
-     * - **RMR_SEND_FAILED** 
-       - 
-         The send operation was not successful and the underlying 
-         transport mechanism indicates a permanent (hard) failure; 
-         retrying the send is not possible. 
-      
-     * - **RMR_ERR_BADARG** 
-       - 
-         The message buffer pointer did not refer to a valid message. 
-      
-     * - **RMR_ERR_NOHDR** 
-       - 
-         The header in the message buffer was not valid or corrupted. 
-      
-     * - **RMR_ERR_NOENDPT** 
-       - 
-         The message type in the message buffer did not map to a known 
-         endpoint. 
-          
- 
- 
-The following values may be assigned to ``errno`` on failure. 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **INVAL** 
-       - 
-         Parameter(s) passed to the function were not valid, or the 
-         underlying message processing environment was unable to 
-         interpret the message. 
-      
-     * - **ENOKEY** 
-       - 
-         The header information in the message buffer was invalid. 
-      
-     * - **ENXIO** 
-       - 
-         No known endpoint for the message could be found. 
-      
-     * - **EMSGSIZE** 
-       - 
-         The underlying transport refused to accept the message 
-         because of a size value issue (message was not attempted to 
-         be sent). 
-      
-     * - **EFAULT** 
-       - 
-         The message referenced by the message buffer is corrupt (nil 
-         pointer or bad internal length). 
-      
-     * - **EBADF** 
-       - 
-         Internal RMR error; information provided to the message 
-         transport environment was not valid. 
-      
-     * - **ENOTSUP** 
-       - 
-         Sending was not supported by the underlying message 
-         transport. 
-      
-     * - **EFSM** 
-       - 
-         The device is not in a state that can accept the message. 
-      
-     * - **EAGAIN** 
-       - 
-         The device is not able to accept a message for sending. The 
-         user application should attempt to resend. 
-      
-     * - **EINTR** 
-       - 
-         The operation was interrupted by delivery of a signal before 
-         the message was sent. 
-      
-     * - **ETIMEDOUT** 
-       - 
-         The underlying message environment timed out during the send 
-         process. 
-      
-     * - **ETERM** 
-       - 
-         The underlying message environment is in a shutdown state. 
-          
- 
+The following values may be passed back in the *state* field
+of the returned message buffer.
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMR_RETRY**
+        -
+          The message could not be sent, but the underlying transport
+          mechanism indicates that the failure is temporary. If the
+          send operation is tried again it might be successful.
+
+      * - **RMR_SEND_FAILED**
+        -
+          The send operation was not successful and the underlying
+          transport mechanism indicates a permanent (hard) failure;
+          retrying the send is not possible.
+
+      * - **RMR_ERR_BADARG**
+        -
+          The message buffer pointer did not refer to a valid message.
+
+      * - **RMR_ERR_NOHDR**
+        -
+          The header in the message buffer was not valid or corrupted.
+
+      * - **RMR_ERR_NOENDPT**
+        -
+          The message type in the message buffer did not map to a known
+          endpoint.
+
+
+
+The following values may be assigned to ``errno`` on failure.
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **INVAL**
+        -
+          Parameter(s) passed to the function were not valid, or the
+          underlying message processing environment was unable to
+          interpret the message.
+
+      * - **ENOKEY**
+        -
+          The header information in the message buffer was invalid.
+
+      * - **ENXIO**
+        -
+          No known endpoint for the message could be found.
+
+      * - **EMSGSIZE**
+        -
+          The underlying transport refused to accept the message
+          because of a size value issue (message was not attempted to
+          be sent).
+
+      * - **EFAULT**
+        -
+          The message referenced by the message buffer is corrupt (nil
+          pointer or bad internal length).
+
+      * - **EBADF**
+        -
+          Internal RMR error; information provided to the message
+          transport environment was not valid.
+
+      * - **ENOTSUP**
+        -
+          Sending was not supported by the underlying message
+          transport.
+
+      * - **EFSM**
+        -
+          The device is not in a state that can accept the message.
+
+      * - **EAGAIN**
+        -
+          The device is not able to accept a message for sending. The
+          user application should attempt to resend.
+
+      * - **EINTR**
+        -
+          The operation was interrupted by delivery of a signal before
+          the message was sent.
+
+      * - **ETIMEDOUT**
+        -
+          The underlying message environment timed out during the send
+          process.
+
+      * - **ETERM**
+        -
+          The underlying message environment is in a shutdown state.
+
+

 
 
 EXAMPLE
 -------
 
 
 
 EXAMPLE
 -------
 

-The following is a simple example of how the 
-``rmr_send_msg`` function is called. In this example, the 
-send message buffer is saved between calls and reused 
-eliminating alloc/free cycles. 
- 
- 
-:: 
- 
-     static rmr_mbuf_t*  send_msg = NULL;        // message to send; reused on each call
-     msg_t*  send_pm;                            // payload for send
-     msg_t*  pm;                                 // our message format in the received payload
-  
-     if( send_msg  == NULL ) {
-         send_msg = rmr_alloc_msg( mr, MAX_SIZE ); // new buffer to send
-     }
-  
-     // reference payload and fill in message type
-     pm = (msg_t*) send_msg->payload;
-     send_msg->mtype = MT_ANSWER;
-  
-     msg->len = generate_data( pm );       // something that fills the payload in
-     msg = rmr_send_msg( mr, send_msg );   // ensure new pointer used after send
-     if( ! msg ) {
-         return ERROR;
-     } else {
-         if( msg->state != RMR_OK ) {
-             // check for RMR_ERR_RETRY, and resend if needed
-             // else return error
-         }
-     }
-     return OK;
-  
- 
+The following is a simple example of how the
+``rmr_send_msg`` function is called. In this example, the
+send message buffer is saved between calls and reused
+eliminating alloc/free cycles.
+
+
+::
+
+      static rmr_mbuf_t*  send_msg = NULL;        // message to send; reused on each call
+      msg_t*  send_pm;                            // payload for send
+      msg_t*  pm;                                 // our message format in the received payload
+
+      if( send_msg  == NULL ) {
+          send_msg = rmr_alloc_msg( mr, MAX_SIZE ); // new buffer to send
+      }
+
+      // reference payload and fill in message type
+      pm = (msg_t*) send_msg->payload;
+      send_msg->mtype = MT_ANSWER;
+
+      msg->len = generate_data( pm );       // something that fills the payload in
+      msg = rmr_send_msg( mr, send_msg );   // ensure new pointer used after send
+      if( ! msg ) {
+          return ERROR;
+      } else {
+          if( msg->state != RMR_OK ) {
+              // check for RMR_ERR_RETRY, and resend if needed
+              // else return error
+          }
+      }
+      return OK;
+
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), 
-rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3), 
-rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3), 
-rmr_ring_free(3), rmr_torcv_rcv(3), rmr_wh_send_msg(3) 
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
+rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
+rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
+rmr_ring_free(3), rmr_torcv_rcv(3), rmr_wh_send_msg(3)

diff --git a/docs/rmr_set_fack.3.rst b/docs/rmr_set_fack.3.rst
index 84f09fc..10cdf59 100644 (file)
--- a/docs/rmr_set_fack.3.rst
+++ b/docs/rmr_set_fack.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_set_fack 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_set_fack
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,44 +19,44 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_set_fack 
+rmr_set_fack

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- void rmr_set_fack( void* vctx );
-  
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  void rmr_set_fack( void* vctx );
+
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_set_fack`` function enables *fast TCP 
-acknowledgements* if the underlying transport library 
-supports it. This might be useful for applications which must 
-send messages at a maximum rate. 
+The ``rmr_set_fack`` function enables *fast TCP
+acknowledgements* if the underlying transport library
+supports it. This might be useful for applications which must
+send messages at a maximum rate.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-There is no return value. 
+There is no return value.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-This function does not generate any errors. 
+This function does not generate any errors.

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_init(3), 
+rmr_init(3),

diff --git a/docs/rmr_set_stimeout.3.rst b/docs/rmr_set_stimeout.3.rst
index fbd1071..22f4423 100644 (file)
--- a/docs/rmr_set_stimeout.3.rst
+++ b/docs/rmr_set_stimeout.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_set_stimeout 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_set_stimeout
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,98 +19,98 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_set_stimeout 
+rmr_set_stimeout

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- int rmr_set_stimeout( void* vctx, int rloops );
-  
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  int rmr_set_stimeout( void* vctx, int rloops );
+
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_set_stimeout`` function sets the configuration for 
-how RMR will retry message send operations which complete 
-with either a *timeout* or *again* completion value. (Send 
-operations include all of the possible message send 
-functions: *rmr_send_msg(), rmr_call(), rmr_rts_msg()* and 
-*rmr_wh_send_msg().* The *rloops* parameter sets the maximum 
-number of retry loops that will be attempted before giving up 
-and returning the unsuccessful state to the user application. 
-Each retry loop is approximately 1000 attempts, and RMR does 
-**not** invoke any sleep function between retries in the 
-loop; a small, 1 mu-sec, sleep is executed between loop sets 
-if the *rloops* value is greater than 1. 
- 
+The ``rmr_set_stimeout`` function sets the configuration for
+how RMR will retry message send operations which complete
+with either a *timeout* or *again* completion value. (Send
+operations include all of the possible message send
+functions: *rmr_send_msg(), rmr_call(), rmr_rts_msg()* and
+*rmr_wh_send_msg().* The *rloops* parameter sets the maximum
+number of retry loops that will be attempted before giving up
+and returning the unsuccessful state to the user application.
+Each retry loop is approximately 1000 attempts, and RMR does
+**not** invoke any sleep function between retries in the
+loop; a small, 1 mu-sec, sleep is executed between loop sets
+if the *rloops* value is greater than 1.
+

 
 
 Disabling Retries
 -----------------
 
 
 
 Disabling Retries
 -----------------
 

-By default, the send operations will execute with an *rloop* 
-setting of 1; each send operation will attempt to resend the 
-message approximately 1000 times before giving up. If the 
-user application does not want to have send operations retry 
-when the underlying transport mechanism indicates *timeout* 
-or *again,* the application should invoke this function and 
-pass a value of 0 (zero) for *rloops.* With this setting, all 
-RMR send operations will attempt a send operation only 
-**once,** returning immediately to the caller with the state 
-of that single attempt. 
+By default, the send operations will execute with an *rloop*
+setting of 1; each send operation will attempt to resend the
+message approximately 1000 times before giving up. If the
+user application does not want to have send operations retry
+when the underlying transport mechanism indicates *timeout*
+or *again,* the application should invoke this function and
+pass a value of 0 (zero) for *rloops.* With this setting, all
+RMR send operations will attempt a send operation only
+**once,** returning immediately to the caller with the state
+of that single attempt.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-This function returns a -1 to indicate that the *rloops* 
-value could not be set, and the value *RMR_OK* to indicate 
-success. 
+This function returns a -1 to indicate that the *rloops*
+value could not be set, and the value *RMR_OK* to indicate
+success.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-Currently errno is **not** set by this function; the only 
-cause of a failure is an invalid context (*vctx*) pointer. 
+Currently errno is **not** set by this function; the only
+cause of a failure is an invalid context (*vctx*) pointer.

 
 
 EXAMPLE
 -------
 
 
 
 EXAMPLE
 -------
 

-The following is a simple example of how the 
-``rmr_set_stimeout`` function is called. 
- 
- 
-:: 
- 
-     #define NO_FLAGS    0
-  
-     char* port = "43086";     // port for message router listen
-     int   max_size = 4096;    // max message size for default allocations
-     void* mr_context;         // message router context
-  
-     mr_context = rmr_init( port, max_size, NO_FLAGS );
-     if( mr_context != NULL ) {
-         rmr_set_stimeout( mr_context, 0 );    // turn off retries
-     }
-  
- 
+The following is a simple example of how the
+``rmr_set_stimeout`` function is called.
+
+
+::
+
+      #define NO_FLAGS    0
+
+      char* port = "43086";     // port for message router listen
+      int   max_size = 4096;    // max message size for default allocations
+      void* mr_context;         // message router context
+
+      mr_context = rmr_init( port, max_size, NO_FLAGS );
+      if( mr_context != NULL ) {
+          rmr_set_stimeout( mr_context, 0 );    // turn off retries
+      }
+
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), 
-rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3), 
-rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3), 
-rmr_ring_free(3), rmr_send_msg(3), rmr_torcv_rcv(3), 
-rmr_wh_send_msg(3) 
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
+rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
+rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
+rmr_ring_free(3), rmr_send_msg(3), rmr_torcv_rcv(3),
+rmr_wh_send_msg(3)

diff --git a/docs/rmr_set_trace.3.rst b/docs/rmr_set_trace.3.rst
index 89c114e..25a0e69 100644 (file)
--- a/docs/rmr_set_trace.3.rst
+++ b/docs/rmr_set_trace.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_set_trace 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_set_trace
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,49 +19,49 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_set_trace 
+rmr_set_trace

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- int rmr_set_trace( rmr_mbuf_t* mbuf, unsigned char* data, int len )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  int rmr_set_trace( rmr_mbuf_t* mbuf, unsigned char* data, int len )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_set_trace`` function will copy ``len`` bytes from 
-``data`` into the trace portion of ``mbuf.`` If the trace 
-area of ``mbuf`` is not the correct size, the message buffer 
-will be reallocated to ensure that enough space is available 
-for the trace data. 
+The ``rmr_set_trace`` function will copy ``len`` bytes from
+``data`` into the trace portion of ``mbuf.`` If the trace
+area of ``mbuf`` is not the correct size, the message buffer
+will be reallocated to ensure that enough space is available
+for the trace data.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-The ``rmr_set_trace`` function returns the number of bytes 
-successfully copied to the message. If 0 is returned either 
-the message pointer was nil, or the size in the parameters 
-was <= 0. 
+The ``rmr_set_trace`` function returns the number of bytes
+successfully copied to the message. If 0 is returned either
+the message pointer was nil, or the size in the parameters
+was <= 0.

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3), 
-rmr_bytes2payload(3), rmr_call(3), rmr_free_msg(3), 
-rmr_get_rcvfd(3), rmr_get_meid(3), rmr_get_trace(3), 
-rmr_get_trlen(3), rmr_init(3), rmr_init_trace(3), 
-rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), 
-rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), 
-rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), 
-rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3), 
-rmr_wh_open(3), rmr_wh_send_msg(3) 
+rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
+rmr_bytes2payload(3), rmr_call(3), rmr_free_msg(3),
+rmr_get_rcvfd(3), rmr_get_meid(3), rmr_get_trace(3),
+rmr_get_trlen(3), rmr_init(3), rmr_init_trace(3),
+rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
+rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
+rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
+rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3),
+rmr_wh_open(3), rmr_wh_send_msg(3)

diff --git a/docs/rmr_set_vlevel.3.rst b/docs/rmr_set_vlevel.3.rst
index 01bf715..37bd8fd 100644 (file)
--- a/docs/rmr_set_vlevel.3.rst
+++ b/docs/rmr_set_vlevel.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_set_vlevel 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_set_vlevel
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,99 +19,99 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_set_vlevel 
+rmr_set_vlevel

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
- #include <rmr/rmr_logging.h>
-  
- void rmr_set_vlevel( int new_level )
- 
+
+::
+
+  #include <rmr/rmr.h>
+  #include <rmr/rmr_logging.h>
+
+  void rmr_set_vlevel( int new_level )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_set_vlevel`` allows the user programme to set the 
-verbosity level which is used to determine the messages RMR 
-writes to standard error. The ``new_vlevel`` value must be 
-one of the following constants which have the indicated 
-meanings: 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **RMR_VL_OFF** 
-       - 
-         Turns off all message writing. This includes the stats and 
-         debugging messages generated by the route collector thread 
-         which are normally affected only by the externally managed 
-         verbose level file (and related environment variable). 
-      
-     * - **RMR_VL_CRIT** 
-       - 
-         Write only messages of critical importance. From the point of 
-         view of RMR, when a critical proper behaviour of the library 
-         cannot be expected or guaranteed. 
-      
-     * - **RMR_VL_ERR** 
-       - 
-         Include error messages in the output. An error is an event 
-         from which RMR has no means to recover. Continued proper 
-         execution is likely except where the affected connection 
-         and/or component mentioned in the error is concerned. 
-      
-     * - **RMR_VL_WARN** 
-       - 
-         Include warning messages in the output. A warning indicates 
-         an event which is not considered to be normal, but is 
-         expected and continued acceptable behaviour of the system is 
-         assured. 
-      
-     * - **RMR_VL_INFO** 
-       - 
-         Include informational messagees in the output. Informational 
-         messages include some diagnostic information which explain 
-         the activities of RMR. 
-      
-     * - **RMR_VL_DEBUG** 
-       - 
-         Include all debugging messages in the output. Debugging must 
-         have also been enabled during the build as a precaution to 
-         accidentally enabling this level of output as it can grossly 
-         affect performance. 
-          
- 
- 
-Generally RMR does not write messages to the standard error 
-device from *critical path* functions, therefore it is 
-usually not harmful to enable a verbosity level of either 
-RMR_VL_CRIT or RMR_VL_ERR. 
- 
-Messages written from the route table collection thread are 
-still governed by the value placed into the verbose level 
-control file (see the man page for rmr_init()); those 
-messages are affected only when logging is completely 
-disabled by passing RMR_VL_OFF to this function. 
- 
-The verbosity level can also be set via an environment 
-variable prior to the start of the RMR based application. The 
-environment variable is read only during initialisation; if 
-the programme must change the value during execution, this 
-function must be used. The default value, if this function is 
-never called, and the environment variable is not present, is 
-RMR_VL_ERR. 
+The ``rmr_set_vlevel`` allows the user programme to set the
+verbosity level which is used to determine the messages RMR
+writes to standard error. The ``new_vlevel`` value must be
+one of the following constants which have the indicated
+meanings:
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMR_VL_OFF**
+        -
+          Turns off all message writing. This includes the stats and
+          debugging messages generated by the route collector thread
+          which are normally affected only by the externally managed
+          verbose level file (and related environment variable).
+
+      * - **RMR_VL_CRIT**
+        -
+          Write only messages of critical importance. From the point of
+          view of RMR, when a critical proper behaviour of the library
+          cannot be expected or guaranteed.
+
+      * - **RMR_VL_ERR**
+        -
+          Include error messages in the output. An error is an event
+          from which RMR has no means to recover. Continued proper
+          execution is likely except where the affected connection
+          and/or component mentioned in the error is concerned.
+
+      * - **RMR_VL_WARN**
+        -
+          Include warning messages in the output. A warning indicates
+          an event which is not considered to be normal, but is
+          expected and continued acceptable behaviour of the system is
+          assured.
+
+      * - **RMR_VL_INFO**
+        -
+          Include informational messagees in the output. Informational
+          messages include some diagnostic information which explain
+          the activities of RMR.
+
+      * - **RMR_VL_DEBUG**
+        -
+          Include all debugging messages in the output. Debugging must
+          have also been enabled during the build as a precaution to
+          accidentally enabling this level of output as it can grossly
+          affect performance.
+
+
+
+Generally RMR does not write messages to the standard error
+device from *critical path* functions, therefore it is
+usually not harmful to enable a verbosity level of either
+RMR_VL_CRIT or RMR_VL_ERR.
+
+Messages written from the route table collection thread are
+still governed by the value placed into the verbose level
+control file (see the man page for rmr_init()); those
+messages are affected only when logging is completely
+disabled by passing RMR_VL_OFF to this function.
+
+The verbosity level can also be set via an environment
+variable prior to the start of the RMR based application. The
+environment variable is read only during initialisation; if
+the programme must change the value during execution, this
+function must be used. The default value, if this function is
+never called, and the environment variable is not present, is
+RMR_VL_ERR.

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_init(3) 
+rmr_init(3)

diff --git a/docs/rmr_str2meid.3.rst b/docs/rmr_str2meid.3.rst
index ae8b57b..b501acf 100644 (file)
--- a/docs/rmr_str2meid.3.rst
+++ b/docs/rmr_str2meid.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_str2meid 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_str2meid
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,63 +19,63 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_str2meid 
+rmr_str2meid

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_str2meid`` function will copy the string pointed to 
-by src to the managed entity ID (meid) field in the given 
-message. The field is a fixed length, gated by the constant 
-``RMR_MAX_MEID`` and if string length is larger than this 
-value, then **nothing** will be copied. (Note, this differs 
-slightly from the behaviour of the ``lrmr_bytes2meid()`` 
-function.) 
+The ``rmr_str2meid`` function will copy the string pointed to
+by src to the managed entity ID (meid) field in the given
+message. The field is a fixed length, gated by the constant
+``RMR_MAX_MEID`` and if string length is larger than this
+value, then **nothing** will be copied. (Note, this differs
+slightly from the behaviour of the ``lrmr_bytes2meid()``
+function.)

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-On success, the value RMR_OK is returned. If the string 
-cannot be copied to the message, the return value will be one 
-of the errors listed below. 
+On success, the value RMR_OK is returned. If the string
+cannot be copied to the message, the return value will be one
+of the errors listed below.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-If the return value is not RMR_OK, then it will be set to one 
-of the values below. 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **RMR_ERR_BADARG** 
-       - 
-         The message, or an internal portion of the message, was 
-         corrupted or the pointer was invalid. 
-      
-     * - **RMR_ERR_OVERFLOW** 
-       - 
-         The length passed in was larger than the maximum length of 
-         the field; only a portion of the source bytes were copied. 
-          
- 
+If the return value is not RMR_OK, then it will be set to one
+of the values below.
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMR_ERR_BADARG**
+        -
+          The message, or an internal portion of the message, was
+          corrupted or the pointer was invalid.
+
+      * - **RMR_ERR_OVERFLOW**
+        -
+          The length passed in was larger than the maximum length of
+          the field; only a portion of the source bytes were copied.
+
+

 
 
 EXAMPLE
 
 
 EXAMPLE


@@ -86,9 +86,9 @@ EXAMPLE
 SEE ALSO
 --------
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), 
-rmr_get_meid(3), rmr_get_rcvfd(3), rmr_payload_size(3), 
-rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3), 
-rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), 
-rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3), 
-rmr_bytes2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3) 
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
+rmr_get_meid(3), rmr_get_rcvfd(3), rmr_payload_size(3),
+rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
+rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
+rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
+rmr_bytes2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3)

diff --git a/docs/rmr_str2xact.3.rst b/docs/rmr_str2xact.3.rst
index 968f0c6..3db1e8e 100644 (file)
--- a/docs/rmr_str2xact.3.rst
+++ b/docs/rmr_str2xact.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_str2xact 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_str2xact
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,63 +19,63 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_str2xact 
+rmr_str2xact

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_str2xact`` function will copy the string pointed to 
-by src to the transaction ID (xaction) field in the given 
-message. The field is a fixed length, gated by the constant 
-``RMR_MAX_XID`` and if string length is larger than this 
-value, then **nothing** will be copied. (Note, this differs 
-slightly from the behaviour of the ``lrmr_bytes2xact()`` 
-function.) 
+The ``rmr_str2xact`` function will copy the string pointed to
+by src to the transaction ID (xaction) field in the given
+message. The field is a fixed length, gated by the constant
+``RMR_MAX_XID`` and if string length is larger than this
+value, then **nothing** will be copied. (Note, this differs
+slightly from the behaviour of the ``lrmr_bytes2xact()``
+function.)

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-On success, the value RMR_OK is returned. If the string 
-cannot be copied to the message, the return value will be one 
-of the errors listed below. 
+On success, the value RMR_OK is returned. If the string
+cannot be copied to the message, the return value will be one
+of the errors listed below.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-If the return value is not RMR_OK, then it will be set to one 
-of the values below. 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **RMR_ERR_BADARG** 
-       - 
-         The message, or an internal portion of the message, was 
-         corrupted or the pointer was invalid. 
-      
-     * - **RMR_ERR_OVERFLOW** 
-       - 
-         The length passed in was larger than the maximum length of 
-         the field; only a portion of the source bytes were copied. 
-          
- 
+If the return value is not RMR_OK, then it will be set to one
+of the values below.
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMR_ERR_BADARG**
+        -
+          The message, or an internal portion of the message, was
+          corrupted or the pointer was invalid.
+
+      * - **RMR_ERR_OVERFLOW**
+        -
+          The length passed in was larger than the maximum length of
+          the field; only a portion of the source bytes were copied.
+
+

 
 
 EXAMPLE
 
 
 EXAMPLE


@@ -86,10 +86,10 @@ EXAMPLE
 SEE ALSO
 --------
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_bytes2xact(3), 
-rmr_call(3), rmr_free_msg(3), rmr_get_meid(3), 
-rmr_get_rcvfd(3), rmr_get_xact(3), rmr_payload_size(3), 
-rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3), 
-rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), 
-rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3), 
-rmr_str2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3) 
+rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_bytes2xact(3),
+rmr_call(3), rmr_free_msg(3), rmr_get_meid(3),
+rmr_get_rcvfd(3), rmr_get_xact(3), rmr_payload_size(3),
+rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
+rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
+rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
+rmr_str2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3)

diff --git a/docs/rmr_support.3.rst b/docs/rmr_support.3.rst
index 648bedf..cc63e43 100644 (file)
--- a/docs/rmr_support.3.rst
+++ b/docs/rmr_support.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_support 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_support
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,118 +19,118 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-RMR support functions 
+RMR support functions

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
- #include <rmr/ring_inline.h>
-  
- char* rmr_fib( char* fname );
- int rmr_has_str( char const* buf, char const* str, char sep, int max );
- int rmr_tokenise( char* buf, char** tokens, int max, char sep );
- void* rmr_mk_ring( int size );
- void rmr_ring_free( void* vr );
-  
- static inline void* rmr_ring_extract( void* vr )
- static inline int rmr_ring_insert( void* vr, void* new_data )
- 
+
+::
+
+  #include <rmr/rmr.h>
+  #include <rmr/ring_inline.h>
+
+  char* rmr_fib( char* fname );
+  int rmr_has_str( char const* buf, char const* str, char sep, int max );
+  int rmr_tokenise( char* buf, char** tokens, int max, char sep );
+  void* rmr_mk_ring( int size );
+  void rmr_ring_free( void* vr );
+
+  static inline void* rmr_ring_extract( void* vr )
+  static inline int rmr_ring_insert( void* vr, void* new_data )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-These functions support the RMR library, and are made 
-available to user applications as some (e.g. route table 
-generators) might need and/or want to make use of them. The 
-``rmr_fib`` function accepts a file name and reads the entire 
-file into a single buffer. The intent is to provide an easy 
-way to load a static route table without a lot of buffered 
-I/O hoops. 
- 
-The ``rmr_has_str`` function accepts a *buffer* containing a 
-set of delimited tokens (e.g. foo,bar,goo) and returns true 
-if the target string, *str,* matches one of the tokens. The 
-*sep* parameter provides the separation character in the 
-buffer (e.g a comma) and *max* indicates the maximum number 
-of tokens to split the buffer into before checking. 
- 
-The ``rmr_tokenise`` function is a simple tokeniser which 
-splits *buf* into tokens at each occurrence of *sep*. 
-Multiple occurrences of the separator character (e.g. a,,b) 
-result in a nil token. Pointers to the tokens are placed into 
-the *tokens* array provided by the caller which is assumed to 
-have at least enough space for *max* entries. 
- 
-The ``rmr_mk_ring`` function creates a buffer ring with 
-*size* entries. 
- 
-The ``rmr_ring_free`` function accepts a pointer to a ring 
-context and frees the associated memory. 
- 
-The ``rmr_ring_insert`` and ``rmr_ring_extract`` functions 
-are provided as static inline functions via the 
-*rmr/ring_inline.h* header file. These functions both accept 
-the ring *context* returned by ``mk_ring,`` and either insert 
-a pointer at the next available slot (tail) or extract the 
-data at the head. 
+These functions support the RMR library, and are made
+available to user applications as some (e.g. route table
+generators) might need and/or want to make use of them. The
+``rmr_fib`` function accepts a file name and reads the entire
+file into a single buffer. The intent is to provide an easy
+way to load a static route table without a lot of buffered
+I/O hoops.
+
+The ``rmr_has_str`` function accepts a *buffer* containing a
+set of delimited tokens (e.g. foo,bar,goo) and returns true
+if the target string, *str,* matches one of the tokens. The
+*sep* parameter provides the separation character in the
+buffer (e.g a comma) and *max* indicates the maximum number
+of tokens to split the buffer into before checking.
+
+The ``rmr_tokenise`` function is a simple tokeniser which
+splits *buf* into tokens at each occurrence of *sep*.
+Multiple occurrences of the separator character (e.g. a,,b)
+result in a nil token. Pointers to the tokens are placed into
+the *tokens* array provided by the caller which is assumed to
+have at least enough space for *max* entries.
+
+The ``rmr_mk_ring`` function creates a buffer ring with
+*size* entries.
+
+The ``rmr_ring_free`` function accepts a pointer to a ring
+context and frees the associated memory.
+
+The ``rmr_ring_insert`` and ``rmr_ring_extract`` functions
+are provided as static inline functions via the
+*rmr/ring_inline.h* header file. These functions both accept
+the ring *context* returned by ``mk_ring,`` and either insert
+a pointer at the next available slot (tail) or extract the
+data at the head.

 
 
 RETURN VALUES
 -------------
 
 
 
 RETURN VALUES
 -------------
 

-The following are the return values for each of these 
-functions. 
- 
-The ``rmr_fib`` function returns a pointer to the buffer 
-containing the contents of the file. The buffer is terminated 
-with a single nil character (0) making it a legitimate C 
-string. If the file was empty or nonexistent, a buffer with 
-an immediate nil character. If it is important to the calling 
-programme to know if the file was empty or did not exist, the 
-caller should use the system stat function call to make that 
-determination. 
- 
-The ``rmr_has_str`` function returns 1 if *buf* contains the 
-token referenced by &ita and false (0) if it does not. On 
-error, a -1 value is returned and ``errno`` is set 
-accordingly. 
- 
-The ``rmr_tokenise`` function returns the actual number of 
-token pointers placed into *tokens* 
- 
-The ``rmr_mk_ring`` function returns a void pointer which is 
-the *context* for the ring. 
- 
-The ``rmr_ring_insert`` function returns 1 if the data was 
-successfully inserted into the ring, and 0 if the ring is 
-full and the pointer could not be deposited. 
- 
-The ``rmr_ring_extract`` will return the data which is at the 
-head of the ring, or NULL if the ring is empty. 
+The following are the return values for each of these
+functions.
+
+The ``rmr_fib`` function returns a pointer to the buffer
+containing the contents of the file. The buffer is terminated
+with a single nil character (0) making it a legitimate C
+string. If the file was empty or nonexistent, a buffer with
+an immediate nil character. If it is important to the calling
+programme to know if the file was empty or did not exist, the
+caller should use the system stat function call to make that
+determination.
+
+The ``rmr_has_str`` function returns 1 if *buf* contains the
+token referenced by &ita and false (0) if it does not. On
+error, a -1 value is returned and ``errno`` is set
+accordingly.
+
+The ``rmr_tokenise`` function returns the actual number of
+token pointers placed into *tokens*
+
+The ``rmr_mk_ring`` function returns a void pointer which is
+the *context* for the ring.
+
+The ``rmr_ring_insert`` function returns 1 if the data was
+successfully inserted into the ring, and 0 if the ring is
+full and the pointer could not be deposited.
+
+The ``rmr_ring_extract`` will return the data which is at the
+head of the ring, or NULL if the ring is empty.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-Not many of these functions set the value in ``errno,`` 
-however the value may be one of the following: 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **INVAL** 
-       - 
-         Parameter(s) passed to the function were not valid. 
-          
- 
+Not many of these functions set the value in ``errno,``
+however the value may be one of the following:
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **INVAL**
+        -
+          Parameter(s) passed to the function were not valid.
+
+

 
 
 EXAMPLE
 
 
 EXAMPLE


@@ -141,6 +141,6 @@ EXAMPLE
 SEE ALSO
 --------
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), 
-rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), 
-rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), 
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
+rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
+rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),

diff --git a/docs/rmr_torcv_msg.3.rst b/docs/rmr_torcv_msg.3.rst
index 21ad8ba..66f98e3 100644 (file)
--- a/docs/rmr_torcv_msg.3.rst
+++ b/docs/rmr_torcv_msg.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_torcv_msg 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_torcv_msg
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,138 +19,138 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_torcv_msg 
+rmr_torcv_msg

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_torcv_msg`` function will pause for *ms_to* 
-milliseconds waiting for a message to arrive. If a message 
-arrives before the timeout expires the message buffer 
-returned will have a status of RMR_OK and the payload will 
-contain the data received. If the timeout expires before the 
-message is received, the status will have the value 
-RMR_ERR_TIMEOUT. When a received message is returned the 
-message buffer will also contain the message type and length 
-set by the sender. If messages were queued while waiting for 
-the response to a previous invocation of ``rmr_call,`` the 
-oldest message is removed from the queue and returned without 
-delay. 
- 
-The *vctx* pointer is the pointer returned by the 
-``rmr_init`` function. *Old_msg* is a pointer to a previously 
-used message buffer or NULL. The ability to reuse message 
-buffers helps to avoid alloc/free cycles in the user 
-application. When no buffer is available to supply, the 
-receive function will allocate one. 
+The ``rmr_torcv_msg`` function will pause for *ms_to*
+milliseconds waiting for a message to arrive. If a message
+arrives before the timeout expires the message buffer
+returned will have a status of RMR_OK and the payload will
+contain the data received. If the timeout expires before the
+message is received, the status will have the value
+RMR_ERR_TIMEOUT. When a received message is returned the
+message buffer will also contain the message type and length
+set by the sender. If messages were queued while waiting for
+the response to a previous invocation of ``rmr_call,`` the
+oldest message is removed from the queue and returned without
+delay.
+
+The *vctx* pointer is the pointer returned by the
+``rmr_init`` function. *Old_msg* is a pointer to a previously
+used message buffer or NULL. The ability to reuse message
+buffers helps to avoid alloc/free cycles in the user
+application. When no buffer is available to supply, the
+receive function will allocate one.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-The function returns a pointer to the ``rmr_mbuf_t`` 
-structure which references the message information (state, 
-length, payload), or a nil pointer in the case of an extreme 
-error. 
+The function returns a pointer to the ``rmr_mbuf_t``
+structure which references the message information (state,
+length, payload), or a nil pointer in the case of an extreme
+error.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-The *state* field in the message buffer will be one of the 
-following: 
- 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **RMR_OK** 
-       - 
-         The message buffer (payload) references the received data. 
-      
-     * - **RMR_ERR_INITFAILED** 
-       - 
-         The first call to this function must initialise an underlying 
-         system notification mechanism. On failure, this error is 
-         returned and errno will have the system error status set. If 
-         this function fails to initialise, the poll mechanism, it is 
-         likely that message receives will never be successful. 
-      
-     * - **RMR_ERR_TIMEOUT** 
-       - 
-         The timeout expired before a complete message was received. 
-         All other fields in the message buffer are not valid. 
-      
-     * - **RMR_ERR_EMPTY** 
-       - 
-         A message was received, but it had no payload. All other 
-         fields in the message buffer are not valid. 
-          
- 
-Upon return the system error number, *errno* might be set 
-with a value that can help to explain the meaning of the 
-state indicated in the message. The following are possible: 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **INVAL** 
-       - 
-         Parameter(s) passed to the function were not valid. 
-      
-     * - **EBADF** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-      
-     * - **ENOTSUP** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-      
-     * - **EFSM** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-      
-     * - **EAGAIN** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-      
-     * - **EINTR** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-      
-     * - **ETIMEDOUT** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-      
-     * - **ETERM** 
-       - 
-         The underlying message transport is unable to process the 
-         request. 
-          
- 
+The *state* field in the message buffer will be one of the
+following:
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMR_OK**
+        -
+          The message buffer (payload) references the received data.
+
+      * - **RMR_ERR_INITFAILED**
+        -
+          The first call to this function must initialise an underlying
+          system notification mechanism. On failure, this error is
+          returned and errno will have the system error status set. If
+          this function fails to initialise, the poll mechanism, it is
+          likely that message receives will never be successful.
+
+      * - **RMR_ERR_TIMEOUT**
+        -
+          The timeout expired before a complete message was received.
+          All other fields in the message buffer are not valid.
+
+      * - **RMR_ERR_EMPTY**
+        -
+          A message was received, but it had no payload. All other
+          fields in the message buffer are not valid.
+
+
+Upon return the system error number, *errno* might be set
+with a value that can help to explain the meaning of the
+state indicated in the message. The following are possible:
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **INVAL**
+        -
+          Parameter(s) passed to the function were not valid.
+
+      * - **EBADF**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+      * - **ENOTSUP**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+      * - **EFSM**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+      * - **EAGAIN**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+      * - **EINTR**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+      * - **ETIMEDOUT**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+      * - **ETERM**
+        -
+          The underlying message transport is unable to process the
+          request.
+
+

 
 
 EXAMPLE
 
 
 EXAMPLE


@@ -161,8 +161,8 @@ EXAMPLE
 SEE ALSO
 --------
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), 
-rmr_get_rcvfd(3), rmr_init(3), rmr_payload_size(3), 
-rmr_rcv_msg(3), rmr_send_msg(3), rmr_rcv_specific(3), 
-rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), 
-rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3) 
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
+rmr_get_rcvfd(3), rmr_init(3), rmr_payload_size(3),
+rmr_rcv_msg(3), rmr_send_msg(3), rmr_rcv_specific(3),
+rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
+rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)

diff --git a/docs/rmr_trace_ref.3.rst b/docs/rmr_trace_ref.3.rst
index b5a7320..b9f4c8a 100644 (file)
--- a/docs/rmr_trace_ref.3.rst
+++ b/docs/rmr_trace_ref.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_trace_ref 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_trace_ref
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,48 +19,48 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_trace_ref 
+rmr_trace_ref

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- int rmr_trace_ref( rmr_mbuf_t* mbuf, int* sizeptr )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  int rmr_trace_ref( rmr_mbuf_t* mbuf, int* sizeptr )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_trace_ref`` function returns a pointer to the trace 
-area in the message, and optionally populates the user 
-programme supplied size integer with the trace area size, if 
-*sizeptr* is not nil. 
+The ``rmr_trace_ref`` function returns a pointer to the trace
+area in the message, and optionally populates the user
+programme supplied size integer with the trace area size, if
+*sizeptr* is not nil.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-On success, a void pointer to the trace area of the message 
-is returned. A nil pointer is returned if the message has no 
-trace data area allocated, or if the message itself is 
-invalid. 
+On success, a void pointer to the trace area of the message
+is returned. A nil pointer is returned if the message has no
+trace data area allocated, or if the message itself is
+invalid.

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3), 
-rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3), 
-rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3), 
-rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3), 
-rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), 
-rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), 
-rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), 
-rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3), 
-rmr_set_trace(3) 
+rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
+rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3),
+rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3),
+rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3),
+rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
+rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
+rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
+rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3),
+rmr_set_trace(3)

diff --git a/docs/rmr_tralloc_msg.3.rst b/docs/rmr_tralloc_msg.3.rst
index 02a8a7c..59ee5b3 100644 (file)
--- a/docs/rmr_tralloc_msg.3.rst
+++ b/docs/rmr_tralloc_msg.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_tralloc_msg 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_tralloc_msg
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,147 +19,147 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_tralloc_msg 
+rmr_tralloc_msg

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
-                              int trace_size, unsigned const char *tr_data );
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
+                               int trace_size, unsigned const char *tr_data );
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_tralloc_msg`` function is used to allocate a buffer 
-which the user programme can write into and then send through 
-the library. The buffer is allocated such that sending it 
-requires no additional copying from the buffer as it passes 
-through the underlying transport mechanism. 
- 
-The *size* parameter is used to set the payload length in the 
-message. If it is 0, then the default size supplied on the 
-*rmr_init* call will be used. In addition to allocating the 
-payload, a space in the buffer is reserved for *trace* data 
-(tr_size bytes), and the bytes pointed to by *tr_data* are 
-copied into that portion of the message. The *vctx* parameter 
-is the void context pointer that was returned by the 
-*rmr_init* function. 
- 
-The pointer to the message buffer returned is a structure 
-which has some user application visible fields; the structure 
-is described in ``rmr.h,`` and is illustrated below. 
- 
- 
-:: 
- 
- typedef struct {
-     int state;
-     int mtype;
-     int len;
-     unsigned char* payload;
-     unsigned char* xaction;
- } rmr_mbuf_t;
- 
- 
-Where: 
- 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **state** 
-       - 
-         Is the current buffer state. Following a call to 
-         ``rmr_send_msg`` the state indicates whether the buffer was 
-         successfully sent which determines exactly what the payload 
-         points to. If the send failed, the payload referenced by the 
-         buffer is the message that failed to send (allowing the 
-         application to attempt a retransmission). When the state is 
-         ``a_OK`` the buffer represents an empty buffer that the 
-         application may fill in in preparation to send. 
-      
-     * - **mtype** 
-       - 
-         When sending a message, the application is expected to set 
-         this field to the appropriate message type value (as 
-         determined by the user programme). Upon send this value 
-         determines how the a library will route the message. For a 
-         buffer which has been received, this field will contain the 
-         message type that was set by the sending application. 
-      
-     * - **len** 
-       - 
-         The application using a buffer to send a message is expected 
-         to set the length value to the actual number of bytes that it 
-         placed into the message. This is likely less than the total 
-         number of bytes that the message can carry. For a message 
-         buffer that is passed to the application as the result of a 
-         receive call, this will be the value that the sending 
-         application supplied and should indicate the number of bytes 
-         in the payload which are valid. 
-      
-     * - **payload** 
-       - 
-         The payload is a pointer to the actual received data. The 
-         user programme may read and write from/to the memory 
-         referenced by the payload up until the point in time that the 
-         buffer is used on a ``rmr_send, rmr_call`` or 
-         ``rmr_reply`` function call. Once the buffer has been passed 
-         back to a a library function the user programme should 
-         **NOT** make use of the payload pointer. 
-      
-     * - **xaction** 
-       - 
-         The *xaction* field is a pointer to a fixed sized area in the 
-         message into which the user may write a transaction ID. The 
-         ID is optional with the exception of when the user 
-         application uses the ``rmr_call`` function to send a message 
-         and wait for the reply; the underlying processing expects 
-         that the matching reply message will also contain the same 
-         data in the *xaction* field. 
-          
- 
+The ``rmr_tralloc_msg`` function is used to allocate a buffer
+which the user programme can write into and then send through
+the library. The buffer is allocated such that sending it
+requires no additional copying from the buffer as it passes
+through the underlying transport mechanism.
+
+The *size* parameter is used to set the payload length in the
+message. If it is 0, then the default size supplied on the
+*rmr_init* call will be used. In addition to allocating the
+payload, a space in the buffer is reserved for *trace* data
+(tr_size bytes), and the bytes pointed to by *tr_data* are
+copied into that portion of the message. The *vctx* parameter
+is the void context pointer that was returned by the
+*rmr_init* function.
+
+The pointer to the message buffer returned is a structure
+which has some user application visible fields; the structure
+is described in ``rmr.h,`` and is illustrated below.
+
+
+::
+
+  typedef struct {
+      int state;
+      int mtype;
+      int len;
+      unsigned char* payload;
+      unsigned char* xaction;
+  } rmr_mbuf_t;
+
+
+Where:
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **state**
+        -
+          Is the current buffer state. Following a call to
+          ``rmr_send_msg`` the state indicates whether the buffer was
+          successfully sent which determines exactly what the payload
+          points to. If the send failed, the payload referenced by the
+          buffer is the message that failed to send (allowing the
+          application to attempt a retransmission). When the state is
+          ``a_OK`` the buffer represents an empty buffer that the
+          application may fill in in preparation to send.
+
+      * - **mtype**
+        -
+          When sending a message, the application is expected to set
+          this field to the appropriate message type value (as
+          determined by the user programme). Upon send this value
+          determines how the a library will route the message. For a
+          buffer which has been received, this field will contain the
+          message type that was set by the sending application.
+
+      * - **len**
+        -
+          The application using a buffer to send a message is expected
+          to set the length value to the actual number of bytes that it
+          placed into the message. This is likely less than the total
+          number of bytes that the message can carry. For a message
+          buffer that is passed to the application as the result of a
+          receive call, this will be the value that the sending
+          application supplied and should indicate the number of bytes
+          in the payload which are valid.
+
+      * - **payload**
+        -
+          The payload is a pointer to the actual received data. The
+          user programme may read and write from/to the memory
+          referenced by the payload up until the point in time that the
+          buffer is used on a ``rmr_send, rmr_call`` or
+          ``rmr_reply`` function call. Once the buffer has been passed
+          back to a a library function the user programme should
+          **NOT** make use of the payload pointer.
+
+      * - **xaction**
+        -
+          The *xaction* field is a pointer to a fixed sized area in the
+          message into which the user may write a transaction ID. The
+          ID is optional with the exception of when the user
+          application uses the ``rmr_call`` function to send a message
+          and wait for the reply; the underlying processing expects
+          that the matching reply message will also contain the same
+          data in the *xaction* field.
+
+

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-The function returns a pointer to a ``rmr_mbuf`` structure, 
-or NULL on error. 
+The function returns a pointer to a ``rmr_mbuf`` structure,
+or NULL on error.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **ENOMEM** 
-       - 
-         Unable to allocate memory. 
-          
- 
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **ENOMEM**
+        -
+          Unable to allocate memory.
+
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3), 
-rmr_init(3), rmr_init_trace(3), rmr_get_trace(3), 
-rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3), 
-rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), 
-rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), 
-rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3) 
+rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3),
+rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
+rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
+rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
+rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
+rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)

diff --git a/docs/rmr_wh_call.3.rst b/docs/rmr_wh_call.3.rst
index 9e6da4e..1024ca3 100644 (file)
--- a/docs/rmr_wh_call.3.rst
+++ b/docs/rmr_wh_call.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_wh_call 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_wh_call
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,208 +19,208 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_wh_call 
+rmr_wh_call

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- rmr_mbuf_t* rmr_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg, int call_id, int max_wait )
-  
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  rmr_mbuf_t* rmr_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg, int call_id, int max_wait )
+
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_wh_call`` function accepts a message buffer (msg) 
-from the user application and attempts to send it using the 
-wormhole ID provided (whid). If the send is successful, the 
-call will block until either a response message is received, 
-or the ``max_wait`` number of milliseconds has passed. In 
-order for the response to be recognised as a response, the 
-remote process **must** use ``rmr_rts_msg()`` to send their 
-response. 
- 
-Like *rmr_wh_send_msg,* this function attempts to send the 
-message directly to a process at the other end of a wormhole 
-which was created with *rmr_wh_open().* When sending message 
-via wormholes, the normal RMR routing based on message type 
-is ignored, and the caller may leave the message type 
-unspecified in the message buffer (unless it is needed by the 
-receiving process). The ``call_id`` parameter is a number in 
-the range of 2 through 255 and is used to identify the 
-calling thread in order to properly match a response message 
-when it arrives. Providing this value, and ensuring the 
-proper uniqueness, is the responsibility of the user 
-application and as such the ability to use the 
-``rmr_wh_call()`` function from potentially non-threaded 
-concurrent applications (such as Go's goroutines) is 
-possible. 
+The ``rmr_wh_call`` function accepts a message buffer (msg)
+from the user application and attempts to send it using the
+wormhole ID provided (whid). If the send is successful, the
+call will block until either a response message is received,
+or the ``max_wait`` number of milliseconds has passed. In
+order for the response to be recognised as a response, the
+remote process **must** use ``rmr_rts_msg()`` to send their
+response.
+
+Like *rmr_wh_send_msg,* this function attempts to send the
+message directly to a process at the other end of a wormhole
+which was created with *rmr_wh_open().* When sending message
+via wormholes, the normal RMR routing based on message type
+is ignored, and the caller may leave the message type
+unspecified in the message buffer (unless it is needed by the
+receiving process). The ``call_id`` parameter is a number in
+the range of 2 through 255 and is used to identify the
+calling thread in order to properly match a response message
+when it arrives. Providing this value, and ensuring the
+proper uniqueness, is the responsibility of the user
+application and as such the ability to use the
+``rmr_wh_call()`` function from potentially non-threaded
+concurrent applications (such as Go's goroutines) is
+possible.

 
 
 Retries
 -------
 
 
 
 Retries
 -------
 

-The send operations in RMR will retry *soft* send failures 
-until one of three conditions occurs: 
- 
- 
-* The message is sent without error 
-  
-* The underlying transport reports a *hard* failure 
-  
-* The maximum number of retry loops has been attempted 
- 
- 
-A retry loop consists of approximately 1000 send attempts 
-**without** any intervening calls to *sleep()* or *usleep().* 
-The number of retry loops defaults to 1, thus a maximum of 
-1000 send attempts is performed before returning to the user 
-application. This value can be set at any point after RMR 
-initialisation using the *rmr_set_stimeout()* function 
-allowing the user application to completely disable retires 
-(set to 0), or to increase the number of retry loops. 
+The send operations in RMR will retry *soft* send failures
+until one of three conditions occurs:
+
+
+* The message is sent without error
+
+* The underlying transport reports a *hard* failure
+
+* The maximum number of retry loops has been attempted
+
+
+A retry loop consists of approximately 1000 send attempts
+**without** any intervening calls to *sleep()* or *usleep().*
+The number of retry loops defaults to 1, thus a maximum of
+1000 send attempts is performed before returning to the user
+application. This value can be set at any point after RMR
+initialisation using the *rmr_set_stimeout()* function
+allowing the user application to completely disable retires
+(set to 0), or to increase the number of retry loops.

 
 
 Transport Level Blocking
 ------------------------
 
 
 
 Transport Level Blocking
 ------------------------
 

-The underlying transport mechanism used to send messages is 
-configured in *non-blocking* mode. This means that if a 
-message cannot be sent immediately the transport mechanism 
-will **not** pause with the assumption that the inability to 
-send will clear quickly (within a few milliseconds). This 
-means that when the retry loop is completely disabled (set to 
-0), that the failure to accept a message for sending by the 
-underlying mechanisms (software or hardware) will be reported 
-immediately to the user application. 
- 
-It should be noted that depending on the underlying transport 
-mechanism being used, it is extremely likely that retry 
-conditions will happen during normal operations. These are 
-completely out of RMR's control, and there is nothing that 
-RMR can do to avoid or mitigate these other than by allowing 
-RMR to retry the send operation, and even then it is possible 
-(e.g., during connection reattempts), that a single retry 
-loop is not enough to guarantee a successful send. 
+The underlying transport mechanism used to send messages is
+configured in *non-blocking* mode. This means that if a
+message cannot be sent immediately the transport mechanism
+will **not** pause with the assumption that the inability to
+send will clear quickly (within a few milliseconds). This
+means that when the retry loop is completely disabled (set to
+0), that the failure to accept a message for sending by the
+underlying mechanisms (software or hardware) will be reported
+immediately to the user application.
+
+It should be noted that depending on the underlying transport
+mechanism being used, it is extremely likely that retry
+conditions will happen during normal operations. These are
+completely out of RMR's control, and there is nothing that
+RMR can do to avoid or mitigate these other than by allowing
+RMR to retry the send operation, and even then it is possible
+(e.g., during connection reattempts), that a single retry
+loop is not enough to guarantee a successful send.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-On success, new message buffer, with the payload containing 
-the response from the remote endpoint is returned. The state 
-in this buffer will reflect the overall send operation state 
-and should be ``RMR_OK.`` 
- 
-If a message is returned with a state which is anything other 
-than ``RMR_OK,`` the indication is that the send was not 
-successful. The user application must check the state and 
-determine the course of action. If the return value is NULL, 
-no message, the indication is that there was no response 
-received within the timeout (max_wait) period of time. 
+On success, new message buffer, with the payload containing
+the response from the remote endpoint is returned. The state
+in this buffer will reflect the overall send operation state
+and should be ``RMR_OK.``
+
+If a message is returned with a state which is anything other
+than ``RMR_OK,`` the indication is that the send was not
+successful. The user application must check the state and
+determine the course of action. If the return value is NULL,
+no message, the indication is that there was no response
+received within the timeout (max_wait) period of time.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-The following values may be passed back in the *state* field 
-of the returned message buffer. 
- 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **RMR_ERR_WHID** 
-       - 
-         The wormhole ID passed in was not associated with an open 
-         wormhole, or was out of range for a valid ID. 
-      
-     * - **RMR_ERR_NOWHOPEN** 
-       - 
-         No wormholes exist, further attempt to validate the ID are 
-         skipped. 
-      
-     * - **RMR_ERR_BADARG** 
-       - 
-         The message buffer pointer did not refer to a valid message. 
-      
-     * - **RMR_ERR_NOHDR** 
-       - 
-         The header in the message buffer was not valid or corrupted. 
-          
- 
+The following values may be passed back in the *state* field
+of the returned message buffer.
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMR_ERR_WHID**
+        -
+          The wormhole ID passed in was not associated with an open
+          wormhole, or was out of range for a valid ID.
+
+      * - **RMR_ERR_NOWHOPEN**
+        -
+          No wormholes exist, further attempt to validate the ID are
+          skipped.
+
+      * - **RMR_ERR_BADARG**
+        -
+          The message buffer pointer did not refer to a valid message.
+
+      * - **RMR_ERR_NOHDR**
+        -
+          The header in the message buffer was not valid or corrupted.
+
+

 
 
 EXAMPLE
 -------
 
 
 
 EXAMPLE
 -------
 

-The following is a simple example of how the a wormhole is 
-created (rmr_wh_open) and then how ``rmr_wh_send_msg`` 
-function is used to send messages. Some error checking is 
-omitted for clarity. 
- 
- 
-:: 
- 
-  
- #include <rmr/rmr.h>    // system headers omitted for clarity
-  
- int main() {
-    rmr_whid_t whid = -1;   // wormhole id for sending
-    void* mrc;      //msg router context
-         int i;
-    rmr_mbuf_t*  sbuf;      // send buffer
-    int     count = 0;
-    int     norm_msg_size = 1500;    // most messages fit in this size
-  
-    mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE );
-    if( mrc == NULL ) {
-       fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" );
-       exit( 1 );
-    }
-  
-    while( ! rmr_ready( mrc ) ) {        // wait for routing table info
-       sleep( 1 );
-    }
-  
-    sbuf = rmr_alloc_msg( mrc, 2048 );
-  
-    while( 1 ) {
-      if( whid < 0 ) {
-        whid = rmr_wh_open( mrc, "localhost:6123" );  // open fails if endpoint refuses conn
-           if( RMR_WH_CONNECTED( wh ) ) {
-            snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
-            sbuf->len =  strlen( sbuf->payload );
-            sbuf = rmr_wh_call( mrc, whid, sbuf, 1000 );        // expect a response in 1s or less
-            if( sbuf != NULL && sbuf->state = RMR_OK ) {
-              sprintf( stderr, "response: %s\\n", sbuf->payload );    // assume they sent a string
-            } else {
-              sprintf( stderr, "response not received, or send error\\n" );
-            }
-         }
-       }
-  
-       sleep( 5 );
-    }
- }
- 
+The following is a simple example of how the a wormhole is
+created (rmr_wh_open) and then how ``rmr_wh_send_msg``
+function is used to send messages. Some error checking is
+omitted for clarity.
+
+
+::
+
+
+  #include <rmr/rmr.h>    // system headers omitted for clarity
+
+  int main() {
+     rmr_whid_t whid = -1;   // wormhole id for sending
+     void* mrc;      //msg router context
+          int i;
+     rmr_mbuf_t*  sbuf;      // send buffer
+     int     count = 0;
+     int     norm_msg_size = 1500;    // most messages fit in this size
+
+     mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE );
+     if( mrc == NULL ) {
+        fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" );
+        exit( 1 );
+     }
+
+     while( ! rmr_ready( mrc ) ) {        // wait for routing table info
+        sleep( 1 );
+     }
+
+     sbuf = rmr_alloc_msg( mrc, 2048 );
+
+     while( 1 ) {
+       if( whid < 0 ) {
+         whid = rmr_wh_open( mrc, "localhost:6123" );  // open fails if endpoint refuses conn
+            if( RMR_WH_CONNECTED( wh ) ) {
+             snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
+             sbuf->len =  strlen( sbuf->payload );
+             sbuf = rmr_wh_call( mrc, whid, sbuf, 1000 );        // expect a response in 1s or less
+             if( sbuf != NULL && sbuf->state = RMR_OK ) {
+               sprintf( stderr, "response: %s\\n", sbuf->payload );    // assume they sent a string
+             } else {
+               sprintf( stderr, "response not received, or send error\\n" );
+             }
+          }
+        }
+
+        sleep( 5 );
+     }
+  }
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), 
-rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3), 
-rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), 
-rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3), 
-rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3), 
-rmr_wh_state(3) 
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
+rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
+rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
+rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
+rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3),
+rmr_wh_state(3)

diff --git a/docs/rmr_wh_close.3.rst b/docs/rmr_wh_close.3.rst
index 3741bab..64faa69 100644 (file)
--- a/docs/rmr_wh_close.3.rst
+++ b/docs/rmr_wh_close.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_wh_close 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_wh_close
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,41 +19,41 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_wh_close 
+rmr_wh_close

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- void rmr_wh_close( void* vctx, rmr_whid_t whid )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  void rmr_wh_close( void* vctx, rmr_whid_t whid )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_wh_close`` function closes the wormhole associated 
-with the wormhole id passed in. Future calls to 
-``rmr_wh_send_msg`` with this ID will fail. 
- 
-The underlying TCP connection to the remote endpoint is 
-**not** closed as this session may be required for regularly 
-routed messages (messages routed based on message type). 
-There is no way to force a TCP session to be closed at this 
-point in time. 
+The ``rmr_wh_close`` function closes the wormhole associated
+with the wormhole id passed in. Future calls to
+``rmr_wh_send_msg`` with this ID will fail.
+
+The underlying TCP connection to the remote endpoint is
+**not** closed as this session may be required for regularly
+routed messages (messages routed based on message type).
+There is no way to force a TCP session to be closed at this
+point in time.

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), 
-rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3), 
-rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), 
-rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), 
-rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3), 
-rmr_wh_send_msg(3) 
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
+rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
+rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
+rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
+rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3),
+rmr_wh_send_msg(3)

diff --git a/docs/rmr_wh_open.3.rst b/docs/rmr_wh_open.3.rst
index d3a9134..ac7a3b8 100644 (file)
--- a/docs/rmr_wh_open.3.rst
+++ b/docs/rmr_wh_open.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_wh_open 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_wh_open
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,112 +19,112 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_wh_open 
+rmr_wh_open

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- rmr_whid_t rmr_wh_open( void* vctx, char* target )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  rmr_whid_t rmr_wh_open( void* vctx, char* target )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_wh_open`` function creates a direct link for 
-sending, a wormhole, to another RMR based process. Sending 
-messages through a wormhole requires that the connection be 
-established overtly by the user application (via this 
-function), and that the ID returned by ``rmr_wh_open`` be 
-passed to the ``rmr_wh_send_msg`` function. 
- 
-*Vctx* is the RMR void context pointer that was returned by 
-the ``rmr_init`` function. *Target* is the *name and port,* 
-or *IP-address and port,* combination for the process that 
-the wormhole should be connected to. For example, 
-"localhost:6123". 
- 
-When invoked, this function immediately attempts to connect 
-to the target process. If the connection cannot be 
-established, an error is returned to the caller, and no 
-direct messages can be sent to the target. Once a wormhole is 
-connected, the underlying transport mechanism (e.g. NNG) will 
-provide reconnects should the connection be lost, however the 
-handling of messages sent when a connection is broken is 
-undetermined as each underlying transport mechanism may 
-handle buffering and retries differently. 
+The ``rmr_wh_open`` function creates a direct link for
+sending, a wormhole, to another RMR based process. Sending
+messages through a wormhole requires that the connection be
+established overtly by the user application (via this
+function), and that the ID returned by ``rmr_wh_open`` be
+passed to the ``rmr_wh_send_msg`` function.
+
+*Vctx* is the RMR void context pointer that was returned by
+the ``rmr_init`` function. *Target* is the *name and port,*
+or *IP-address and port,* combination for the process that
+the wormhole should be connected to. For example,
+"localhost:6123".
+
+When invoked, this function immediately attempts to connect
+to the target process. If the connection cannot be
+established, an error is returned to the caller, and no
+direct messages can be sent to the target. Once a wormhole is
+connected, the underlying transport mechanism (e.g. NNG) will
+provide reconnects should the connection be lost, however the
+handling of messages sent when a connection is broken is
+undetermined as each underlying transport mechanism may
+handle buffering and retries differently.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-The ``rmr_wh_open`` function returns a type 
-``rmr_whid_t`` which must be passed to the 
-``rmr_wh_send_msg`` function when sending a message. The id 
-may also be tested to determine success or failure of the 
-connection by using the RMR_WH_CONNECTED macro and passing 
-the ID as the parameter; a result of 1 indicates that the 
-connection was established and that the ID is valid. 
+The ``rmr_wh_open`` function returns a type
+``rmr_whid_t`` which must be passed to the
+``rmr_wh_send_msg`` function when sending a message. The id
+may also be tested to determine success or failure of the
+connection by using the RMR_WH_CONNECTED macro and passing
+the ID as the parameter; a result of 1 indicates that the
+connection was established and that the ID is valid.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-The following error values are specifically set by this RMR 
-function. In some cases the error message of a system call is 
-propagated up, and thus this list might be incomplete. 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **EINVAL** 
-       - 
-         A parameter passed was not valid. 
-      
-     * - **EACCESS** 
-       - 
-         The user application does not have the ability to establish a 
-         wormhole to the indicated target (or maybe any target). 
-      
-     * - **ECONNREFUSED** 
-       - 
-         The connection was refused. 
-          
- 
+The following error values are specifically set by this RMR
+function. In some cases the error message of a system call is
+propagated up, and thus this list might be incomplete.
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **EINVAL**
+        -
+          A parameter passed was not valid.
+
+      * - **EACCESS**
+        -
+          The user application does not have the ability to establish a
+          wormhole to the indicated target (or maybe any target).
+
+      * - **ECONNREFUSED**
+        -
+          The connection was refused.
+
+

 
 
 EXAMPLE
 -------
 
 
 
 EXAMPLE
 -------
 

- 
-:: 
- 
-    void*  rmc;
-    rmr_whid_t wh;
-  
-    rmc = rmr_init( "43086", 4096, 0 ); // init context
-    wh = rmr_wh_open( rmc, "localhost:6123" );
-    if( !RMR_WH_CONNECTED( wh ) ) {
-      fprintf( stderr, "unable to connect wormhole: %s\\n",
-              strerror( errno ) );
-    }
- 
+
+::
+
+     void*  rmc;
+     rmr_whid_t wh;
+
+     rmc = rmr_init( "43086", 4096, 0 ); // init context
+     wh = rmr_wh_open( rmc, "localhost:6123" );
+     if( !RMR_WH_CONNECTED( wh ) ) {
+       fprintf( stderr, "unable to connect wormhole: %s\\n",
+               strerror( errno ) );
+     }
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), 
-rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3), 
-rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), 
-rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), 
-rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_close(3), 
-rmr_wh_send_msg(3), rmr_wh_state(3) 
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
+rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
+rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
+rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
+rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_close(3),
+rmr_wh_send_msg(3), rmr_wh_state(3)

diff --git a/docs/rmr_wh_send_msg.3.rst b/docs/rmr_wh_send_msg.3.rst
index 7de91a8..66af85b 100644 (file)
--- a/docs/rmr_wh_send_msg.3.rst
+++ b/docs/rmr_wh_send_msg.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_wh_send_msg 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_wh_send_msg
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,264 +19,264 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_wh_send_msg 
+rmr_wh_send_msg

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_wh_send_msg`` function accepts a message buffer 
-from the user application and attempts to send it using the 
-wormhole ID provided (id). Unlike *rmr_send_msg,* this 
-function attempts to send the message directly to a process 
-at the other end of a wormhole which was created with 
-*rmr_wh_open().* When sending message via wormholes, the 
-normal RMR routing based on message type is ignored, and the 
-caller may leave the message type unspecified in the message 
-buffer (unless it is needed by the receiving process). 
- 
-*Vctx* is the RMR void context pointer that was returned by 
-the ``rmr_init`` function. The message buffer (msg) used to 
-send is the same format as used for regular RMR send and 
-reply to sender operations, thus any buffer allocated by 
-these means, or calls to *rmr_rcv_msg()* can be passed to 
-this function. 
+The ``rmr_wh_send_msg`` function accepts a message buffer
+from the user application and attempts to send it using the
+wormhole ID provided (id). Unlike *rmr_send_msg,* this
+function attempts to send the message directly to a process
+at the other end of a wormhole which was created with
+*rmr_wh_open().* When sending message via wormholes, the
+normal RMR routing based on message type is ignored, and the
+caller may leave the message type unspecified in the message
+buffer (unless it is needed by the receiving process).
+
+*Vctx* is the RMR void context pointer that was returned by
+the ``rmr_init`` function. The message buffer (msg) used to
+send is the same format as used for regular RMR send and
+reply to sender operations, thus any buffer allocated by
+these means, or calls to *rmr_rcv_msg()* can be passed to
+this function.

 
 
 Retries
 -------
 
 
 
 Retries
 -------
 

-The send operations in RMR will retry *soft* send failures 
-until one of three conditions occurs: 
- 
- 
-* The message is sent without error 
-  
-* The underlying transport reports a *hard* failure 
-  
-* The maximum number of retry loops has been attempted 
- 
- 
-A retry loop consists of approximately 1000 send attempts 
-**without** any intervening calls to *sleep()* or *usleep().* 
-The number of retry loops defaults to 1, thus a maximum of 
-1000 send attempts is performed before returning to the user 
-application. This value can be set at any point after RMR 
-initialisation using the *rmr_set_stimeout()* function 
-allowing the user application to completely disable retires 
-(set to 0), or to increase the number of retry loops. 
+The send operations in RMR will retry *soft* send failures
+until one of three conditions occurs:
+
+
+* The message is sent without error
+
+* The underlying transport reports a *hard* failure
+
+* The maximum number of retry loops has been attempted
+
+
+A retry loop consists of approximately 1000 send attempts
+**without** any intervening calls to *sleep()* or *usleep().*
+The number of retry loops defaults to 1, thus a maximum of
+1000 send attempts is performed before returning to the user
+application. This value can be set at any point after RMR
+initialisation using the *rmr_set_stimeout()* function
+allowing the user application to completely disable retires
+(set to 0), or to increase the number of retry loops.

 
 
 Transport Level Blocking
 ------------------------
 
 
 
 Transport Level Blocking
 ------------------------
 

-The underlying transport mechanism used to send messages is 
-configured in *non-blocking* mode. This means that if a 
-message cannot be sent immediately the transport mechanism 
-will **not** pause with the assumption that the inability to 
-send will clear quickly (within a few milliseconds). This 
-means that when the retry loop is completely disabled (set to 
-0), that the failure to accept a message for sending by the 
-underlying mechanisms (software or hardware) will be reported 
-immediately to the user application. 
- 
-It should be noted that depending on the underlying transport 
-mechanism being used, it is extremely likely that retry 
-conditions will happen during normal operations. These are 
-completely out of RMR's control, and there is nothing that 
-RMR can do to avoid or mitigate these other than by allowing 
-RMR to retry the send operation, and even then it is possible 
-(e.g., during connection reattempts), that a single retry 
-loop is not enough to guarantee a successful send. 
+The underlying transport mechanism used to send messages is
+configured in *non-blocking* mode. This means that if a
+message cannot be sent immediately the transport mechanism
+will **not** pause with the assumption that the inability to
+send will clear quickly (within a few milliseconds). This
+means that when the retry loop is completely disabled (set to
+0), that the failure to accept a message for sending by the
+underlying mechanisms (software or hardware) will be reported
+immediately to the user application.
+
+It should be noted that depending on the underlying transport
+mechanism being used, it is extremely likely that retry
+conditions will happen during normal operations. These are
+completely out of RMR's control, and there is nothing that
+RMR can do to avoid or mitigate these other than by allowing
+RMR to retry the send operation, and even then it is possible
+(e.g., during connection reattempts), that a single retry
+loop is not enough to guarantee a successful send.

 
 
 RETURN VALUE
 ------------
 
 
 
 RETURN VALUE
 ------------
 

-On success, a new message buffer, with an empty payload, is 
-returned for the application to use for the next send. The 
-state in this buffer will reflect the overall send operation 
-state and should be ``RMR_OK.`` 
- 
-If the state in the returned buffer is anything other than 
-``RMR_OK,`` the user application may need to attempt a 
-retransmission of the message, or take other action depending 
-on the setting of ``errno`` as described below. 
- 
-In the event of extreme failure, a nil pointer is returned. 
-In this case the value of ``errno`` might be of some use, for 
-documentation, but there will be little that the user 
-application can do other than to move on. 
+On success, a new message buffer, with an empty payload, is
+returned for the application to use for the next send. The
+state in this buffer will reflect the overall send operation
+state and should be ``RMR_OK.``
+
+If the state in the returned buffer is anything other than
+``RMR_OK,`` the user application may need to attempt a
+retransmission of the message, or take other action depending
+on the setting of ``errno`` as described below.
+
+In the event of extreme failure, a nil pointer is returned.
+In this case the value of ``errno`` might be of some use, for
+documentation, but there will be little that the user
+application can do other than to move on.

 
 
 ERRORS
 ------
 
 
 
 ERRORS
 ------
 

-The following values may be passed back in the *state* field 
-of the returned message buffer. 
- 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **RMR_ERR_WHID** 
-       - 
-         The wormhole ID passed in was not associated with an open 
-         wormhole, or was out of range for a valid ID. 
-      
-     * - **RMR_ERR_NOWHOPEN** 
-       - 
-         No wormholes exist, further attempt to validate the ID are 
-         skipped. 
-      
-     * - **RMR_ERR_BADARG** 
-       - 
-         The message buffer pointer did not refer to a valid message. 
-      
-     * - **RMR_ERR_NOHDR** 
-       - 
-         The header in the message buffer was not valid or corrupted. 
-          
- 
- 
-The following values may be assigned to ``errno`` on failure. 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **INVAL** 
-       - 
-         Parameter(s) passed to the function were not valid, or the 
-         underlying message processing environment was unable to 
-         interpret the message. 
-      
-     * - **ENOKEY** 
-       - 
-         The header information in the message buffer was invalid. 
-      
-     * - **ENXIO** 
-       - 
-         No known endpoint for the message could be found. 
-      
-     * - **EMSGSIZE** 
-       - 
-         The underlying transport refused to accept the message 
-         because of a size value issue (message was not attempted to 
-         be sent). 
-      
-     * - **EFAULT** 
-       - 
-         The message referenced by the message buffer is corrupt (nil 
-         pointer or bad internal length). 
-      
-     * - **EBADF** 
-       - 
-         Internal RMR error; information provided to the message 
-         transport environment was not valid. 
-      
-     * - **ENOTSUP** 
-       - 
-         Sending was not supported by the underlying message 
-         transport. 
-      
-     * - **EFSM** 
-       - 
-         The device is not in a state that can accept the message. 
-      
-     * - **EAGAIN** 
-       - 
-         The device is not able to accept a message for sending. The 
-         user application should attempt to resend. 
-      
-     * - **EINTR** 
-       - 
-         The operation was interrupted by delivery of a signal before 
-         the message was sent. 
-      
-     * - **ETIMEDOUT** 
-       - 
-         The underlying message environment timed out during the send 
-         process. 
-      
-     * - **ETERM** 
-       - 
-         The underlying message environment is in a shutdown state. 
-          
- 
+The following values may be passed back in the *state* field
+of the returned message buffer.
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMR_ERR_WHID**
+        -
+          The wormhole ID passed in was not associated with an open
+          wormhole, or was out of range for a valid ID.
+
+      * - **RMR_ERR_NOWHOPEN**
+        -
+          No wormholes exist, further attempt to validate the ID are
+          skipped.
+
+      * - **RMR_ERR_BADARG**
+        -
+          The message buffer pointer did not refer to a valid message.
+
+      * - **RMR_ERR_NOHDR**
+        -
+          The header in the message buffer was not valid or corrupted.
+
+
+
+The following values may be assigned to ``errno`` on failure.
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **INVAL**
+        -
+          Parameter(s) passed to the function were not valid, or the
+          underlying message processing environment was unable to
+          interpret the message.
+
+      * - **ENOKEY**
+        -
+          The header information in the message buffer was invalid.
+
+      * - **ENXIO**
+        -
+          No known endpoint for the message could be found.
+
+      * - **EMSGSIZE**
+        -
+          The underlying transport refused to accept the message
+          because of a size value issue (message was not attempted to
+          be sent).
+
+      * - **EFAULT**
+        -
+          The message referenced by the message buffer is corrupt (nil
+          pointer or bad internal length).
+
+      * - **EBADF**
+        -
+          Internal RMR error; information provided to the message
+          transport environment was not valid.
+
+      * - **ENOTSUP**
+        -
+          Sending was not supported by the underlying message
+          transport.
+
+      * - **EFSM**
+        -
+          The device is not in a state that can accept the message.
+
+      * - **EAGAIN**
+        -
+          The device is not able to accept a message for sending. The
+          user application should attempt to resend.
+
+      * - **EINTR**
+        -
+          The operation was interrupted by delivery of a signal before
+          the message was sent.
+
+      * - **ETIMEDOUT**
+        -
+          The underlying message environment timed out during the send
+          process.
+
+      * - **ETERM**
+        -
+          The underlying message environment is in a shutdown state.
+
+

 
 
 EXAMPLE
 -------
 
 
 
 EXAMPLE
 -------
 

-The following is a simple example of how the a wormhole is 
-created (rmr_wh_open) and then how ``rmr_wh_send_msg`` 
-function is used to send messages. Some error checking is 
-omitted for clarity. 
- 
- 
-:: 
- 
-  
- #include <rmr/rmr.h>    // system headers omitted for clarity
-  
- int main() {
-    rmr_whid_t whid = -1;   // wormhole id for sending
-    void* mrc;      //msg router context
-         int i;
-    rmr_mbuf_t*  sbuf;      // send buffer
-    int     count = 0;
-    int     norm_msg_size = 1500;  // most msg fit in this size
-  
-    mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE );
-    if( mrc == NULL ) {
-       fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" );
-       exit( 1 );
-    }
-  
-    while( ! rmr_ready( mrc ) ) {        // wait for routing table info
-       sleep( 1 );
-    }
-  
-    sbuf = rmr_alloc_msg( mrc, 2048 );
-  
-    while( 1 ) {
-      if( whid < 0 ) {
-        whid = rmr_wh_open( mrc, "localhost:6123" );  // open fails if endpoint refuses conn
-           if( RMR_WH_CONNECTED( wh ) ) {
-            snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
-            sbuf->len =  strlen( sbuf->payload );
-            sbuf = rmr_wh_send_msg( mrc, whid, sbuf );
-         }
-      }
-  
-      sleep( 5 );
-    }
- }
- 
+The following is a simple example of how the a wormhole is
+created (rmr_wh_open) and then how ``rmr_wh_send_msg``
+function is used to send messages. Some error checking is
+omitted for clarity.
+
+
+::
+
+
+  #include <rmr/rmr.h>    // system headers omitted for clarity
+
+  int main() {
+     rmr_whid_t whid = -1;   // wormhole id for sending
+     void* mrc;      //msg router context
+          int i;
+     rmr_mbuf_t*  sbuf;      // send buffer
+     int     count = 0;
+     int     norm_msg_size = 1500;  // most msg fit in this size
+
+     mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE );
+     if( mrc == NULL ) {
+        fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" );
+        exit( 1 );
+     }
+
+     while( ! rmr_ready( mrc ) ) {        // wait for routing table info
+        sleep( 1 );
+     }
+
+     sbuf = rmr_alloc_msg( mrc, 2048 );
+
+     while( 1 ) {
+       if( whid < 0 ) {
+         whid = rmr_wh_open( mrc, "localhost:6123" );  // open fails if endpoint refuses conn
+            if( RMR_WH_CONNECTED( wh ) ) {
+             snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
+             sbuf->len =  strlen( sbuf->payload );
+             sbuf = rmr_wh_send_msg( mrc, whid, sbuf );
+          }
+       }
+
+       sleep( 5 );
+     }
+  }
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), 
-rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3), 
-rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), 
-rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3), 
-rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3), 
-rmr_wh_state(3) 
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
+rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
+rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
+rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
+rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3),
+rmr_wh_state(3)

diff --git a/docs/rmr_wh_state.3.rst b/docs/rmr_wh_state.3.rst
index 6054932..805ae78 100644 (file)
--- a/docs/rmr_wh_state.3.rst
+++ b/docs/rmr_wh_state.3.rst
@@ -1,14 +1,14 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Man Page: rmr_wh_state 
-============================================================================================ 
- 
- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Man Page: rmr_wh_state
+============================================================================================
+
+

 
 
 RMR LIBRARY FUNCTIONS
 
 
 RMR LIBRARY FUNCTIONS


@@ -19,70 +19,70 @@ RMR LIBRARY FUNCTIONS
 NAME
 ----
 
 NAME
 ----
 

-rmr_wh_state 
+rmr_wh_state

 
 
 SYNOPSIS
 --------
 
 
 
 SYNOPSIS
 --------
 

- 
-:: 
- 
- #include <rmr/rmr.h>
-  
- int rmr_wh_state( void* vctx, rmr_whid_t whid )
- 
+
+::
+
+  #include <rmr/rmr.h>
+
+  int rmr_wh_state( void* vctx, rmr_whid_t whid )
+

 
 
 DESCRIPTION
 -----------
 
 
 
 DESCRIPTION
 -----------
 

-The ``rmr_wh_state`` function will return the current state 
-of the connection associated with the given wormhole (whid). 
-The return value indicates whether the connection is open 
-(RMR_OK), or closed (any other return value). 
- 
-When using some transport mechanisms (e.g. NNG), it may not 
-be possible for RMR to know the actual state and the 
-connection may always be reported as "open." 
+The ``rmr_wh_state`` function will return the current state
+of the connection associated with the given wormhole (whid).
+The return value indicates whether the connection is open
+(RMR_OK), or closed (any other return value).
+
+When using some transport mechanisms (e.g. NNG), it may not
+be possible for RMR to know the actual state and the
+connection may always be reported as "open."

 
 
 RETURN
 ------
 
 
 
 RETURN
 ------
 

-The following values are potential return values. 
- 
- 
-   .. list-table:: 
-     :widths: auto 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **RMR_OK** 
-       - 
-         The wormhole ID is valid and the connection is "open." 
-      
-     * - **RMR_ERR_WHID** 
-       - 
-         THe wormhole ID passed into the function was not valid. 
-      
-     * - **RMR_ERR_NOENDPT** 
-       - 
-         The wormhole is not open (not connected). 
-      
-     * - **RMR_ERR_BADARG** 
-       - 
-         The context passed to the function was nil or invalid. 
-      
-     * - **RMR_ERR_NOWHOPEN** 
-       - 
-         Wormholes have not been initialised (no wormhole open call 
-         has been made). 
-          
- 
+The following values are potential return values.
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMR_OK**
+        -
+          The wormhole ID is valid and the connection is "open."
+
+      * - **RMR_ERR_WHID**
+        -
+          THe wormhole ID passed into the function was not valid.
+
+      * - **RMR_ERR_NOENDPT**
+        -
+          The wormhole is not open (not connected).
+
+      * - **RMR_ERR_BADARG**
+        -
+          The context passed to the function was nil or invalid.
+
+      * - **RMR_ERR_NOWHOPEN**
+        -
+          Wormholes have not been initialised (no wormhole open call
+          has been made).
+
+

 
 
 SEE ALSO
 --------
 
 
 
 SEE ALSO
 --------
 

-rmr_wh_open(3), rmr_wh_send_msg(3), rmr_wh_close(3) 
+rmr_wh_open(3), rmr_wh_send_msg(3), rmr_wh_close(3)

diff --git a/docs/rt_tables.rst b/docs/rt_tables.rst
index 807c56e..c4f869e 100644 (file)
--- a/docs/rt_tables.rst
+++ b/docs/rt_tables.rst
@@ -1,646 +1,646 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-Route Table Guide 
-============================================================================================ 
--------------------------------------------------------------------------------------------- 
-RIC Message Router -- RMR 
--------------------------------------------------------------------------------------------- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+Route Table Guide
+============================================================================================
+--------------------------------------------------------------------------------------------
+RIC Message Router -- RMR
+--------------------------------------------------------------------------------------------

 
 
 Overview
 ========
 
 
 
 Overview
 ========
 

-Messages sent via the RIC Message Router (RMR) are routed to 
-an endpoint (another application) based on a combination of 
-the *message type* (MT) and *subscription ID* (SID) supplied 
-in the message. RMR determines the endpoint by matching the 
-MT and SID combination to an entry in a route table which has 
-been supplied dynamically by a *Route Manager* service, or as 
-a static table loaded during RMR initialisation. It is also 
-possible to route messages directly to an endpoint which is 
-the *managed entity* "owner," using the *managed entity ID* 
-(MEID). 
- 
-For most xAPP developers the format of the RMR route table is 
-not important beyond understanding how to create a static 
-table for local testing. For developers of a *Route Manager* 
-service, the need is certainly a requirement. This document 
-describes the overall syntax of a route table and the 
-interface between the *Route Manager* service and RMR. 
+Messages sent via the RIC Message Router (RMR) are routed to
+an endpoint (another application) based on a combination of
+the *message type* (MT) and *subscription ID* (SID) supplied
+in the message. RMR determines the endpoint by matching the
+MT and SID combination to an entry in a route table which has
+been supplied dynamically by a *Route Manager* service, or as
+a static table loaded during RMR initialisation. It is also
+possible to route messages directly to an endpoint which is
+the *managed entity* "owner," using the *managed entity ID*
+(MEID).
+
+For most xAPP developers the format of the RMR route table is
+not important beyond understanding how to create a static
+table for local testing. For developers of a *Route Manager*
+service, the need is certainly a requirement. This document
+describes the overall syntax of a route table and the
+interface between the *Route Manager* service and RMR.

 
 
 Contents of a Route Table
 =========================
 
 
 
 Contents of a Route Table
 =========================
 

-The table consists of a start record, one or more entry 
-records, and an end record. Each entry record defines one 
-message type, with an optional sender application, and the 
-endpoint(s) which accept the indicated message type. All 
-table records contain fields separated with vertical bars 
-(|), and allow for trailing comments with the standard shell 
-comment symbol (hash, #) provided that the start of the 
-comment is separated from the last token on the record by one 
-or more spaces. Leading and trailing white space in each 
-field is ignored. Figure 1 illustrates a very basic route 
-table with two message types, 1000 and 2000, and two 
-subscription IDs for message type 1000. 
- 
- 
-:: 
- 
+The table consists of a start record, one or more entry
+records, and an end record. Each entry record defines one
+message type, with an optional sender application, and the
+endpoint(s) which accept the indicated message type. All
+table records contain fields separated with vertical bars
+(|), and allow for trailing comments with the standard shell
+comment symbol (hash, #) provided that the start of the
+comment is separated from the last token on the record by one
+or more spaces. Leading and trailing white space in each
+field is ignored. Figure 1 illustrates a very basic route
+table with two message types, 1000 and 2000, and two
+subscription IDs for message type 1000.
+
+
+::
+

     newrt | start | rt-0928
     rte   | 2000  | logger:30311
     mse   | 1000  | 10 | forwarder:43086
     mse   | 1000  | 21 | app0:43086,app1:43086
     newrt | end   | 3
     newrt | start | rt-0928
     rte   | 2000  | logger:30311
     mse   | 1000  | 10 | forwarder:43086
     mse   | 1000  | 21 | app0:43086,app1:43086
     newrt | end   | 3

- 
-Figure 1: A basic route table. 
+
+Figure 1: A basic route table.

 
 
 Entry record syntax
 -------------------
 
 
 
 Entry record syntax
 -------------------
 

-Two types of table entries are supported for compatibility 
-with the original RMR implementation, but only the *mse* 
-entry type is needed and that should be the entry used when 
-creating new tables. The following shows the syntax for both 
-entry types: 
- 
- 
-:: 
- 
+Two types of table entries are supported for compatibility
+with the original RMR implementation, but only the *mse*
+entry type is needed and that should be the entry used when
+creating new tables. The following shows the syntax for both
+entry types:
+
+
+::
+

    rte | <msg-type>[,<sender-endpoint>] | <endpoint-group>[;<endpoint-group>;...]
    mse | <msg-type>[,<sender-endpoint>] | <sub-id> | <endpoint-group>[;<endpoint-group>;...]
    rte | <msg-type>[,<sender-endpoint>] | <endpoint-group>[;<endpoint-group>;...]
    mse | <msg-type>[,<sender-endpoint>] | <sub-id> | <endpoint-group>[;<endpoint-group>;...]

- 
- 
-Where: 
- 
- 
-    .. list-table:: 
-      :widths: 25,70 
-      :header-rows: 0 
-      :class: borderless 
-       
-      * - **mse, rte** 
-        - 
-          is the table entry type 
-       
-      * - **<msg-type>** 
-        - 
-          is the integer message type 
-       
-      * - **<sender-endpoint>** 
-        - 
-          is the endpoint description of the message sender; only that 
-          sender will read the entry from the table, so a single table 
-          may be used for all senders when a common message type is 
-          delivered to varying endpoints based on senders. If the 
-          sender endpoint is omitted from the entry, then the entry 
-          will be used by all applications. 
-       
-      * - **<sub-id>** 
-        - 
-          is the subscription id (integer) for subscription-based 
-          messages, or -1 if the message type is not 
-          subscription-based. An *mse* entry with a sub-id of -1 is the 
-          **same** as an *rte* entry with the same message type. 
-       
-      * - **<endpoint-group>** 
-        - 
-          is one or more, comma separated, endpoint descriptions. 
-           
- 
- 
-When an application sends a message with the indicated type, 
-the message will be sent to one endpoint in the group in a 
-round-robin ordering. If multiple endpoint groups are given, 
-then the message is sent to a member selected from each 
-group; 3 groups, then three messages will be sent. The first 
-group is required. 
+
+
+Where:
+
+
+    .. list-table::
+      :widths: 25,70
+      :header-rows: 0
+      :class: borderless
+
+      * - **mse, rte**
+        -
+          is the table entry type
+
+      * - **<msg-type>**
+        -
+          is the integer message type
+
+      * - **<sender-endpoint>**
+        -
+          is the endpoint description of the message sender; only that
+          sender will read the entry from the table, so a single table
+          may be used for all senders when a common message type is
+          delivered to varying endpoints based on senders. If the
+          sender endpoint is omitted from the entry, then the entry
+          will be used by all applications.
+
+      * - **<sub-id>**
+        -
+          is the subscription id (integer) for subscription-based
+          messages, or -1 if the message type is not
+          subscription-based. An *mse* entry with a sub-id of -1 is the
+          **same** as an *rte* entry with the same message type.
+
+      * - **<endpoint-group>**
+        -
+          is one or more, comma separated, endpoint descriptions.
+
+
+
+When an application sends a message with the indicated type,
+the message will be sent to one endpoint in the group in a
+round-robin ordering. If multiple endpoint groups are given,
+then the message is sent to a member selected from each
+group; 3 groups, then three messages will be sent. The first
+group is required.

 
 
 Line separation
 ---------------
 
 
 
 Line separation
 ---------------
 

-Table entries **must** end with a record termination sequence 
-which may be one of the following three sequences: 
- 
- 
-* a single newline (\\n) 
-* a DOS style CRLF pair (\\r\\n) 
-* a single carriage return (\\r) 
- 
- 
-Care must be taken when manually editing a static table; some 
-editors do **not** add a final record termination sequence to 
-the last line of a file. RMR expects the final record to have 
-a termination sequence to ensure that the record was not 
-truncated (especially important when receiving dynamic 
-tables). 
+Table entries **must** end with a record termination sequence
+which may be one of the following three sequences:
+
+
+* a single newline (\\n)
+* a DOS style CRLF pair (\\r\\n)
+* a single carriage return (\\r)
+
+
+Care must be taken when manually editing a static table; some
+editors do **not** add a final record termination sequence to
+the last line of a file. RMR expects the final record to have
+a termination sequence to ensure that the record was not
+truncated (especially important when receiving dynamic
+tables).

 
 
 Table framing
 -------------
 
 
 
 Table framing
 -------------
 

-The route table parser within RMR assumes that route table 
-entries are sent via RMR messages as a stream. To ensure 
-synchronisation and prevent malformed tables because of 
-broken sessions or lost packets, each table must begin and 
-end with an *newrt* record. Each *newrt* record has one of 
-two possible syntax layouts as described below. 
- 
- 
-:: 
- 
+The route table parser within RMR assumes that route table
+entries are sent via RMR messages as a stream. To ensure
+synchronisation and prevent malformed tables because of
+broken sessions or lost packets, each table must begin and
+end with an *newrt* record. Each *newrt* record has one of
+two possible syntax layouts as described below.
+
+
+::
+

     newrt | begin [| table-id-string]
     newrt | end  [| record-count]
     newrt | begin [| table-id-string]
     newrt | end  [| record-count]

- 
-Figure 2: Illustration of the newrt records in the table. 
- 
-The *table-id-string* is an optional string which is used by 
-RMR when sending an acknowledgement back to the *Route 
-Manager* service (see the *Route Manager Interface* section 
-for more details). If a *record-count* is given as the final 
-field on the *end* record, RMR will verify that the number of 
-*mse* and *rte* entries in the table matches the count; if 
-there is a mismatch in values the table is not used. 
+
+Figure 2: Illustration of the newrt records in the table.
+
+The *table-id-string* is an optional string which is used by
+RMR when sending an acknowledgement back to the *Route
+Manager* service (see the *Route Manager Interface* section
+for more details). If a *record-count* is given as the final
+field on the *end* record, RMR will verify that the number of
+*mse* and *rte* entries in the table matches the count; if
+there is a mismatch in values the table is not used.

 
 
 Comments, spaces, and blank lines
 ---------------------------------
 
 
 
 Comments, spaces, and blank lines
 ---------------------------------
 

-Comments may be placed to the right of any table entry line 
-using the standard shell comment symbol (#). The start of a 
-comment must be separated from any previous record content by 
-at least one space or tab. Complete lines are treated as 
-comments when the first non-whitespace character of a line is 
-a comment symbol. Blank lines are also ignored. 
- 
-Fields on table records are separated using the vertical bar 
-(|) character. Any white space (tabs or spaces) which appear 
-immediately before or after a separator are ignored. 
+Comments may be placed to the right of any table entry line
+using the standard shell comment symbol (#). The start of a
+comment must be separated from any previous record content by
+at least one space or tab. Complete lines are treated as
+comments when the first non-whitespace character of a line is
+a comment symbol. Blank lines are also ignored.
+
+Fields on table records are separated using the vertical bar
+(|) character. Any white space (tabs or spaces) which appear
+immediately before or after a separator are ignored.

 
 
 Endpoint Description
 --------------------
 
 
 
 Endpoint Description
 --------------------
 

-The endpoint description is either the hostname or IP address 
-followed by a port number; the two are separated by a single 
-colon. The illustration below assumes that host names (e.g. 
-forwarder and app1) are defined; they also make the tables 
-easier to read. The port number given is the port number that 
-the user application provides to RMR when the RMR 
-initialisation function is invoked (and thus is the port that 
-RMR is listening on). 
+The endpoint description is either the hostname or IP address
+followed by a port number; the two are separated by a single
+colon. The illustration below assumes that host names (e.g.
+forwarder and app1) are defined; they also make the tables
+easier to read. The port number given is the port number that
+the user application provides to RMR when the RMR
+initialisation function is invoked (and thus is the port that
+RMR is listening on).

 
 
 Table Mechanics
 ===============
 
 
 
 Table Mechanics
 ===============
 

-Creating a table from the two entry types is fairly simple, 
-however there are some subtleties which should be pointed out 
-to avoid unexpected behaviour. For this discussion the 
-following complete table will be used. 
- 
-.. list-table:: 
-  :widths: 75,10 
-  :header-rows: 0 
-  :class: borderless 
- 
- 
-  * -  
-        
-       :: 
-        
-           newrt | start | rt-0928
-           rte | 2000 | logger:30311
-           mse | 1000 | 10 | forwarder:43086
-           mse | 1000,forwarder:43086 | 10 | app2:43086
-           mse | 1000 | -1 | app0:43086,app1:43086; logger:20311
-           newrt | end | 4
-        
-    -  
-        
-       :: 
-        
-         (1)
-         (2)
-         (3)
-         (4)
-         (5)
-         (6)
-        
-        
-Figure 3: A complete RMR routing table (line numbers to the 
-right for reference). 
+Creating a table from the two entry types is fairly simple,
+however there are some subtleties which should be pointed out
+to avoid unexpected behaviour. For this discussion the
+following complete table will be used.
+
+.. list-table::
+  :widths: 75,10
+  :header-rows: 0
+  :class: borderless
+
+
+  * -
+
+        ::
+
+            newrt | start | rt-0928
+            rte | 2000 | logger:30311
+            mse | 1000 | 10 | forwarder:43086
+            mse | 1000,forwarder:43086 | 10 | app2:43086
+            mse | 1000 | -1 | app0:43086,app1:43086; logger:20311
+            newrt | end | 4
+
+    -
+
+        ::
+
+          (1)
+          (2)
+          (3)
+          (4)
+          (5)
+          (6)
+
+
+Figure 3: A complete RMR routing table (line numbers to the
+right for reference).

 
 
 Table Entry Ordering
 --------------------
 
 
 
 Table Entry Ordering
 --------------------
 

-Whether a table is read from a file on disk, or is received 
-from a *Route Manager* service, RMR parses the records to 
-build an internal route table keeping only the relevant 
-information. Entries are read in the order they appear (from 
-the file or in messages received), and RMR will use only one 
-entry for each MT/SID pair. 
- 
-For most tables, the ordering of entries is not important, 
-but when there are entries which duplicate the MT/SID pair 
-ordering becomes significant. RMR will use the **last** valid 
-entry for a MT/SID pair that it encounters. An entry is 
-considered valid if there is no sender identified with the 
-message type (line 3), and when the sender (host and port) 
-match the the applications' location and the port provided to 
-RMR for listening. 
- 
-Using the table in figure 3 as an example, there are two 
-entries which match the MT/SID pair of 1000/10. When this 
-table is parsed on any host, RMR will recognise and add the 
-first entry (line 3) to the internal representation; this 
-entry is valid for all applications. The second 1000/10 entry 
-(line 4) is valid when the table is parsed on the *forwarder* 
-host, and only by the application which is listening on port 
-43086. For this application the entry will override the more 
-generic entry for the MT/SID combination. 
- 
-As a rule, the ordering of entries for a given MT/SID pair 
-should be from most generic to most specific. 
+Whether a table is read from a file on disk, or is received
+from a *Route Manager* service, RMR parses the records to
+build an internal route table keeping only the relevant
+information. Entries are read in the order they appear (from
+the file or in messages received), and RMR will use only one
+entry for each MT/SID pair.
+
+For most tables, the ordering of entries is not important,
+but when there are entries which duplicate the MT/SID pair
+ordering becomes significant. RMR will use the **last** valid
+entry for a MT/SID pair that it encounters. An entry is
+considered valid if there is no sender identified with the
+message type (line 3), and when the sender (host and port)
+match the the applications' location and the port provided to
+RMR for listening.
+
+Using the table in figure 3 as an example, there are two
+entries which match the MT/SID pair of 1000/10. When this
+table is parsed on any host, RMR will recognise and add the
+first entry (line 3) to the internal representation; this
+entry is valid for all applications. The second 1000/10 entry
+(line 4) is valid when the table is parsed on the *forwarder*
+host, and only by the application which is listening on port
+43086. For this application the entry will override the more
+generic entry for the MT/SID combination.
+
+As a rule, the ordering of entries for a given MT/SID pair
+should be from most generic to most specific.

 
 
 Route Manager Communications
 ============================
 
 
 
 Route Manager Communications
 ============================
 

-During initialisation RMR will use the value of the 
-``RMR_RTG_SVC`` environment variable to connect to the *Route 
-Manager* service in order to request a route table. The 
-connection between RMR and the *Route Manager* is also an RMR 
-session and thus RMR messages will be used to exchange 
-requests and responses. 
+During initialisation RMR will use the value of the
+``RMR_RTG_SVC`` environment variable to connect to the *Route
+Manager* service in order to request a route table. The
+connection between RMR and the *Route Manager* is also an RMR
+session and thus RMR messages will be used to exchange
+requests and responses.

 
 
 Table Request
 -------------
 
 
 
 Table Request
 -------------
 

-During initialisation, RMR establishes a wormhole connection 
-to the *Route Manager* and sends a message type of 21 to 
-request a new table. RMR will continue to send table requests 
-until a table is received and accepted; in other words it is 
-fine for the *Route Manager* to ignore the requests if it is 
-not ready to respond. 
+During initialisation, RMR establishes a wormhole connection
+to the *Route Manager* and sends a message type of 21 to
+request a new table. RMR will continue to send table requests
+until a table is received and accepted; in other words it is
+fine for the *Route Manager* to ignore the requests if it is
+not ready to respond.

 
 
 Sending Tables To RMR
 ---------------------
 
 
 
 Sending Tables To RMR
 ---------------------
 

-Table entry data is expected to arrive via RMR message with a 
-message type of 20. The message may contain one or more 
-entries provided that the entries are newline separated. 
-Current versions of RMR support very large messages, however 
-to ensure compatibility with an xAPP built using an older 
-version of RMR (pre 3.8), messages should be limited to 4 
-KiB. 
+Table entry data is expected to arrive via RMR message with a
+message type of 20. The message may contain one or more
+entries provided that the entries are newline separated.
+Current versions of RMR support very large messages, however
+to ensure compatibility with an xAPP built using an older
+version of RMR (pre 3.8), messages should be limited to 4
+KiB.

 
 
 Table Acceptance and Acknowledgement
 ------------------------------------
 
 
 
 Table Acceptance and Acknowledgement
 ------------------------------------
 

-When RMR receives the table end entry (newrt|end), it will 
-send a state message back to the *Route Manager* to indicate 
-the state of the received table. The message type is 22 and 
-the payload will contain UTF-8 tokens which indicate the 
-state. The second token will be the *table ID* supplied on 
-the start record, or the string "<id-missing>." When the 
-state is an error state, RMR might add a final set of tokens 
-which contain the reason for the failure. 
- 
-Upon receipt of a status message which indicates an "OK" 
-response, the *Route Manager* can assume that the table has 
-been installed and is in use. Any other response indicates 
-that RMR did not use the table and has dropped it; the 
-previous table is still in use. 
+When RMR receives the table end entry (newrt|end), it will
+send a state message back to the *Route Manager* to indicate
+the state of the received table. The message type is 22 and
+the payload will contain UTF-8 tokens which indicate the
+state. The second token will be the *table ID* supplied on
+the start record, or the string "<id-missing>." When the
+state is an error state, RMR might add a final set of tokens
+which contain the reason for the failure.
+
+Upon receipt of a status message which indicates an "OK"
+response, the *Route Manager* can assume that the table has
+been installed and is in use. Any other response indicates
+that RMR did not use the table and has dropped it; the
+previous table is still in use.

 
 
 Using A Static Route Table
 --------------------------
 
 
 
 Using A Static Route Table
 --------------------------
 

-A static route table can be provided to assist with testing, 
-or to provide a bootstrap set of route information until a 
-dynamic table is received from a routing manager. The 
-environment variable ``RMR_SEED_RT`` is checked during RMR 
-initialisation and if set is expected to reference a file 
-containing a route table. This table will be loaded and used 
-until overlaid by a table sent by the *Route Manager*. 
- 
-For testing, the static table will be reloaded periodically 
-if the ``RMR_RTG_SVC`` environment variable is set to -1. 
-When this testing feature is enabled RMR will not listen for 
-*Route Manager* connections, nor will it attempt to request a 
-dynamic table. 
+A static route table can be provided to assist with testing,
+or to provide a bootstrap set of route information until a
+dynamic table is received from a routing manager. The
+environment variable ``RMR_SEED_RT`` is checked during RMR
+initialisation and if set is expected to reference a file
+containing a route table. This table will be loaded and used
+until overlaid by a table sent by the *Route Manager*.
+
+For testing, the static table will be reloaded periodically
+if the ``RMR_RTG_SVC`` environment variable is set to -1.
+When this testing feature is enabled RMR will not listen for
+*Route Manager* connections, nor will it attempt to request a
+dynamic table.

 
 
 Routing Using MEID
 ==================
 
 
 
 Routing Using MEID
 ==================
 

-Starting with version 1.13.0, RMR provides the ability to 
-select the endpoint for a message based on the MEID (managed 
-entity ID) in the message, rather than selecting the endpoint 
-from the round-robin list for the matching route table entry. 
-When the MEID is used, the message is sent to the endpoint 
-which *owns,* or is responsible for the managed entity. 
-Should the *owner* change messages will be routed to the new 
-owner when the route table is updated. To make use of MEID 
-routing, there must be one or more route table entries which 
-list the special endpoint name ``%meid`` instead of providing 
-a round robin list. As an example, consider the following 
-route table entry: 
- 
- 
-:: 
- 
-   mse| 1000,forwarder:43086 | 10 | %meid
- 
-Figure 4: Sample route entry with the meid flag. 
- 
-The final field of the entry doesn't specify a round-robin 
-group which means that when an application attempts to send a 
-message with type 1000, and the subscription ID of 10, the 
-MEID in the message will be used to select the endpoint. 
+Starting with version 1.13.0, RMR provides the ability to
+select the endpoint for a message based on the MEID (managed
+entity ID) in the message, rather than selecting the endpoint
+from the round-robin list for the matching route table entry.
+When the MEID is used, the message is sent to the endpoint
+which *owns,* or is responsible for the managed entity.
+Should the *owner* change messages will be routed to the new
+owner when the route table is updated. To make use of MEID
+routing, there must be one or more route table entries which
+list the special endpoint name ``%meid`` instead of providing
+a round robin list. As an example, consider the following
+route table entry:
+
+
+::
+
+    mse| 1000,forwarder:43086 | 10 | %meid
+
+Figure 4: Sample route entry with the meid flag.
+
+The final field of the entry doesn't specify a round-robin
+group which means that when an application attempts to send a
+message with type 1000, and the subscription ID of 10, the
+MEID in the message will be used to select the endpoint.

 
 
 MEID endpoint selection
 -----------------------
 
 
 
 MEID endpoint selection
 -----------------------
 

-To select an endpoint for the message based on the MEID in a 
-message, RMR must know which endpoint owns the MEID. This 
-information, known as an MEID map, is provided by the *Route 
-Manager* over the same communication path as the route table 
-is supplied. The following is the syntax for an MEID map. 
- 
- 
-:: 
- 
-   meid_map | start | <table-id>
-   mme_ar | <owner-endpoint> | <meid> [<meid>...]
-   mme_del | <meid> [<meid>...]
-   meid_map | end | <count> [| <md5sum> ]
- 
-Figure 5: Meid map table. 
- 
-The mme_ar records are add/update records and allow for the 
-list of MEIDs to be associated with (owned by) the indicated 
-endpoint. The <owner-endpoint> is the hostname:port, or IP 
-address and port, of the application which owns the MEID and 
-thus should receive any messages which are routed based on a 
-route table entry with %meid as the round-robin group. The 
-mme_del records allow for MEIDs to be deleted from RMR's 
-view. Finally, the <count> is the number of add/replace and 
-delete records which were sent; if RMR does not match the 
-<count> value to the number of records, then it will not add 
-the data to the table. Updates only need to list the 
-ownership changes that are necessary; in other words, the 
-*Route Manager* does not need to supply all of the MEID 
-relationships with each update. 
- 
-The optional <md5sum> field on the end record should be the 
-MD5 hash of all of the records between the start and end 
-records. This allows for a precise verification that the 
-transmitted data was correctly received. 
- 
-If a static seed file is being used for the route table, a 
-second section can be given which supplies the MEID map. The 
-following is a small example of a seed file: 
- 
- 
-:: 
- 
-  newrt|start | id-64306
-  mse|0|-1| %meid
-  mse|1|-1|172.19.0.2:4560
-  mse|2|-1|172.19.0.2:4560
-  mse|3|-1|172.19.0.2:4560
-  mse|4|-1|172.19.0.2:4560
-  mse|5|-1|172.19.0.2:4560
-  newrt|end
-  
-  meid_map | start | id-028919
-  mme_ar| 172.19.0.2:4560 | meid000 meid001 meid002 meid003 meid004 meid005
-  mme_ar| 172.19.0.42:4560 | meid100 meid101 meid102 meid103
-  mme_del | meid1000
-  meid_map | end | 1
- 
-Figure 6: Illustration of both a route table and meid map in 
-the same file. 
- 
-The tables above will route all messages with a message type 
-of 0 based on the MEID. There are 10 meids which are owned by 
-two different endpoints. The table also deletes the MEID 
-meid1000 from RMR's view. 
+To select an endpoint for the message based on the MEID in a
+message, RMR must know which endpoint owns the MEID. This
+information, known as an MEID map, is provided by the *Route
+Manager* over the same communication path as the route table
+is supplied. The following is the syntax for an MEID map.
+
+
+::
+
+    meid_map | start | <table-id>
+    mme_ar | <owner-endpoint> | <meid> [<meid>...]
+    mme_del | <meid> [<meid>...]
+    meid_map | end | <count> [| <md5sum> ]
+
+Figure 5: Meid map table.
+
+The mme_ar records are add/update records and allow for the
+list of MEIDs to be associated with (owned by) the indicated
+endpoint. The <owner-endpoint> is the hostname:port, or IP
+address and port, of the application which owns the MEID and
+thus should receive any messages which are routed based on a
+route table entry with %meid as the round-robin group. The
+mme_del records allow for MEIDs to be deleted from RMR's
+view. Finally, the <count> is the number of add/replace and
+delete records which were sent; if RMR does not match the
+<count> value to the number of records, then it will not add
+the data to the table. Updates only need to list the
+ownership changes that are necessary; in other words, the
+*Route Manager* does not need to supply all of the MEID
+relationships with each update.
+
+The optional <md5sum> field on the end record should be the
+MD5 hash of all of the records between the start and end
+records. This allows for a precise verification that the
+transmitted data was correctly received.
+
+If a static seed file is being used for the route table, a
+second section can be given which supplies the MEID map. The
+following is a small example of a seed file:
+
+
+::
+
+   newrt|start | id-64306
+   mse|0|-1| %meid
+   mse|1|-1|172.19.0.2:4560
+   mse|2|-1|172.19.0.2:4560
+   mse|3|-1|172.19.0.2:4560
+   mse|4|-1|172.19.0.2:4560
+   mse|5|-1|172.19.0.2:4560
+   newrt|end
+
+   meid_map | start | id-028919
+   mme_ar| 172.19.0.2:4560 | meid000 meid001 meid002 meid003 meid004 meid005
+   mme_ar| 172.19.0.42:4560 | meid100 meid101 meid102 meid103
+   mme_del | meid1000
+   meid_map | end | 1
+
+Figure 6: Illustration of both a route table and meid map in
+the same file.
+
+The tables above will route all messages with a message type
+of 0 based on the MEID. There are 10 meids which are owned by
+two different endpoints. The table also deletes the MEID
+meid1000 from RMR's view.

 
 
 Reserved Message Types
 ======================
 
 
 
 Reserved Message Types
 ======================
 

-RMR is currently reserving message types in the range of 0 
-through 99 (inclusive) for its own use. Please do not use 
-these types in any production or test environment as the 
-results may be undesired. 
- 
+RMR is currently reserving message types in the range of 0
+through 99 (inclusive) for its own use. Please do not use
+these types in any production or test environment as the
+results may be undesired.
+

 
 
 Appendix A -- Glossary
 ======================
 
 
 
 Appendix A -- Glossary
 ======================
 

-Many terms in networking can be interpreted with multiple 
-meanings, and several terms used in various RMR documentation 
-are RMR specific. The following definitions are the meanings 
-of terms used within RMR documentation and should help the 
-reader to understand the intent of meaning. 
- 
-   .. list-table:: 
-     :widths: 25,70 
-     :header-rows: 0 
-     :class: borderless 
-      
-     * - **application** 
-       - 
-         A programme which uses RMR to send and/or receive messages 
-         to/from another RMR based application. 
-      
-     * - **Critical error** 
-       - 
-         An error that RMR has encountered which will prevent further 
-         successful processing by RMR. Critical errors usually 
-         indicate that the application should abort. 
-      
-     * - **Endpoint** 
-       - 
-         An RMR based application that is defined as being capable of 
-         receiving one or more types of messages (as defined by a 
-         *routing key.*) 
-      
-     * - **Environment variable** 
-       - 
-         A key/value pair which is set externally to the application, 
-         but which is available to the application (and referenced 
-         libraries) through the ``getenv`` system call. Environment 
-         variables are the main method of communicating information 
-         such as port numbers to RMR. 
-      
-     * - **Error** 
-       - 
-         An abnormal condition that RMR has encountered, but will not 
-         affect the overall processing by RMR, but may impact certain 
-         aspects such as the ability to communicate with a specific 
-         endpoint. Errors generally indicate that something, usually 
-         external to RMR, must be addressed. 
-      
-     * - **Host name** 
-       - 
-         The name of the host as returned by the ``gethostbyname`` 
-         system call. In a containerised environment this might be the 
-         container or service name depending on how the container is 
-         started. From RMR's point of view, a host name can be used to 
-         resolve an *endpoint* definition in a *route* table.) 
-      
-     * - **IP** 
-       - 
-         Internet protocol. A low level transmission protocol which 
-         governs the transmission of datagrams across network 
-         boundaries. 
-      
-     * - **Listen socket** 
-       - 
-         A *TCP* socket used to await incoming connection requests. 
-         Listen sockets are defined by an interface and port number 
-         combination where the port number is unique for the 
-         interface. 
-      
-     * - **Message** 
-       - 
-         A series of bytes transmitted from the application to another 
-         RMR based application. A message is comprised of RMR specific 
-         data (a header), and application data (a payload). 
-      
-     * - **Message buffer** 
-       - 
-         A data structure used to describe a message which is to be 
-         sent or has been received. The message buffer includes the 
-         payload length, message type, message source, and other 
-         information. 
-      
-     * - **Message type** 
-       - 
-         A signed integer (0-32000) which identifies the type of 
-         message being transmitted, and is one of the two components 
-         of a *routing key.* See *Subscription ID.* 
-      
-     * - **Payload** 
-       - 
-         The portion of a message which holds the user data to be 
-         transmitted to the remote *endpoint.* The payload contents 
-         are completely application defined. 
-      
-     * - **RMR context** 
-       - 
-         A set of information which defines the current state of the 
-         underlying transport connections that RMR is managing. The 
-         application will be give a context reference (pointer) that 
-         is supplied to most RMR functions as the first parameter. 
-      
-     * - **Round robin** 
-       - 
-         The method of selecting an *endpoint* from a list such that 
-         all *endpoints* are selected before starting at the head of 
-         the list. 
-      
-     * - **Route table** 
-       - 
-         A series of "rules" which define the possible *endpoints* for 
-         each *routing key.* 
-      
-     * - **Route table manager** 
-       - 
-         An application responsible for building a *route table* and 
-         then distributing it to all applicable RMR based 
-         applications. 
-      
-     * - **Routing** 
-       - 
-         The process of selecting an *endpoint* which will be the 
-         recipient of a message. 
-      
-     * - **Routing key** 
-       - 
-         A combination of *message type* and *subscription ID* which 
-         RMR uses to select the destination *endpoint* when sending a 
-         message. 
-      
-     * - **Source** 
-       - 
-         The sender of a message. 
-      
-     * - **Subscription ID** 
-       - 
-         A signed integer value (0-32000) which identifies the 
-         subscription characteristic of a message. It is used in 
-         conjunction with the *message type* to determine the *routing 
-         key.* 
-      
-     * - **Target** 
-       - 
-         The *endpoint* selected to receive a message. 
-      
-     * - **TCP** 
-       - 
-         Transmission Control Protocol. A connection based internet 
-         protocol which provides for lossless packet transportation, 
-         usually over IP. 
-      
-     * - **Thread** 
-       - 
-         Also called a *process thread, or pthread.* This is a 
-         lightweight process which executes in concurrently with the 
-         application and shares the same address space. RMR uses 
-         threads to manage asynchronous functions such as route table 
-         updates. 
-      
-     * - **Trace information** 
-       - 
-         An optional portion of the message buffer that the 
-         application may populate with data that allows for tracing 
-         the progress of the transaction or application activity 
-         across components. RMR makes no use of this data. 
-      
-     * - **Transaction ID** 
-       - 
-         A fixed number of bytes in the *message* buffer) which the 
-         application may populate with information related to the 
-         transaction. RMR makes use of the transaction ID for matching 
-         response messages with the &c function is used to send a 
-         message. 
-      
-     * - **Transient failure** 
-       - 
-         An error state that is believed to be short lived and that 
-         the operation, if retried by the application, might be 
-         successful. C programmers will recognise this as 
-         ``EAGAIN.`` 
-      
-     * - **Warning** 
-       - 
-         A warning occurs when RMR has encountered something that it 
-         believes isn't correct, but has a defined work round. 
-      
-     * - **Wormhole** 
-       - 
-         A direct connection managed by RMR between the user 
-         application and a remote, RMR based, application. 
-          
- 
- 
+Many terms in networking can be interpreted with multiple
+meanings, and several terms used in various RMR documentation
+are RMR specific. The following definitions are the meanings
+of terms used within RMR documentation and should help the
+reader to understand the intent of meaning.
+
+    .. list-table::
+      :widths: 25,70
+      :header-rows: 0
+      :class: borderless
+
+      * - **application**
+        -
+          A programme which uses RMR to send and/or receive messages
+          to/from another RMR based application.
+
+      * - **Critical error**
+        -
+          An error that RMR has encountered which will prevent further
+          successful processing by RMR. Critical errors usually
+          indicate that the application should abort.
+
+      * - **Endpoint**
+        -
+          An RMR based application that is defined as being capable of
+          receiving one or more types of messages (as defined by a
+          *routing key.*)
+
+      * - **Environment variable**
+        -
+          A key/value pair which is set externally to the application,
+          but which is available to the application (and referenced
+          libraries) through the ``getenv`` system call. Environment
+          variables are the main method of communicating information
+          such as port numbers to RMR.
+
+      * - **Error**
+        -
+          An abnormal condition that RMR has encountered, but will not
+          affect the overall processing by RMR, but may impact certain
+          aspects such as the ability to communicate with a specific
+          endpoint. Errors generally indicate that something, usually
+          external to RMR, must be addressed.
+
+      * - **Host name**
+        -
+          The name of the host as returned by the ``gethostbyname``
+          system call. In a containerised environment this might be the
+          container or service name depending on how the container is
+          started. From RMR's point of view, a host name can be used to
+          resolve an *endpoint* definition in a *route* table.)
+
+      * - **IP**
+        -
+          Internet protocol. A low level transmission protocol which
+          governs the transmission of datagrams across network
+          boundaries.
+
+      * - **Listen socket**
+        -
+          A *TCP* socket used to await incoming connection requests.
+          Listen sockets are defined by an interface and port number
+          combination where the port number is unique for the
+          interface.
+
+      * - **Message**
+        -
+          A series of bytes transmitted from the application to another
+          RMR based application. A message is comprised of RMR specific
+          data (a header), and application data (a payload).
+
+      * - **Message buffer**
+        -
+          A data structure used to describe a message which is to be
+          sent or has been received. The message buffer includes the
+          payload length, message type, message source, and other
+          information.
+
+      * - **Message type**
+        -
+          A signed integer (0-32000) which identifies the type of
+          message being transmitted, and is one of the two components
+          of a *routing key.* See *Subscription ID.*
+
+      * - **Payload**
+        -
+          The portion of a message which holds the user data to be
+          transmitted to the remote *endpoint.* The payload contents
+          are completely application defined.
+
+      * - **RMR context**
+        -
+          A set of information which defines the current state of the
+          underlying transport connections that RMR is managing. The
+          application will be give a context reference (pointer) that
+          is supplied to most RMR functions as the first parameter.
+
+      * - **Round robin**
+        -
+          The method of selecting an *endpoint* from a list such that
+          all *endpoints* are selected before starting at the head of
+          the list.
+
+      * - **Route table**
+        -
+          A series of "rules" which define the possible *endpoints* for
+          each *routing key.*
+
+      * - **Route table manager**
+        -
+          An application responsible for building a *route table* and
+          then distributing it to all applicable RMR based
+          applications.
+
+      * - **Routing**
+        -
+          The process of selecting an *endpoint* which will be the
+          recipient of a message.
+
+      * - **Routing key**
+        -
+          A combination of *message type* and *subscription ID* which
+          RMR uses to select the destination *endpoint* when sending a
+          message.
+
+      * - **Source**
+        -
+          The sender of a message.
+
+      * - **Subscription ID**
+        -
+          A signed integer value (0-32000) which identifies the
+          subscription characteristic of a message. It is used in
+          conjunction with the *message type* to determine the *routing
+          key.*
+
+      * - **Target**
+        -
+          The *endpoint* selected to receive a message.
+
+      * - **TCP**
+        -
+          Transmission Control Protocol. A connection based internet
+          protocol which provides for lossless packet transportation,
+          usually over IP.
+
+      * - **Thread**
+        -
+          Also called a *process thread, or pthread.* This is a
+          lightweight process which executes in concurrently with the
+          application and shares the same address space. RMR uses
+          threads to manage asynchronous functions such as route table
+          updates.
+
+      * - **Trace information**
+        -
+          An optional portion of the message buffer that the
+          application may populate with data that allows for tracing
+          the progress of the transaction or application activity
+          across components. RMR makes no use of this data.
+
+      * - **Transaction ID**
+        -
+          A fixed number of bytes in the *message* buffer) which the
+          application may populate with information related to the
+          transaction. RMR makes use of the transaction ID for matching
+          response messages with the &c function is used to send a
+          message.
+
+      * - **Transient failure**
+        -
+          An error state that is believed to be short lived and that
+          the operation, if retried by the application, might be
+          successful. C programmers will recognise this as
+          ``EAGAIN.``
+
+      * - **Warning**
+        -
+          A warning occurs when RMR has encountered something that it
+          believes isn't correct, but has a defined work round.
+
+      * - **Wormhole**
+        -
+          A direct connection managed by RMR between the user
+          application and a remote, RMR based, application.
+
+
+

diff --git a/docs/user-guide.rst b/docs/user-guide.rst
index a825c50..e12e009 100644 (file)
--- a/docs/user-guide.rst
+++ b/docs/user-guide.rst
@@ -1,892 +1,892 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
-.. SPDX-License-Identifier: CC-BY-4.0 
-.. CAUTION: this document is generated from source in doc/src/rtd. 
-.. To make changes edit the source and recompile the document. 
-.. Do NOT make changes directly to .rst or .md files. 
- 
-============================================================================================ 
-User's Guide 
-============================================================================================ 
--------------------------------------------------------------------------------------------- 
-RIC Message Router -- RMR 
--------------------------------------------------------------------------------------------- 
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+============================================================================================
+User's Guide
+============================================================================================
+--------------------------------------------------------------------------------------------
+RIC Message Router -- RMR
+--------------------------------------------------------------------------------------------

 
 
 Overview
 ========
 
 
 
 Overview
 ========
 

-The RIC Message Router (RMR) is a library for peer-to-peer 
-communication. Applications use the library to send and 
-receive messages where the message routing and endpoint 
-selection is based on the message type rather than DNS host 
-name-IP port combinations. The library provides the following 
-major features: 
- 
- 
-* Routing and endpoint selection is based on *message type.* 
-   
-* Application is insulated from the underlying transport 
-  mechanism and/or protocols. 
-   
-* Message distribution (round robin or fanout) is selectable 
-  by message type. 
-   
-* Route management updates are received and processed 
-  asynchronously and without overt application involvement. 
- 
- 
+The RIC Message Router (RMR) is a library for peer-to-peer
+communication. Applications use the library to send and
+receive messages where the message routing and endpoint
+selection is based on the message type rather than DNS host
+name-IP port combinations. The library provides the following
+major features:
+
+
+* Routing and endpoint selection is based on *message type.*
+
+* Application is insulated from the underlying transport
+  mechanism and/or protocols.
+
+* Message distribution (round robin or fanout) is selectable
+  by message type.
+
+* Route management updates are received and processed
+  asynchronously and without overt application involvement.
+
+

 
 
 Purpose
 -------
 
 
 
 Purpose
 -------
 

-RMR's main purpose is to provide an application with the 
-ability to send and receive messages to/from other peer 
-applications with minimal effort on the application's part. 
-To achieve this, RMR manages all endpoint information, 
-connections, and routing information necessary to establish 
-and maintain communication. From the application's point of 
-view, all that is required to send a message is to allocate 
-(via RMR) a message buffer, add the payload data, and set the 
-message type. To receive a message, the application needs 
-only to invoke the receive function; when a message arrives a 
-message buffer will be returned as the function result. 
+RMR's main purpose is to provide an application with the
+ability to send and receive messages to/from other peer
+applications with minimal effort on the application's part.
+To achieve this, RMR manages all endpoint information,
+connections, and routing information necessary to establish
+and maintain communication. From the application's point of
+view, all that is required to send a message is to allocate
+(via RMR) a message buffer, add the payload data, and set the
+message type. To receive a message, the application needs
+only to invoke the receive function; when a message arrives a
+message buffer will be returned as the function result.

 
 
 Message Routing
 ---------------
 
 
 
 Message Routing
 ---------------
 

-Applications are required to place a message type into a 
-message before sending, and may optionally add a subscription 
-ID when appropriate. The combination of message type, and 
-subscription ID are refered to as the *message key,* and is 
-used to match an entry in a routing table which provides the 
-possible endpoints expecting to receive messages with the 
-matching key. 
+Applications are required to place a message type into a
+message before sending, and may optionally add a subscription
+ID when appropriate. The combination of message type, and
+subscription ID are refered to as the *message key,* and is
+used to match an entry in a routing table which provides the
+possible endpoints expecting to receive messages with the
+matching key.

 
 
 Round Robin Delivery
 --------------------
 
 
 
 Round Robin Delivery
 --------------------
 

-An endpoint from RMR's perspective is an application to which 
-RMR may establish a connection, and expect to send messages 
-with one or more defined message keys. Each entry in the 
-route table consists of one or more endpoint groups, called 
-round robin groups. When a message matches a specific entry, 
-the entry's groups are used to select the destination of the 
-message. A message is sent once to each group, with messages 
-being *balanced* across the endpoints of a group via round 
-robin selection. Care should be taken when defining multiple 
-groups for a message type as there is extra overhead required 
-and thus the overall message latency is somewhat increased. 
+An endpoint from RMR's perspective is an application to which
+RMR may establish a connection, and expect to send messages
+with one or more defined message keys. Each entry in the
+route table consists of one or more endpoint groups, called
+round robin groups. When a message matches a specific entry,
+the entry's groups are used to select the destination of the
+message. A message is sent once to each group, with messages
+being *balanced* across the endpoints of a group via round
+robin selection. Care should be taken when defining multiple
+groups for a message type as there is extra overhead required
+and thus the overall message latency is somewhat increased.

 
 
 Routing Table Updates
 ---------------------
 
 
 
 Routing Table Updates
 ---------------------
 

-Route table information is made available to RMR a static 
-file (loaded once), or by updates sent from a separate route 
-manager application. If a static table is provided, it is 
-loaded during RMR initialization and will remain in use until 
-an external process connects and delivers a route table 
-update (often referred to as a dynamic update). Dynamic 
-updates are listened for in a separate process thread and 
-applied automatically; the application does not need to allow 
-for, or trigger, updates. 
+Route table information is made available to RMR a static
+file (loaded once), or by updates sent from a separate route
+manager application. If a static table is provided, it is
+loaded during RMR initialization and will remain in use until
+an external process connects and delivers a route table
+update (often referred to as a dynamic update). Dynamic
+updates are listened for in a separate process thread and
+applied automatically; the application does not need to allow
+for, or trigger, updates.

 
 
 Latency And Throughput
 ----------------------
 
 
 
 Latency And Throughput
 ----------------------
 

-While providing insulation from the underlying message 
-transport mechanics, RMR must also do so in such a manner 
-that message latency and throughput are not impacted. In 
-general, the RMR induced overhead, incurred due to the 
-process of selecting an endpoint for each message, is minimal 
-and should not impact the overall latency or throughput of 
-the application. This impact has been measured with test 
-applications running on the same physical host and the 
-average latency through RMR for a message was on the order of 
-0.02 milliseconds. 
- 
-As an application's throughput increases, it becomes easy for 
-the application to overrun the underlying transport mechanism 
-(e.g. NNG), consume all available TCP transmit buffers, or 
-otherwise find itself in a situation where a send might not 
-immediately complete. RMR offers different *modes* which 
-allow the application to manage these states based on the 
-overall needs of the application. These modes are discussed 
-in the *Configuration* section of this document. 
+While providing insulation from the underlying message
+transport mechanics, RMR must also do so in such a manner
+that message latency and throughput are not impacted. In
+general, the RMR induced overhead, incurred due to the
+process of selecting an endpoint for each message, is minimal
+and should not impact the overall latency or throughput of
+the application. This impact has been measured with test
+applications running on the same physical host and the
+average latency through RMR for a message was on the order of
+0.02 milliseconds.
+
+As an application's throughput increases, it becomes easy for
+the application to overrun the underlying transport mechanism
+(e.g. NNG), consume all available TCP transmit buffers, or
+otherwise find itself in a situation where a send might not
+immediately complete. RMR offers different *modes* which
+allow the application to manage these states based on the
+overall needs of the application. These modes are discussed
+in the *Configuration* section of this document.

 
 
 General Use
 ===========
 
 
 
 General Use
 ===========
 

-To use, the RMR based application simply needs to initialise 
-the RMR environment, wait for RMR to have received a routing 
-table (become ready), and then invoke either the send or 
-receive functions. These steps, and some behind the scenes 
-details, are described in the following paragraphs. 
+To use, the RMR based application simply needs to initialise
+the RMR environment, wait for RMR to have received a routing
+table (become ready), and then invoke either the send or
+receive functions. These steps, and some behind the scenes
+details, are described in the following paragraphs.

 
 
 Initialisation
 --------------
 
 
 
 Initialisation
 --------------
 

-The RMR function ``rmr_init()`` is used to set up the RMR 
-environment and must be called before messages can be sent or 
-received. One of the few parameters that the application must 
-communicate to RMR is the port number that will be used as 
-the listen port for new connections. The port number is 
-passed on the initialisation function call and a TCP listen 
-socket will be opened with this port. If the port is already 
-in use RMR will report a failure; the application will need 
-to reinitialise with a different port number, abort, or take 
-some other action appropriate for the application. 
- 
-In addition to creating a TCP listen port, RMR will start a 
-process thread which will be responsible for receiving 
-dynamic updates to the route table. This thread also causes a 
-TCP listen port to be opened as it is expected that the 
-process which generates route table updates will connect and 
-send new information when needed. The route table update port 
-is **not** supplied by the application, but is supplied via 
-an environment variable as this value is likely determined by 
-the mechanism which is starting and configuring the 
-application. 
+The RMR function ``rmr_init()`` is used to set up the RMR
+environment and must be called before messages can be sent or
+received. One of the few parameters that the application must
+communicate to RMR is the port number that will be used as
+the listen port for new connections. The port number is
+passed on the initialisation function call and a TCP listen
+socket will be opened with this port. If the port is already
+in use RMR will report a failure; the application will need
+to reinitialise with a different port number, abort, or take
+some other action appropriate for the application.
+
+In addition to creating a TCP listen port, RMR will start a
+process thread which will be responsible for receiving
+dynamic updates to the route table. This thread also causes a
+TCP listen port to be opened as it is expected that the
+process which generates route table updates will connect and
+send new information when needed. The route table update port
+is **not** supplied by the application, but is supplied via
+an environment variable as this value is likely determined by
+the mechanism which is starting and configuring the
+application.

 
 
 The RMR Context
 ---------------
 
 
 
 The RMR Context
 ---------------
 

-On successful initialisation, a void pointer, often called a 
-*handle* by some programming languages, is returned to the 
-application. This is a reference to the RMR control 
-information and must be passed as the first parameter on most 
-RMR function calls. RMR refers to this as the context, or 
-ctx. 
+On successful initialisation, a void pointer, often called a
+*handle* by some programming languages, is returned to the
+application. This is a reference to the RMR control
+information and must be passed as the first parameter on most
+RMR function calls. RMR refers to this as the context, or
+ctx.

 
 
 Wait For Ready
 --------------
 
 
 
 Wait For Ready
 --------------
 

-An application which is only receiving messages does not need 
-to wait for RMR to *become ready* after the call to the 
-initialization function. However, before the application can 
-successfully send a message, RMR must have loaded a route 
-table, and the application must wait for RMR to report that 
-it has done so. The RMR function ``rmr_ready()`` will return 
-the value *true* (1) when a complete route table has been 
-loaded and can be used to determine the endpoint for a send 
-request. 
+An application which is only receiving messages does not need
+to wait for RMR to *become ready* after the call to the
+initialization function. However, before the application can
+successfully send a message, RMR must have loaded a route
+table, and the application must wait for RMR to report that
+it has done so. The RMR function ``rmr_ready()`` will return
+the value *true* (1) when a complete route table has been
+loaded and can be used to determine the endpoint for a send
+request.

 
 
 Receiving Messages
 ------------------
 
 
 
 Receiving Messages
 ------------------
 

-The process of receiving is fairly straight forward. The 
-application invokes the RMR ``rmr_rcv_msg()`` function which 
-will block until a message is received. The function returns 
-a pointer to a message block which provides all of the 
-details about the message. Specifically, the application has 
-access to the following information either directly or 
-indirectly: 
- 
- 
-* The payload (actual data) 
-   
-* The total payload length in bytes 
-   
-* The number of bytes of the payload which contain valid data 
-   
-* The message type and subscription ID values 
-   
-* The hostname and IP address of the source of the message 
-  (the sender) 
-   
-* The transaction ID 
-   
-* Tracing data (if provided) 
- 
- 
+The process of receiving is fairly straight forward. The
+application invokes the RMR ``rmr_rcv_msg()`` function which
+will block until a message is received. The function returns
+a pointer to a message block which provides all of the
+details about the message. Specifically, the application has
+access to the following information either directly or
+indirectly:
+
+
+* The payload (actual data)
+
+* The total payload length in bytes
+
+* The number of bytes of the payload which contain valid data
+
+* The message type and subscription ID values
+
+* The hostname and IP address of the source of the message
+  (the sender)
+
+* The transaction ID
+
+* Tracing data (if provided)
+
+

 
 
 The Message Payload
 -------------------
 
 
 
 The Message Payload
 -------------------
 

-The message payload contains the *raw* data that was sent by 
-the peer application. The format will likely depend on the 
-message type, and is expected to be known by the application. 
-A direct pointer to the payload is available from the message 
-buffer (see appendix B for specific message buffer details). 
- 
-Two payload-related length values are also directly 
-available: the total payload length, and the number of bytes 
-actually filled with data. The used length is set by the 
-caller, and may or not be an accurate value. The total 
-payload length is determined when the buffer is created for 
-sending, and is the maximum number of bytes that the 
-application may modify should the buffer be used to return a 
-response. 
+The message payload contains the *raw* data that was sent by
+the peer application. The format will likely depend on the
+message type, and is expected to be known by the application.
+A direct pointer to the payload is available from the message
+buffer (see appendix B for specific message buffer details).
+
+Two payload-related length values are also directly
+available: the total payload length, and the number of bytes
+actually filled with data. The used length is set by the
+caller, and may or not be an accurate value. The total
+payload length is determined when the buffer is created for
+sending, and is the maximum number of bytes that the
+application may modify should the buffer be used to return a
+response.

 
 
 Message Type and Subscription ID
 --------------------------------
 
 
 
 Message Type and Subscription ID
 --------------------------------
 

-The message type and subscription ID are both directly 
-available from the message buffer, and are the values which 
-were used to by RMR in the sending application to select the 
-endpoint. If the application resends the message, as opposed 
-to returning the message buffer as a response, the message 
-number and/or the subscription ID might need to be changed to 
-avoid potential issues[1]. 
+The message type and subscription ID are both directly
+available from the message buffer, and are the values which
+were used to by RMR in the sending application to select the
+endpoint. If the application resends the message, as opposed
+to returning the message buffer as a response, the message
+number and/or the subscription ID might need to be changed to
+avoid potential issues[1].

 
 
 Sender Information
 ------------------
 
 
 
 Sender Information
 ------------------
 

-The source, or sender information, is indirectly available to 
-the application via the ``rmr_get_src()`` and 
-``rmr_get_ip()`` functions. The former returns a string 
-containing ``hostname:port,`` while the string 
-``ip:port`` is returned by the latter. 
+The source, or sender information, is indirectly available to
+the application via the ``rmr_get_src()`` and
+``rmr_get_ip()`` functions. The former returns a string
+containing ``hostname:port,`` while the string
+``ip:port`` is returned by the latter.

 
 
 Transaction ID
 --------------
 
 
 
 Transaction ID
 --------------
 

-The message buffer contains a fixed length set of bytes which 
-applications can set to track related messages across the 
-application concept of a transaction. RMR will use the 
-transaction ID for matching a response message when the 
-``rmr_call()`` function is used to send a message. 
+The message buffer contains a fixed length set of bytes which
+applications can set to track related messages across the
+application concept of a transaction. RMR will use the
+transaction ID for matching a response message when the
+``rmr_call()`` function is used to send a message.

 
 
 Trace Information
 -----------------
 
 
 
 Trace Information
 -----------------
 

-RMR supports the addition of an optional trace information to 
-any message. The presence and size is controlled by the 
-application, and can vary from message to message if desired. 
-The actual contents of the trace information is determined by 
-the application; RMR provides only the means to set, extract, 
-and obtain a direct reference to the trace bytes. The trace 
-data field in a message buffer is discussed in greater detail 
-in the *Trace Data* section. 
+RMR supports the addition of an optional trace information to
+any message. The presence and size is controlled by the
+application, and can vary from message to message if desired.
+The actual contents of the trace information is determined by
+the application; RMR provides only the means to set, extract,
+and obtain a direct reference to the trace bytes. The trace
+data field in a message buffer is discussed in greater detail
+in the *Trace Data* section.

 
 
 Sending Messages
 ----------------
 
 
 
 Sending Messages
 ----------------
 

-Sending requires only slightly more work on the part of the 
-application than receiving a message. The application must 
-allocate an RMR message buffer, populate the message payload 
-with data, set the message type and length, and optionally 
-set the subscription ID. Information such as the source IP 
-address, hostname, and port are automatically added to the 
-message buffer by RMR, so there is no need for the 
-application to worry about these. 
+Sending requires only slightly more work on the part of the
+application than receiving a message. The application must
+allocate an RMR message buffer, populate the message payload
+with data, set the message type and length, and optionally
+set the subscription ID. Information such as the source IP
+address, hostname, and port are automatically added to the
+message buffer by RMR, so there is no need for the
+application to worry about these.

 
 
 Message Buffer Allocation
 -------------------------
 
 
 
 Message Buffer Allocation
 -------------------------
 

-The function ``rmr_msg_alloc()`` allocates a *zero copy* 
-buffer and returns a pointer to the RMR ``rmr_mbuf_t`` 
-structure. The message buffer provides direct access to the 
-payload, length, message type and subscription ID fields. The 
-buffer must be preallocated in order to allow the underlying 
-transport mechanism to allocate the payload space from its 
-internal memory pool; this eliminates multiple copies as the 
-message is sent, and thus is more efficient. 
- 
-If a message buffer has been received, and the application 
-wishes to use the buffer to send a response, or to forward 
-the buffer to another application, a new buffer does **not** 
-need to be allocated. The application may set the necessary 
-information (message type, etc.), and adjust the payload, as 
-is necessary and then pass the message buffer to 
-``rmr_send_msg()`` or ``rmr_rts_msg()`` to be sent or 
-returned to the sender. 
+The function ``rmr_msg_alloc()`` allocates a *zero copy*
+buffer and returns a pointer to the RMR ``rmr_mbuf_t``
+structure. The message buffer provides direct access to the
+payload, length, message type and subscription ID fields. The
+buffer must be preallocated in order to allow the underlying
+transport mechanism to allocate the payload space from its
+internal memory pool; this eliminates multiple copies as the
+message is sent, and thus is more efficient.
+
+If a message buffer has been received, and the application
+wishes to use the buffer to send a response, or to forward
+the buffer to another application, a new buffer does **not**
+need to be allocated. The application may set the necessary
+information (message type, etc.), and adjust the payload, as
+is necessary and then pass the message buffer to
+``rmr_send_msg()`` or ``rmr_rts_msg()`` to be sent or
+returned to the sender.

 
 
 Populating the Message Buffer
 -----------------------------
 
 
 
 Populating the Message Buffer
 -----------------------------
 

-The application has direct access to several of the message 
-buffer fields, and should set them appropriately. 
- 
- 
-    .. list-table:: 
-      :widths: 15,80 
-      :header-rows: 0 
-      :class: borderless 
-       
-      * - **len** 
-        - 
-          This is the number of bytes that the application placed into 
-          the payload. Setting length to 0 is allowed, and length may 
-          be less than the allocated payload size. 
-       
-      * - **mtype** 
-        - 
-          The message type that RMR will use to determine the endpoint 
-          used as the target of the send. 
-       
-      * - **sub_id** 
-        - 
-          The subscription ID if the message is to be routed based on 
-          the combination of message type and subscription ID. If no 
-          subscription ID is valid for the message, the application 
-          should set the field with the RMR constant 
-          ``RMR_VOID_SUBID.`` 
-       
-      * - **payload** 
-        - 
-          The application should obtain the reference (pointer) to the 
-          payload from the message buffer and place any data into the 
-          payload. The application is responsible for ensuring that the 
-          maximum payload size is not exceeded. The application may 
-          obtain the maximum size via the ``rmr_payload_size()`` 
-          function. 
-       
-      * - **trace data** 
-        - 
-          Optionally, the application may add trace information to the 
-          message buffer. 
-           
- 
- 
+The application has direct access to several of the message
+buffer fields, and should set them appropriately.
+
+
+    .. list-table::
+      :widths: 15,80
+      :header-rows: 0
+      :class: borderless
+
+      * - **len**
+        -
+          This is the number of bytes that the application placed into
+          the payload. Setting length to 0 is allowed, and length may
+          be less than the allocated payload size.
+
+      * - **mtype**
+        -
+          The message type that RMR will use to determine the endpoint
+          used as the target of the send.
+
+      * - **sub_id**
+        -
+          The subscription ID if the message is to be routed based on
+          the combination of message type and subscription ID. If no
+          subscription ID is valid for the message, the application
+          should set the field with the RMR constant
+          ``RMR_VOID_SUBID.``
+
+      * - **payload**
+        -
+          The application should obtain the reference (pointer) to the
+          payload from the message buffer and place any data into the
+          payload. The application is responsible for ensuring that the
+          maximum payload size is not exceeded. The application may
+          obtain the maximum size via the ``rmr_payload_size()``
+          function.
+
+      * - **trace data**
+        -
+          Optionally, the application may add trace information to the
+          message buffer.
+
+
+

 
 
 Sending a Message Buffer
 ------------------------
 
 
 
 Sending a Message Buffer
 ------------------------
 

-Once the application has populated the necessary bits of a 
-message, it may be sent by passing the buffer to the 
-``rmr_send_msg()`` function. This function will select an 
-endpoint to receive the message, based on message type and 
-subscription ID, and will pass the message to the underlying 
-transport mechanism for actual transmission on the 
-connection. (Depending on the underlying transport mechanism, 
-the actual connection to the endpoint may happen at the time 
-of the first message sent to the endpoint, and thus the 
-latency of the first send might be longer than expected.) 
- 
-On success, the send function will return a reference to a 
-message buffer; the status within that message buffer will 
-indicate what the message buffer contains. When the status is 
-``RMR_OK`` the reference is to a **new** message buffer for 
-the application to use for the next send; the payload size is 
-the same as the payload size allocated for the message that 
-was just sent. This is a convenience as it eliminates the 
-need for the application to call the message allocation 
-function at some point in the future, and assumes the 
-application will send many messages which will require the 
-same payload dimensions. 
- 
-If the message contains any status other than ``RMR_OK,`` 
-then the message could **not** be sent, and the reference is 
-to the unsent message buffer. The value of the status will 
-indicate whether the nature of the failure was transient ( 
-``RMR_ERR_RETRY``) or not. Transient failures are likely to 
-be successful if the application attempts to send the message 
-at a later time. Unfortunately, it is impossible for RMR to 
-know the exact transient failure (e.g. connection being 
-established, or TCP buffer shortage), and thus it is not 
-possible to communicate how long the application should wait 
-before attempting to resend, if the application wishes to 
-resend the message. (More discussion with respect to message 
-retries can be found in the *Handling Failures* section.) 
+Once the application has populated the necessary bits of a
+message, it may be sent by passing the buffer to the
+``rmr_send_msg()`` function. This function will select an
+endpoint to receive the message, based on message type and
+subscription ID, and will pass the message to the underlying
+transport mechanism for actual transmission on the
+connection. (Depending on the underlying transport mechanism,
+the actual connection to the endpoint may happen at the time
+of the first message sent to the endpoint, and thus the
+latency of the first send might be longer than expected.)
+
+On success, the send function will return a reference to a
+message buffer; the status within that message buffer will
+indicate what the message buffer contains. When the status is
+``RMR_OK`` the reference is to a **new** message buffer for
+the application to use for the next send; the payload size is
+the same as the payload size allocated for the message that
+was just sent. This is a convenience as it eliminates the
+need for the application to call the message allocation
+function at some point in the future, and assumes the
+application will send many messages which will require the
+same payload dimensions.
+
+If the message contains any status other than ``RMR_OK,``
+then the message could **not** be sent, and the reference is
+to the unsent message buffer. The value of the status will
+indicate whether the nature of the failure was transient (
+``RMR_ERR_RETRY``) or not. Transient failures are likely to
+be successful if the application attempts to send the message
+at a later time. Unfortunately, it is impossible for RMR to
+know the exact transient failure (e.g. connection being
+established, or TCP buffer shortage), and thus it is not
+possible to communicate how long the application should wait
+before attempting to resend, if the application wishes to
+resend the message. (More discussion with respect to message
+retries can be found in the *Handling Failures* section.)

 
 
 Advanced Usage
 ==============
 
 
 
 Advanced Usage
 ==============
 

-Several forms of usage fall into a more advanced category and 
-are described in the following sections. These include 
-blocking call, return to sender and wormhole functions. 
+Several forms of usage fall into a more advanced category and
+are described in the following sections. These include
+blocking call, return to sender and wormhole functions.

 
 
 The Call Function
 -----------------
 
 
 
 The Call Function
 -----------------
 

-The RMR function ``rmr_call()`` sends a message in the exact 
-same manner as the ``rmr_send_msg()()`` function, with the 
-endpoint selection based on the message key. But unlike the 
-send function, ``rmr_call()`` will block and wait for a 
-response from the application that is selected to receive the 
-message. The matching message is determined by the 
-transaction ID which the application must place into the 
-message buffer prior to invoking ``rmr_call()``. Similarly, 
-the responding application must ensure that the same 
-transaction ID is placed into the message buffer before 
-returning its response. 
- 
-The return from the call is a message buffer with the 
-response message; there is no difference between a message 
-buffer returned by the receive function and one returned by 
-the ``rmr_call()`` function. If a response is not received in 
-a reasonable amount of time, a nil message buffer is returned 
-to the calling application. 
+The RMR function ``rmr_call()`` sends a message in the exact
+same manner as the ``rmr_send_msg()()`` function, with the
+endpoint selection based on the message key. But unlike the
+send function, ``rmr_call()`` will block and wait for a
+response from the application that is selected to receive the
+message. The matching message is determined by the
+transaction ID which the application must place into the
+message buffer prior to invoking ``rmr_call()``. Similarly,
+the responding application must ensure that the same
+transaction ID is placed into the message buffer before
+returning its response.
+
+The return from the call is a message buffer with the
+response message; there is no difference between a message
+buffer returned by the receive function and one returned by
+the ``rmr_call()`` function. If a response is not received in
+a reasonable amount of time, a nil message buffer is returned
+to the calling application.

 
 
 Returning a Response
 --------------------
 
 
 
 Returning a Response
 --------------------
 

-Because of the nature of RMR's routing policies, it is 
-generally not possible for an application to control exactly 
-which endpoint is sent a message. There are cases, such as 
-responding to a message delivered via ``rmr_call()`` that the 
-application must send a message and guarantee that RMR routes 
-it to an exact destination. To enable this, RMR provides the 
-``rmr_rts_msg(),`` return to sender, function. Upon receipt 
-of any message, an application may alter the payload, and if 
-necessary the message type and subscription ID, and pass the 
-altered message buffer to the ``rmr_rts_msg()`` function to 
-return the altered message to the application which sent it. 
-When this function is used, RMR will examine the message 
-buffer for the source information and use that to select the 
-connection on which to write the response. 
+Because of the nature of RMR's routing policies, it is
+generally not possible for an application to control exactly
+which endpoint is sent a message. There are cases, such as
+responding to a message delivered via ``rmr_call()`` that the
+application must send a message and guarantee that RMR routes
+it to an exact destination. To enable this, RMR provides the
+``rmr_rts_msg(),`` return to sender, function. Upon receipt
+of any message, an application may alter the payload, and if
+necessary the message type and subscription ID, and pass the
+altered message buffer to the ``rmr_rts_msg()`` function to
+return the altered message to the application which sent it.
+When this function is used, RMR will examine the message
+buffer for the source information and use that to select the
+connection on which to write the response.

 
 
 Multi-threaded Calls
 --------------------
 
 
 
 Multi-threaded Calls
 --------------------
 

-The basic call mechanism described above is **not** thread 
-safe, as it is not possible to guarantee that a response 
-message is delivered to the correct thread. The RMR function 
-``rmr_mt_call()`` accepts an additional parameter which 
-identifies the calling thread in order to ensure that the 
-response is delivered properly. In addition, the application 
-must specifically initialise the multi-threaded call 
-environment by passing the ``RMRFL_MTCALL`` flag as an option 
-to the ``rmr_init()`` function. 
- 
-One advantage of the multi-threaded call capability in RMR is 
-the fact that only the calling thread is blocked. Messages 
-received which are not responses to the call are continued to 
-be delivered via normal ``rmr_rcv_msg()`` calls. 
- 
-While the process is blocked waiting for the response, it is 
-entirely possible that asynchronous, non-matching, messages 
-will arrive. When this happens, RMR will queues the messages 
-and return them to the application over the next calls to 
-``rmr_rcv_msg().`` 
+The basic call mechanism described above is **not** thread
+safe, as it is not possible to guarantee that a response
+message is delivered to the correct thread. The RMR function
+``rmr_mt_call()`` accepts an additional parameter which
+identifies the calling thread in order to ensure that the
+response is delivered properly. In addition, the application
+must specifically initialise the multi-threaded call
+environment by passing the ``RMRFL_MTCALL`` flag as an option
+to the ``rmr_init()`` function.
+
+One advantage of the multi-threaded call capability in RMR is
+the fact that only the calling thread is blocked. Messages
+received which are not responses to the call are continued to
+be delivered via normal ``rmr_rcv_msg()`` calls.
+
+While the process is blocked waiting for the response, it is
+entirely possible that asynchronous, non-matching, messages
+will arrive. When this happens, RMR will queues the messages
+and return them to the application over the next calls to
+``rmr_rcv_msg().``

 
 
 Wormholes
 ---------
 
 
 
 Wormholes
 ---------
 

-As was mentioned earlier, the design of RMR is to eliminate 
-the need for an application to know a specific endpoint, even 
-when a response message is being sent. In some rare cases it 
-may be necessary for an application to establish a direct 
-connection to an RMR-based application rather than relying on 
-message type and subscription ID based routing. The 
-*wormhole* functions provide an application with the ability 
-to create a direct connection and then to send and receive 
-messages across the connection. The following are the RMR 
-functions which provide wormhole communications: 
- 
- 
-    .. list-table:: 
-      :widths: auto 
-      :header-rows: 0 
-      :class: borderless 
-       
-      * - **rmr_wh_open** 
-        - 
-          Open a connection to an endpoint. Name or IP address and port 
-          of the endpoint is supplied. Returns a wormhole ID that the 
-          application must use when sending a direct message. 
-       
-      * - **rmr_wh_send_msg** 
-        - 
-          Sends an RMR message buffer to the connected application. The 
-          message type and subscription ID may be set in the message, 
-          but RMR will ignore both. 
-       
-      * - **rmr_wh_close** 
-        - 
-          Closes the direct connection. 
-           
- 
- 
+As was mentioned earlier, the design of RMR is to eliminate
+the need for an application to know a specific endpoint, even
+when a response message is being sent. In some rare cases it
+may be necessary for an application to establish a direct
+connection to an RMR-based application rather than relying on
+message type and subscription ID based routing. The
+*wormhole* functions provide an application with the ability
+to create a direct connection and then to send and receive
+messages across the connection. The following are the RMR
+functions which provide wormhole communications:
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **rmr_wh_open**
+        -
+          Open a connection to an endpoint. Name or IP address and port
+          of the endpoint is supplied. Returns a wormhole ID that the
+          application must use when sending a direct message.
+
+      * - **rmr_wh_send_msg**
+        -
+          Sends an RMR message buffer to the connected application. The
+          message type and subscription ID may be set in the message,
+          but RMR will ignore both.
+
+      * - **rmr_wh_close**
+        -
+          Closes the direct connection.
+
+
+

 
 
 Handling Failures
 =================
 
 
 
 Handling Failures
 =================
 

-The vast majority of states reported by RMR are fatal; if 
-encountered during setup or initialization, then it is 
-unlikely that any message oriented processing should 
-continue, and when encountered on a message operation 
-continued operation on that message should be abandoned. 
-Specifically with regard to message sending, it is very 
-likely that the underlying transport mechanism will report a 
-*soft,* or transient, failure which might be successful if 
-the operation is retried at a later point in time. The 
-paragraphs below discuss the methods that an application 
-might deal with these soft failures. 
+The vast majority of states reported by RMR are fatal; if
+encountered during setup or initialization, then it is
+unlikely that any message oriented processing should
+continue, and when encountered on a message operation
+continued operation on that message should be abandoned.
+Specifically with regard to message sending, it is very
+likely that the underlying transport mechanism will report a
+*soft,* or transient, failure which might be successful if
+the operation is retried at a later point in time. The
+paragraphs below discuss the methods that an application
+might deal with these soft failures.

 
 
 Failure Notification
 --------------------
 
 
 
 Failure Notification
 --------------------
 

-When a soft failure is reported, the returned message buffer 
-returned by the RMR function will be ``RMR_ERR_RETRY.`` These 
-types of failures can occur for various reasons; one of two 
-reasons is typically the underlying cause: 
- 
- 
-* The session to the targeted recipient (endpoint) is not 
-  connected. 
-   
-* The transport mechanism buffer pool is full and cannot 
-  accept another buffer. 
-   
- 
- 
-Unfortunately, it is not possible for RMR to determine which 
-of these two cases is occurring, and equally as unfortunate 
-the time to resolve each is different. The first, no 
-connection, may require up to a second before a message can 
-be accepted, while a rejection because of buffer shortage is 
-likely to resolve in less than a millisecond. 
+When a soft failure is reported, the returned message buffer
+returned by the RMR function will be ``RMR_ERR_RETRY.`` These
+types of failures can occur for various reasons; one of two
+reasons is typically the underlying cause:
+
+
+* The session to the targeted recipient (endpoint) is not
+  connected.
+
+* The transport mechanism buffer pool is full and cannot
+  accept another buffer.
+
+
+
+Unfortunately, it is not possible for RMR to determine which
+of these two cases is occurring, and equally as unfortunate
+the time to resolve each is different. The first, no
+connection, may require up to a second before a message can
+be accepted, while a rejection because of buffer shortage is
+likely to resolve in less than a millisecond.

 
 
 Application Response
 --------------------
 
 
 
 Application Response
 --------------------
 

-The action which an application takes when a soft failure is 
-reported ultimately depends on the nature of the application 
-with respect to factors such as tolerance to extended message 
-latency, dropped messages, and over all message rate. 
+The action which an application takes when a soft failure is
+reported ultimately depends on the nature of the application
+with respect to factors such as tolerance to extended message
+latency, dropped messages, and over all message rate.

 
 
 RMR Retry Modes
 ---------------
 
 
 
 RMR Retry Modes
 ---------------
 

-In an effort to reduce the workload of an application 
-developer, RMR has a default retry policy such that RMR will 
-attempt to retransmit a message up to 1000 times when a soft 
-failure is reported. These retries generally take less than 1 
-millisecond (if all 1000 are attempted) and in most cases 
-eliminates nearly all reported soft failures to the 
-application. When using this mode, it might allow the 
-application to simply treat all bad return values from a send 
-attempt as permanent failures. 
- 
-If an application is so sensitive to any delay in RMR, or the 
-underlying transport mechanism, it is possible to set RMR to 
-return a failure immediately on any kind of error (permanent 
-failures are always reported without retry). In this mode, 
-RMR will still set the state in the message buffer to 
-``RMR_ERR_RETRY,`` but will **not** make any attempts to 
-resend the message. This zero-retry policy is enabled by 
-invoking the ``rmr_set_stimeout()`` with a value of 0; this 
-can be done once immediately after ``rmr_init()`` is invoked. 
- 
-Regardless of the retry mode which the application sets, it 
-will ultimately be up to the application to handle failures 
-by queuing the message internally for resend, retrying 
-immediately, or dropping the send attempt all together. As 
-stated before, only the application can determine how to best 
-handle send failures. 
+In an effort to reduce the workload of an application
+developer, RMR has a default retry policy such that RMR will
+attempt to retransmit a message up to 1000 times when a soft
+failure is reported. These retries generally take less than 1
+millisecond (if all 1000 are attempted) and in most cases
+eliminates nearly all reported soft failures to the
+application. When using this mode, it might allow the
+application to simply treat all bad return values from a send
+attempt as permanent failures.
+
+If an application is so sensitive to any delay in RMR, or the
+underlying transport mechanism, it is possible to set RMR to
+return a failure immediately on any kind of error (permanent
+failures are always reported without retry). In this mode,
+RMR will still set the state in the message buffer to
+``RMR_ERR_RETRY,`` but will **not** make any attempts to
+resend the message. This zero-retry policy is enabled by
+invoking the ``rmr_set_stimeout()`` with a value of 0; this
+can be done once immediately after ``rmr_init()`` is invoked.
+
+Regardless of the retry mode which the application sets, it
+will ultimately be up to the application to handle failures
+by queuing the message internally for resend, retrying
+immediately, or dropping the send attempt all together. As
+stated before, only the application can determine how to best
+handle send failures.

 
 
 Other Failures
 --------------
 
 
 
 Other Failures
 --------------
 

-RMR will return the state of processing for message based 
-operations (send/receive) as the status in the message 
-buffer. For non-message operations, state is returned to the 
-caller as the integer return value for all functions which 
-are not expected to return a pointer (e.g. 
-``rmr_init()``.) The following are the RMR state constants 
-and a brief description of their meaning. 
- 
- 
-    .. list-table:: 
-      :widths: auto 
-      :header-rows: 0 
-      :class: borderless 
-       
-      * - **RMR_OK** 
-        - 
-          state is good; operation finished successfully 
-       
-      * - **RMR_ERR_BADARG** 
-        - 
-          argument passed to function was unusable 
-       
-      * - **RMR_ERR_NOENDPT** 
-        - 
-          send/call could not find an endpoint based on msg type 
-       
-      * - **RMR_ERR_EMPTY** 
-        - 
-          msg received had no payload; attempt to send an empty message 
-       
-      * - **RMR_ERR_NOHDR** 
-        - 
-          message didn't contain a valid header 
-       
-      * - **RMR_ERR_SENDFAILED** 
-        - 
-          send failed; errno may contain the transport provider reason 
-       
-      * - **RMR_ERR_CALLFAILED** 
-        - 
-          unable to send the message for a call function; errno may 
-          contain the transport provider reason 
-       
-      * - **RMR_ERR_NOWHOPEN** 
-        - 
-          no wormholes are open 
-       
-      * - **RMR_ERR_WHID** 
-        - 
-          the wormhole id provided was invalid 
-       
-      * - **RMR_ERR_OVERFLOW** 
-        - 
-          operation would have busted through a buffer/field size 
-       
-      * - **RMR_ERR_RETRY** 
-        - 
-          request (send/call/rts) failed, but caller should retry 
-          (EAGAIN for wrappers) 
-       
-      * - **RMR_ERR_RCVFAILED** 
-        - 
-          receive failed (hard error) 
-       
-      * - **RMR_ERR_TIMEOUT** 
-        - 
-          response message not received in a reasonable amount of time 
-       
-      * - **RMR_ERR_UNSET** 
-        - 
-          the message hasn't been populated with a transport buffer 
-       
-      * - **RMR_ERR_TRUNC** 
-        - 
-          length in the received buffer is longer than the size of the 
-          allocated payload, received message likely truncated (length 
-          set by sender could be wrong, but we can't know that) 
-       
-      * - **RMR_ERR_INITFAILED** 
-        - 
-          initialisation of something (probably message) failed 
-       
-      * - **RMR_ERR_NOTSUPP** 
-        - 
-          the request is not supported, or RMR was not initialised for 
-          the request 
-           
- 
- 
-Depending on the underlying transport mechanism, and the 
-nature of the call that RMR attempted, the system 
-``errno`` value might reflect additional detail about the 
-failure. Applications should **not** rely on errno as some 
-transport mechanisms do not set it with any consistency. 
+RMR will return the state of processing for message based
+operations (send/receive) as the status in the message
+buffer. For non-message operations, state is returned to the
+caller as the integer return value for all functions which
+are not expected to return a pointer (e.g.
+``rmr_init()``.) The following are the RMR state constants
+and a brief description of their meaning.
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMR_OK**
+        -
+          state is good; operation finished successfully
+
+      * - **RMR_ERR_BADARG**
+        -
+          argument passed to function was unusable
+
+      * - **RMR_ERR_NOENDPT**
+        -
+          send/call could not find an endpoint based on msg type
+
+      * - **RMR_ERR_EMPTY**
+        -
+          msg received had no payload; attempt to send an empty message
+
+      * - **RMR_ERR_NOHDR**
+        -
+          message didn't contain a valid header
+
+      * - **RMR_ERR_SENDFAILED**
+        -
+          send failed; errno may contain the transport provider reason
+
+      * - **RMR_ERR_CALLFAILED**
+        -
+          unable to send the message for a call function; errno may
+          contain the transport provider reason
+
+      * - **RMR_ERR_NOWHOPEN**
+        -
+          no wormholes are open
+
+      * - **RMR_ERR_WHID**
+        -
+          the wormhole id provided was invalid
+
+      * - **RMR_ERR_OVERFLOW**
+        -
+          operation would have busted through a buffer/field size
+
+      * - **RMR_ERR_RETRY**
+        -
+          request (send/call/rts) failed, but caller should retry
+          (EAGAIN for wrappers)
+
+      * - **RMR_ERR_RCVFAILED**
+        -
+          receive failed (hard error)
+
+      * - **RMR_ERR_TIMEOUT**
+        -
+          response message not received in a reasonable amount of time
+
+      * - **RMR_ERR_UNSET**
+        -
+          the message hasn't been populated with a transport buffer
+
+      * - **RMR_ERR_TRUNC**
+        -
+          length in the received buffer is longer than the size of the
+          allocated payload, received message likely truncated (length
+          set by sender could be wrong, but we can't know that)
+
+      * - **RMR_ERR_INITFAILED**
+        -
+          initialisation of something (probably message) failed
+
+      * - **RMR_ERR_NOTSUPP**
+        -
+          the request is not supported, or RMR was not initialised for
+          the request
+
+
+
+Depending on the underlying transport mechanism, and the
+nature of the call that RMR attempted, the system
+``errno`` value might reflect additional detail about the
+failure. Applications should **not** rely on errno as some
+transport mechanisms do not set it with any consistency.

 
 
 Configuration and Control
 =========================
 
 
 
 Configuration and Control
 =========================
 

-With the assumption that most RMR based applications will be 
-executed in a containerised environment, there are some 
-underlying mechanics which the developer may need to know in 
-order to properly provide a configuration specification to 
-the container management system. The following paragraphs 
-briefly discuss these. 
- 
+With the assumption that most RMR based applications will be
+executed in a containerised environment, there are some
+underlying mechanics which the developer may need to know in
+order to properly provide a configuration specification to
+the container management system. The following paragraphs
+briefly discuss these.
+

 
 
 TCP Ports
 ---------
 
 
 
 TCP Ports
 ---------
 

-RMR requires two (2) TCP listen ports: one for general 
-application-to-application communications and one for 
-route-table updates. The general communication port is 
-specified by the application at the time RMR is initialised. 
-The port used to listen for route table updates is likely to 
-be a constant port shared by all applications provided they 
-are running in separate containers. To that end, the port 
-number defaults to 4561, but can be configured with an 
-environment variable (see later paragraph in this section). 
+RMR requires two (2) TCP listen ports: one for general
+application-to-application communications and one for
+route-table updates. The general communication port is
+specified by the application at the time RMR is initialised.
+The port used to listen for route table updates is likely to
+be a constant port shared by all applications provided they
+are running in separate containers. To that end, the port
+number defaults to 4561, but can be configured with an
+environment variable (see later paragraph in this section).

 
 
 Host Names
 ----------
 
 
 
 Host Names
 ----------
 

-RMR is typically host name agnostic. Route table entries may 
-contain endpoints defined either by host name or IP address. 
-In the container world the concept of a *service name* might 
-exist, and likely is different than a host name. RMR's only 
-requirement with respect to host names is that a name used on 
-a route table entry must be resolvable via the 
-``gethostbyname`` system call. 
+RMR is typically host name agnostic. Route table entries may
+contain endpoints defined either by host name or IP address.
+In the container world the concept of a *service name* might
+exist, and likely is different than a host name. RMR's only
+requirement with respect to host names is that a name used on
+a route table entry must be resolvable via the
+``gethostbyname`` system call.

 
 
 Environment Variables
 ---------------------
 
 
 
 Environment Variables
 ---------------------
 

-Several environment variables are recognised by RMR which, in 
-general, are used to define interfaces and listen ports (e.g. 
-the route table update listen port), or debugging 
-information. Generally this information is system controlled 
-and thus RMR expects this information to be defined in the 
-environment rather than provided by the application. The 
-following is a list of the environment variables which RMR 
-recognises: 
- 
- 
-    .. list-table:: 
-      :widths: auto 
-      :header-rows: 0 
-      :class: borderless 
-       
-      * - **RMR_BIND_IF** 
-        - 
-          The interface to bind to listen ports to. If not defined 
-          0.0.0.0 (all interfaces) is assumed. 
-       
-      * - **RMR_RTG_SVC** 
-        - 
-          The port RMR will listen on for route manager connections. If 
-          not defined 4561 is used. 
-       
-      * - **RMR_SEED_RT** 
-        - 
-          Where RMR expects to find the name of the seed (static) route 
-          table. If not defined no static table is read. 
-       
-      * - **RMR_RTG_ISRAW** 
-        - 
-          If the value set to 0, RMR expects the route table manager 
-          messages to be messages with and RMR header. If this is not 
-          defined messages are assumed to be "raw" (without an RMR 
-          header. 
-       
-      * - **RMR_VCTL_FILE** 
-        - 
-          Provides a file which is used to set the verbose level of the 
-          route table collection thread. The first line of the file is 
-          read and expected to contain an integer value to set the 
-          verbose level. The value may be changed at any time and the 
-          route table thread will adjust accordingly. 
-       
-      * - **RMR_SRC_NAMEONLY** 
-        - 
-          If the value of this variable is greater than 0, RMR will not 
-          permit the IP address to be sent as the message source. Only 
-          the host name will be sent as the source in the message 
-          header. 
-           
- 
- 
+Several environment variables are recognised by RMR which, in
+general, are used to define interfaces and listen ports (e.g.
+the route table update listen port), or debugging
+information. Generally this information is system controlled
+and thus RMR expects this information to be defined in the
+environment rather than provided by the application. The
+following is a list of the environment variables which RMR
+recognises:
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **RMR_BIND_IF**
+        -
+          The interface to bind to listen ports to. If not defined
+          0.0.0.0 (all interfaces) is assumed.
+
+      * - **RMR_RTG_SVC**
+        -
+          The port RMR will listen on for route manager connections. If
+          not defined 4561 is used.
+
+      * - **RMR_SEED_RT**
+        -
+          Where RMR expects to find the name of the seed (static) route
+          table. If not defined no static table is read.
+
+      * - **RMR_RTG_ISRAW**
+        -
+          If the value set to 0, RMR expects the route table manager
+          messages to be messages with and RMR header. If this is not
+          defined messages are assumed to be "raw" (without an RMR
+          header.
+
+      * - **RMR_VCTL_FILE**
+        -
+          Provides a file which is used to set the verbose level of the
+          route table collection thread. The first line of the file is
+          read and expected to contain an integer value to set the
+          verbose level. The value may be changed at any time and the
+          route table thread will adjust accordingly.
+
+      * - **RMR_SRC_NAMEONLY**
+        -
+          If the value of this variable is greater than 0, RMR will not
+          permit the IP address to be sent as the message source. Only
+          the host name will be sent as the source in the message
+          header.
+
+
+

 
 
 Logging
 -------
 
 
 
 Logging
 -------
 

-RMR does **not** use any logging libraries; any error or 
-warning messages are written to standard error. RMR messages 
-are written with one of three prefix strings: 
- 
- 
-    .. list-table:: 
-      :widths: auto 
-      :header-rows: 0 
-      :class: borderless 
-       
-      * - **[CRI]** 
-        - 
-          The event is of a critical nature and it is unlikely that RMR 
-          will continue to operate correctly if at all. It is almost 
-          certain that immediate action will be needed to resolve the 
-          issue. 
-       
-      * - **[ERR]** 
-        - 
-          The event is not expected and RMR is not able to handle it. 
-          There is a small chance that continued operation will be 
-          negatively impacted. Eventual action to diagnose and correct 
-          the issue will be necessary. 
-       
-      * - **[WRN]** 
-        - 
-          The event was not expected by RMR, but can be worked round. 
-          Normal operation will continue, but it is recommended that 
-          the cause of the problem be investigated. 
-           
- 
- 
+RMR does **not** use any logging libraries; any error or
+warning messages are written to standard error. RMR messages
+are written with one of three prefix strings:
+
+
+    .. list-table::
+      :widths: auto
+      :header-rows: 0
+      :class: borderless
+
+      * - **[CRI]**
+        -
+          The event is of a critical nature and it is unlikely that RMR
+          will continue to operate correctly if at all. It is almost
+          certain that immediate action will be needed to resolve the
+          issue.
+
+      * - **[ERR]**
+        -
+          The event is not expected and RMR is not able to handle it.
+          There is a small chance that continued operation will be
+          negatively impacted. Eventual action to diagnose and correct
+          the issue will be necessary.
+
+      * - **[WRN]**
+        -
+          The event was not expected by RMR, but can be worked round.
+          Normal operation will continue, but it is recommended that
+          the cause of the problem be investigated.
+
+
+

 
 
 Notes
 =====
 
 
 
 Notes
 =====
 

- 
- [1] It is entirely possible to design a routing table, and 
- application group, such that the same message type is is 
- left unchanged and the message is forwarded by an 
- application after updating the payload. This type of 
- behaviour is often referred to as service chaining, and can 
- be done without any "knowledge" by an application with 
- respect to where the message goes next. Service chaining is 
- supported by RMR in as much as it allows the message to be 
- resent, but the actual complexities of designing and 
- implementing service chaining lie with the route table 
- generator process. 
- 
- 
- 
- 
+
+ [1] It is entirely possible to design a routing table, and
+ application group, such that the same message type is is
+ left unchanged and the message is forwarded by an
+ application after updating the payload. This type of
+ behaviour is often referred to as service chaining, and can
+ be done without any "knowledge" by an application with
+ respect to where the message goes next. Service chaining is
+ supported by RMR in as much as it allows the message to be
+ resent, but the actual complexities of designing and
+ implementing service chaining lie with the route table
+ generator process.
+
+
+
+

 
 
 Appendix A -- Quick Reference
 =============================
 
 
 
 Appendix A -- Quick Reference
 =============================
 

-Please  refer  to  the RMR manual pages on the Read the Docs 
-site 
- 
-https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-lib-rmr/en/latest/index.html 
- 
+Please  refer  to  the RMR manual pages on the Read the Docs
+site
+
+https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-lib-rmr/en/latest/index.html
+

 
 
 Appendix B -- Message Buffer Details
 ====================================
 
 
 
 Appendix B -- Message Buffer Details
 ====================================
 

-The RMR message buffer is a C structure which is exposed  in 
-the  ``rmr.h``  header  file. It is used to manage a message 
-received from a peer endpoint, or a message  that  is  being 
-sent  to  a  peer.  Fields include payload length, amount of 
-payload actually  used,  status,  and  a  reference  to  the 
-payload.  There are also fields which the application should 
-ignore, and could be hidden in the header file, but we chose 
-not  to.  These fields include a reference to the RMR header 
-information,  and  to  the  underlying  transport  mechanism 
-message  struct  which may or may not be the same as the RMR 
-header reference. 
+The RMR message buffer is a C structure which is exposed  in
+the  ``rmr.h``  header  file. It is used to manage a message
+received from a peer endpoint, or a message  that  is  being
+sent  to  a  peer.  Fields include payload length, amount of
+payload actually  used,  status,  and  a  reference  to  the
+payload.  There are also fields which the application should
+ignore, and could be hidden in the header file, but we chose
+not  to.  These fields include a reference to the RMR header
+information,  and  to  the  underlying  transport  mechanism
+message  struct  which may or may not be the same as the RMR
+header reference.

 
 
 The Structure
 -------------
 
 
 
 The Structure
 -------------
 

-The following is the C structure. Readers are  cautioned  to 
-examine  the ``rmr.h`` header file directly; the information 
-here may be out of date (old document in  some  cache),  and 
-thus it may be incorrect. 
- 
- 
-:: 
- 
-   
+The following is the C structure. Readers are  cautioned  to
+examine  the ``rmr.h`` header file directly; the information
+here may be out of date (old document in  some  cache),  and
+thus it may be incorrect.
+
+
+::
+
+

   typedef struct {
       int    state;            // state of processing
       int    mtype;            // message type
   typedef struct {
       int    state;            // state of processing
       int    mtype;            // message type


@@ -895,7 +895,7 @@ thus it may be incorrect.
       unsigned char* xaction;  // pointer to fixed length transaction id bytes
       int    sub_id;           // subscription id
       int    tp_state;         // transport state (errno)
       unsigned char* xaction;  // pointer to fixed length transaction id bytes
       int    sub_id;           // subscription id
       int    tp_state;         // transport state (errno)

-   
+

                                // these things are off limits to the user application
       void*    tp_buf;         // underlying transport allocated pointer (e.g. nng message)
       void*    header;         // internal message header (whole buffer: header+payload)
                                // these things are off limits to the user application
       void*    tp_buf;         // underlying transport allocated pointer (e.g. nng message)
       void*    header;         // internal message header (whole buffer: header+payload)


@@ -906,287 +906,287 @@ thus it may be incorrect.
       int      rts_fd;         // SI fd for return to sender
       int      cookie;         // cookie to detect user misuse of free'd msg
   } rmr_mbuf_t;
       int      rts_fd;         // SI fd for return to sender
       int      cookie;         // cookie to detect user misuse of free'd msg
   } rmr_mbuf_t;

- 
- 
+
+

 
 
 State vs Transport State
 ------------------------
 
 
 
 State vs Transport State
 ------------------------
 

-The  state  field reflects the state at the time the message 
-buffer is returned to the calling application.  For  a  send 
-operation,  if  the state is not ``RMR_OK`` then the message 
-buffer references the payload that could not  be  sent,  and 
-when the state is ``RMR_OK`` the buffer references a *fresh* 
-payload that the application may fill in. 
- 
-When the state is not ``RMR_OK,`` C programmes  may  examine 
-the  global ``errno`` value which RMR will have left set, if 
-it was set, by the underlying transport mechanism.  In  some 
-cases,  wrapper  modules are not able to directly access the 
-C-library ``errno``  value,  and  to  assist  with  possible 
-transport  error  details,  the  send and receive operations 
-populate ``tp_state`` with the value of ``errno.`` 
- 
-Regardless of whether  the  application  makes  use  of  the 
-``tp_state,`` or the ``errno`` value, it should be noted that 
-the underlying transport mechanism may not  actually  update 
-the errno value; in other words: it might not be accurate. In 
-addition, RMR populates the ``tp_state`` value in the message 
-buffer **only** when the state is not ``RMR_OK.`` 
+The  state  field reflects the state at the time the message
+buffer is returned to the calling application.  For  a  send
+operation,  if  the state is not ``RMR_OK`` then the message
+buffer references the payload that could not  be  sent,  and
+when the state is ``RMR_OK`` the buffer references a *fresh*
+payload that the application may fill in.
+
+When the state is not ``RMR_OK,`` C programmes  may  examine
+the  global ``errno`` value which RMR will have left set, if
+it was set, by the underlying transport mechanism.  In  some
+cases,  wrapper  modules are not able to directly access the
+C-library ``errno``  value,  and  to  assist  with  possible
+transport  error  details,  the  send and receive operations
+populate ``tp_state`` with the value of ``errno.``
+
+Regardless of whether  the  application  makes  use  of  the
+``tp_state,`` or the ``errno`` value, it should be noted that
+the underlying transport mechanism may not  actually  update
+the errno value; in other words: it might not be accurate. In
+addition, RMR populates the ``tp_state`` value in the message
+buffer **only** when the state is not ``RMR_OK.``

 
 
 Field References
 ----------------
 
 
 
 Field References
 ----------------
 

-The  transaction  field  was exposed in the first version of 
-RMR, and in hindsight this shouldn't have been done.  Rather 
-than  break  any  existing  code the reference was left, but 
-additional fields such as  trace  data,  were  not  directly 
-exposed  to  the  application.  The application developer is 
-strongly encouraged to use the functions which get  and  set 
-the  transaction  ID rather than using the pointer directly; 
-any data overruns will not be detected if the  reference  is 
-used directly. 
- 
-In contrast, the payload reference should be used directly by 
-the application  in  the  interest  of  speed  and  ease  of 
-programming.  The same care to prevent writing more bytes to 
-the payload buffer than it can hold must  be  taken  by  the 
-application.  By the nature of the allocation of the payload 
-in transport space, RMR is unable to add guard bytes  and/or 
-test for data overrun. 
+The  transaction  field  was exposed in the first version of
+RMR, and in hindsight this shouldn't have been done.  Rather
+than  break  any  existing  code the reference was left, but
+additional fields such as  trace  data,  were  not  directly
+exposed  to  the  application.  The application developer is
+strongly encouraged to use the functions which get  and  set
+the  transaction  ID rather than using the pointer directly;
+any data overruns will not be detected if the  reference  is
+used directly.
+
+In contrast, the payload reference should be used directly by
+the application  in  the  interest  of  speed  and  ease  of
+programming.  The same care to prevent writing more bytes to
+the payload buffer than it can hold must  be  taken  by  the
+application.  By the nature of the allocation of the payload
+in transport space, RMR is unable to add guard bytes  and/or
+test for data overrun.

 
 
 Actual Transmission
 -------------------
 
 
 
 Actual Transmission
 -------------------
 

-When RMR sends the application's message, the message buffer 
-is **not** transmitted. The transport buffer (tp_buf)  which 
-contains  the RMR header and application payload is the only 
-set of bytes which are transmitted. While it may seem to the 
-caller  like  the function ``rmr_send_msg()`` is returning a 
-new message buffer, the same struct is reused and only a new 
-transport  buffer  is  allocated.  The intent is to keep the 
-alloc/free cycles to a minimum. 
- 
+When RMR sends the application's message, the message buffer
+is **not** transmitted. The transport buffer (tp_buf)  which
+contains  the RMR header and application payload is the only
+set of bytes which are transmitted. While it may seem to the
+caller  like  the function ``rmr_send_msg()`` is returning a
+new message buffer, the same struct is reused and only a new
+transport  buffer  is  allocated.  The intent is to keep the
+alloc/free cycles to a minimum.
+

 
 
 Appendix C -- Glossary
 ======================
 
 
 
 Appendix C -- Glossary
 ======================
 

-Many terms in networking can be  interpreted  with  multiple 
-meanings, and several terms used in various RMR documentation 
-are RMR specific. The following definitions are the meanings 
-of  terms  used within RMR documentation and should help the 
-reader to understand the intent of meaning. 
- 
-    .. list-table:: 
-      :widths: 25,70 
-      :header-rows: 0 
-      :class: borderless 
-       
-      * - **application** 
-        - 
-          A programme which uses RMR to send and/or  receive  messages 
-          to/from another RMR based application. 
-       
-      * - **Critical error** 
-        - 
-          An error that RMR has encountered which will prevent further 
-          successful  processing  by  RMR.  Critical  errors  usually  
-          indicate that the application should abort. 
-       
-      * - **Endpoint** 
-        - 
-          An RMR based application that is defined as being capable of 
-          receiving one or more types of messages  (as  defined  by  a 
-          *routing key.*) 
-       
-      * - **Environment variable** 
-        - 
-          A key/value pair which is set externally to the application, 
-          but which is available to the  application  (and  referenced 
-          libraries)  through  the ``getenv`` system call. Environment 
-          variables are the main method of  communicating  information 
-          such as port numbers to RMR. 
-       
-      * - **Error** 
-        - 
-          An abnormal condition that RMR has encountered, but will not 
-          affect the overall processing by RMR, but may impact certain 
-          aspects  such  as the ability to communicate with a specific 
-          endpoint. Errors generally indicate that something,  usually 
-          external to RMR, must be addressed. 
-       
-      * - **Host name** 
-        - 
-          The  name  of  the host as returned by the ``gethostbyname`` 
-          system call. In a containerised environment this might be the 
-          container  or service name depending on how the container is 
-          started. From RMR's point of view, a host name can be used to 
-          resolve an *endpoint* definition in a *route* table.) 
-       
-      * - **IP** 
-        - 
-          Internet  protocol.  A low level transmission protocol which 
-          governs   the  transmission  of  datagrams  across  network  
-          boundaries. 
-       
-      * - **Listen socket** 
-        - 
-          A  *TCP*  socket used to await incoming connection requests. 
-          Listen sockets are defined by an interface and  port  number 
-          combination  where  the  port  number  is  unique  for  the  
-          interface. 
-       
-      * - **Message** 
-        - 
-          A series of bytes transmitted from the application to another 
-          RMR based application. A message is comprised of RMR specific 
-          data (a header), and application data (a payload). 
-       
-      * - **Message buffer** 
-        - 
-          A data structure used to describe a message which is  to  be 
-          sent  or  has been received. The message buffer includes the 
-          payload length, message  type,  message  source,  and  other 
-          information. 
-       
-      * - **Message type** 
-        - 
-          A  signed  integer  (0-32000)  which  identifies the type of 
-          message being transmitted, and is one of the two  components 
-          of a *routing key.* See *Subscription ID.* 
-       
-      * - **Payload** 
-        - 
-          The  portion  of  a  message which holds the user data to be 
-          transmitted to the remote *endpoint.* The  payload  contents 
-          are completely application defined. 
-       
-      * - **RMR context** 
-        - 
-          A  set of information which defines the current state of the 
-          underlying transport connections that RMR is  managing.  The 
-          application  will be give a context reference (pointer) that 
-          is supplied to most RMR functions as the first parameter. 
-       
-      * - **Round robin** 
-        - 
-          The method of selecting an *endpoint* from a list such  that 
-          all  *endpoints* are selected before starting at the head of 
-          the list. 
-       
-      * - **Route table** 
-        - 
-          A series of "rules" which define the possible *endpoints* for 
-          each *routing key.* 
-       
-      * - **Route table manager** 
-        - 
-          An  application responsible for building a *route table* and 
-          then   distributing   it   to   all  applicable  RMR  based  
-          applications. 
-       
-      * - **Routing** 
-        - 
-          The  process  of  selecting  an *endpoint* which will be the 
-          recipient of a message. 
-       
-      * - **Routing key** 
-        - 
-          A combination of *message type* and *subscription ID*  which 
-          RMR uses to select the destination *endpoint* when sending a 
-          message. 
-       
-      * - **Source** 
-        - 
-          The sender of a message. 
-       
-      * - **Subscription ID** 
-        - 
-          A  signed  integer  value  (0-32000)  which  identifies  the 
-          subscription  characteristic  of  a  message.  It is used in 
-          conjunction with the *message type* to determine the *routing 
-          key.* 
-       
-      * - **Target** 
-        - 
-          The *endpoint* selected to receive a message. 
-       
-      * - **TCP** 
-        - 
-          Transmission  Control  Protocol. A connection based internet 
-          protocol which provides for lossless packet  transportation, 
-          usually over IP. 
-       
-      * - **Thread** 
-        - 
-          Also  called  a  *process  thread,  or  pthread.*  This is a 
-          lightweight process which executes in concurrently with  the 
-          application  and  shares  the  same  address space. RMR uses 
-          threads to manage asynchronous functions such as route table 
-          updates. 
-       
-      * - **Trace information** 
-        - 
-          An   optional  portion  of  the  message  buffer  that  the  
-          application may populate with data that allows  for  tracing 
-          the  progress  of  the  transaction  or application activity 
-          across components. RMR makes no use of this data. 
-       
-      * - **Transaction ID** 
-        - 
-          A fixed number of bytes in the *message* buffer)  which  the 
-          application  may  populate  with  information related to the 
-          transaction. RMR makes use of the transaction ID for matching 
-          response  messages  with  the  &c function is used to send a 
-          message. 
-       
-      * - **Transient failure** 
-        - 
-          An error state that is believed to be short lived  and  that 
-          the  operation,  if  retried  by  the  application, might be 
-          successful.   C   programmers   will   recognise   this  as  
-          ``EAGAIN.`` 
-       
-      * - **Warning** 
-        - 
-          A  warning occurs when RMR has encountered something that it 
-          believes isn't correct, but has a defined work round. 
-       
-      * - **Wormhole** 
-        - 
-          A  direct  connection  managed  by  RMR  between  the  user  
-          application and a remote, RMR based, application. 
-           
- 
- 
+Many terms in networking can be  interpreted  with  multiple
+meanings, and several terms used in various RMR documentation
+are RMR specific. The following definitions are the meanings
+of  terms  used within RMR documentation and should help the
+reader to understand the intent of meaning.
+
+    .. list-table::
+      :widths: 25,70
+      :header-rows: 0
+      :class: borderless
+
+      * - **application**
+        -
+          A programme which uses RMR to send and/or  receive  messages
+          to/from another RMR based application.
+
+      * - **Critical error**
+        -
+          An error that RMR has encountered which will prevent further
+          successful  processing  by  RMR.  Critical  errors  usually
+          indicate that the application should abort.
+
+      * - **Endpoint**
+        -
+          An RMR based application that is defined as being capable of
+          receiving one or more types of messages  (as  defined  by  a
+          *routing key.*)
+
+      * - **Environment variable**
+        -
+          A key/value pair which is set externally to the application,
+          but which is available to the  application  (and  referenced
+          libraries)  through  the ``getenv`` system call. Environment
+          variables are the main method of  communicating  information
+          such as port numbers to RMR.
+
+      * - **Error**
+        -
+          An abnormal condition that RMR has encountered, but will not
+          affect the overall processing by RMR, but may impact certain
+          aspects  such  as the ability to communicate with a specific
+          endpoint. Errors generally indicate that something,  usually
+          external to RMR, must be addressed.
+
+      * - **Host name**
+        -
+          The  name  of  the host as returned by the ``gethostbyname``
+          system call. In a containerised environment this might be the
+          container  or service name depending on how the container is
+          started. From RMR's point of view, a host name can be used to
+          resolve an *endpoint* definition in a *route* table.)
+
+      * - **IP**
+        -
+          Internet  protocol.  A low level transmission protocol which
+          governs   the  transmission  of  datagrams  across  network
+          boundaries.
+
+      * - **Listen socket**
+        -
+          A  *TCP*  socket used to await incoming connection requests.
+          Listen sockets are defined by an interface and  port  number
+          combination  where  the  port  number  is  unique  for  the
+          interface.
+
+      * - **Message**
+        -
+          A series of bytes transmitted from the application to another
+          RMR based application. A message is comprised of RMR specific
+          data (a header), and application data (a payload).
+
+      * - **Message buffer**
+        -
+          A data structure used to describe a message which is  to  be
+          sent  or  has been received. The message buffer includes the
+          payload length, message  type,  message  source,  and  other
+          information.
+
+      * - **Message type**
+        -
+          A  signed  integer  (0-32000)  which  identifies the type of
+          message being transmitted, and is one of the two  components
+          of a *routing key.* See *Subscription ID.*
+
+      * - **Payload**
+        -
+          The  portion  of  a  message which holds the user data to be
+          transmitted to the remote *endpoint.* The  payload  contents
+          are completely application defined.
+
+      * - **RMR context**
+        -
+          A  set of information which defines the current state of the
+          underlying transport connections that RMR is  managing.  The
+          application  will be give a context reference (pointer) that
+          is supplied to most RMR functions as the first parameter.
+
+      * - **Round robin**
+        -
+          The method of selecting an *endpoint* from a list such  that
+          all  *endpoints* are selected before starting at the head of
+          the list.
+
+      * - **Route table**
+        -
+          A series of "rules" which define the possible *endpoints* for
+          each *routing key.*
+
+      * - **Route table manager**
+        -
+          An  application responsible for building a *route table* and
+          then   distributing   it   to   all  applicable  RMR  based
+          applications.
+
+      * - **Routing**
+        -
+          The  process  of  selecting  an *endpoint* which will be the
+          recipient of a message.
+
+      * - **Routing key**
+        -
+          A combination of *message type* and *subscription ID*  which
+          RMR uses to select the destination *endpoint* when sending a
+          message.
+
+      * - **Source**
+        -
+          The sender of a message.
+
+      * - **Subscription ID**
+        -
+          A  signed  integer  value  (0-32000)  which  identifies  the
+          subscription  characteristic  of  a  message.  It is used in
+          conjunction with the *message type* to determine the *routing
+          key.*
+
+      * - **Target**
+        -
+          The *endpoint* selected to receive a message.
+
+      * - **TCP**
+        -
+          Transmission  Control  Protocol. A connection based internet
+          protocol which provides for lossless packet  transportation,
+          usually over IP.
+
+      * - **Thread**
+        -
+          Also  called  a  *process  thread,  or  pthread.*  This is a
+          lightweight process which executes in concurrently with  the
+          application  and  shares  the  same  address space. RMR uses
+          threads to manage asynchronous functions such as route table
+          updates.
+
+      * - **Trace information**
+        -
+          An   optional  portion  of  the  message  buffer  that  the
+          application may populate with data that allows  for  tracing
+          the  progress  of  the  transaction  or application activity
+          across components. RMR makes no use of this data.
+
+      * - **Transaction ID**
+        -
+          A fixed number of bytes in the *message* buffer)  which  the
+          application  may  populate  with  information related to the
+          transaction. RMR makes use of the transaction ID for matching
+          response  messages  with  the  &c function is used to send a
+          message.
+
+      * - **Transient failure**
+        -
+          An error state that is believed to be short lived  and  that
+          the  operation,  if  retried  by  the  application, might be
+          successful.   C   programmers   will   recognise   this  as
+          ``EAGAIN.``
+
+      * - **Warning**
+        -
+          A  warning occurs when RMR has encountered something that it
+          believes isn't correct, but has a defined work round.
+
+      * - **Wormhole**
+        -
+          A  direct  connection  managed  by  RMR  between  the  user
+          application and a remote, RMR based, application.
+
+
+

 
 
 Appendix D -- Code Examples
 ===========================
 
 
 
 Appendix D -- Code Examples
 ===========================
 

-The  following  snippet of code illustrate some of the basic 
-operation of the RMR library. Please refer to  the  examples 
-and  test directories in the RMR repository for complete RMR 
-based programmes. 
+The  following  snippet of code illustrate some of the basic
+operation of the RMR library. Please refer to  the  examples
+and  test directories in the RMR repository for complete RMR
+based programmes.

 
 
 Sender Sample
 -------------
 
 
 
 Sender Sample
 -------------
 

-The following code segment shows how a message buffer can be 
-allocated, populated, and sent. The snippet also illustrates 
-how the result from the ``rmr_send_msg()`` function is  used 
-to send the next message. It does not illustrate error and/or 
-retry handling. 
- 
- 
-:: 
- 
-   
+The following code segment shows how a message buffer can be
+allocated, populated, and sent. The snippet also illustrates
+how the result from the ``rmr_send_msg()`` function is  used
+to send the next message. It does not illustrate error and/or
+retry handling.
+
+
+::
+
+

   #include <unistd.h>
   #include <errno.h>
   #include <string.h>
   #include <unistd.h>
   #include <errno.h>
   #include <string.h>


@@ -1194,9 +1194,9 @@ retry handling.
   #include <stdlib.h>
   #include <sys/epoll.h>
   #include <time.h>
   #include <stdlib.h>
   #include <sys/epoll.h>
   #include <time.h>

-   
+

   #include <rmr/rmr.h>
   #include <rmr/rmr.h>

-   
+

   int main( int argc, char** argv ) {
       void* mrc;                            // msg router context
       struct epoll_event events[1];        // list of events to give to epoll
   int main( int argc, char** argv ) {
       void* mrc;                            // msg router context
       struct epoll_event events[1];        // list of events to give to epoll


@@ -1212,7 +1212,7 @@ retry handling.
       int        delay = 1000000;            // mu-sec delay between messages
       int        mtype = 0;
       int        stats_freq = 100;
       int        delay = 1000000;            // mu-sec delay between messages
       int        mtype = 0;
       int        stats_freq = 100;

-   
+

       if( argc > 1 ) {                    // simplistic arg picking
           listen_port = argv[1];
       }
       if( argc > 1 ) {                    // simplistic arg picking
           listen_port = argv[1];
       }


@@ -1222,15 +1222,15 @@ retry handling.
       if( argc > 3 ) {
           mtype = atoi( argv[3] );
       }
       if( argc > 3 ) {
           mtype = atoi( argv[3] );
       }

-   
+

       fprintf( stderr, "<DEMO> listen port: %s; mtype: %d; delay: %d\\n",
           listen_port, mtype, delay );
       fprintf( stderr, "<DEMO> listen port: %s; mtype: %d; delay: %d\\n",
           listen_port, mtype, delay );

-   
+

       if( (mrc = rmr_init( listen_port, 1400, RMRFL_NONE )) == NULL ) {
           fprintf( stderr, "<DEMO> unable to initialise RMR\\n" );
           exit( 1 );
       }
       if( (mrc = rmr_init( listen_port, 1400, RMRFL_NONE )) == NULL ) {
           fprintf( stderr, "<DEMO> unable to initialise RMR\\n" );
           exit( 1 );
       }

-   
+

       rcv_fd = rmr_get_rcvfd( mrc );  // set up epoll things, start by getting the FD from RMR
       if( rcv_fd < 0 ) {
           fprintf( stderr, "<DEMO> unable to set up polling fd\\n" );
       rcv_fd = rmr_get_rcvfd( mrc );  // set up epoll things, start by getting the FD from RMR
       if( rcv_fd < 0 ) {
           fprintf( stderr, "<DEMO> unable to set up polling fd\\n" );


@@ -1242,26 +1242,26 @@ retry handling.
       }
       epe.events = EPOLLIN;
       epe.data.fd = rcv_fd;
       }
       epe.events = EPOLLIN;
       epe.data.fd = rcv_fd;

-   
+

       if( epoll_ctl( ep_fd, EPOLL_CTL_ADD, rcv_fd, &epe ) != 0 )  {
           fprintf( stderr, "[FAIL] epoll_ctl status not 0 : %s\\n", strerror( errno ) );
           exit( 1 );
       }
       if( epoll_ctl( ep_fd, EPOLL_CTL_ADD, rcv_fd, &epe ) != 0 )  {
           fprintf( stderr, "[FAIL] epoll_ctl status not 0 : %s\\n", strerror( errno ) );
           exit( 1 );
       }

-   
+

       sbuf = rmr_alloc_msg( mrc, 256 );    // alloc 1st send buf; subsequent bufs alloc on send
       rbuf = NULL;                        // don't need to alloc receive buffer
       sbuf = rmr_alloc_msg( mrc, 256 );    // alloc 1st send buf; subsequent bufs alloc on send
       rbuf = NULL;                        // don't need to alloc receive buffer

-   
+

       while( ! rmr_ready( mrc ) ) {        // must have route table
           sleep( 1 );                        // wait til we get one
       }
       fprintf( stderr, "<DEMO> rmr is ready\\n" );
       while( ! rmr_ready( mrc ) ) {        // must have route table
           sleep( 1 );                        // wait til we get one
       }
       fprintf( stderr, "<DEMO> rmr is ready\\n" );

-   
-   
+
+

       while( 1 ) {            // send messages until the cows come home
           snprintf( sbuf->payload, 200,
               "count=%d received= %d ts=%lld %d stand up and cheer!",    // create the payload
               count, rcvd_count, (long long) time( NULL ), rand() );
       while( 1 ) {            // send messages until the cows come home
           snprintf( sbuf->payload, 200,
               "count=%d received= %d ts=%lld %d stand up and cheer!",    // create the payload
               count, rcvd_count, (long long) time( NULL ), rand() );

-   
+

           sbuf->mtype = mtype;                            // fill in the message bits
           sbuf->len =  strlen( sbuf->payload ) + 1;        // send full ascii-z string
           sbuf->state = 0;
           sbuf->mtype = mtype;                            // fill in the message bits
           sbuf->len =  strlen( sbuf->payload ) + 1;        // send full ascii-z string
           sbuf->state = 0;


@@ -1270,7 +1270,7 @@ retry handling.
               sbuf = rmr_send_msg( mrc, sbuf );            // w/ simple spin that doesn't give up
           }
           count++;
               sbuf = rmr_send_msg( mrc, sbuf );            // w/ simple spin that doesn't give up
           }
           count++;

-   
+

           // check to see if anything was received and pull all messages in
           while( (nready = epoll_wait( ep_fd, events, 1, 0 )) > 0 ) { // 0 is non-blocking
               if( events[0].data.fd == rcv_fd ) {     // waiting on 1 thing, so [0] is ok
           // check to see if anything was received and pull all messages in
           while( (nready = epoll_wait( ep_fd, events, 1, 0 )) > 0 ) { // 0 is non-blocking
               if( events[0].data.fd == rcv_fd ) {     // waiting on 1 thing, so [0] is ok


@@ -1281,40 +1281,40 @@ retry handling.
                   }
               }
           }
                   }
               }
           }

-   
+

           if( (count % stats_freq) == 0 ) {            // occasional stats out to tty
               fprintf( stderr, "<DEMO> sent %d   received %d\\n", count, rcvd_count );
           }
           if( (count % stats_freq) == 0 ) {            // occasional stats out to tty
               fprintf( stderr, "<DEMO> sent %d   received %d\\n", count, rcvd_count );
           }

-   
+

           usleep( delay );
       }
   }
           usleep( delay );
       }
   }

-   
- 
+
+

 
 
 Receiver Sample
 ---------------
 
 
 
 Receiver Sample
 ---------------
 

-The receiver code is even simpler than the sender code as it 
-does  not  need  to  wait  for a route table to arrive (only 
-senders need to do that), nor does it need  to  allocate  an 
-initial  buffer.  The  example  assumes  that  the sender is 
-transmitting a zero terminated string as the payload. 
- 
- 
-:: 
- 
-   
+The receiver code is even simpler than the sender code as it
+does  not  need  to  wait  for a route table to arrive (only
+senders need to do that), nor does it need  to  allocate  an
+initial  buffer.  The  example  assumes  that  the sender is
+transmitting a zero terminated string as the payload.
+
+
+::
+
+

   #include <unistd.h>
   #include <errno.h>
   #include <stdio.h>
   #include <stdlib.h>
   #include <time.h>
   #include <unistd.h>
   #include <errno.h>
   #include <stdio.h>
   #include <stdlib.h>
   #include <time.h>

-   
+

   #include <rmr/rmr.h>
   #include <rmr/rmr.h>

-   
-   
+
+

   int main( int argc, char** argv ) {
       void* mrc;                     // msg router context
       long long total = 0;
   int main( int argc, char** argv ) {
       void* mrc;                     // msg router context
       long long total = 0;


@@ -1325,7 +1325,7 @@ transmitting a zero terminated string as the payload.
       long long count = 0;
       long long bad = 0;
       long long empty = 0;
       long long count = 0;
       long long bad = 0;
       long long empty = 0;

-   
+

       if( argc > 1 ) {
           listen_port = argv[1];
       }
       if( argc > 1 ) {
           listen_port = argv[1];
       }


@@ -1334,22 +1334,22 @@ transmitting a zero terminated string as the payload.
       }
       fprintf( stderr, "<DEMO> listening on port: %s\\n", listen_port );
       fprintf( stderr, "<DEMO> stats will be reported every %d messages\\n", stat_freq );
       }
       fprintf( stderr, "<DEMO> listening on port: %s\\n", listen_port );
       fprintf( stderr, "<DEMO> stats will be reported every %d messages\\n", stat_freq );

-   
+

       mrc = rmr_init( listen_port, RMR_MAX_RCV_BYTES, RMRFL_NONE );
       if( mrc == NULL ) {
           fprintf( stderr, "<DEMO> ABORT:  unable to initialise RMr\\n" );
           exit( 1 );
       }
       mrc = rmr_init( listen_port, RMR_MAX_RCV_BYTES, RMRFL_NONE );
       if( mrc == NULL ) {
           fprintf( stderr, "<DEMO> ABORT:  unable to initialise RMr\\n" );
           exit( 1 );
       }

-   
+

       while( ! rmr_ready( mrc ) ) {    // wait for RMR to get a route table
           fprintf( stderr, "<DEMO> waiting for ready\\n" );
           sleep( 3 );
       }
       fprintf( stderr, "<DEMO> rmr now shows ready\\n" );
       while( ! rmr_ready( mrc ) ) {    // wait for RMR to get a route table
           fprintf( stderr, "<DEMO> waiting for ready\\n" );
           sleep( 3 );
       }
       fprintf( stderr, "<DEMO> rmr now shows ready\\n" );

-   
+

       while( 1 ) {                              // receive until killed
           msg = rmr_rcv_msg( mrc, msg );        // block until one arrives
       while( 1 ) {                              // receive until killed
           msg = rmr_rcv_msg( mrc, msg );        // block until one arrives

-   
+

           if( msg ) {
               if( msg->state == RMR_OK ) {
                   count++;                      // nothing fancy, just count
           if( msg ) {
               if( msg->state == RMR_OK ) {
                   count++;                      // nothing fancy, just count


@@ -1359,67 +1359,67 @@ transmitting a zero terminated string as the payload.
           } else {
               empty++;
           }
           } else {
               empty++;
           }

-   
+

           if( (count % stat_freq) == 0  ) {
               fprintf( stderr, "<DEMO> total received: %lld; errors: %lld; empty: %lld\\n",
                   count, bad, empty );
           }
       }
   }
           if( (count % stat_freq) == 0  ) {
               fprintf( stderr, "<DEMO> total received: %lld; errors: %lld; empty: %lld\\n",
                   count, bad, empty );
           }
       }
   }

-   
- 
+
+

 
 
 Receive and Send Sample
 -----------------------
 
 
 
 Receive and Send Sample
 -----------------------
 

-The following code snippet receives messages and responds to 
-the  sender if the message type is odd. The code illustrates 
-how the received message may be used to return a message  to 
-the source. Variable type definitions are omitted for clarity 
-and should be obvious. 
- 
-It should also be noted that things like  the  message  type 
-which  id returned to the sender (99) is a random value that 
-these applications would have agreed on in  advance  and  is 
-**not** an RMR definition. 
- 
- 
-:: 
- 
+The following code snippet receives messages and responds to
+the  sender if the message type is odd. The code illustrates
+how the received message may be used to return a message  to
+the source. Variable type definitions are omitted for clarity
+and should be obvious.
+
+It should also be noted that things like  the  message  type
+which  id returned to the sender (99) is a random value that
+these applications would have agreed on in  advance  and  is
+**not** an RMR definition.
+
+
+::
+

   mrc = rmr_init( listen_port, MAX_BUF_SZ, RMRFL_NOFLAGS );
   rmr_set_stimeout( mrc, 1 );        // allow RMR to retry failed sends for ~1ms
   mrc = rmr_init( listen_port, MAX_BUF_SZ, RMRFL_NOFLAGS );
   rmr_set_stimeout( mrc, 1 );        // allow RMR to retry failed sends for ~1ms

-   
+

   while( ! rmr_ready( mrc ) ) {        // we send, therefore we need a route table
       sleep( 1 );
   }
   while( ! rmr_ready( mrc ) ) {        // we send, therefore we need a route table
       sleep( 1 );
   }

-   
+

   mbuf = NULL;                        // ensure our buffer pointer is nil for 1st call
   mbuf = NULL;                        // ensure our buffer pointer is nil for 1st call

-   
+

   while( TRUE ) {
       mbuf = rmr_rcv_msg( mrc, mbuf );        // wait for message
   while( TRUE ) {
       mbuf = rmr_rcv_msg( mrc, mbuf );        // wait for message

-   
+

       if( mbuf == NULL || mbuf->state != RMR_OK ) {
           break;
       }
       if( mbuf == NULL || mbuf->state != RMR_OK ) {
           break;
       }

-   
+

       if( mbuf->mtype % 2 ) {                // respond to odd message types
           plen = rmr_payload_size( mbuf );        // max size
       if( mbuf->mtype % 2 ) {                // respond to odd message types
           plen = rmr_payload_size( mbuf );        // max size

-   
+

                                                   // reset necessary fields in msg
           mbuf->mtype = 99;                       // response type
           mbuf->sub_id = RMR_VOID_SUBID;          // we turn subid off
           mbuf->len = snprintf( mbuf->payload, plen, "pong: %s", get_info() );
                                                   // reset necessary fields in msg
           mbuf->mtype = 99;                       // response type
           mbuf->sub_id = RMR_VOID_SUBID;          // we turn subid off
           mbuf->len = snprintf( mbuf->payload, plen, "pong: %s", get_info() );

-   
+

           mbuf = rmr_rts_msg( mrc, mbuf );        // return to sender
           if( mbuf == NULL || mbuf->state != RMR_OK ) {
               fprintf( stderr, "return to sender failed\\n" );
           }
       }
   }
           mbuf = rmr_rts_msg( mrc, mbuf );        // return to sender
           if( mbuf == NULL || mbuf->state != RMR_OK ) {
               fprintf( stderr, "return to sender failed\\n" );
           }
       }
   }

-   
+

   fprintf( stderr, "abort: receive failure\\n" );
   rmr_close( mrc );
   fprintf( stderr, "abort: receive failure\\n" );
   rmr_close( mrc );

-   
- 
- 
+
+
+

diff --git a/src/rmr/si/src/si95/siconnect.c b/src/rmr/si/src/si95/siconnect.c
index 77dce63..ad5135d 100644 (file)
--- a/src/rmr/si/src/si95/siconnect.c
+++ b/src/rmr/si/src/si95/siconnect.c
@@ -131,14 +131,12 @@ extern int SIconnect( struct ginfo_blk *gptr, char *abuf ) {
                errno = 0;
                if( tpptr->flags & TPF_SAFEC ) {
                        if( safe_connect( tpptr->fd, taddr, tpptr->palen ) != 0 ) {             // fd closed on failure
                errno = 0;
                if( tpptr->flags & TPF_SAFEC ) {
                        if( safe_connect( tpptr->fd, taddr, tpptr->palen ) != 0 ) {             // fd closed on failure

-                               SItrash( TP_BLK, tpptr );

                                tpptr->fd = -1;
                        }
                } else {
                        if( CONNECT( tpptr->fd, taddr, tpptr->palen ) != 0 ) {
                                CLOSE( tpptr->fd );                             // clean up fd and tp_block
                                tpptr->fd = -1;
                                tpptr->fd = -1;
                        }
                } else {
                        if( CONNECT( tpptr->fd, taddr, tpptr->palen ) != 0 ) {
                                CLOSE( tpptr->fd );                             // clean up fd and tp_block
                                tpptr->fd = -1;

-                               SItrash( TP_BLK, tpptr );               // free the trasnsport block

                        }
                }
 
                        }
                }
 


@@ -152,6 +150,8 @@ extern int SIconnect( struct ginfo_blk *gptr, char *abuf ) {
                        gptr->tplist = tpptr;                           //  point at new head
                        fd = tpptr->fd;                                 //  save for return value
                        SImap_fd( gptr, fd, tpptr );
                        gptr->tplist = tpptr;                           //  point at new head
                        fd = tpptr->fd;                                 //  save for return value
                        SImap_fd( gptr, fd, tpptr );

+               } else {
+                       SItrash( TP_BLK, tpptr );               // free the trasnsport block

                }
        }
 
                }
        }