man page updates for tip

4 files changed, 163 insertions, 26 deletions

diff --git a/man/tip/nng_bus.7.html b/man/tip/nng_bus.7.html
index 0c643e84..464e74ae 100644
--- a/man/tip/nng_bus.7.html
+++ b/man/tip/nng_bus.7.html
@@ -609,7 +609,19 @@ Sending messages will attempt to deliver to each directly connected peer.</p>
 <div class="sect2">
 <h3 id="_protocol_headers">Protocol Headers</h3>
 <div class="paragraph">
-<p>The <em>bus</em> protocol has no protocol-specific headers.</p>
+<p>When using a &#8220;<a href="nng.7.html#raw_mode">raw</a>&#8221; <em>bus</em> socket, received messages will
+contain the incoming <a href="nng_pipe.5.html">pipe</a> ID as the sole element in the header.
+If a message containing such a header is sent using a raw <em>bus</em> socket, then,
+the message will be delivered to all connected pipes <em>except</em> the one
+identified in the header.
+This behavior is intended for use with <a href="nng_device.3.html#device">device</a>
+configurations consisting of just a single socket.
+Such configurations are useful in the creation of rebroadcasters, and this
+capaibility prevents a message from being routed back to its source.
+If no header is present, then a message is sent to all connected pipes.</p>
+</div>
+<div class="paragraph">
+<p>When using &#8220;cooked&#8221; <em>bus</em> sockets, no message headers are present.</p>
 </div>
 </div>
 </div>
diff --git a/man/tip/nng_pipe_notify.3.html b/man/tip/nng_pipe_notify.3.html
index 9c22bbdd..443b7ed9 100644
--- a/man/tip/nng_pipe_notify.3.html
+++ b/man/tip/nng_pipe_notify.3.html
@@ -527,14 +527,15 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <div class="content">
 <pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span> <span class="tok-cpf">&lt;nng/nng.h&gt;</span><span class="tok-cp"></span>
 
-<span class="tok-k">typedef</span> <span class="tok-k">enum</span> <span class="tok-p">{</span>
-        <span class="tok-n">NNG_PIPE_ADD</span><span class="tok-p">,</span>
-        <span class="tok-n">NNG_PIPE_REM</span><span class="tok-p">,</span>
-<span class="tok-p">}</span> <span class="tok-n">nng_pipe_action</span><span class="tok-p">;</span>
+<span class="tok-k">enum</span> <span class="tok-p">{</span>
+        <span class="tok-n">NNG_PIPE_EV_ADD_PRE</span><span class="tok-p">,</span>
+        <span class="tok-n">NNG_PIPE_EV_ADD_POST</span><span class="tok-p">,</span>
+        <span class="tok-n">NNG_PIPE_EV_REM_POST</span><span class="tok-p">,</span>
+<span class="tok-p">};</span>
 
-<span class="tok-k">typedef</span> <span class="tok-nf">void</span> <span class="tok-p">(</span><span class="tok-o">*</span><span class="tok-n">nng_pipe_cb</span><span class="tok-p">)(</span><span class="tok-n">nng_pipe</span><span class="tok-p">,</span> <span class="tok-n">nng_pipe_action</span><span class="tok-p">,</span> <span class="tok-kt">void</span> <span class="tok-o">*</span><span class="tok-p">);</span>
+<span class="tok-k">typedef</span> <span class="tok-nf">void</span> <span class="tok-p">(</span><span class="tok-o">*</span><span class="tok-n">nng_pipe_cb</span><span class="tok-p">)(</span><span class="tok-n">nng_pipe</span><span class="tok-p">,</span> <span class="tok-kt">int</span><span class="tok-p">,</span> <span class="tok-kt">void</span> <span class="tok-o">*</span><span class="tok-p">);</span>
 
-<span class="tok-kt">int</span> <span class="tok-nf">nng_pipe_notify</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span> <span class="tok-n">s</span><span class="tok-p">,</span> <span class="tok-n">nng_pipe_cb</span> <span class="tok-n">cb</span><span class="tok-p">,</span> <span class="tok-kt">void</span> <span class="tok-o">*</span><span class="tok-n">arg</span><span class="tok-p">);</span></code></pre>
+<span class="tok-kt">int</span> <span class="tok-nf">nng_pipe_notify</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span> <span class="tok-n">s</span><span class="tok-p">,</span> <span class="tok-kt">int</span> <span class="tok-n">ev</span><span class="tok-p">,</span> <span class="tok-n">nng_pipe_cb</span> <span class="tok-n">cb</span><span class="tok-p">,</span> <span class="tok-kt">void</span> <span class="tok-o">*</span><span class="tok-n">arg</span><span class="tok-p">);</span></code></pre>
 </div>
 </div>
 </div>
@@ -544,30 +545,55 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <div class="sectionbody">
 <div class="paragraph">
 <p>The <code>nng_pipe_notify()</code> function registers the callback function <em>cb</em>
-to be called whenever a <a href="nng_pipe.5.html">pipe</a> is added to or removed from the
-socket <em>s</em>.</p>
+to be called whenever a <a href="nng_pipe.5.html">pipe</a> the pipe event specified by
+<em>ev</em> occurs on the socket <em>s</em>.
+The callback <em>cb</em> will be passed <em>arg</em> as its final argument.</p>
 </div>
 <div class="paragraph">
-<p>The function <em>cb</em> will be called with the action <code>NNG_PIPE_ADD</code> just before
-a pipe is added to the socket (as a result of a connection being established).
-The final argument passed will be the argument <em>arg</em> that was specified when
-the function was registered.</p>
+<p>A different callback may be supplied for each event.
+Each event may have at most one callback registered.
+Registering a callback implicitly unregisters any previously registered.</p>
 </div>
 <div class="paragraph">
