Manual page updates for v1.3.2

1 files changed, 379 insertions, 0 deletions

diff --git a/man/v1.3.2/nng.7.html b/man/v1.3.2/nng.7.html
new file mode 100644
index 00000000..69c59393
--- /dev/null
+++ b/man/v1.3.2/nng.7.html
@@ -0,0 +1,379 @@
+---
+version: v1.3.2
+layout: manpage_v2
+---
+<h1>nng(7)</h1>
+<div class="sect1">
+<h2 id="_name">NAME</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>nng - nanomsg next generation</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_synopsis">SYNOPSIS</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><strong>cc</strong> [&#39;flags&#39;] &#39;files&#39; <strong>-lnng</strong> [&#39;libraries&#39;]</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_description">DESCRIPTION</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><em>NNG</em> provides a common messaging framework intended to
+solve common communication problems in distributed applications.
+It offers a number of <em>protocols</em>, and also a number of <em>transports</em>.</p>
+</div>
+<div class="paragraph">
+<p>The <em>protocols</em> implement the semantics associated with particular
+communications scenarios, such as RPC style services, service discovery,
+publish/subscribe, and so forth.</p>
+</div>
+<div class="paragraph">
+<p>The <em>transports</em> provide support for underlying transport methods, such
+as TCP, IPC, websockets, and so forth.</p>
+</div>
+<div class="paragraph">
+<p><em>NNG</em> is designed to permit easy creation of new <em>transports</em> and,
+to a lesser extent, new <em>protocols</em>.</p>
+</div>
+<div class="paragraph">
+<p><em>NNG</em> is wire compatible with the SP protocols described in
+the nanomsg project; projects using
+<a href="https://github.com/nanomsg/nanomsg"><em>libnanomsg</em></a> can inter-operate with
+nng as well as other conforming implementations.  (One such implementation
+is <a href="https://github.com/go-mangos/mangos"><em>mangos</em></a>.)
+Applications using <em>NNG</em>
+which wish to communicate with other libraries must ensure that they only
+use protocols or transports offered by the other library.</p>
+</div>
+<div class="paragraph">
+<p><em>NNG</em> also offers a compatible API, permitting legacy code to
+be recompiled or relinked against <em>NNG</em>.  When doing this, support for
+certain enhancements or features will likely be absent, requiring the
+application developer to use the new-style API.</p>
+</div>
+<div class="paragraph">
+<p><em>NNG</em> is implemented in pure C; if you need bindings for
+other languages please check the <a href="http://nanomsg.org/">website</a>.</p>
+</div>
+<div class="sect2">
+<h3 id="_protocols">Protocols</h3>
+<div class="hdlist">
+<table>
+<tr>
+<td class="hdlist1">
+<a href="nng_bus.7.html">nng_bus(7)</a>
+</td>
+<td class="hdlist2">
+<p>Bus protocol</p>
+</td>
+</tr>
+<tr>
+<td class="hdlist1">
+<a href="nng_pair.7.html">nng_pair(7)</a>
+</td>
+<td class="hdlist2">
+<p>Pair protocol</p>
+</td>
+</tr>
+<tr>
+<td class="hdlist1">
+<a href="nng_pub.7.html">nng_pub(7)</a>
+</td>
+<td class="hdlist2">
+<p>Publisher side of publish/subscribe protocol</p>
+</td>
+</tr>
+<tr>
+<td class="hdlist1">
+<a href="nng_pull.7.html">nng_pull(7)</a>
+</td>
+<td class="hdlist2">
+<p>Pull side of pipeline protocol</p>
+</td>
+</tr>
+<tr>
+<td class="hdlist1">
+<a href="nng_push.7.html">nng_push(7)</a>
+</td>
+<td class="hdlist2">
+<p>Push side of pipeline protocol</p>
+</td>
+</tr>
+<tr>
+<td class="hdlist1">
+<a href="nng_sub.7.html">nng_sub(7)</a>
+</td>
+<td class="hdlist2">
+<p>Subscriber side of publish/subscribe protocol</p>
+</td>
+</tr>
+<tr>
+<td class="hdlist1">
+<a href="nng_rep.7.html">nng_rep(7)</a>
+</td>
+<td class="hdlist2">
+<p>Reply side of request/reply protocol</p>
+</td>
+</tr>
+<tr>
+<td class="hdlist1">
+<a href="nng_req.7.html">nng_req(7)</a>
+</td>
+<td class="hdlist2">
+<p>Request side of request/reply protocol</p>
+</td>
+</tr>
+<tr>
+<td class="hdlist1">
+<a href="nng_respondent.7.html">nng_respondent(7)</a>
+</td>
+<td class="hdlist2">
+<p>Respondent side of survey protocol</p>
+</td>
+</tr>
+<tr>
+<td class="hdlist1">
+<a href="nng_surveyor.7.html">nng_surveyor(7)</a>
+</td>
+<td class="hdlist2">
+<p>Surveyor side of survey protocol</p>
+</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_transports">Transports</h3>
+<div class="hdlist">
+<table>
+<tr>
+<td class="hdlist1">
+<a href="nng_inproc.7.html">nng_inproc(7)</a>
+</td>
+<td class="hdlist2">
+<p>Intra-process transport</p>
+</td>
+</tr>
+<tr>
+<td class="hdlist1">
+<a href="nng_ipc.7.html">nng_ipc(7)</a>
+</td>
+<td class="hdlist2">
+<p>Inter-process transport</p>
+</td>
+</tr>
+<tr>
+<td class="hdlist1">
+<a href="nng_tls.7.html">nng_tls(7)</a>
+</td>
+<td class="hdlist2">
+<p>TLSv1.2 over TCP transport</p>
+</td>
+</tr>
+<tr>
+<td class="hdlist1">
+<a href="nng_tcp.7.html">nng_tcp(7)</a>
+</td>
+<td class="hdlist2">
+<p>TCP (and TCPv6) transport</p>
+</td>
+</tr>
+<tr>
+<td class="hdlist1">
+<a href="nng_ws.7.html">nng_ws(7)</a>
+</td>
+<td class="hdlist2">
+<p>WebSocket transport</p>
+</td>
+</tr>
+<tr>
+<td class="hdlist1">
+<a href="nng_zerotier.7.html">nng_zerotier(7)</a>
+</td>
+<td class="hdlist2">
+<p>ZeroTier transport</p>
+</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_conceptual_overview">Conceptual Overview</h3>
+<div class="paragraph">
+<p><em>NNG</em> presents a <em>socket</em> view of networking.
+The sockets are constructed using protocol-specific functions, as a given
+socket implements precisely one protocol.</p>
+</div>
+<div class="paragraph">
+<p>Each socket can be used to send and receive messages (if the protocol)
+supports it, and implements the appropriate protocol semantics.
+For example, <a href="nng_sub.7.html"><em>sub</em></a> sockets automatically filter incoming
+messages to discard those for topics that have not been subscribed.</p>
+</div>
+<div class="paragraph">
+<p><em>NNG</em> sockets are message oriented, so that messages are either delivered
+wholly, or not at all.  Partial delivery is not possible.
+Furthermore, <em>NNG</em> does not provide any other delivery or ordering guarantees;
+messages may be dropped or reordered
+(Some protocols, such as <a href="nng_req.7.html"><em>req</em></a> may offer stronger
+guarantees by performing their own retry and validation schemes.)</p>
+</div>
+<div class="paragraph">
+<p>Each socket can have zero, one, or many endpoints, which are either
+<em>listeners</em> or <em>dialers</em>.
+(A given socket may freely choose whether it uses listeners, dialers, or both.)
+These endpoints provide access to underlying transports, such as TCP, etc.</p>
+</div>
+<div class="paragraph">
+<p>Each endpoint is associated with a URL, which is a service address.
+For dialers, this will be the service address that will be contacted, whereas
+for listeners this is where the listener will accept new connections.</p>
+</div>
+<div class="paragraph">
+<p>Endpoints do not themselves transport data.
+They are instead responsible for the creation of <em>pipes</em>, which can be
+thought of as message-oriented connected streams.
+Pipes frequently correspond to a single underlying byte stream.
+For example both IPC and TCP transports implement their
+pipes using a 1:1 relationship with a connected operating system socket.</p>
+</div>
+<div class="paragraph">
+<p>Endpoints create pipes as needed.
+Listeners will create them when a new client connection request arrives,
+and dialers will generally create one, then wait for it to disconnect before
+reconnecting.</p>
+</div>
+<div class="paragraph">
+<p>Most applications should not have to worry about endpoints or pipes at
+all; the socket abstraction should provide all the functionality needed
+other than in a few specific circumstances.</p>
+</div>
+<div class="sect3">
+<h4 id="raw_mode">Raw Mode</h4>
+<div class="paragraph">
+<p>Most applications will use sockets in normal, or <em>cooked</em>, mode.
+This mode provides the full semantics of the protocol.
+For example, <a href="nng_req.7.html"><em>req</em></a> sockets will automatically
+match a reply to a request, and resend requests periodically if no reply
+was received.</p>
+</div>
+<div class="paragraph">
+<p>There are situations, such as with <a href="nng_device.3.html">proxies</a>,
+where it is desirable to bypass these semantics and simply pass messages
+to and from the socket with no extra semantic handling.
+This is possible using <em>raw</em> mode sockets.</p>
+</div>
+<div class="paragraph">
+<p>Raw mode sockets are generally constructed with a different function,
+such as <a href="nng_req_open.3.html"><code>nng_req0_open_raw()</code></a>.
+Using these sockets, the application can simply send and receive messages,
+and is responsible for supplying any additional socket semantics.
+Typically this means that the application will need to inspect message
+headers on incoming messages, and supply them on outgoing messages.</p>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+The <a href="nng_device.3.html"><code>nng_device()</code></a> function only works with raw mode
+sockets, but as it only forwards the messages, no additional application
+processing is needed.
+</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_urls">URLs</h4>
+<div class="paragraph">
+<p><em>NNG</em> uses universal resource locators (URLs)
+following the format specified in
+<a href="https://tools.ietf.org/html/rfc3986">RFC 3986</a>,
+including some schemes that are unique
+to SP.
+The URLs used in <em>NNG</em> are canonicalized as follows, mostly in
+accordance with
+<a href="https://tools.ietf.org/html/rfc3986#section-6.2.2">RFC 3986 6.2.2</a>:</p>
+</div>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>The URL is parsed into scheme, userinfo, host, port, path, query and
+    fragment components.  (Not all of these members are necessarily present.)</p>
+</li>
+<li>
+<p>The scheme, hostname, and port if present, are converted to lower case.</p>
+</li>
+<li>
+<p>Percent-encoded values for
+    <a href="https://tools.ietf.org/html/rfc3986#section-2.3">unreserved characters</a>
+    converted to their unencoded forms.</p>
+</li>
+<li>
+<p>Additionally URL percent-encoded values for characters in the path
+    and with numeric values larger than 127 (i.e. not ASCII) are decoded.</p>
+</li>
+<li>
+<p>The resulting path is checked for invalid UTF-8 sequences, consisting
+    of surrogate pairs, illegal byte sequences, or overlong encodings.
+    If this check fails, then the entire URL is considered invalid.</p>
+</li>
+<li>
+<p>Path segments consisting of <code>.</code> and <code>..</code> are resolved as per
+    <a href="https://tools.ietf.org/html/rfc3986#section-6.2.2.3">RFC 3986 6.2.2.3</a>.</p>
+</li>
+<li>
+<p>Further, empty path segments are removed, meaning that duplicate
+    slash (<code>/</code>) separators are removed from the path.</p>
+</li>
+</ol>
+</div>
+<div class="paragraph">
+<p>Note that steps 4, 5, and 7 are not specified by RFC 3986, but performing
+them is believed to improve both the usability and security of
+applications, without violating RFC 3986 itself.</p>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+Port numbers may be service names in some instances, but it is recommended
+that numeric port numbers be used when known.
+If service names are used, it is recommended that they follow the naming
+conventions for C identifiers, and not be longer than 32 characters in length.
+This will maximize compatibility across systems and minimize opportunities for
+confusion when they are parsed on different systems.
+</td>
+</tr>
+</table>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_api">API</h3>
+<div class="paragraph">
+<p>The library API is documented at <a href="libnng.3.html">libnng(3)</a>.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_see_also">SEE ALSO</h2>
+<div class="sectionbody">
+<div class="paragraph text-left">
+<p><a href="libnng.3.html">libnng(3)</a>,
+<a href="nng_compat.3compat.html">nng_compat(3compat)</a></p>
+</div>
+</div>
+</div>