-<p>The function <em>cb</em> will also be called with the action <code>NNG_PIPE_REM</code> when
-the pipe is being removed from the socket for any reason.
-This will also use the same argument <em>arg</em>.</p>
+<p>The following pipe events are supported:</p>
 </div>
-<div class="admonitionblock note">
+<div class="dlist">
+<dl>
+<dt class="hdlist1"><code>NNG_PIPE_EV_ADD_PRE</code></dt>
+<dd>
+<p>This event occurs after a connection and negotiation
+has completed, but before the pipe is added to the socket.
+If the pipe is closed (using <code><a href="nng_pipe_close.3.html">nng_pipe_close()</a></code>) at
+this point, the socket will never see the pipe, and no further events will
+occur for the given pipe.</p>
+</dd>
+<dt class="hdlist1"><code>NNG_PIPE_EV_ADD_POST</code></dt>
+<dd>
+<p>This event occurs after the pipe is fully added to
+the socket.
+Prior to this time, it is not possible to communicate over the pipe with
+the socket.</p>
+</dd>
+<dt class="hdlist1"><code>NNG_PIPE_EV_REM_POST</code></dt>
+<dd>
+<p>This event occurs after the pipe has been removed
+from the socket.
+The underlying transport may be closed at this point, and it is not
+possible communicate using this pipe.</p>
+</dd>
+</dl>
+</div>
+<div class="admonitionblock tip">
 <table>
 <tr>
 <td class="icon">
-<i class="fa icon-note" title="Note"></i>
+<i class="fa icon-tip" title="Tip"></i>
 </td>
 <td class="content">
-Only one callback can be registered for a given socket.
-Subsequent calls to <code>nng_pipe_notify()</code> on the same socket will overwrite
-any prior registration.
+The callback <em>cb</em> may close a pipe for any reason by simply closing
+it using <code><a href="nng_pipe_close.3.html">nng_pipe_close()</a></code>.
+This might be done before the pipe is added to the socket (during
+<code>NNG_PIPE_EV_ADD_PRE</code>), for example, if the remote peer is not authorized.
 </td>
 </tr>
 </table>
@@ -579,11 +605,20 @@ any prior registration.
 <i class="fa icon-tip" title="Tip"></i>
 </td>
 <td class="content">
-The callback <em>cb</em> may reject a pipe for any reason by simply closing
-it using <code><a href="nng_pipe_close.3.html">nng_pipe_close()</a></code>.
-This might be done, for example, if the remote peer is not authorized to
-access this session, based on values determined with the aid of
-<code><a href="nng_pipe_getopt.3.html">nng_pipe_getopt()</a></code>.
+It is possible to register the same <em>cb</em> and <em>arg</em> for different events
+by calling this function separately for different values of <em>ev</em>.
+</td>
+</tr>
+</table>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+This function ignores invalid values for <em>ev</em>.
 </td>
 </tr>
 </table>
diff --git a/man/tip/nng_tcp.7.html b/man/tip/nng_tcp.7.html
index a1f31e2e..ee7185fc 100644
--- a/man/tip/nng_tcp.7.html
+++ b/man/tip/nng_tcp.7.html
@@ -564,6 +564,51 @@ For example, to contact port 80 on the localhost either of the following URIs
 could be used: <code>tcp://127.0.0.1:80</code> or <code>tcp://localhost:80</code>.</p>
 </div>
 <div class="paragraph">
+<p>A URI may be restricted to IPv6 using the scheme <code>tcp6://</code>, and may
+be restricted to IPv4 using the scheme <code>tcp4://</code>.</p>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+Specifying <code>tcp6://</code> may not prevent IPv4 hosts from being used with
+IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with
+listeners.
+The details of varies across operating systems.
+</td>
+</tr>
+</table>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+Both <code>tcp6://</code> and <code>tcp4://</code> are <em>nng</em> extensions, and will not
+be understood by other implementations such as <em>libnanomsg</em>.
+</td>
+</tr>
+</table>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+We recommend using either numeric IP addresses, or names that are
+specific to either IPv4 or IPv6 to prevent confusion and surprises.
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
 <p>When specifying IPv6 addresses, the address must be enclosed in
 square brackets (<code>[]</code>) to avoid confusion with the final colon
 separating the port.</p>
diff --git a/man/tip/nng_tls.7.html b/man/tip/nng_tls.7.html
index b91bd66f..70669dd0 100644
--- a/man/tip/nng_tls.7.html
+++ b/man/tip/nng_tls.7.html
@@ -612,6 +612,51 @@ either of the following URIs could be used: <code>tls+tcp://127.0.0.1:4433</code
 <code>tls+tcp://localhost:4433</code>.</p>
 </div>
 <div class="paragraph">
+<p>A URI may be restricted to IPv6 using the scheme <code>tls+tcp6://</code>, and may
+be restricted to IPv4 using the scheme <code>tls+tcp4://</code>.</p>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+Specifying <code>tls+tcp6://</code> may not prevent IPv4 hosts from being used with
+IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with
+listeners.
+The details of varies across operating systems.
+</td>
+</tr>
+</table>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+Both <code>tls+tcp6://</code> and <code>tls+tcp4://</code> are <em>nng</em> extensions, and will not
+be understood by other implementations such as <em>mangos</em>.
+</td>
+</tr>
+</table>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+We recommend using either numeric IP addresses, or names that are
+specific to either IPv4 or IPv6 to prevent confusion and surprises.
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
 <p>When specifying IPv6 addresses, the address must be enclosed in
 square brackets (<code>[]</code>) to avoid confusion with the final colon
 separating the port.</p>