deploy: ffeb31c64ea72c4eb287f75b641ca2a707df90b0

author: gdamore <gdamore@users.noreply.github.com> 2024-10-27 18:55:51 +0000
committer: gdamore <gdamore@users.noreply.github.com> 2024-10-27 18:55:51 +0000
commit: 45ac4fa56b6e5c31a28fd08eaad14a09bf3934f6 (patch)
tree: e0ed7b8907d4f6ac5651fb6c9d38556ec46b231a /ref/api
parent: b83fdb3ff1327e4376acd0ca24479b16b24f7e0b (diff)
download: nng-45ac4fa56b6e5c31a28fd08eaad14a09bf3934f6.tar.gz
nng-45ac4fa56b6e5c31a28fd08eaad14a09bf3934f6.tar.bz2
nng-45ac4fa56b6e5c31a28fd08eaad14a09bf3934f6.zip
14 files changed, 5799 insertions, 0 deletions
diff --git a/ref/api/aio.html b/ref/api/aio.html
new file mode 100644
index 00000000..fa90d946
--- /dev/null
+++ b/ref/api/aio.html
@@ -0,0 +1,558 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>Asynchronous I/O - NNG Reference Manual (DRAFT)</title>
+
+
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="../favicon.svg">
+        <link rel="shortcut icon" href="../favicon.png">
+        <link rel="stylesheet" href="../css/variables.css">
+        <link rel="stylesheet" href="../css/general.css">
+        <link rel="stylesheet" href="../css/chrome.css">
+        <link rel="stylesheet" href="../css/print.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="../fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="../highlight.css">
+        <link rel="stylesheet" href="../tomorrow-night.css">
+        <link rel="stylesheet" href="../ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+        <link rel="stylesheet" href="../theme/pagetoc.css">
+
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "../";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded affix "><a href="../copyright.html">Copyright</a></li><li class="chapter-item expanded affix "><a href="../dedication.html">Dedication</a></li><li class="chapter-item expanded affix "><a href="../preface.html">Preface</a></li><li class="chapter-item expanded "><a href="../api/index.html"><strong aria-hidden="true">1.</strong> API Reference</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../api/msg.html"><strong aria-hidden="true">1.1.</strong> Messages</a></li><li class="chapter-item expanded "><a href="../api/memory.html"><strong aria-hidden="true">1.2.</strong> Memory</a></li><li class="chapter-item expanded "><a href="../api/time.html"><strong aria-hidden="true">1.3.</strong> Time</a></li><li class="chapter-item expanded "><a href="../api/url.html"><strong aria-hidden="true">1.4.</strong> URLs</a></li><li class="chapter-item expanded "><a href="../api/aio.html" class="active"><strong aria-hidden="true">1.5.</strong> Asynchronous I/O</a></li><li class="chapter-item expanded "><a href="../api/synch.html"><strong aria-hidden="true">1.6.</strong> Synchronization</a></li><li class="chapter-item expanded "><a href="../api/thread.html"><strong aria-hidden="true">1.7.</strong> Threads</a></li><li class="chapter-item expanded "><a href="../api/logging.html"><strong aria-hidden="true">1.8.</strong> Logging</a></li><li class="chapter-item expanded "><a href="../api/stats.html"><strong aria-hidden="true">1.9.</strong> Statistics</a></li><li class="chapter-item expanded "><a href="../api/errors.html"><strong aria-hidden="true">1.10.</strong> Errors</a></li><li class="chapter-item expanded "><a href="../api/misc.html"><strong aria-hidden="true">1.11.</strong> Miscellaneous</a></li><li class="chapter-item expanded "><a href="../api/id_map.html"><strong aria-hidden="true">1.12.</strong> ID Map</a></li><li class="chapter-item expanded "><a href="../api/cmd_opts.html"><strong aria-hidden="true">1.13.</strong> Command Options</a></li></ol></li><li class="chapter-item expanded "><a href="../proto/index.html"><strong aria-hidden="true">2.</strong> Protocols</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../proto/bus.html"><strong aria-hidden="true">2.1.</strong> BUS Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pair.html"><strong aria-hidden="true">2.2.</strong> PAIR Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pub.html"><strong aria-hidden="true">2.3.</strong> PUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pull.html"><strong aria-hidden="true">2.4.</strong> PULL Protocol</a></li><li class="chapter-item expanded "><a href="../proto/push.html"><strong aria-hidden="true">2.5.</strong> PUSH Protocol</a></li><li class="chapter-item expanded "><a href="../proto/rep.html"><strong aria-hidden="true">2.6.</strong> REP Protocol</a></li><li class="chapter-item expanded "><a href="../proto/req.html"><strong aria-hidden="true">2.7.</strong> REQ Protocol</a></li><li class="chapter-item expanded "><a href="../proto/respondent.html"><strong aria-hidden="true">2.8.</strong> RESPONDENT Protocol</a></li><li class="chapter-item expanded "><a href="../proto/sub.html"><strong aria-hidden="true">2.9.</strong> SUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/surveyor.html"><strong aria-hidden="true">2.10.</strong> SURVEYOR Protocol</a></li></ol></li><li class="chapter-item expanded "><a href="../tran/index.html"><strong aria-hidden="true">3.</strong> Transports</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../tran/inproc.html"><strong aria-hidden="true">3.1.</strong> Intra-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/ipc.html"><strong aria-hidden="true">3.2.</strong> Inter-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/socket.html"><strong aria-hidden="true">3.3.</strong> BSD Socket (Experimental)</a></li><li class="chapter-item expanded "><a href="../tran/udp.html"><strong aria-hidden="true">3.4.</strong> UDP Transport (Experimental)</a></li></ol></li><li class="chapter-item expanded "><a href="../migrate/index.html"><strong aria-hidden="true">4.</strong> Migration Guides</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../migrate/nng1.html"><strong aria-hidden="true">4.1.</strong> Migrating from NNG 1.x</a></li><li class="chapter-item expanded "><a href="../migrate/nanomsg.html"><strong aria-hidden="true">4.2.</strong> Migrating from libnanomsg</a></li></ol></li><li class="chapter-item expanded "><a href="../indexing.html">Index</a></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
+                <div class="sidebar-resize-indicator"></div>
+            </div>
+        </nav>
+
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">NNG Reference Manual (DRAFT)</h1>
+
+                    <div class="right-buttons">
+                        <a href="../print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <style>
+.mdbook-alerts {
+  padding: 8px 16px;
+  margin-bottom: 16px;
+  border-left: 0.25em solid var(--mdbook-alerts-color);
+}
+
+.mdbook-alerts > *:first-child {
+  margin-top: 0;
+}
+
+.mdbook-alerts > *:last-child {
+  margin-bottom: 0;
+}
+
+.mdbook-alerts-title {
+  display: flex;
+  font-weight: 600;
+  align-items: center;
+  line-height: 1;
+  color: var(--mdbook-alerts-color);
+  text-transform: capitalize;
+}
+
+.mdbook-alerts-icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  margin-right: 0.2em;
+  background-color: currentColor;
+  -webkit-mask: no-repeat center / 100%;
+  mask: no-repeat center / 100%;
+  -webkit-mask-image: var(--mdbook-alerts-icon);
+  mask-image: var(--mdbook-alerts-icon);
+}
+
+.mdbook-alerts-note {
+  --mdbook-alerts-color: rgb(9, 105, 218);
+  /* https://icon-sets.iconify.design/material-symbols/info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16v-4q0-.425-.288-.712T12 11q-.425 0-.712.288T11 12v4q0 .425.288.713T12 17m0-8q.425 0 .713-.288T13 8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8q0 .425.288.713T12 9m0 13q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12q0-3.35-2.325-5.675T12 4Q8.65 4 6.325 6.325T4 12q0 3.35 2.325 5.675T12 20m0-8"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-tip {
+  --mdbook-alerts-color: rgb(26, 127, 55);
+  /* https://icon-sets.iconify.design/material-symbols/lightbulb-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 22q-.825 0-1.412-.587T10 20h4q0 .825-.587 1.413T12 22m-3-3q-.425 0-.712-.288T8 18q0-.425.288-.712T9 17h6q.425 0 .713.288T16 18q0 .425-.288.713T15 19zm-.75-3q-1.725-1.025-2.738-2.75T4.5 9.5q0-3.125 2.188-5.312T12 2q3.125 0 5.313 2.188T19.5 9.5q0 2.025-1.012 3.75T15.75 16zm.6-2h6.3q1.125-.8 1.738-1.975T17.5 9.5q0-2.3-1.6-3.9T12 4Q9.7 4 8.1 5.6T6.5 9.5q0 1.35.613 2.525T8.85 14M12 14"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-important {
+  --mdbook-alerts-color: rgb(130, 80, 223);
+  /* https://icon-sets.iconify.design/material-symbols/chat-info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 7q.425 0 .713-.288T13 6q0-.425-.288-.712T12 5q-.425 0-.712.288T11 6q0 .425.288.713T12 7m0 8q.425 0 .713-.288T13 14v-4q0-.425-.288-.712T12 9q-.425 0-.712.288T11 10v4q0 .425.288.713T12 15m-6 3l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-warning {
+  --mdbook-alerts-color: rgb(154, 103, 0);
+  /* https://icon-sets.iconify.design/material-symbols/warning-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M2.725 21q-.275 0-.5-.137t-.35-.363q-.125-.225-.137-.488t.137-.512l9.25-16q.15-.25.388-.375T12 3q.25 0 .488.125t.387.375l9.25 16q.15.25.138.513t-.138.487q-.125.225-.35.363t-.5.137zm1.725-2h15.1L12 6zM12 18q.425 0 .713-.288T13 17q0-.425-.288-.712T12 16q-.425 0-.712.288T11 17q0 .425.288.713T12 18m0-3q.425 0 .713-.288T13 14v-3q0-.425-.288-.712T12 10q-.425 0-.712.288T11 11v3q0 .425.288.713T12 15m0-2.5"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-caution {
+  --mdbook-alerts-color: rgb(207, 34, 46);
+  /* https://icon-sets.iconify.design/material-symbols/brightness-alert-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16q0-.425-.288-.712T12 15q-.425 0-.712.288T11 16q0 .425.288.713T12 17m0-4q.425 0 .713-.288T13 12V8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8v4q0 .425.288.713T12 13m-3.35 7H6q-.825 0-1.412-.587T4 18v-2.65L2.075 13.4q-.275-.3-.425-.662T1.5 12q0-.375.15-.737t.425-.663L4 8.65V6q0-.825.588-1.412T6 4h2.65l1.95-1.925q.3-.275.663-.425T12 1.5q.375 0 .738.15t.662.425L15.35 4H18q.825 0 1.413.588T20 6v2.65l1.925 1.95q.275.3.425.663t.15.737q0 .375-.15.738t-.425.662L20 15.35V18q0 .825-.587 1.413T18 20h-2.65l-1.95 1.925q-.3.275-.662.425T12 22.5q-.375 0-.737-.15t-.663-.425zm.85-2l2.5 2.5l2.5-2.5H18v-3.5l2.5-2.5L18 9.5V6h-3.5L12 3.5L9.5 6H6v3.5L3.5 12L6 14.5V18zm2.5-6"%2F%3E%3C%2Fsvg%3E');
+}
+
+</style>
+<h1 id="asynchronous-operations"><a class="header" href="#asynchronous-operations">Asynchronous Operations</a></h1>
+<p>In order to obtain significant scalability, with low-latency, and minimal
+overheads, <em>NNG</em> supports performing operations asynchronously.</p>
+<p>One way that applications can perform work asynchronously and concurrently
+is by using <a href="/api/thread.html">threads</a>, but threads carry significant resource overheads
+and frequently there are limits on the number that can easily be created.</p>
+<p>Additionally, with most network applications, the flow of execution will spend
+the bulk of its time waiting for traffic from a peer.</p>
+<p>For these kinds of applications, it is far more efficient to use asynchronous operations
+using the mechanisms described in this chapter.</p>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  tip
+</p>
+<p>To get the highest performance with the least overhead, applications should use
+asynchronous operations described in this chapter whenever possible.</p>
+</div>
+<h2 id="asynchronous-io-handle"><a class="header" href="#asynchronous-io-handle">Asynchronous I/O Handle</a></h2>
+<pre><code class="language-c">typedef struct nng_aio nng_aio;
+</code></pre>
+<p>An <a name="a001"></a><code>nng_aio</code><a name="a002"></a> is an opaque structure used in conjunction with
+<a name="a003"></a>asynchronous I/O operations.
+Every asynchronous operation uses one of these structures, each of which
+can only be used with a single operation at a time.</p>
+<p>Asynchronous operations are performed without blocking calling application threads.
+Instead the application registers a callback function to be executed
+when the operation is complete (whether successfully or not).
+This callback will be executed exactly once.</p>
+<p>The asynchronous I/O framework also supports <a href="/api/aio.html#cancellation">cancellation</a> of
+operations that are already in progress as well setting a maximum
+<a href="/TODO.html">timeout</a> for them to complete.</p>
+<p>It is also possible to initiate an asynchronous operation, and <a href="/api/api.html#wait-for-completion">wait</a> for it to
+complete, creating a synchronous flow from an asynchronous one.</p>
+<h2 id="create-handle"><a class="header" href="#create-handle">Create Handle</a></h2>
+<pre><code class="language-c">int nng_aio_alloc(nng_aio **aiop, void (*callb)(void *), void *arg);
+</code></pre>
+<p>The <a name="a004"></a><code>nng_aio_alloc</code> function creates an <a href="/TODO.html"><code>nng_aio</code></a> object, with the
+<a name="a005"></a>callback <em>callb</em> taking the argument <em>arg</em>, and returns it in <em>aiop</em>.</p>
+<p>If this succeeds, the function returns zero. Otherwise it may return <a href="/api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>.</p>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  tip
+</p>
+<p>The <em>arg</em> should normally be a structure that contains a pointer to the <em>aiop</em>,
+or from which it can be located. This allows <em>callb</em> to check the handle for
+success using <a href="/api/api.html#result-of-operation"><code>nng_aio_result</code></a>, as well access other properties of <em>aiop</em>.</p>
+</div>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  tip
+</p>
+<p>The <em>callb</em> may be executed on another <a href="/api/thread.html">thread</a>, so it may be necessary to use
+<a href="/api/synch.html">synchronization</a> methods in <em>callb</em> to avoid data races.</p>
+</div>
+<h2 id="destroy-handle"><a class="header" href="#destroy-handle">Destroy Handle</a></h2>
+<pre><code class="language-c">void nng_aio_free(nng_aio *aio);
+void nng_aio_reap(nng_aio *aio);
+</code></pre>
+<p>The <a name="a006"></a><code>nng_aio_free</code> handle destroys the handle <em>aio</em>, waiting for any operations
+and associated callbacks to complete before doing so.</p>
+<p>The <a name="a007"></a><code>nng_aio_reap</code> handle destroys the handle <em>aio</em> asynchronously, using a <em>reaper</em>
+<a href="/api/thread.html">thread</a> to do so. It does not wait for the object to be destroyed. Thus this function
+is safe to call from <em>aio</em>’s own callback.</p>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  note
+</p>
+<p>The <code>nng_aio_free</code> function must never be called from an <em>aio</em> callback.
+Use <code>nng_aio_reap</code> instead if an object must be destroyed from a callback.</p>
+</div>
+<h2 id="cancellation"><a class="header" href="#cancellation">Cancellation</a></h2>
+<pre><code class="language-c">void nng_aio_abort(nng_aio *aio, int err);
+void nng_aio_cancel(nng_aio *aio);
+void nng_aio_stop(nng_aio *aio);
+</code></pre>
+<p>These functions are used to stop a previously submitted asynchronous
+I/O operation. The operation may be canceled, or may continue to
+completion. If no operation is in progress (perhaps because it has
+already completed), then these operations have no effect.
+If the operation is successfully canceled or aborted, then the callback
+will still be called.</p>
+<p>The <a name="a008"></a><code>nng_aio_abort</code> function aborts the operation associated with <em>aio</em>
+and returns immediately without waiting. If cancellation was successful,
+then <a href="/api/api.html#result-of-operation"><code>nng_aio_result</code></a> will return <em>err</em>.</p>
+<p>The <a name="a009"></a><code>nng_aio_cancel</code> function acts like <code>nng_aio_abort</code>, but uses the error code
+<a href="/api/errors.html#NNG_ECANCELED"><code>NNG_ECANCELED</code></a><a name="a010"></a>.</p>
+<p>The <a name="a011"></a><code>nng_aio_stop</code> function aborts the <em>aio</em> operation with <a href="/api/errors.html#NNG_ECANCELED"><code>NNG_ECANCELED</code></a>,
+and then waits the operation and any associated callback to complete.
+This function also marks <em>aio</em> itself permanently stopped, so that any
+new operations scheduled by I/O providers using <a href="/TODO.html"><code>nng_aio_begin</code></a>
+return false. Thus this function should be used to teardown operations.</p>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  tip
+</p>
+<p>When multiple asynchronous I/O handles are in use and need to be
+deallocated, it is safest to stop all of them using <code>nng_aio_stop</code>,
+before deallocating any of them with <a href="/api/aio.html#destroy-handle"><code>nng_aio_free</code></a>,
+particularly if the callbacks might attempt to reschedule further operations.</p>
+</div>
+<h2 id="set-timeout"><a class="header" href="#set-timeout">Set Timeout</a></h2>
+<pre><code class="language-c">void nng_aio_set_timeout(nng_aio *aio, nng_duration timeout);
+void nng_aio_set_expire(nng_aio *aio, nng_time expiration);
+</code></pre>
+<p>The <code>nng_aio_set_timeout</code> function sets a <a name="a012"></a><em>timeout</em>
+for the asynchronous operation associated with <em>aio</em>.
+This causes a timer to be started when the operation is actually started.
+If the timer expires before the operation is completed, then it is
+<a href="/api/aio.html#cancellation">aborted</a> with an error of <code>NNG_ETIMEDOUT</code>.
+The <em>timeout</em> <a href="/api/time.html">duration</a> is specified as a relative number of milliseconds.</p>
+<p>If the timeout is <a href="/api/time.html#duration-type"><code>NNG_DURATION_INFINITE</code></a>, then no timeout is used.
+If the timeout is <a href="/api/time.html#duration-type"><code>NNG_DURATION_DEFAULT</code></a>, then a “default” or socket-specific
+timeout is used.
+(This is frequently the same as <a href="/api/time.html#duration-type"><code>NNG_DURATION_INFINITE</code></a>.)</p>
+<p>The <a name="a013"></a><code>nng_aio_set_expire</code> function is similar to <code>nng_aio_set_timeout</code>, but sets
+an expiration time based on the system clock. The <em>expiration</em>
+<a href="/api/time.html">time</a> is a clock timestamp, such as would be returned by <a href="/api/time.html#get-the-current-time"><code>nng_clock</code></a>.</p>
+<h2 id="wait-for-completion"><a class="header" href="#wait-for-completion">Wait for Completion</a></h2>
+<pre><code class="language-c">void nng_aio_wait(nng_aio *aio);
+</code></pre>
+<p>The <a name="a014"></a><code>nng_aio_wait</code> function waits for an asynchronous I/O operation to complete.
+If the operation has not been started, or has already completed, then it returns immediately.</p>
+<p>If a callback was set with <em>aio</em> when it was allocated, then this
+function will not be called until the callback has completed.</p>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
+<p>The <code>nng_aio_wait</code> function should never be called from a function that itself
+is a callback of an <a href="/TODO.html"><code>nng_aio</code></a>, either this one or any other.
+Doing so may result in a deadlock.</p>
+</div>
+<h2 id="test-for-completion"><a class="header" href="#test-for-completion">Test for Completion</a></h2>
+<pre><code class="language-c">bool nng_aio_busy(nng_aio *aio);
+</code></pre>
+<p>The <a name="a015"></a><code>nng_aio_busy</code> function returns <code>true</code> if the <em>aio</em> is currently busy performing an
+operation or is executing a completion callback. Otherwise it return <code>false</code>.
+This is the same test used internally by <a href="/api/api.html#wait-for-completion"><code>nng_aio_wait</code></a>.</p>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
+<p>The caller is responsible for coordinating any use of this with any reuse of the <em>aio</em>.
+Because the <em>aio</em> can be reused use of this function can be racy.</p>
+</div>
+<h2 id="result-of-operation"><a class="header" href="#result-of-operation">Result of Operation</a></h2>
+<pre><code class="language-c">int nng_aio_result(nng_aio *aio);
+size_t nng_aio_count(nng_aio *aio);
+</code></pre>
+<p>The <a name="a016"></a><code>nng_aio_result</code> function returns the result of the operation associated
+with the handle <em>aio</em>.
+If the operation was successful, then 0 is returned.
+Otherwise a non-zero <a href="/api/errors.html">error</a> code, such as <a href="/api/errors.html#NNG_ECANCELED"><code>NNG_ECANCELED</code></a> or <a href="/api/errors.html#NNG_ETIMEDOUT"><code>NNG_ETIMEDOUT</code></a>, is returned.</p>
+<p>For operations that transfer data, <a name="a017"></a><code>nng_aio_count</code> returns the
+number of bytes transferred by the operation associated with the handle <em>aio</em>.
+Operations that do not transfer data, or do not keep a count, may return zero for this function.</p>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  note
+</p>
+<p>The return value from these functions is undefined if the operation has not completed yet.
+Either call these from the handle’s completion callback, or after waiting for the
+operation to complete with <a href="/api/api.html#wait-for-completion"><code>nng_aio_wait</code></a>.</p>
+</div>
+<h2 id="messages"><a class="header" href="#messages">Messages</a></h2>
+<pre><code class="language-c">nng_msg *nng_aio_get_msg(nng_aio *aio);
+void nng_aio_set_msg(nng_aio *aio, nng_msg *msg);
+</code></pre>
+<p>The <a name="a018"></a><code>nng_aio_get_msg</code> and <a name="a019"></a><code>nng_aio_set_msg</code> functions retrieve and store a <a href="/api/msg.html">message</a>
+in <em>aio</em>.
+For example, if a function to receive data is called, that function can generally be expected
+to store a message on the asssociated <em>aio</em>, for the application to retrieve with
+<code>nng_aio_get_msg</code>.
+Conversely an application desiring to send a message <em>msg</em> will store it in the <em>aio</em> using
+<code>nng_aio_set_msg</code>. The function implementing the send operation will retrieve the message
+and arrange for it to be sent.</p>
+<h3 id="message-ownership"><a class="header" href="#message-ownership">Message Ownership</a></h3>
+<p>For send or transmit operations, the rule of thumb is that implementation of the operation
+is responsible for taking ownership of the message (and releasing resources when it is complete),
+if it will return success. If the operation will end in error, then the message will be
+retained and it is the consuming application’s responsibility to dispose of the message.
+This allows an application the opportunity to reuse the message to try again, if it so desires.</p>
+<p>For receive operations, the implementation of the operation will set the message on the <em>aio</em>
+on success, and the consuming application hasa responsibility to retrieve and dispose of the
+message. Failure to do so will leak the message. If the operation does not complete successfully,
+then no message is stored on the <em>aio</em>.</p>
+<h2 id="io-vector"><a class="header" href="#io-vector">I/O Vector</a></h2>
+<pre><code class="language-c">typedef struct nng_iov {
+    void * iov_buf;
+    size_t iov_len;
+};
+
+int nng_aio_set_iov(nng_aio *aio, unsigned int niov, nng_iov *iov);
+</code></pre>
+<p>For some operations, the unit of data transferred is not a <a href="/api/msg.html">message</a>, but
+rather a stream of bytes.</p>
+<p>For these operations, an array of <em>niov</em> <a name="a020"></a><code>nng_iov</code> structures can be passed to
+the <a name="a021"></a><code>nng_aio_set_iov</code> function to provide a scatter/gather array of
+elements describing the location (<code>iov_buf</code>) and length (<code>iov_len</code>) of data,
+to transfer.</p>
+<p>The <em>iov</em> vector is copied into storage in the <em>aio</em> itself, so that callers may use stack allocated <code>nng_iov</code> structures.
+The values pointed to by the <code>iov_buf</code> members are <em>not</em> copied by this function though.</p>
+<p>A maximum of four (4) <code>nng_iov</code> members may be supplied.</p>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  tip
+</p>
+<p>Most functions using <code>nng_iov</code> do not guarantee to transfer all of the data that they
+are requested to. To be sure that correct amount of data is transferred, as well as to
+start an attempt to complete any partial transfer, check the amount of data transferred by
+calling <a href="/api/api.html#result-of-operation"><code>nng_aio_count</code></a>.</p>
+</div>
+<h2 id="inputs-and-outputs"><a class="header" href="#inputs-and-outputs">Inputs and Outputs</a></h2>
+<pre><code class="language-c">void nng_aio_set_input(nng_aio *aio, unsigned int index, void *param);
+void *nng_aio_get_output(nng_aio *aio, unsigned int index);
+</code></pre>
+<p>Asynchronous operations can take additional input parameters, and
+provide additional result outputs besides the <a href="/api/api.html#result-of-operation">result</a> code.</p>
+<p>The <code>nng_aio_set_input</code> function sets the input parameter at <em>index</em>
+to <em>param</em> for the operation associated with <em>aio</em>.</p>
+<p>The <code>nng_aio_get_output</code> function returns the output result at <em>index</em>
+for the operation associated with <em>aio</em>.</p>
+<p>The type and semantics of input parameters and output results are determined by specific
+operations. The documentation for the operation should provide details.</p>
+<p>The valid values of <em>index</em> range from zero (0) to three (3), as no operation
+currently defined can accept more than four parameters or return more than four additional
+results.</p>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  note
+</p>
+<p>If the <em>index</em> does not correspond to a defined input for the operation,
+then <code>nng_aio_set_input</code> will have no effect, and <code>nng_aio_get_output</code> will
+return <code>NULL</code>.</p>
+</div>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
+<p>It is an error to call this function while the <em>aio</em> is currently
+in use by an active asynchronous operation.</p>
+</div>
+<h2 id="see-also"><a class="header" href="#see-also">See Also</a></h2>
+<p><a href="/api/synch.html">Synchronization</a>,
+<a href="/api/thread.html">Threads</a>,
+<a href="/api/time.html">Time</a></p>
+<!-- Symbol cross reference -->
+<!-- Macros -->
+<!-- Protocols -->
+<!-- Transports -->
+<!-- Concept index -->
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../api/url.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+
+                            <a rel="next prefetch" href="../api/synch.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="../api/url.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+
+                    <a rel="next prefetch" href="../api/synch.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="../elasticlunr.min.js"></script>
+        <script src="../mark.min.js"></script>
+        <script src="../searcher.js"></script>
+
+        <script src="../clipboard.min.js"></script>
+        <script src="../highlight.js"></script>
+        <script src="../book.js"></script>
+
+        <!-- Custom JS scripts -->
+        <script src="../theme/pagetoc.js"></script>
+
+
+    </div>
+    </body>
+</html>
diff --git a/ref/api/cmd_opts.html b/ref/api/cmd_opts.html
new file mode 100644
index 00000000..fff75be4
--- /dev/null
+++ b/ref/api/cmd_opts.html
@@ -0,0 +1,454 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>Command Options - NNG Reference Manual (DRAFT)</title>
+
+
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="../favicon.svg">
+        <link rel="shortcut icon" href="../favicon.png">
+        <link rel="stylesheet" href="../css/variables.css">
+        <link rel="stylesheet" href="../css/general.css">
+        <link rel="stylesheet" href="../css/chrome.css">
+        <link rel="stylesheet" href="../css/print.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="../fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="../highlight.css">
+        <link rel="stylesheet" href="../tomorrow-night.css">
+        <link rel="stylesheet" href="../ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+        <link rel="stylesheet" href="../theme/pagetoc.css">
+
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "../";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded affix "><a href="../copyright.html">Copyright</a></li><li class="chapter-item expanded affix "><a href="../dedication.html">Dedication</a></li><li class="chapter-item expanded affix "><a href="../preface.html">Preface</a></li><li class="chapter-item expanded "><a href="../api/index.html"><strong aria-hidden="true">1.</strong> API Reference</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../api/msg.html"><strong aria-hidden="true">1.1.</strong> Messages</a></li><li class="chapter-item expanded "><a href="../api/memory.html"><strong aria-hidden="true">1.2.</strong> Memory</a></li><li class="chapter-item expanded "><a href="../api/time.html"><strong aria-hidden="true">1.3.</strong> Time</a></li><li class="chapter-item expanded "><a href="../api/url.html"><strong aria-hidden="true">1.4.</strong> URLs</a></li><li class="chapter-item expanded "><a href="../api/aio.html"><strong aria-hidden="true">1.5.</strong> Asynchronous I/O</a></li><li class="chapter-item expanded "><a href="../api/synch.html"><strong aria-hidden="true">1.6.</strong> Synchronization</a></li><li class="chapter-item expanded "><a href="../api/thread.html"><strong aria-hidden="true">1.7.</strong> Threads</a></li><li class="chapter-item expanded "><a href="../api/logging.html"><strong aria-hidden="true">1.8.</strong> Logging</a></li><li class="chapter-item expanded "><a href="../api/stats.html"><strong aria-hidden="true">1.9.</strong> Statistics</a></li><li class="chapter-item expanded "><a href="../api/errors.html"><strong aria-hidden="true">1.10.</strong> Errors</a></li><li class="chapter-item expanded "><a href="../api/misc.html"><strong aria-hidden="true">1.11.</strong> Miscellaneous</a></li><li class="chapter-item expanded "><a href="../api/id_map.html"><strong aria-hidden="true">1.12.</strong> ID Map</a></li><li class="chapter-item expanded "><a href="../api/cmd_opts.html" class="active"><strong aria-hidden="true">1.13.</strong> Command Options</a></li></ol></li><li class="chapter-item expanded "><a href="../proto/index.html"><strong aria-hidden="true">2.</strong> Protocols</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../proto/bus.html"><strong aria-hidden="true">2.1.</strong> BUS Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pair.html"><strong aria-hidden="true">2.2.</strong> PAIR Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pub.html"><strong aria-hidden="true">2.3.</strong> PUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pull.html"><strong aria-hidden="true">2.4.</strong> PULL Protocol</a></li><li class="chapter-item expanded "><a href="../proto/push.html"><strong aria-hidden="true">2.5.</strong> PUSH Protocol</a></li><li class="chapter-item expanded "><a href="../proto/rep.html"><strong aria-hidden="true">2.6.</strong> REP Protocol</a></li><li class="chapter-item expanded "><a href="../proto/req.html"><strong aria-hidden="true">2.7.</strong> REQ Protocol</a></li><li class="chapter-item expanded "><a href="../proto/respondent.html"><strong aria-hidden="true">2.8.</strong> RESPONDENT Protocol</a></li><li class="chapter-item expanded "><a href="../proto/sub.html"><strong aria-hidden="true">2.9.</strong> SUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/surveyor.html"><strong aria-hidden="true">2.10.</strong> SURVEYOR Protocol</a></li></ol></li><li class="chapter-item expanded "><a href="../tran/index.html"><strong aria-hidden="true">3.</strong> Transports</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../tran/inproc.html"><strong aria-hidden="true">3.1.</strong> Intra-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/ipc.html"><strong aria-hidden="true">3.2.</strong> Inter-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/socket.html"><strong aria-hidden="true">3.3.</strong> BSD Socket (Experimental)</a></li><li class="chapter-item expanded "><a href="../tran/udp.html"><strong aria-hidden="true">3.4.</strong> UDP Transport (Experimental)</a></li></ol></li><li class="chapter-item expanded "><a href="../migrate/index.html"><strong aria-hidden="true">4.</strong> Migration Guides</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../migrate/nng1.html"><strong aria-hidden="true">4.1.</strong> Migrating from NNG 1.x</a></li><li class="chapter-item expanded "><a href="../migrate/nanomsg.html"><strong aria-hidden="true">4.2.</strong> Migrating from libnanomsg</a></li></ol></li><li class="chapter-item expanded "><a href="../indexing.html">Index</a></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
+                <div class="sidebar-resize-indicator"></div>
+            </div>
+        </nav>
+
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">NNG Reference Manual (DRAFT)</h1>
+
+                    <div class="right-buttons">
+                        <a href="../print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <style>
+.mdbook-alerts {
+  padding: 8px 16px;
+  margin-bottom: 16px;
+  border-left: 0.25em solid var(--mdbook-alerts-color);
+}
+
+.mdbook-alerts > *:first-child {
+  margin-top: 0;
+}
+
+.mdbook-alerts > *:last-child {
+  margin-bottom: 0;
+}
+
+.mdbook-alerts-title {
+  display: flex;
+  font-weight: 600;
+  align-items: center;
+  line-height: 1;
+  color: var(--mdbook-alerts-color);
+  text-transform: capitalize;
+}
+
+.mdbook-alerts-icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  margin-right: 0.2em;
+  background-color: currentColor;
+  -webkit-mask: no-repeat center / 100%;
+  mask: no-repeat center / 100%;
+  -webkit-mask-image: var(--mdbook-alerts-icon);
+  mask-image: var(--mdbook-alerts-icon);
+}
+
+.mdbook-alerts-note {
+  --mdbook-alerts-color: rgb(9, 105, 218);
+  /* https://icon-sets.iconify.design/material-symbols/info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16v-4q0-.425-.288-.712T12 11q-.425 0-.712.288T11 12v4q0 .425.288.713T12 17m0-8q.425 0 .713-.288T13 8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8q0 .425.288.713T12 9m0 13q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12q0-3.35-2.325-5.675T12 4Q8.65 4 6.325 6.325T4 12q0 3.35 2.325 5.675T12 20m0-8"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-tip {
+  --mdbook-alerts-color: rgb(26, 127, 55);
+  /* https://icon-sets.iconify.design/material-symbols/lightbulb-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 22q-.825 0-1.412-.587T10 20h4q0 .825-.587 1.413T12 22m-3-3q-.425 0-.712-.288T8 18q0-.425.288-.712T9 17h6q.425 0 .713.288T16 18q0 .425-.288.713T15 19zm-.75-3q-1.725-1.025-2.738-2.75T4.5 9.5q0-3.125 2.188-5.312T12 2q3.125 0 5.313 2.188T19.5 9.5q0 2.025-1.012 3.75T15.75 16zm.6-2h6.3q1.125-.8 1.738-1.975T17.5 9.5q0-2.3-1.6-3.9T12 4Q9.7 4 8.1 5.6T6.5 9.5q0 1.35.613 2.525T8.85 14M12 14"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-important {
+  --mdbook-alerts-color: rgb(130, 80, 223);
+  /* https://icon-sets.iconify.design/material-symbols/chat-info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 7q.425 0 .713-.288T13 6q0-.425-.288-.712T12 5q-.425 0-.712.288T11 6q0 .425.288.713T12 7m0 8q.425 0 .713-.288T13 14v-4q0-.425-.288-.712T12 9q-.425 0-.712.288T11 10v4q0 .425.288.713T12 15m-6 3l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-warning {
+  --mdbook-alerts-color: rgb(154, 103, 0);
+  /* https://icon-sets.iconify.design/material-symbols/warning-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M2.725 21q-.275 0-.5-.137t-.35-.363q-.125-.225-.137-.488t.137-.512l9.25-16q.15-.25.388-.375T12 3q.25 0 .488.125t.387.375l9.25 16q.15.25.138.513t-.138.487q-.125.225-.35.363t-.5.137zm1.725-2h15.1L12 6zM12 18q.425 0 .713-.288T13 17q0-.425-.288-.712T12 16q-.425 0-.712.288T11 17q0 .425.288.713T12 18m0-3q.425 0 .713-.288T13 14v-3q0-.425-.288-.712T12 10q-.425 0-.712.288T11 11v3q0 .425.288.713T12 15m0-2.5"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-caution {
+  --mdbook-alerts-color: rgb(207, 34, 46);
+  /* https://icon-sets.iconify.design/material-symbols/brightness-alert-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16q0-.425-.288-.712T12 15q-.425 0-.712.288T11 16q0 .425.288.713T12 17m0-4q.425 0 .713-.288T13 12V8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8v4q0 .425.288.713T12 13m-3.35 7H6q-.825 0-1.412-.587T4 18v-2.65L2.075 13.4q-.275-.3-.425-.662T1.5 12q0-.375.15-.737t.425-.663L4 8.65V6q0-.825.588-1.412T6 4h2.65l1.95-1.925q.3-.275.663-.425T12 1.5q.375 0 .738.15t.662.425L15.35 4H18q.825 0 1.413.588T20 6v2.65l1.925 1.95q.275.3.425.663t.15.737q0 .375-.15.738t-.425.662L20 15.35V18q0 .825-.587 1.413T18 20h-2.65l-1.95 1.925q-.3.275-.662.425T12 22.5q-.375 0-.737-.15t-.663-.425zm.85-2l2.5 2.5l2.5-2.5H18v-3.5l2.5-2.5L18 9.5V6h-3.5L12 3.5L9.5 6H6v3.5L3.5 12L6 14.5V18zm2.5-6"%2F%3E%3C%2Fsvg%3E');
+}
+
+</style>
+<h1 id="command-options"><a class="header" href="#command-options">Command Options</a></h1>
+<p>Some <em>NNG</em> utilities need to parse command line options,
+and the supplementary function here allows applications that
+need the same support to benefit from this.</p>
+<p>To make use of this, the supplemental header <code>&lt;nng/supplemental/util/options.h&gt;</code>
+must be included.</p>
+<h2 id="parse-command-line-options"><a class="header" href="#parse-command-line-options">Parse Command Line Options</a></h2>
+<pre><code class="language-c">typedef struct nng_optspec {
+    const char *o_name;  // Long style name (may be NULL for short only)
+    int         o_short; // Short option (no clustering!)
+    int         o_val;   // Value stored on a good parse (&gt;0)
+    bool        o_arg;   // Option takes an argument if true
+} nng_optspec;
+
+int nng_opts_parse(int argc, char *const *argv,
+                   const nng_optspec *spec, int *val, char **arg, int *idx);
+</code></pre>
+<p>The <a name="a001"></a><code>nng_opts_parse</code> function is a intended to facilitate parsing
+<a name="a002"></a>command-line arguments.
+This function exists largely to stand in for <a name="a003"></a><code>getopt</code> from POSIX systems,
+but it is available everywhere that <em>NNG</em> is, and it includes
+some capabilities missing from <code>getopt</code>.</p>
+<p>The function parses arguments from
+<code>main</code><sup><a name="to-footnote-1"><a href="#footnote-1">1</a></a></sup>
+(using <em>argc</em> and <em>argv</em>),
+starting at the index referenced by <em>idx</em>.
+(New invocations typically set the value pointed to by <em>idx</em> to 1.)</p>
+<p>Options are parsed as specified by <em>spec</em> (see <a href="#option-specification">Option Specification</a>.)
+The value of the parsed option will be stored at the address indicated by
+<em>val</em>, and the value of <em>idx</em> will be incremented to reflect the next
+option to parse.</p>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  tip
+</p>
+<p>For using this to parse command-line like strings that do not include
+the command name itself, set the value referenced by <em>idx</em> to zero instead of one.</p>
+</div>
+<p>If the option had an argument, a pointer to that is returned at the address
+referenced by <em>arg</em>.</p>
+<p>This function should be called repeatedly, until it returns either -1
+(indicating the end of options is reached) or a non-zero error code is
+returned.</p>
+<p>This function may return the following errors:</p>
+<ul>
+<li><a href="/api/errors.html#NNG_EAMBIGUOUS"><code>NNG_EAMBIGUOUS</code></a>: Parsed option matches more than one specification.</li>
+<li><a href="/api/errors.html#NNG_ENOARG"><code>NNG_ENOARG</code></a>: Option requires an argument, but one is not present.</li>
+<li><a href="/api/errors.html#NNG_EINVAL"><code>NNG_EINVAL</code></a>: An invalid (unknown) argument is present.</li>
+</ul>
+<h3 id="option-specification"><a class="header" href="#option-specification">Option Specification</a></h3>
+<p>The calling program must first create an array of <a name="a004"></a><code>nng_optspec</code> structures
+describing the options to be supported.
+This structure has the following members:</p>
+<ul>
+<li>
+<p><code>o_name</code>:</p>
+<p>The long style name for the option, such as “verbose”.
+This will be parsed as a <a href="#long-options">long option</a> on the command line when it is prefixed with two dashes.
+It may be <code>NULL</code> if only a <a href="#short-options">short option</a> is to be supported.</p>
+</li>
+<li>
+<p><code>o_short</code>:</p>
+<p>This is a single letter (at present only ASCII letters are supported).
+These options appear as just a single letter, and are prefixed with a single dash on the command line.
+The use of a slash in lieu of the dash is <em>not</em> supported, in order to avoid confusion with path name arguments.
+This value may be set to 0 if no <a href="#short-options">short option</a> is needed.</p>
+</li>
+<li>
+<p><code>o_val</code>:</p>
+<p>This is a numeric value that is unique to this option.
+This value is assigned by the application program, and must be non-zero for a valid option.
+If this is zero, then it indicates the end of the specifications, and the
+rest of this structure is ignored.
+The value will be returned to the caller in <em>val</em> by <code>nng_opts_parse</code> when
+this option is parsed from the command line.</p>
+</li>
+<li>
+<p><code>o_arg</code>:</p>
+<p>This value should be set to <code>true</code> if the option should take an argument.</p>
+</li>
+</ul>
+<h3 id="long-options"><a class="header" href="#long-options">Long Options</a></h3>
+<p>Long options are parsed from the <em>argv</em> array, and are indicated when
+the element being scanned starts with two dashes.
+For example, the “verbose” option would be specified as <code>--verbose</code> on
+the command line.
+If a long option takes an argument, it can either immediately follow
+the option as the next element in <em>argv</em>, or it can be appended to
+the option, separated from the option by an equals sign (<code>=</code>) or a
+colon (<code>:</code>).</p>
+<h3 id="short-options"><a class="header" href="#short-options">Short Options</a></h3>
+<p>Short options appear by themselves in an <em>argv</em> element, prefixed by a dash (<code>-</code>).
+If the short option takes an argument, it can either be appended in the
+same element of <em>argv</em>, or may appear in the next <em>argv</em> element.</p>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  note
+</p>
+<p>Option clustering, where multiple options can be crammed together in
+a single <em>argv</em> element, is not supported by this function (yet).</p>
+</div>
+<h3 id="prefix-matching"><a class="header" href="#prefix-matching">Prefix Matching</a></h3>
+<p>When using long options, the parser will match if it is equal to a prefix
+of the <code>o_name</code> member of a option specification, provided that it do so
+unambiguously (meaning it must not match any other option specification.)</p>
+<h2 id="example"><a class="header" href="#example">Example</a></h2>
+<p>The following program fragment demonstrates this function.</p>
+<pre><code class="language-c">    enum { OPT_LOGFILE, OPT_VERBOSE };
+    char *logfile; // options to be set
+    bool verbose;
+
+    static nng_optspec specs[] = {
+        {
+            .o_name = "logfile",
+            .o_short = 'D',
+            .o_val = OPT_LOGFILE,
+            .o_arg = true,
+        }, {
+            .o_name = "verbose",
+            .o_short = 'V',
+            .o_val = OPT_VERBOSE,
+            .o_arg = false,
+        }, {
+            .o_val = 0; // Terminate array
+        }
+    };
+
+    for (int idx = 1;;) {
+        int rv, opt;
+        char *arg;
+        rv = nng_opts_parse(argc, argv, specs, &amp;opt, &amp;arg, &amp;idx);
+        if (rv != 0) {
+            break;
+        }
+        switch (opt) {
+        case OPT_LOGFILE:
+            logfile = arg;
+            break;
+        case OPT_VERBOSE:
+            verbose = true;
+            break;
+        }
+    }
+    if (rv != -1) {
+        printf("Options error: %s\n", nng_strerror(rv));
+        exit(1);
+    }
+</code></pre>
+<!-- Symbol cross reference -->
+<!-- Macros -->
+<!-- Protocols -->
+<!-- Transports -->
+<!-- Concept index -->
+<p><hr/>
+<p><a name="footnote-1"><a href="#to-footnote-1">1</a></a>: Parsing argument strings from other sources can be done as well,
+although usually then <em>idx</em> will be initialized to zero.</p>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../api/id_map.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+
+                            <a rel="next prefetch" href="../proto/index.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="../api/id_map.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+
+                    <a rel="next prefetch" href="../proto/index.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="../elasticlunr.min.js"></script>
+        <script src="../mark.min.js"></script>
+        <script src="../searcher.js"></script>
+
+        <script src="../clipboard.min.js"></script>
+        <script src="../highlight.js"></script>
+        <script src="../book.js"></script>
+
+        <!-- Custom JS scripts -->
+        <script src="../theme/pagetoc.js"></script>
+
+
+    </div>
+    </body>
+</html>
diff --git a/ref/api/errors.html b/ref/api/errors.html
new file mode 100644
index 00000000..b928bbf5
--- /dev/null
+++ b/ref/api/errors.html
@@ -0,0 +1,370 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>Errors - NNG Reference Manual (DRAFT)</title>
+
+
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="../favicon.svg">
+        <link rel="shortcut icon" href="../favicon.png">
+        <link rel="stylesheet" href="../css/variables.css">
+        <link rel="stylesheet" href="../css/general.css">
+        <link rel="stylesheet" href="../css/chrome.css">
+        <link rel="stylesheet" href="../css/print.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="../fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="../highlight.css">
+        <link rel="stylesheet" href="../tomorrow-night.css">
+        <link rel="stylesheet" href="../ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+        <link rel="stylesheet" href="../theme/pagetoc.css">
+
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "../";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded affix "><a href="../copyright.html">Copyright</a></li><li class="chapter-item expanded affix "><a href="../dedication.html">Dedication</a></li><li class="chapter-item expanded affix "><a href="../preface.html">Preface</a></li><li class="chapter-item expanded "><a href="../api/index.html"><strong aria-hidden="true">1.</strong> API Reference</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../api/msg.html"><strong aria-hidden="true">1.1.</strong> Messages</a></li><li class="chapter-item expanded "><a href="../api/memory.html"><strong aria-hidden="true">1.2.</strong> Memory</a></li><li class="chapter-item expanded "><a href="../api/time.html"><strong aria-hidden="true">1.3.</strong> Time</a></li><li class="chapter-item expanded "><a href="../api/url.html"><strong aria-hidden="true">1.4.</strong> URLs</a></li><li class="chapter-item expanded "><a href="../api/aio.html"><strong aria-hidden="true">1.5.</strong> Asynchronous I/O</a></li><li class="chapter-item expanded "><a href="../api/synch.html"><strong aria-hidden="true">1.6.</strong> Synchronization</a></li><li class="chapter-item expanded "><a href="../api/thread.html"><strong aria-hidden="true">1.7.</strong> Threads</a></li><li class="chapter-item expanded "><a href="../api/logging.html"><strong aria-hidden="true">1.8.</strong> Logging</a></li><li class="chapter-item expanded "><a href="../api/stats.html"><strong aria-hidden="true">1.9.</strong> Statistics</a></li><li class="chapter-item expanded "><a href="../api/errors.html" class="active"><strong aria-hidden="true">1.10.</strong> Errors</a></li><li class="chapter-item expanded "><a href="../api/misc.html"><strong aria-hidden="true">1.11.</strong> Miscellaneous</a></li><li class="chapter-item expanded "><a href="../api/id_map.html"><strong aria-hidden="true">1.12.</strong> ID Map</a></li><li class="chapter-item expanded "><a href="../api/cmd_opts.html"><strong aria-hidden="true">1.13.</strong> Command Options</a></li></ol></li><li class="chapter-item expanded "><a href="../proto/index.html"><strong aria-hidden="true">2.</strong> Protocols</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../proto/bus.html"><strong aria-hidden="true">2.1.</strong> BUS Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pair.html"><strong aria-hidden="true">2.2.</strong> PAIR Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pub.html"><strong aria-hidden="true">2.3.</strong> PUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pull.html"><strong aria-hidden="true">2.4.</strong> PULL Protocol</a></li><li class="chapter-item expanded "><a href="../proto/push.html"><strong aria-hidden="true">2.5.</strong> PUSH Protocol</a></li><li class="chapter-item expanded "><a href="../proto/rep.html"><strong aria-hidden="true">2.6.</strong> REP Protocol</a></li><li class="chapter-item expanded "><a href="../proto/req.html"><strong aria-hidden="true">2.7.</strong> REQ Protocol</a></li><li class="chapter-item expanded "><a href="../proto/respondent.html"><strong aria-hidden="true">2.8.</strong> RESPONDENT Protocol</a></li><li class="chapter-item expanded "><a href="../proto/sub.html"><strong aria-hidden="true">2.9.</strong> SUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/surveyor.html"><strong aria-hidden="true">2.10.</strong> SURVEYOR Protocol</a></li></ol></li><li class="chapter-item expanded "><a href="../tran/index.html"><strong aria-hidden="true">3.</strong> Transports</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../tran/inproc.html"><strong aria-hidden="true">3.1.</strong> Intra-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/ipc.html"><strong aria-hidden="true">3.2.</strong> Inter-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/socket.html"><strong aria-hidden="true">3.3.</strong> BSD Socket (Experimental)</a></li><li class="chapter-item expanded "><a href="../tran/udp.html"><strong aria-hidden="true">3.4.</strong> UDP Transport (Experimental)</a></li></ol></li><li class="chapter-item expanded "><a href="../migrate/index.html"><strong aria-hidden="true">4.</strong> Migration Guides</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../migrate/nng1.html"><strong aria-hidden="true">4.1.</strong> Migrating from NNG 1.x</a></li><li class="chapter-item expanded "><a href="../migrate/nanomsg.html"><strong aria-hidden="true">4.2.</strong> Migrating from libnanomsg</a></li></ol></li><li class="chapter-item expanded "><a href="../indexing.html">Index</a></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
+                <div class="sidebar-resize-indicator"></div>
+            </div>
+        </nav>
+
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">NNG Reference Manual (DRAFT)</h1>
+
+                    <div class="right-buttons">
+                        <a href="../print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <style>
+.mdbook-alerts {
+  padding: 8px 16px;
+  margin-bottom: 16px;
+  border-left: 0.25em solid var(--mdbook-alerts-color);
+}
+
+.mdbook-alerts > *:first-child {
+  margin-top: 0;
+}
+
+.mdbook-alerts > *:last-child {
+  margin-bottom: 0;
+}
+
+.mdbook-alerts-title {
+  display: flex;
+  font-weight: 600;
+  align-items: center;
+  line-height: 1;
+  color: var(--mdbook-alerts-color);
+  text-transform: capitalize;
+}
+
+.mdbook-alerts-icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  margin-right: 0.2em;
+  background-color: currentColor;
+  -webkit-mask: no-repeat center / 100%;
+  mask: no-repeat center / 100%;
+  -webkit-mask-image: var(--mdbook-alerts-icon);
+  mask-image: var(--mdbook-alerts-icon);
+}
+
+.mdbook-alerts-note {
+  --mdbook-alerts-color: rgb(9, 105, 218);
+  /* https://icon-sets.iconify.design/material-symbols/info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16v-4q0-.425-.288-.712T12 11q-.425 0-.712.288T11 12v4q0 .425.288.713T12 17m0-8q.425 0 .713-.288T13 8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8q0 .425.288.713T12 9m0 13q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12q0-3.35-2.325-5.675T12 4Q8.65 4 6.325 6.325T4 12q0 3.35 2.325 5.675T12 20m0-8"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-tip {
+  --mdbook-alerts-color: rgb(26, 127, 55);
+  /* https://icon-sets.iconify.design/material-symbols/lightbulb-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 22q-.825 0-1.412-.587T10 20h4q0 .825-.587 1.413T12 22m-3-3q-.425 0-.712-.288T8 18q0-.425.288-.712T9 17h6q.425 0 .713.288T16 18q0 .425-.288.713T15 19zm-.75-3q-1.725-1.025-2.738-2.75T4.5 9.5q0-3.125 2.188-5.312T12 2q3.125 0 5.313 2.188T19.5 9.5q0 2.025-1.012 3.75T15.75 16zm.6-2h6.3q1.125-.8 1.738-1.975T17.5 9.5q0-2.3-1.6-3.9T12 4Q9.7 4 8.1 5.6T6.5 9.5q0 1.35.613 2.525T8.85 14M12 14"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-important {
+  --mdbook-alerts-color: rgb(130, 80, 223);
+  /* https://icon-sets.iconify.design/material-symbols/chat-info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 7q.425 0 .713-.288T13 6q0-.425-.288-.712T12 5q-.425 0-.712.288T11 6q0 .425.288.713T12 7m0 8q.425 0 .713-.288T13 14v-4q0-.425-.288-.712T12 9q-.425 0-.712.288T11 10v4q0 .425.288.713T12 15m-6 3l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-warning {
+  --mdbook-alerts-color: rgb(154, 103, 0);
+  /* https://icon-sets.iconify.design/material-symbols/warning-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M2.725 21q-.275 0-.5-.137t-.35-.363q-.125-.225-.137-.488t.137-.512l9.25-16q.15-.25.388-.375T12 3q.25 0 .488.125t.387.375l9.25 16q.15.25.138.513t-.138.487q-.125.225-.35.363t-.5.137zm1.725-2h15.1L12 6zM12 18q.425 0 .713-.288T13 17q0-.425-.288-.712T12 16q-.425 0-.712.288T11 17q0 .425.288.713T12 18m0-3q.425 0 .713-.288T13 14v-3q0-.425-.288-.712T12 10q-.425 0-.712.288T11 11v3q0 .425.288.713T12 15m0-2.5"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-caution {
+  --mdbook-alerts-color: rgb(207, 34, 46);
+  /* https://icon-sets.iconify.design/material-symbols/brightness-alert-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16q0-.425-.288-.712T12 15q-.425 0-.712.288T11 16q0 .425.288.713T12 17m0-4q.425 0 .713-.288T13 12V8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8v4q0 .425.288.713T12 13m-3.35 7H6q-.825 0-1.412-.587T4 18v-2.65L2.075 13.4q-.275-.3-.425-.662T1.5 12q0-.375.15-.737t.425-.663L4 8.65V6q0-.825.588-1.412T6 4h2.65l1.95-1.925q.3-.275.663-.425T12 1.5q.375 0 .738.15t.662.425L15.35 4H18q.825 0 1.413.588T20 6v2.65l1.925 1.95q.275.3.425.663t.15.737q0 .375-.15.738t-.425.662L20 15.35V18q0 .825-.587 1.413T18 20h-2.65l-1.95 1.925q-.3.275-.662.425T12 22.5q-.375 0-.737-.15t-.663-.425zm.85-2l2.5 2.5l2.5-2.5H18v-3.5l2.5-2.5L18 9.5V6h-3.5L12 3.5L9.5 6H6v3.5L3.5 12L6 14.5V18zm2.5-6"%2F%3E%3C%2Fsvg%3E');
+}
+
+</style>
+<h1 id="errors"><a class="header" href="#errors">Errors</a></h1>
+<p>Many <em>NNG</em> functions can fail for a variety of reasons.
+These functions tend to return either zero on success,
+or a non-zero error code to indicate failure.
+<sup><a name="to-footnote-1"><a href="#footnote-1">1</a></a></sup></p>
+<p>All these error codes are <code>int</code>.</p>
+<p>Not every possible error code is defined here, as sometimes
+an underlying system or library error code is “wrapped”.</p>
+<h2 id="human-readable-error-message"><a class="header" href="#human-readable-error-message">Human Readable Error Message</a></h2>
+<pre><code class="language-c">const char *nng_strerror(int err);
+</code></pre>
+<p>The <a name="a001"></a><code>nng_strerror</code> returns the human-readable description of the
+given error in <code>err</code>.</p>
+<p>The error message returned is a fixed <code>NUL</code>-terminated string and may be located in
+read-only memory.</p>
+<p>The returned <a name="a002"></a>error message is provided in US English, but in the
+future locale-specific strings may be presented instead.</p>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  note
+</p>
+<p>The specific strings associated with specific error messages are
+subject to change.
+Therefore applications must not depend on the message,
+but may use them verbatim when supplying information to end-users, such
+as in diagnostic messages or log entries.</p>
+</div>
+<h2 id="list-of-errors"><a class="header" href="#list-of-errors">List of Errors</a></h2>
+<div class="table-wrapper"><table><thead><tr><th>Error</th><th>Value</th><th>Description</th></tr></thead><tbody>
+<tr><td><code>NNG_EINTR</code><a name="NNG_EINTR"></a></td><td>1</td><td>Operation interrupted.</td></tr>
+<tr><td><code>NNG_ENOMEM</code><a name="NNG_ENOMEM"></a></td><td>2</td><td>Out of memory, or other resource exahusted.</td></tr>
+<tr><td><code>NNG_EINVAL</code><a name="NNG_EINVAL"></a></td><td>3</td><td>Invalid argument. The arguments are invalid or malformed somehow.</td></tr>
+<tr><td><code>NNG_EBUSY</code><a name="NNG_EBUSY"></a></td><td>4</td><td>Resource busy.</td></tr>
+<tr><td><code>NNG_ETIMEDOUT</code><a name="NNG_ETIMEDOUT"></a></td><td>5</td><td>Timed out. The operation took longer than the allotted time.</td></tr>
+<tr><td><code>NNG_ECONNREFUSED</code><a name="NNG_ECONNREFUSED"></a></td><td>6</td><td>Connection refused. Usually indicates the wrong address or a server is running.</td></tr>
+<tr><td><code>NNG_ECLOSED</code><a name="NNG_ECLOSED"></a></td><td>7</td><td>Object closed. Typically the <a href="/TODO.html">socket</a> is closed.</td></tr>
+<tr><td><code>NNG_EAGAIN</code><a name="NNG_EAGAIN"></a></td><td>8</td><td>Try again. Typcally for a non-blocking operation that might succeed later.</td></tr>
+<tr><td><code>NNG_ENOTSUP</code><a name="NNG_ENOTSUP"></a></td><td>9</td><td>Not supported. Perhaps the protocol or transport is not supported, or the operation is not not supported with the transport or protocol.</td></tr>
+<tr><td><code>NNG_EADDRINUSE</code><a name="NNG_EADDRINUSE"></a></td><td>10</td><td>Address in use. The network address is already used by another process. Most often this is seen for <a href="/TODO.html">listeners</a>.</td></tr>
+<tr><td><code>NNG_ESTATE</code><a name="NNG_ESTATE"></a></td><td>11</td><td>Incorrect state. The operation cannot be performed in the current state, such as trying to send a response when no request has yet been received.</td></tr>
+<tr><td><code>NNG_ENOENT</code><a name="NNG_ENOENT"></a></td><td>12</td><td>Entry not found (no such object.) Can also indicate that a file does not exist.</td></tr>
+<tr><td><code>NNG_EPROTO</code><a name="NNG_EPROTO"></a></td><td>13</td><td>Protocol error. Typically this indicates incorrect messages over a network.</td></tr>
+<tr><td><code>NNG_EUNREACHABLE</code><a name="NNG_EUNREACHABLE"></a></td><td>14</td><td>Destination unreachable.</td></tr>
+<tr><td><code>NNG_EADDRINVAL</code><a name="NNG_EADDRINVAL"></a></td><td>15</td><td>Address invalid. Like <a href="/api/errors.html#NNG_EINVAL"><code>NNG_EINVAL</code></a>, but only for network addresses.</td></tr>
+<tr><td><code>NNG_EPERM</code><a name="NNG_EPERM"></a></td><td>16</td><td>Permission denied.</td></tr>
+<tr><td><code>NNG_EMSGSIZE</code><a name="NNG_EMSGSIZE"></a></td><td>17</td><td>Message too large.</td></tr>
+<tr><td><code>NNG_ECONNABORTED</code><a name="NNG_ECONNABORTED"></a></td><td>18</td><td>Connection aborted. A connection attempt was aborted locally.</td></tr>
+<tr><td><code>NNG_ECONNRESET</code><a name="NNG_ECONNRESET"></a></td><td>19</td><td>Connection reset. The remote peer reset the connection unexpectedly.</td></tr>
+<tr><td><code>NNG_ECANCELED</code><a name="NNG_ECANCELED"></a></td><td>20</td><td>Operation canceled. Typically as a result of <a href="/api/aio.html#cancellation"><code>nng_aio_cancel</code></a> or similar.</td></tr>
+<tr><td><code>NNG_ENOFILES</code><a name="NNG_ENOFILES"></a></td><td>21</td><td>Out of files. Either the destination file system cannot store files, or all available file handles are used.</td></tr>
+<tr><td><code>NNG_ENOSPC</code><a name="NNG_ENOSPC"></a></td><td>22</td><td>Out of space. Destination table or filesystem is full.</td></tr>
+<tr><td><code>NNG_EEXIST</code><a name="NNG_EEXIST"></a></td><td>23</td><td>Resource already exists.</td></tr>
+<tr><td><code>NNG_EREADONLY</code><a name="NNG_EREADONLY"></a></td><td>24</td><td>Read only resource. An attempt to modify a read-only file or other object.</td></tr>
+<tr><td><code>NNG_EWRITEONLY</code><a name="NNG_EWRITEONLY"></a></td><td>25</td><td>Write only resource. A read operation failed because the object only supports writes.</td></tr>
+<tr><td><code>NNG_ECRYPTO</code><a name="NNG_ECRYPTO"></a></td><td>26</td><td>Cryptographic error. Usually indicates an invalid key was used for TLS.</td></tr>
+<tr><td><code>NNG_EPEERAUTH</code><a name="NNG_EPEERAUTH"></a></td><td>27</td><td>Peer could not be authenticated.</td></tr>
+<tr><td><code>NNG_ENOARG</code><a name="NNG_ENOARG"></a></td><td>28</td><td>Option requires argument. A command-line option was supplied without an argument. Only used with <a href="/TODO.html"><code>nng_opts_parse</code></a>.</td></tr>
+<tr><td><code>NNG_EAMBIGUOUS</code><a name="NNG_EAMBIGUOUS"></a></td><td>29</td><td>Ambiguous option. The command line option could not be unambiguously resolved. Only used with <a href="/TODO.html"><code>nng_opts_parse</code></a>.</td></tr>
+<tr><td><code>NNG_EBADTYPE</code><a name="NNG_EBADTYPE"></a></td><td>30</td><td>Incorrect type. A type-specific function was used for an object of the wrong type.</td></tr>
+<tr><td><code>NNG_ECONNSHUT</code><a name="NNG_ECONNSHUT"></a></td><td>31</td><td>Connection shutdown. The connection was shut down and cannot be used.</td></tr>
+<tr><td><code>NNG_EINTERNAL</code><a name="NNG_EINTERNAL"></a></td><td>1000</td><td>An unidentifier internal error occurred.</td></tr>
+<tr><td><code>NNG_ESYSERR</code><a name="NNG_ESYSERR"></a></td><td>0x10000000 - 0x1FFFFFFF</td><td>An unidentified system error occurred. These are errors reported by the operating system.</td></tr>
+<tr><td><code>NNG_ETRANERR</code><a name="NNG_ETRANERR"></a></td><td>0x20000000 - 0x2FFFFFFF</td><td>An unidentified transport error occurred.</td></tr>
+</tbody></table>
+</div><!-- Symbol cross reference -->
+<!-- Macros -->
+<!-- Protocols -->
+<!-- Transports -->
+<!-- Concept index -->
+<p><hr/>
+<p><a name="footnote-1"><a href="#to-footnote-1">1</a></a>: This convention goes back to UNIX system calls,
+which behave the same way, but <em>NNG</em> does not use a separate
+<em>errno</em> variable.</p>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../api/stats.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+
+                            <a rel="next prefetch" href="../api/misc.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="../api/stats.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+
+                    <a rel="next prefetch" href="../api/misc.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="../elasticlunr.min.js"></script>
+        <script src="../mark.min.js"></script>
+        <script src="../searcher.js"></script>
+
+        <script src="../clipboard.min.js"></script>
+        <script src="../highlight.js"></script>
+        <script src="../book.js"></script>
+
+        <!-- Custom JS scripts -->
+        <script src="../theme/pagetoc.js"></script>
+
+
+    </div>
+    </body>
+</html>
diff --git a/ref/api/id_map.html b/ref/api/id_map.html
new file mode 100644
index 00000000..26970d26
--- /dev/null
+++ b/ref/api/id_map.html
@@ -0,0 +1,423 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>ID Map - NNG Reference Manual (DRAFT)</title>
+
+
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="../favicon.svg">
+        <link rel="shortcut icon" href="../favicon.png">
+        <link rel="stylesheet" href="../css/variables.css">
+        <link rel="stylesheet" href="../css/general.css">
+        <link rel="stylesheet" href="../css/chrome.css">
+        <link rel="stylesheet" href="../css/print.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="../fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="../highlight.css">
+        <link rel="stylesheet" href="../tomorrow-night.css">
+        <link rel="stylesheet" href="../ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+        <link rel="stylesheet" href="../theme/pagetoc.css">
+
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "../";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded affix "><a href="../copyright.html">Copyright</a></li><li class="chapter-item expanded affix "><a href="../dedication.html">Dedication</a></li><li class="chapter-item expanded affix "><a href="../preface.html">Preface</a></li><li class="chapter-item expanded "><a href="../api/index.html"><strong aria-hidden="true">1.</strong> API Reference</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../api/msg.html"><strong aria-hidden="true">1.1.</strong> Messages</a></li><li class="chapter-item expanded "><a href="../api/memory.html"><strong aria-hidden="true">1.2.</strong> Memory</a></li><li class="chapter-item expanded "><a href="../api/time.html"><strong aria-hidden="true">1.3.</strong> Time</a></li><li class="chapter-item expanded "><a href="../api/url.html"><strong aria-hidden="true">1.4.</strong> URLs</a></li><li class="chapter-item expanded "><a href="../api/aio.html"><strong aria-hidden="true">1.5.</strong> Asynchronous I/O</a></li><li class="chapter-item expanded "><a href="../api/synch.html"><strong aria-hidden="true">1.6.</strong> Synchronization</a></li><li class="chapter-item expanded "><a href="../api/thread.html"><strong aria-hidden="true">1.7.</strong> Threads</a></li><li class="chapter-item expanded "><a href="../api/logging.html"><strong aria-hidden="true">1.8.</strong> Logging</a></li><li class="chapter-item expanded "><a href="../api/stats.html"><strong aria-hidden="true">1.9.</strong> Statistics</a></li><li class="chapter-item expanded "><a href="../api/errors.html"><strong aria-hidden="true">1.10.</strong> Errors</a></li><li class="chapter-item expanded "><a href="../api/misc.html"><strong aria-hidden="true">1.11.</strong> Miscellaneous</a></li><li class="chapter-item expanded "><a href="../api/id_map.html" class="active"><strong aria-hidden="true">1.12.</strong> ID Map</a></li><li class="chapter-item expanded "><a href="../api/cmd_opts.html"><strong aria-hidden="true">1.13.</strong> Command Options</a></li></ol></li><li class="chapter-item expanded "><a href="../proto/index.html"><strong aria-hidden="true">2.</strong> Protocols</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../proto/bus.html"><strong aria-hidden="true">2.1.</strong> BUS Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pair.html"><strong aria-hidden="true">2.2.</strong> PAIR Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pub.html"><strong aria-hidden="true">2.3.</strong> PUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pull.html"><strong aria-hidden="true">2.4.</strong> PULL Protocol</a></li><li class="chapter-item expanded "><a href="../proto/push.html"><strong aria-hidden="true">2.5.</strong> PUSH Protocol</a></li><li class="chapter-item expanded "><a href="../proto/rep.html"><strong aria-hidden="true">2.6.</strong> REP Protocol</a></li><li class="chapter-item expanded "><a href="../proto/req.html"><strong aria-hidden="true">2.7.</strong> REQ Protocol</a></li><li class="chapter-item expanded "><a href="../proto/respondent.html"><strong aria-hidden="true">2.8.</strong> RESPONDENT Protocol</a></li><li class="chapter-item expanded "><a href="../proto/sub.html"><strong aria-hidden="true">2.9.</strong> SUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/surveyor.html"><strong aria-hidden="true">2.10.</strong> SURVEYOR Protocol</a></li></ol></li><li class="chapter-item expanded "><a href="../tran/index.html"><strong aria-hidden="true">3.</strong> Transports</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../tran/inproc.html"><strong aria-hidden="true">3.1.</strong> Intra-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/ipc.html"><strong aria-hidden="true">3.2.</strong> Inter-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/socket.html"><strong aria-hidden="true">3.3.</strong> BSD Socket (Experimental)</a></li><li class="chapter-item expanded "><a href="../tran/udp.html"><strong aria-hidden="true">3.4.</strong> UDP Transport (Experimental)</a></li></ol></li><li class="chapter-item expanded "><a href="../migrate/index.html"><strong aria-hidden="true">4.</strong> Migration Guides</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../migrate/nng1.html"><strong aria-hidden="true">4.1.</strong> Migrating from NNG 1.x</a></li><li class="chapter-item expanded "><a href="../migrate/nanomsg.html"><strong aria-hidden="true">4.2.</strong> Migrating from libnanomsg</a></li></ol></li><li class="chapter-item expanded "><a href="../indexing.html">Index</a></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
+                <div class="sidebar-resize-indicator"></div>
+            </div>
+        </nav>
+
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">NNG Reference Manual (DRAFT)</h1>
+
+                    <div class="right-buttons">
+                        <a href="../print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <style>
+.mdbook-alerts {
+  padding: 8px 16px;
+  margin-bottom: 16px;
+  border-left: 0.25em solid var(--mdbook-alerts-color);
+}
+
+.mdbook-alerts > *:first-child {
+  margin-top: 0;
+}
+
+.mdbook-alerts > *:last-child {
+  margin-bottom: 0;
+}
+
+.mdbook-alerts-title {
+  display: flex;
+  font-weight: 600;
+  align-items: center;
+  line-height: 1;
+  color: var(--mdbook-alerts-color);
+  text-transform: capitalize;
+}
+
+.mdbook-alerts-icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  margin-right: 0.2em;
+  background-color: currentColor;
+  -webkit-mask: no-repeat center / 100%;
+  mask: no-repeat center / 100%;
+  -webkit-mask-image: var(--mdbook-alerts-icon);
+  mask-image: var(--mdbook-alerts-icon);
+}
+
+.mdbook-alerts-note {
+  --mdbook-alerts-color: rgb(9, 105, 218);
+  /* https://icon-sets.iconify.design/material-symbols/info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16v-4q0-.425-.288-.712T12 11q-.425 0-.712.288T11 12v4q0 .425.288.713T12 17m0-8q.425 0 .713-.288T13 8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8q0 .425.288.713T12 9m0 13q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12q0-3.35-2.325-5.675T12 4Q8.65 4 6.325 6.325T4 12q0 3.35 2.325 5.675T12 20m0-8"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-tip {
+  --mdbook-alerts-color: rgb(26, 127, 55);
+  /* https://icon-sets.iconify.design/material-symbols/lightbulb-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 22q-.825 0-1.412-.587T10 20h4q0 .825-.587 1.413T12 22m-3-3q-.425 0-.712-.288T8 18q0-.425.288-.712T9 17h6q.425 0 .713.288T16 18q0 .425-.288.713T15 19zm-.75-3q-1.725-1.025-2.738-2.75T4.5 9.5q0-3.125 2.188-5.312T12 2q3.125 0 5.313 2.188T19.5 9.5q0 2.025-1.012 3.75T15.75 16zm.6-2h6.3q1.125-.8 1.738-1.975T17.5 9.5q0-2.3-1.6-3.9T12 4Q9.7 4 8.1 5.6T6.5 9.5q0 1.35.613 2.525T8.85 14M12 14"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-important {
+  --mdbook-alerts-color: rgb(130, 80, 223);
+  /* https://icon-sets.iconify.design/material-symbols/chat-info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 7q.425 0 .713-.288T13 6q0-.425-.288-.712T12 5q-.425 0-.712.288T11 6q0 .425.288.713T12 7m0 8q.425 0 .713-.288T13 14v-4q0-.425-.288-.712T12 9q-.425 0-.712.288T11 10v4q0 .425.288.713T12 15m-6 3l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-warning {
+  --mdbook-alerts-color: rgb(154, 103, 0);
+  /* https://icon-sets.iconify.design/material-symbols/warning-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M2.725 21q-.275 0-.5-.137t-.35-.363q-.125-.225-.137-.488t.137-.512l9.25-16q.15-.25.388-.375T12 3q.25 0 .488.125t.387.375l9.25 16q.15.25.138.513t-.138.487q-.125.225-.35.363t-.5.137zm1.725-2h15.1L12 6zM12 18q.425 0 .713-.288T13 17q0-.425-.288-.712T12 16q-.425 0-.712.288T11 17q0 .425.288.713T12 18m0-3q.425 0 .713-.288T13 14v-3q0-.425-.288-.712T12 10q-.425 0-.712.288T11 11v3q0 .425.288.713T12 15m0-2.5"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-caution {
+  --mdbook-alerts-color: rgb(207, 34, 46);
+  /* https://icon-sets.iconify.design/material-symbols/brightness-alert-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16q0-.425-.288-.712T12 15q-.425 0-.712.288T11 16q0 .425.288.713T12 17m0-4q.425 0 .713-.288T13 12V8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8v4q0 .425.288.713T12 13m-3.35 7H6q-.825 0-1.412-.587T4 18v-2.65L2.075 13.4q-.275-.3-.425-.662T1.5 12q0-.375.15-.737t.425-.663L4 8.65V6q0-.825.588-1.412T6 4h2.65l1.95-1.925q.3-.275.663-.425T12 1.5q.375 0 .738.15t.662.425L15.35 4H18q.825 0 1.413.588T20 6v2.65l1.925 1.95q.275.3.425.663t.15.737q0 .375-.15.738t-.425.662L20 15.35V18q0 .825-.587 1.413T18 20h-2.65l-1.95 1.925q-.3.275-.662.425T12 22.5q-.375 0-.737-.15t-.663-.425zm.85-2l2.5 2.5l2.5-2.5H18v-3.5l2.5-2.5L18 9.5V6h-3.5L12 3.5L9.5 6H6v3.5L3.5 12L6 14.5V18zm2.5-6"%2F%3E%3C%2Fsvg%3E');
+}
+
+</style>
+<h1 id="id-map"><a class="header" href="#id-map">ID Map</a></h1>
+<p>Internally, <em>NNG</em> uses a map of numeric identifiers to data structures.
+This feature is also exposed for application use, as a “supplemental” feature.</p>
+<p>When using these functions, it is necessary to add the <code>#include &lt;nng/supplemental/util/idhash.h&gt;</code>
+include file to list of includes.</p>
+<h2 id="id-map-structure"><a class="header" href="#id-map-structure">ID Map Structure</a></h2>
+<pre><code class="language-c">#include &lt;nng/nng.h&gt;
+#include &lt;nng/supplemental/util/idhash.h&gt;
+
+typedef struct nng_id_map_s nng_id_map;
+</code></pre>
+<p>The ID map structure, <a name="a001"></a><code>nng_id_map</code> provides a table of identifiers mapping
+to user-supplied pointers (which must not be <code>NULL</code>). The identifiers can be
+thought of as indices into the table, with the pointers providing the reference
+for the user supplied data.</p>
+<p>The values of identifiers can be supplied by the user, or can be allocated automatically
+by <code>nng_id_map</code> from a predefined range. The starting point for allocations
+can also be randomly within the range.</p>
+<p>The identifiers are 64-bit unsigned integers and can be sparse; the structure
+will use space efficiently even if identifiers are very far apart.
+<sup><a name="to-footnote-1"><a href="#footnote-1">1</a></a></sup></p>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
+<p>The function available for <code>nng_id_map</code> are <em>not</em> thread-safe.
+Callers should use a <a href="/api/synch.html#mutual-exclusion-lock">mutex</a> or similar approach when thread-safety is needed.</p>
+</div>
+<h2 id="create-id-map"><a class="header" href="#create-id-map">Create ID Map</a></h2>
+<pre><code class="language-c">#define NNG_MAP_RANDOM 1
+
+int nng_id_map_alloc(nng_id_map **map_p, uint64_t lo, uint64_t hi, int flags);
+</code></pre>
+<p>The <a name="a002"></a><code>nng_id_map_alloc</code> function allocates a map without any data in it,
+and returns a pointer to it in <em>map_p</em>. When allocating identifiers dynamically,
+the values will be chosen from the range defined by <em>lo</em> and <em>hi</em>, inclusive.</p>
+<p>The <em>flags</em> argument is a bit mask of flags that can adjust behavior of the map.
+The only flag defined at present
+is <code>NNG_MAP_RANDOM</code>, which causes the first identifier allocation to start at a random
+point within the range.
+This is useful to reduce the odds of different instances of an application using
+the same identifiers at the same time.</p>
+<p>If both <em>lo</em> and <em>hi</em> are zero, then the values <code>0</code> and <code>0xffffffff</code> are substituted
+in their place, giving a full range of 32-bit identifiers.</p>
+<p>This function can return <a href="/api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a> if it is unable to allocate resources, otherwise
+it returns zero on success.</p>
+<h2 id="destroy-map"><a class="header" href="#destroy-map">Destroy Map</a></h2>
+<pre><code class="language-c">void nng_id_map_free(nng_id_map *map);
+</code></pre>
+<p>The <a name="a003"></a><code>nng_id_map_free</code> function destroys <em>map</em>, releasing any resources associated
+with it.</p>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  note
+</p>
+<p>The <code>nng_id_map_free</code> frees the map itself, but will not free memory associated with
+any strctures contained within it.</p>
+</div>
+<h2 id="store-a-value"><a class="header" href="#store-a-value">Store a Value</a></h2>
+<pre><code class="language-c">int nng_id_set(nng_id_map *map, uint64_t id, void *value);
+</code></pre>
+<p>The <a name="a004"></a><code>nng_id_map_set</code> function is used to store the <em>value</em> in the <em>map</em> at
+index <em>id</em>.</p>
+<p>If another value is already stored at that same location, then it is overwritten with
+<em>value</em>.</p>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  note
+</p>
+<p>The <em>value</em> must not be <code>NULL</code>.</p>
+</div>
+<p>If the table has to grow to accommodate this value, it may fail if insufficient
+memory is available, returning <a href="/api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>. Otherwise it returns zero.</p>
+<h2 id="lookup-a-value"><a class="header" href="#lookup-a-value">Lookup a Value</a></h2>
+<pre><code class="language-c">void *nng_id_get(nng_id_map *map, uint64_t id);
+</code></pre>
+<p>The <a name="a005"></a><code>nng_id_get</code> function looks up the entry for <em>id</em> in <em>map</em>, returning the
+associated value if present, or <code>NULL</code> if no such entry exists.</p>
+<h2 id="allocate-an-id"><a class="header" href="#allocate-an-id">Allocate an ID</a></h2>
+<pre><code class="language-c">int nng_id_alloc(nng_id_map *map, uint64_t *id_p, void *value);
+</code></pre>
+<p>The <a name="a006"></a><code>nng_id_alloc</code> stores the <em>value</em> in the <em>map</em>, at a newly allocated index,
+and returns the index in <em>id_p</em>.</p>
+<p>Identifiers are allocated in increasing order, without reusing old identifiers until the
+largest possible identifier is allocated. After wrapping, only identifiers that are no longer
+in use will be considered.
+No effort is made to order the availability of identifiers based on
+when they were freed.<sup><a name="to-footnote-2"><a href="#footnote-2">2</a></a></sup></p>
+<p>As with <a href="/api/id_map.html#store-a-value"><code>nng_id_set</code></a>, this may need to allocate memory and can thus
+fail with <a href="/api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>.</p>
+<p>Additionally, if there are no more free identifiers within the range specified
+when <em>map</em> was created, then it will return <a href="/api/errors.html#NNG_ENOSPC"><code>NNG_ENOSPC</code></a>.</p>
+<p>Otherwise it returns zero, indicating success.</p>
+<h2 id="remove-an-id"><a class="header" href="#remove-an-id">Remove an ID</a></h2>
+<pre><code class="language-c">int nng_id_remove(nng_id_map *map, uint64_t id);
+</code></pre>
+<p>The <a name="a007"></a><code>nng_id_remove</code> removes the entry at index <em>id</em> from <em>map</em>.</p>
+<p>If no such entry exist, it will return <a href="/api/errors.html#NNG_ENOENT"><code>NNG_ENOENT</code></a>. Otherwise it returns zero.</p>
+<h2 id="iterating-ids"><a class="header" href="#iterating-ids">Iterating IDs</a></h2>
+<pre><code class="language-c">bool nng_id_visit(nng_id_map *map, uint64_t *id_p, void **value_p, uint32_t *cursor);
+</code></pre>
+<p>The <a name="a008"></a><code>nng_id_visit</code> function is used to iterate over all items in the table.
+The caller starts the iteration by setting the <em>cursor</em> to 0 before calling it.
+For each call, the associated key and value of the next item will be returned in <em>id_p</em>,
+and <em>value_p</em> and the <em>cursor</em> will be updated.
+When all items have been iterated, the function returns <code>false</code>.
+The order of items returned is not guaranteed to be sequential.
+The caller must not attempt to derive any value of the <em>cursor</em> as it refers to internal table indices.</p>
+<p>Entries may be safely removed from <em>map</em> while iterating.</p>
+<p>However, if new entries are added to the table while iterating, the result of
+iteration is undefined; entries may be repeated or omitted during such an iteration.</p>
+<p>The caller must not attempt to derive any value of the <em>cursor</em> as it refers to internal
+table indices.</p>
+<!-- Symbol cross reference -->
+<!-- Macros -->
+<!-- Protocols -->
+<!-- Transports -->
+<!-- Concept index -->
+<p><hr/>
+<p><a name="footnote-1"><a href="#to-footnote-1">1</a></a>: The ID map is capable of storing at most 2<sup>32</sup> identifiers, even though the identifers may
+themselves be much larger than this.</p>
+<p><a name="footnote-2"><a href="#to-footnote-2">2</a></a>: The concern about possibly reusing a
+recently released identifier comes into consideration after the range has wrapped.
+Given a sufficiently large range, this is unlikely to be a concern.</p>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../api/misc.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+
+                            <a rel="next prefetch" href="../api/cmd_opts.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="../api/misc.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+
+                    <a rel="next prefetch" href="../api/cmd_opts.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="../elasticlunr.min.js"></script>
+        <script src="../mark.min.js"></script>
+        <script src="../searcher.js"></script>
+
+        <script src="../clipboard.min.js"></script>
+        <script src="../highlight.js"></script>
+        <script src="../book.js"></script>
+
+        <!-- Custom JS scripts -->
+        <script src="../theme/pagetoc.js"></script>
+
+
+    </div>
+    </body>
+</html>
diff --git a/ref/api/index.html b/ref/api/index.html
new file mode 100644
index 00000000..61df6062
--- /dev/null
+++ b/ref/api/index.html
@@ -0,0 +1,311 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>API Reference - NNG Reference Manual (DRAFT)</title>
+
+
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="../favicon.svg">
+        <link rel="shortcut icon" href="../favicon.png">
+        <link rel="stylesheet" href="../css/variables.css">
+        <link rel="stylesheet" href="../css/general.css">
+        <link rel="stylesheet" href="../css/chrome.css">
+        <link rel="stylesheet" href="../css/print.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="../fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="../highlight.css">
+        <link rel="stylesheet" href="../tomorrow-night.css">
+        <link rel="stylesheet" href="../ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+        <link rel="stylesheet" href="../theme/pagetoc.css">
+
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "../";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded affix "><a href="../copyright.html">Copyright</a></li><li class="chapter-item expanded affix "><a href="../dedication.html">Dedication</a></li><li class="chapter-item expanded affix "><a href="../preface.html">Preface</a></li><li class="chapter-item expanded "><a href="../api/index.html" class="active"><strong aria-hidden="true">1.</strong> API Reference</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../api/msg.html"><strong aria-hidden="true">1.1.</strong> Messages</a></li><li class="chapter-item expanded "><a href="../api/memory.html"><strong aria-hidden="true">1.2.</strong> Memory</a></li><li class="chapter-item expanded "><a href="../api/time.html"><strong aria-hidden="true">1.3.</strong> Time</a></li><li class="chapter-item expanded "><a href="../api/url.html"><strong aria-hidden="true">1.4.</strong> URLs</a></li><li class="chapter-item expanded "><a href="../api/aio.html"><strong aria-hidden="true">1.5.</strong> Asynchronous I/O</a></li><li class="chapter-item expanded "><a href="../api/synch.html"><strong aria-hidden="true">1.6.</strong> Synchronization</a></li><li class="chapter-item expanded "><a href="../api/thread.html"><strong aria-hidden="true">1.7.</strong> Threads</a></li><li class="chapter-item expanded "><a href="../api/logging.html"><strong aria-hidden="true">1.8.</strong> Logging</a></li><li class="chapter-item expanded "><a href="../api/stats.html"><strong aria-hidden="true">1.9.</strong> Statistics</a></li><li class="chapter-item expanded "><a href="../api/errors.html"><strong aria-hidden="true">1.10.</strong> Errors</a></li><li class="chapter-item expanded "><a href="../api/misc.html"><strong aria-hidden="true">1.11.</strong> Miscellaneous</a></li><li class="chapter-item expanded "><a href="../api/id_map.html"><strong aria-hidden="true">1.12.</strong> ID Map</a></li><li class="chapter-item expanded "><a href="../api/cmd_opts.html"><strong aria-hidden="true">1.13.</strong> Command Options</a></li></ol></li><li class="chapter-item expanded "><a href="../proto/index.html"><strong aria-hidden="true">2.</strong> Protocols</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../proto/bus.html"><strong aria-hidden="true">2.1.</strong> BUS Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pair.html"><strong aria-hidden="true">2.2.</strong> PAIR Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pub.html"><strong aria-hidden="true">2.3.</strong> PUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pull.html"><strong aria-hidden="true">2.4.</strong> PULL Protocol</a></li><li class="chapter-item expanded "><a href="../proto/push.html"><strong aria-hidden="true">2.5.</strong> PUSH Protocol</a></li><li class="chapter-item expanded "><a href="../proto/rep.html"><strong aria-hidden="true">2.6.</strong> REP Protocol</a></li><li class="chapter-item expanded "><a href="../proto/req.html"><strong aria-hidden="true">2.7.</strong> REQ Protocol</a></li><li class="chapter-item expanded "><a href="../proto/respondent.html"><strong aria-hidden="true">2.8.</strong> RESPONDENT Protocol</a></li><li class="chapter-item expanded "><a href="../proto/sub.html"><strong aria-hidden="true">2.9.</strong> SUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/surveyor.html"><strong aria-hidden="true">2.10.</strong> SURVEYOR Protocol</a></li></ol></li><li class="chapter-item expanded "><a href="../tran/index.html"><strong aria-hidden="true">3.</strong> Transports</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../tran/inproc.html"><strong aria-hidden="true">3.1.</strong> Intra-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/ipc.html"><strong aria-hidden="true">3.2.</strong> Inter-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/socket.html"><strong aria-hidden="true">3.3.</strong> BSD Socket (Experimental)</a></li><li class="chapter-item expanded "><a href="../tran/udp.html"><strong aria-hidden="true">3.4.</strong> UDP Transport (Experimental)</a></li></ol></li><li class="chapter-item expanded "><a href="../migrate/index.html"><strong aria-hidden="true">4.</strong> Migration Guides</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../migrate/nng1.html"><strong aria-hidden="true">4.1.</strong> Migrating from NNG 1.x</a></li><li class="chapter-item expanded "><a href="../migrate/nanomsg.html"><strong aria-hidden="true">4.2.</strong> Migrating from libnanomsg</a></li></ol></li><li class="chapter-item expanded "><a href="../indexing.html">Index</a></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
+                <div class="sidebar-resize-indicator"></div>
+            </div>
+        </nav>
+
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">NNG Reference Manual (DRAFT)</h1>
+
+                    <div class="right-buttons">
+                        <a href="../print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <style>
+.mdbook-alerts {
+  padding: 8px 16px;
+  margin-bottom: 16px;
+  border-left: 0.25em solid var(--mdbook-alerts-color);
+}
+
+.mdbook-alerts > *:first-child {
+  margin-top: 0;
+}
+
+.mdbook-alerts > *:last-child {
+  margin-bottom: 0;
+}
+
+.mdbook-alerts-title {
+  display: flex;
+  font-weight: 600;
+  align-items: center;
+  line-height: 1;
+  color: var(--mdbook-alerts-color);
+  text-transform: capitalize;
+}
+
+.mdbook-alerts-icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  margin-right: 0.2em;
+  background-color: currentColor;
+  -webkit-mask: no-repeat center / 100%;
+  mask: no-repeat center / 100%;
+  -webkit-mask-image: var(--mdbook-alerts-icon);
+  mask-image: var(--mdbook-alerts-icon);
+}
+
+.mdbook-alerts-note {
+  --mdbook-alerts-color: rgb(9, 105, 218);
+  /* https://icon-sets.iconify.design/material-symbols/info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16v-4q0-.425-.288-.712T12 11q-.425 0-.712.288T11 12v4q0 .425.288.713T12 17m0-8q.425 0 .713-.288T13 8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8q0 .425.288.713T12 9m0 13q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12q0-3.35-2.325-5.675T12 4Q8.65 4 6.325 6.325T4 12q0 3.35 2.325 5.675T12 20m0-8"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-tip {
+  --mdbook-alerts-color: rgb(26, 127, 55);
+  /* https://icon-sets.iconify.design/material-symbols/lightbulb-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 22q-.825 0-1.412-.587T10 20h4q0 .825-.587 1.413T12 22m-3-3q-.425 0-.712-.288T8 18q0-.425.288-.712T9 17h6q.425 0 .713.288T16 18q0 .425-.288.713T15 19zm-.75-3q-1.725-1.025-2.738-2.75T4.5 9.5q0-3.125 2.188-5.312T12 2q3.125 0 5.313 2.188T19.5 9.5q0 2.025-1.012 3.75T15.75 16zm.6-2h6.3q1.125-.8 1.738-1.975T17.5 9.5q0-2.3-1.6-3.9T12 4Q9.7 4 8.1 5.6T6.5 9.5q0 1.35.613 2.525T8.85 14M12 14"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-important {
+  --mdbook-alerts-color: rgb(130, 80, 223);
+  /* https://icon-sets.iconify.design/material-symbols/chat-info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 7q.425 0 .713-.288T13 6q0-.425-.288-.712T12 5q-.425 0-.712.288T11 6q0 .425.288.713T12 7m0 8q.425 0 .713-.288T13 14v-4q0-.425-.288-.712T12 9q-.425 0-.712.288T11 10v4q0 .425.288.713T12 15m-6 3l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-warning {
+  --mdbook-alerts-color: rgb(154, 103, 0);
+  /* https://icon-sets.iconify.design/material-symbols/warning-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M2.725 21q-.275 0-.5-.137t-.35-.363q-.125-.225-.137-.488t.137-.512l9.25-16q.15-.25.388-.375T12 3q.25 0 .488.125t.387.375l9.25 16q.15.25.138.513t-.138.487q-.125.225-.35.363t-.5.137zm1.725-2h15.1L12 6zM12 18q.425 0 .713-.288T13 17q0-.425-.288-.712T12 16q-.425 0-.712.288T11 17q0 .425.288.713T12 18m0-3q.425 0 .713-.288T13 14v-3q0-.425-.288-.712T12 10q-.425 0-.712.288T11 11v3q0 .425.288.713T12 15m0-2.5"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-caution {
+  --mdbook-alerts-color: rgb(207, 34, 46);
+  /* https://icon-sets.iconify.design/material-symbols/brightness-alert-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16q0-.425-.288-.712T12 15q-.425 0-.712.288T11 16q0 .425.288.713T12 17m0-4q.425 0 .713-.288T13 12V8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8v4q0 .425.288.713T12 13m-3.35 7H6q-.825 0-1.412-.587T4 18v-2.65L2.075 13.4q-.275-.3-.425-.662T1.5 12q0-.375.15-.737t.425-.663L4 8.65V6q0-.825.588-1.412T6 4h2.65l1.95-1.925q.3-.275.663-.425T12 1.5q.375 0 .738.15t.662.425L15.35 4H18q.825 0 1.413.588T20 6v2.65l1.925 1.95q.275.3.425.663t.15.737q0 .375-.15.738t-.425.662L20 15.35V18q0 .825-.587 1.413T18 20h-2.65l-1.95 1.925q-.3.275-.662.425T12 22.5q-.375 0-.737-.15t-.663-.425zm.85-2l2.5 2.5l2.5-2.5H18v-3.5l2.5-2.5L18 9.5V6h-3.5L12 3.5L9.5 6H6v3.5L3.5 12L6 14.5V18zm2.5-6"%2F%3E%3C%2Fsvg%3E');
+}
+
+</style>
+<h1 id="api-reference"><a class="header" href="#api-reference">API Reference</a></h1>
+<p>This section is a reference guide for the <em>NNG</em> programming interfaces.
+It is meant to serve as a refernce, rather than as a tutorial.</p>
+<p>The material here is organized by major areas of functionality.</p>
+<p>Note that unless indicated otherwise, consumers of these interfaces must
+include the <code>nng/nng.h</code> header file like so:</p>
+<pre><code class="language-c">#include &lt;nng/nng.h&gt;
+</code></pre>
+<h2 id="chapters"><a class="header" href="#chapters">Chapters</a></h2>
+<ul>
+<li><a href="msg/">Messages</a></li>
+<li><a href="thr/">Threading and Synchronization</a></li>
+<li><a href="logging.html">Logging</a></li>
+<li><a href="util/">Utility Functions</a></li>
+</ul>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../preface.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+
+                            <a rel="next prefetch" href="../api/msg.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="../preface.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+
+                    <a rel="next prefetch" href="../api/msg.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="../elasticlunr.min.js"></script>
+        <script src="../mark.min.js"></script>
+        <script src="../searcher.js"></script>
+
+        <script src="../clipboard.min.js"></script>
+        <script src="../highlight.js"></script>
+        <script src="../book.js"></script>
+
+        <!-- Custom JS scripts -->
+        <script src="../theme/pagetoc.js"></script>
+
+
+    </div>
+    </body>
+</html>
diff --git a/ref/api/logging.html b/ref/api/logging.html
new file mode 100644
index 00000000..4402ff40
--- /dev/null
+++ b/ref/api/logging.html
@@ -0,0 +1,437 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>Logging - NNG Reference Manual (DRAFT)</title>
+
+
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="../favicon.svg">
+        <link rel="shortcut icon" href="../favicon.png">
+        <link rel="stylesheet" href="../css/variables.css">
+        <link rel="stylesheet" href="../css/general.css">
+        <link rel="stylesheet" href="../css/chrome.css">
+        <link rel="stylesheet" href="../css/print.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="../fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="../highlight.css">
+        <link rel="stylesheet" href="../tomorrow-night.css">
+        <link rel="stylesheet" href="../ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+        <link rel="stylesheet" href="../theme/pagetoc.css">
+
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "../";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded affix "><a href="../copyright.html">Copyright</a></li><li class="chapter-item expanded affix "><a href="../dedication.html">Dedication</a></li><li class="chapter-item expanded affix "><a href="../preface.html">Preface</a></li><li class="chapter-item expanded "><a href="../api/index.html"><strong aria-hidden="true">1.</strong> API Reference</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../api/msg.html"><strong aria-hidden="true">1.1.</strong> Messages</a></li><li class="chapter-item expanded "><a href="../api/memory.html"><strong aria-hidden="true">1.2.</strong> Memory</a></li><li class="chapter-item expanded "><a href="../api/time.html"><strong aria-hidden="true">1.3.</strong> Time</a></li><li class="chapter-item expanded "><a href="../api/url.html"><strong aria-hidden="true">1.4.</strong> URLs</a></li><li class="chapter-item expanded "><a href="../api/aio.html"><strong aria-hidden="true">1.5.</strong> Asynchronous I/O</a></li><li class="chapter-item expanded "><a href="../api/synch.html"><strong aria-hidden="true">1.6.</strong> Synchronization</a></li><li class="chapter-item expanded "><a href="../api/thread.html"><strong aria-hidden="true">1.7.</strong> Threads</a></li><li class="chapter-item expanded "><a href="../api/logging.html" class="active"><strong aria-hidden="true">1.8.</strong> Logging</a></li><li class="chapter-item expanded "><a href="../api/stats.html"><strong aria-hidden="true">1.9.</strong> Statistics</a></li><li class="chapter-item expanded "><a href="../api/errors.html"><strong aria-hidden="true">1.10.</strong> Errors</a></li><li class="chapter-item expanded "><a href="../api/misc.html"><strong aria-hidden="true">1.11.</strong> Miscellaneous</a></li><li class="chapter-item expanded "><a href="../api/id_map.html"><strong aria-hidden="true">1.12.</strong> ID Map</a></li><li class="chapter-item expanded "><a href="../api/cmd_opts.html"><strong aria-hidden="true">1.13.</strong> Command Options</a></li></ol></li><li class="chapter-item expanded "><a href="../proto/index.html"><strong aria-hidden="true">2.</strong> Protocols</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../proto/bus.html"><strong aria-hidden="true">2.1.</strong> BUS Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pair.html"><strong aria-hidden="true">2.2.</strong> PAIR Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pub.html"><strong aria-hidden="true">2.3.</strong> PUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pull.html"><strong aria-hidden="true">2.4.</strong> PULL Protocol</a></li><li class="chapter-item expanded "><a href="../proto/push.html"><strong aria-hidden="true">2.5.</strong> PUSH Protocol</a></li><li class="chapter-item expanded "><a href="../proto/rep.html"><strong aria-hidden="true">2.6.</strong> REP Protocol</a></li><li class="chapter-item expanded "><a href="../proto/req.html"><strong aria-hidden="true">2.7.</strong> REQ Protocol</a></li><li class="chapter-item expanded "><a href="../proto/respondent.html"><strong aria-hidden="true">2.8.</strong> RESPONDENT Protocol</a></li><li class="chapter-item expanded "><a href="../proto/sub.html"><strong aria-hidden="true">2.9.</strong> SUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/surveyor.html"><strong aria-hidden="true">2.10.</strong> SURVEYOR Protocol</a></li></ol></li><li class="chapter-item expanded "><a href="../tran/index.html"><strong aria-hidden="true">3.</strong> Transports</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../tran/inproc.html"><strong aria-hidden="true">3.1.</strong> Intra-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/ipc.html"><strong aria-hidden="true">3.2.</strong> Inter-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/socket.html"><strong aria-hidden="true">3.3.</strong> BSD Socket (Experimental)</a></li><li class="chapter-item expanded "><a href="../tran/udp.html"><strong aria-hidden="true">3.4.</strong> UDP Transport (Experimental)</a></li></ol></li><li class="chapter-item expanded "><a href="../migrate/index.html"><strong aria-hidden="true">4.</strong> Migration Guides</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../migrate/nng1.html"><strong aria-hidden="true">4.1.</strong> Migrating from NNG 1.x</a></li><li class="chapter-item expanded "><a href="../migrate/nanomsg.html"><strong aria-hidden="true">4.2.</strong> Migrating from libnanomsg</a></li></ol></li><li class="chapter-item expanded "><a href="../indexing.html">Index</a></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
+                <div class="sidebar-resize-indicator"></div>
+            </div>
+        </nav>
+
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">NNG Reference Manual (DRAFT)</h1>
+
+                    <div class="right-buttons">
+                        <a href="../print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <style>
+.mdbook-alerts {
+  padding: 8px 16px;
+  margin-bottom: 16px;
+  border-left: 0.25em solid var(--mdbook-alerts-color);
+}
+
+.mdbook-alerts > *:first-child {
+  margin-top: 0;
+}
+
+.mdbook-alerts > *:last-child {
+  margin-bottom: 0;
+}
+
+.mdbook-alerts-title {
+  display: flex;
+  font-weight: 600;
+  align-items: center;
+  line-height: 1;
+  color: var(--mdbook-alerts-color);
+  text-transform: capitalize;
+}
+
+.mdbook-alerts-icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  margin-right: 0.2em;
+  background-color: currentColor;
+  -webkit-mask: no-repeat center / 100%;
+  mask: no-repeat center / 100%;
+  -webkit-mask-image: var(--mdbook-alerts-icon);
+  mask-image: var(--mdbook-alerts-icon);
+}
+
+.mdbook-alerts-note {
+  --mdbook-alerts-color: rgb(9, 105, 218);
+  /* https://icon-sets.iconify.design/material-symbols/info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16v-4q0-.425-.288-.712T12 11q-.425 0-.712.288T11 12v4q0 .425.288.713T12 17m0-8q.425 0 .713-.288T13 8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8q0 .425.288.713T12 9m0 13q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12q0-3.35-2.325-5.675T12 4Q8.65 4 6.325 6.325T4 12q0 3.35 2.325 5.675T12 20m0-8"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-tip {
+  --mdbook-alerts-color: rgb(26, 127, 55);
+  /* https://icon-sets.iconify.design/material-symbols/lightbulb-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 22q-.825 0-1.412-.587T10 20h4q0 .825-.587 1.413T12 22m-3-3q-.425 0-.712-.288T8 18q0-.425.288-.712T9 17h6q.425 0 .713.288T16 18q0 .425-.288.713T15 19zm-.75-3q-1.725-1.025-2.738-2.75T4.5 9.5q0-3.125 2.188-5.312T12 2q3.125 0 5.313 2.188T19.5 9.5q0 2.025-1.012 3.75T15.75 16zm.6-2h6.3q1.125-.8 1.738-1.975T17.5 9.5q0-2.3-1.6-3.9T12 4Q9.7 4 8.1 5.6T6.5 9.5q0 1.35.613 2.525T8.85 14M12 14"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-important {
+  --mdbook-alerts-color: rgb(130, 80, 223);
+  /* https://icon-sets.iconify.design/material-symbols/chat-info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 7q.425 0 .713-.288T13 6q0-.425-.288-.712T12 5q-.425 0-.712.288T11 6q0 .425.288.713T12 7m0 8q.425 0 .713-.288T13 14v-4q0-.425-.288-.712T12 9q-.425 0-.712.288T11 10v4q0 .425.288.713T12 15m-6 3l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-warning {
+  --mdbook-alerts-color: rgb(154, 103, 0);
+  /* https://icon-sets.iconify.design/material-symbols/warning-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M2.725 21q-.275 0-.5-.137t-.35-.363q-.125-.225-.137-.488t.137-.512l9.25-16q.15-.25.388-.375T12 3q.25 0 .488.125t.387.375l9.25 16q.15.25.138.513t-.138.487q-.125.225-.35.363t-.5.137zm1.725-2h15.1L12 6zM12 18q.425 0 .713-.288T13 17q0-.425-.288-.712T12 16q-.425 0-.712.288T11 17q0 .425.288.713T12 18m0-3q.425 0 .713-.288T13 14v-3q0-.425-.288-.712T12 10q-.425 0-.712.288T11 11v3q0 .425.288.713T12 15m0-2.5"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-caution {
+  --mdbook-alerts-color: rgb(207, 34, 46);
+  /* https://icon-sets.iconify.design/material-symbols/brightness-alert-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16q0-.425-.288-.712T12 15q-.425 0-.712.288T11 16q0 .425.288.713T12 17m0-4q.425 0 .713-.288T13 12V8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8v4q0 .425.288.713T12 13m-3.35 7H6q-.825 0-1.412-.587T4 18v-2.65L2.075 13.4q-.275-.3-.425-.662T1.5 12q0-.375.15-.737t.425-.663L4 8.65V6q0-.825.588-1.412T6 4h2.65l1.95-1.925q.3-.275.663-.425T12 1.5q.375 0 .738.15t.662.425L15.35 4H18q.825 0 1.413.588T20 6v2.65l1.925 1.95q.275.3.425.663t.15.737q0 .375-.15.738t-.425.662L20 15.35V18q0 .825-.587 1.413T18 20h-2.65l-1.95 1.925q-.3.275-.662.425T12 22.5q-.375 0-.737-.15t-.663-.425zm.85-2l2.5 2.5l2.5-2.5H18v-3.5l2.5-2.5L18 9.5V6h-3.5L12 3.5L9.5 6H6v3.5L3.5 12L6 14.5V18zm2.5-6"%2F%3E%3C%2Fsvg%3E');
+}
+
+</style>
+<h1 id="logging"><a class="header" href="#logging">Logging</a></h1>
+<p>This chapter describes the support for message logs.
+Both applications and <em>NNG</em> itself can emit logs, which can be useful
+for application field support and debugging. Additionally applications
+can customize the handling of this logging as needed.</p>
+<p>Note that logging is disabled by default unless an application
+configures a suitable logger with <a href="#log-handlers"><code>nng_log_set_logger</code></a>.</p>
+<h2 id="submitting-logs"><a class="header" href="#submitting-logs">Submitting Logs</a></h2>
+<pre><code class="language-c">void nng_log_err(const char *msgid, const char *msg, ...);
+void nng_log_warn(const char *msgid, const char *msg, ...);
+void nng_log_notice(const char *msgid, const char *msg, ...);
+void nng_log_info(const char *msgid, const char *msg, ...);
+void nng_log_debug(const char *msgid, const char *msg, ...);
+</code></pre>
+<p>These <a name="a001"></a> functions inject a a message into the
+logging system, where it will be processed and potentially go to
+system logs, standard output, or procssed further.</p>
+<p>The <em>msgid</em> is a short prefix that should uniquely identify the message,
+possibly also with some kind of category. It is recommended that
+strings between 8 and 16 charactes be used. As this may, but will not necessarily
+be displayed to the user, the content of the message should not appear
+solely in this field. A <code>NULL</code> value is permitted here, but that may
+make filtering the message or other automatic processing more difficult.</p>
+<p>The <em>msg</em> is a <code>printf</code>-style format string, which is used to format the
+message content. The following arguments are consumed in the
+same manner as <code>printf</code>.</p>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  tip
+</p>
+<p>Applications should take care to limit the use of higher severity levels, as message logs
+are potentially expensive, increase stress for end users and administrators, and further may
+mask real problems if incorrectly over used.</p>
+<p>Warnings and error messages should be concise and actionable, and notices should only
+really be those things that are worthy of attention.</p>
+<p>Informational and debug messages used during development should be removed when no longer
+needed, as these messages can overwhelm logging subsystems and can reduce the
+signal-to-noise value for the message logs, impairing the diagnostic value of the logs.</p>
+</div>
+<h2 id="auth-logs"><a class="header" href="#auth-logs">Auth Logs</a></h2>
+<pre><code class="language-c">void nng_log_auth(nng_log_level level, const char *msgid, const char *msg, ...);
+</code></pre>
+<p>The <a name="a002"></a><code>nng_log_auth</code> function formats and injects a security related log message.
+(“Auth” can indicate either “authentication” or “authorization”.)
+The <em>level</em> is a <a href="#log-levels">log level</a>.
+The <em>msgid</em>, <em>msg</em>, and any remaining arguments are processed in a fashion
+similar to the other <a href="#submitting-logs">logging functions</a>, except that the
+logs may be are logged using the <code>NNG_LOG_AUTH</code> <a href="#log-facilities">facility</a>, and thus may be
+redirected or receive other special treatment.</p>
+<h2 id="log-levels"><a class="header" href="#log-levels">Log Levels</a></h2>
+<pre><code class="language-c">typedef enum nng_log_level nng_log_level;
+
+void nng_log_set_level(nng_log_level level);
+nng_log_level nng_log_get_level(void);
+</code></pre>
+<p>The <a name="a003"></a><code>nng_log_level</code> type represents a severity for logged messages.
+These levels correspond to those found in the UNIX syslog subsystem,
+although applications should not depend upon the values being identical.</p>
+<p>The <a name="a004"></a><code>nng_log_set_level</code> function sets the log level.
+Messages with a severity that is numerically greater than this (less-severe)
+will be discarded.</p>
+<p>The <a name="a005"></a><code>nng_log_get_level</code> function returns the log level most recently
+set by <code>nng_log_set_level</code> or the default
+if that function has not been called.</p>
+<p>The log levels are defined as follows:</p>
+<pre><code class="language-c">typedef enum nng_log_level {
+	NNG_LOG_NONE   = 0, // used for filters only, NNG suppresses these
+	NNG_LOG_ERR    = 3,
+	NNG_LOG_WARN   = 4,
+	NNG_LOG_NOTICE = 5,
+	NNG_LOG_INFO   = 6,
+	NNG_LOG_DEBUG  = 7
+} nng_log_level;
+</code></pre>
+<p>The value <code>NNG_LOG_NONE</code> may be useful to suppress message logs altogether.</p>
+<p>The default level is typically <code>NNG_LOG_NOTICE</code>, but applications should
+select a value rather than relying upon the default.</p>
+<h2 id="log-facilities"><a class="header" href="#log-facilities">Log Facilities</a></h2>
+<pre><code class="language-c">typedef enum nng_log_facility
+
+void nng_log_set_facility(nng_log_facility facility);
+</code></pre>
+<p>Logging facilities are used to indicate the source of a log message,
+and may be useful in routing and processing these logs.
+Traditionally these are used with the UNIX <code>syslog</code> system, and
+the values here represent some (but not all) of the values found there.</p>
+<p>The following values are defined:</p>
+<pre><code class="language-c">typedef enum nng_log_facility {
+	NNG_LOG_USER   = 1,
+	NNG_LOG_DAEMON = 3,
+	NNG_LOG_AUTH   = 10,
+	NNG_LOG_LOCAL0 = 16,
+	NNG_LOG_LOCAL1 = 17,
+	NNG_LOG_LOCAL2 = 18,
+	NNG_LOG_LOCAL3 = 19,
+	NNG_LOG_LOCAL4 = 20,
+	NNG_LOG_LOCAL5 = 21,
+	NNG_LOG_LOCAL6 = 22,
+	NNG_LOG_LOCAL7 = 23,
+} nng_log_facility;
+</code></pre>
+<p>The <a name="a006"></a><code>nng_log_set_facility</code> function can be used to
+set the facility that the application will use when emitting log
+messages. This should be called as part of initialization of the
+application, if logging is to be used.</p>
+<p>The default facility is typically <code>NNG_LOG_USER</code>, but applications should
+select a value rather than relying upon the default.</p>
+<h2 id="log-handlers"><a class="header" href="#log-handlers">Log Handlers</a></h2>
+<pre><code class="language-c">typedef void (*nng_logger)(nng_log_level level, nng_log_facility facility,
+    const char *msgid, const char *msg);
+
+void nng_null_logger(nng_log_level, nng_log_facility, const char *, const char *);
+void nng_stderr_logger(nng_log_level, nng_log_facility, const char *, const char *);
+void nng_system_logger(nng_log_level, nng_log_facility, const char *, const char *);
+
+void nng_log_set_logger(nng_logger logger);
+</code></pre>
+<p><a name="a007"></a>Log handlers are responsible for actually processing the logged messages.</p>
+<p>The <a name="a008"></a><code>nng_log_set_logger</code> function installs the named <em>logger</em>, of type <a name="a009"></a><code>nng_logger</code>,
+as the log handler. The function <em>logger</em> will be called when any message is meant to
+be processed. (Messages are first filtered by <a href="#log-levels">severity</a>, then formatted,
+before calling the logger.)</p>
+<p>Any previously installed logger is replaced by <em>logger</em>.</p>
+<p>The <a name="a010"></a><code>nng_null_logger</code> function is an implementation of <code>nng_logger</code> that simply discards the content.
+This is the default logger, so logging is disabled by default.</p>
+<p>The <a name="a011"></a><code>nng_stderr_logger</code> function is an implementation that logs messages to the standard error stream.
+It will attempt to colorize messages by the severity, if the standard error is a terminal device.
+This can be suppressed by setting either the <code>NO_COLOR</code> or <code>NNG_LOG_NO_COLOR</code> environment variables.</p>
+<p>The <a name="a012"></a><code>nng_system_logger</code> attempts to use an appropriate system facility to log messages.
+For POSIX systems, this means using <code>syslog</code> to process the messages.
+For other systems the defauilt behavior may be the same as <code>nng_stderr_logger</code>.</p>
+<h2 id="see-also"><a class="header" href="#see-also">See Also</a></h2>
+<p>The Syslog Protocol upon which this is based is documented in the following two IETF
+RFCS,</p>
+<ul>
+<li>R. Gerhards, <a href="https://datatracker.ietf.org/doc/html/rfc5424">RFC 5424</a>, <em>The Syslog Protocol</em>,
+March 2009</li>
+<li>C. Lonvick, <a href="https://datatracker.ietf.org/doc/html/rfc3164">RFC 3164</a>, <em>The BSD syslog Protocol</em>,
+August 2001</li>
+</ul>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../api/thread.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+
+                            <a rel="next prefetch" href="../api/stats.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="../api/thread.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+
+                    <a rel="next prefetch" href="../api/stats.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="../elasticlunr.min.js"></script>
+        <script src="../mark.min.js"></script>
+        <script src="../searcher.js"></script>
+
+        <script src="../clipboard.min.js"></script>
+        <script src="../highlight.js"></script>
+        <script src="../book.js"></script>
+
+        <!-- Custom JS scripts -->
+        <script src="../theme/pagetoc.js"></script>
+
+
+    </div>
+    </body>
+</html>
diff --git a/ref/api/memory.html b/ref/api/memory.html
new file mode 100644
index 00000000..3d58726f
--- /dev/null
+++ b/ref/api/memory.html
@@ -0,0 +1,351 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>Memory - NNG Reference Manual (DRAFT)</title>
+
+
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="../favicon.svg">
+        <link rel="shortcut icon" href="../favicon.png">
+        <link rel="stylesheet" href="../css/variables.css">
+        <link rel="stylesheet" href="../css/general.css">
+        <link rel="stylesheet" href="../css/chrome.css">
+        <link rel="stylesheet" href="../css/print.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="../fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="../highlight.css">
+        <link rel="stylesheet" href="../tomorrow-night.css">
+        <link rel="stylesheet" href="../ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+        <link rel="stylesheet" href="../theme/pagetoc.css">
+
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "../";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded affix "><a href="../copyright.html">Copyright</a></li><li class="chapter-item expanded affix "><a href="../dedication.html">Dedication</a></li><li class="chapter-item expanded affix "><a href="../preface.html">Preface</a></li><li class="chapter-item expanded "><a href="../api/index.html"><strong aria-hidden="true">1.</strong> API Reference</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../api/msg.html"><strong aria-hidden="true">1.1.</strong> Messages</a></li><li class="chapter-item expanded "><a href="../api/memory.html" class="active"><strong aria-hidden="true">1.2.</strong> Memory</a></li><li class="chapter-item expanded "><a href="../api/time.html"><strong aria-hidden="true">1.3.</strong> Time</a></li><li class="chapter-item expanded "><a href="../api/url.html"><strong aria-hidden="true">1.4.</strong> URLs</a></li><li class="chapter-item expanded "><a href="../api/aio.html"><strong aria-hidden="true">1.5.</strong> Asynchronous I/O</a></li><li class="chapter-item expanded "><a href="../api/synch.html"><strong aria-hidden="true">1.6.</strong> Synchronization</a></li><li class="chapter-item expanded "><a href="../api/thread.html"><strong aria-hidden="true">1.7.</strong> Threads</a></li><li class="chapter-item expanded "><a href="../api/logging.html"><strong aria-hidden="true">1.8.</strong> Logging</a></li><li class="chapter-item expanded "><a href="../api/stats.html"><strong aria-hidden="true">1.9.</strong> Statistics</a></li><li class="chapter-item expanded "><a href="../api/errors.html"><strong aria-hidden="true">1.10.</strong> Errors</a></li><li class="chapter-item expanded "><a href="../api/misc.html"><strong aria-hidden="true">1.11.</strong> Miscellaneous</a></li><li class="chapter-item expanded "><a href="../api/id_map.html"><strong aria-hidden="true">1.12.</strong> ID Map</a></li><li class="chapter-item expanded "><a href="../api/cmd_opts.html"><strong aria-hidden="true">1.13.</strong> Command Options</a></li></ol></li><li class="chapter-item expanded "><a href="../proto/index.html"><strong aria-hidden="true">2.</strong> Protocols</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../proto/bus.html"><strong aria-hidden="true">2.1.</strong> BUS Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pair.html"><strong aria-hidden="true">2.2.</strong> PAIR Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pub.html"><strong aria-hidden="true">2.3.</strong> PUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pull.html"><strong aria-hidden="true">2.4.</strong> PULL Protocol</a></li><li class="chapter-item expanded "><a href="../proto/push.html"><strong aria-hidden="true">2.5.</strong> PUSH Protocol</a></li><li class="chapter-item expanded "><a href="../proto/rep.html"><strong aria-hidden="true">2.6.</strong> REP Protocol</a></li><li class="chapter-item expanded "><a href="../proto/req.html"><strong aria-hidden="true">2.7.</strong> REQ Protocol</a></li><li class="chapter-item expanded "><a href="../proto/respondent.html"><strong aria-hidden="true">2.8.</strong> RESPONDENT Protocol</a></li><li class="chapter-item expanded "><a href="../proto/sub.html"><strong aria-hidden="true">2.9.</strong> SUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/surveyor.html"><strong aria-hidden="true">2.10.</strong> SURVEYOR Protocol</a></li></ol></li><li class="chapter-item expanded "><a href="../tran/index.html"><strong aria-hidden="true">3.</strong> Transports</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../tran/inproc.html"><strong aria-hidden="true">3.1.</strong> Intra-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/ipc.html"><strong aria-hidden="true">3.2.</strong> Inter-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/socket.html"><strong aria-hidden="true">3.3.</strong> BSD Socket (Experimental)</a></li><li class="chapter-item expanded "><a href="../tran/udp.html"><strong aria-hidden="true">3.4.</strong> UDP Transport (Experimental)</a></li></ol></li><li class="chapter-item expanded "><a href="../migrate/index.html"><strong aria-hidden="true">4.</strong> Migration Guides</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../migrate/nng1.html"><strong aria-hidden="true">4.1.</strong> Migrating from NNG 1.x</a></li><li class="chapter-item expanded "><a href="../migrate/nanomsg.html"><strong aria-hidden="true">4.2.</strong> Migrating from libnanomsg</a></li></ol></li><li class="chapter-item expanded "><a href="../indexing.html">Index</a></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
+                <div class="sidebar-resize-indicator"></div>
+            </div>
+        </nav>
+
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">NNG Reference Manual (DRAFT)</h1>
+
+                    <div class="right-buttons">
+                        <a href="../print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <style>
+.mdbook-alerts {
+  padding: 8px 16px;
+  margin-bottom: 16px;
+  border-left: 0.25em solid var(--mdbook-alerts-color);
+}
+
+.mdbook-alerts > *:first-child {
+  margin-top: 0;
+}
+
+.mdbook-alerts > *:last-child {
+  margin-bottom: 0;
+}
+
+.mdbook-alerts-title {
+  display: flex;
+  font-weight: 600;
+  align-items: center;
+  line-height: 1;
+  color: var(--mdbook-alerts-color);
+  text-transform: capitalize;
+}
+
+.mdbook-alerts-icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  margin-right: 0.2em;
+  background-color: currentColor;
+  -webkit-mask: no-repeat center / 100%;
+  mask: no-repeat center / 100%;
+  -webkit-mask-image: var(--mdbook-alerts-icon);
+  mask-image: var(--mdbook-alerts-icon);
+}
+
+.mdbook-alerts-note {
+  --mdbook-alerts-color: rgb(9, 105, 218);
+  /* https://icon-sets.iconify.design/material-symbols/info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16v-4q0-.425-.288-.712T12 11q-.425 0-.712.288T11 12v4q0 .425.288.713T12 17m0-8q.425 0 .713-.288T13 8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8q0 .425.288.713T12 9m0 13q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12q0-3.35-2.325-5.675T12 4Q8.65 4 6.325 6.325T4 12q0 3.35 2.325 5.675T12 20m0-8"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-tip {
+  --mdbook-alerts-color: rgb(26, 127, 55);
+  /* https://icon-sets.iconify.design/material-symbols/lightbulb-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 22q-.825 0-1.412-.587T10 20h4q0 .825-.587 1.413T12 22m-3-3q-.425 0-.712-.288T8 18q0-.425.288-.712T9 17h6q.425 0 .713.288T16 18q0 .425-.288.713T15 19zm-.75-3q-1.725-1.025-2.738-2.75T4.5 9.5q0-3.125 2.188-5.312T12 2q3.125 0 5.313 2.188T19.5 9.5q0 2.025-1.012 3.75T15.75 16zm.6-2h6.3q1.125-.8 1.738-1.975T17.5 9.5q0-2.3-1.6-3.9T12 4Q9.7 4 8.1 5.6T6.5 9.5q0 1.35.613 2.525T8.85 14M12 14"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-important {
+  --mdbook-alerts-color: rgb(130, 80, 223);
+  /* https://icon-sets.iconify.design/material-symbols/chat-info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 7q.425 0 .713-.288T13 6q0-.425-.288-.712T12 5q-.425 0-.712.288T11 6q0 .425.288.713T12 7m0 8q.425 0 .713-.288T13 14v-4q0-.425-.288-.712T12 9q-.425 0-.712.288T11 10v4q0 .425.288.713T12 15m-6 3l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-warning {
+  --mdbook-alerts-color: rgb(154, 103, 0);
+  /* https://icon-sets.iconify.design/material-symbols/warning-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M2.725 21q-.275 0-.5-.137t-.35-.363q-.125-.225-.137-.488t.137-.512l9.25-16q.15-.25.388-.375T12 3q.25 0 .488.125t.387.375l9.25 16q.15.25.138.513t-.138.487q-.125.225-.35.363t-.5.137zm1.725-2h15.1L12 6zM12 18q.425 0 .713-.288T13 17q0-.425-.288-.712T12 16q-.425 0-.712.288T11 17q0 .425.288.713T12 18m0-3q.425 0 .713-.288T13 14v-3q0-.425-.288-.712T12 10q-.425 0-.712.288T11 11v3q0 .425.288.713T12 15m0-2.5"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-caution {
+  --mdbook-alerts-color: rgb(207, 34, 46);
+  /* https://icon-sets.iconify.design/material-symbols/brightness-alert-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16q0-.425-.288-.712T12 15q-.425 0-.712.288T11 16q0 .425.288.713T12 17m0-4q.425 0 .713-.288T13 12V8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8v4q0 .425.288.713T12 13m-3.35 7H6q-.825 0-1.412-.587T4 18v-2.65L2.075 13.4q-.275-.3-.425-.662T1.5 12q0-.375.15-.737t.425-.663L4 8.65V6q0-.825.588-1.412T6 4h2.65l1.95-1.925q.3-.275.663-.425T12 1.5q.375 0 .738.15t.662.425L15.35 4H18q.825 0 1.413.588T20 6v2.65l1.925 1.95q.275.3.425.663t.15.737q0 .375-.15.738t-.425.662L20 15.35V18q0 .825-.587 1.413T18 20h-2.65l-1.95 1.925q-.3.275-.662.425T12 22.5q-.375 0-.737-.15t-.663-.425zm.85-2l2.5 2.5l2.5-2.5H18v-3.5l2.5-2.5L18 9.5V6h-3.5L12 3.5L9.5 6H6v3.5L3.5 12L6 14.5V18zm2.5-6"%2F%3E%3C%2Fsvg%3E');
+}
+
+</style>
+<h1 id="memory"><a class="header" href="#memory">Memory</a></h1>
+<p>Managing <a name="a001"></a>memory and <a name="a002"></a>allocations is something that every C program has to deal with.
+In the case of <em>NNG</em>, it can be more complicated because the underlying platform
+code can provide different allocators that might not be compatible with the use
+system allocator used by <code>malloc</code> and <code>free</code>.</p>
+<h2 id="allocate-memory"><a class="header" href="#allocate-memory">Allocate Memory</a></h2>
+<pre><code class="language-c">void *nng_alloc(size_t size);
+</code></pre>
+<p>The <a name="a003"></a><code>nng_alloc</code> function allocates a contiguous memory region of
+at least <em>size</em> bytes, and returns a pointer to it.
+The memory will be 64-bit aligned.
+Note that the memory may have random data in it, just like with <code>malloc</code>.</p>
+<p>If memory cannot be allocated for any reason, then <code>NULL</code> will be returned.
+Applications that experience this should treat this like <a href="/api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>.</p>
+<p>Memory returned by <code>nng_alloc</code> can be used to hold message buffers, in which
+case it can be directly passed to <a href="/TODO.html"><code>nng_send</code></a> using the flag <code>NNG_FLAG_ALLOC</code>.
+Alternatively, it can be freed when no longer needed using <a href="/api/memory.html#deallocate-memory"><code>nng_free</code></a>.</p>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
+<p>Do not use the system <code>free</code> function (or the C++ <code>delete</code> operator) to release this memory.
+On some configurations this may work, but on others it will lead to a crash or
+other unpredictable behavior.</p>
+</div>
+<h2 id="deallocate-memory"><a class="header" href="#deallocate-memory">Deallocate Memory</a></h2>
+<pre><code class="language-c">void nng_free(void *ptr, size_t size);
+</code></pre>
+<p>The <a name="a004"></a><code>nng_free</code> function deallocates memory previously allocated by <a href="/api/memory.html#allocate-memory"><code>nng_alloc</code></a>.</p>
+<p>The <em>size</em> argument must exactly match the <em>size</em> argument that was supplied to
+<a href="/api/memory.html#allocate-memory"><code>nng_alloc</code></a> when the memory was allocated.</p>
+<h2 id="duplicate-string"><a class="header" href="#duplicate-string">Duplicate String</a></h2>
+<pre><code class="language-c">char *nng_strdup(const char *src);
+</code></pre>
+<p>The <a name="a005"></a><code>nng_strdup</code> duplicates the string <em>src</em> and returns it.</p>
+<p>This is logically equivalent to using <a href="/api/memory.html#allocate-memory"><code>nng_alloc</code></a>
+to allocate a region of memory of <code>strlen(s) + 1</code> bytes, and then
+using <code>strcpy</code> to copy the string into the destination before
+returning it.</p>
+<p>The returned string should be deallocated with
+<a href="/api/memory.html#free-string"><code>nng_strfree</code></a>, or may be deallocated using the
+<a href="/api/memory.html#deallocate-memory"><code>nng_free</code></a> using the length of the returned string plus
+one (for the <code>NUL</code> terminating byte).</p>
+<h2 id="free-string"><a class="header" href="#free-string">Free String</a></h2>
+<pre><code class="language-c">void nng_strfree(char *str);
+</code></pre>
+<p>The <a name="a006"></a><code>nng_strfree</code> function is a convenience function that
+can be used to deallocate strings allocated with <a href="/api/memory.html#duplicate-string"><code>nng_strdup</code></a>.</p>
+<p>It is effectively the same as <code>nng_free(strlen(str) + 1)</code>.</p>
+<!-- Symbol cross reference -->
+<!-- Macros -->
+<!-- Protocols -->
+<!-- Transports -->
+<!-- Concept index -->
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../api/msg.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+
+                            <a rel="next prefetch" href="../api/time.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="../api/msg.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+
+                    <a rel="next prefetch" href="../api/time.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="../elasticlunr.min.js"></script>
+        <script src="../mark.min.js"></script>
+        <script src="../searcher.js"></script>
+
+        <script src="../clipboard.min.js"></script>
+        <script src="../highlight.js"></script>
+        <script src="../book.js"></script>
+
+        <!-- Custom JS scripts -->
+        <script src="../theme/pagetoc.js"></script>
+
+
+    </div>
+    </body>
+</html>
diff --git a/ref/api/misc.html b/ref/api/misc.html
new file mode 100644
index 00000000..3968b7ff
--- /dev/null
+++ b/ref/api/misc.html
@@ -0,0 +1,350 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>Miscellaneous - NNG Reference Manual (DRAFT)</title>
+
+
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="../favicon.svg">
+        <link rel="shortcut icon" href="../favicon.png">
+        <link rel="stylesheet" href="../css/variables.css">
+        <link rel="stylesheet" href="../css/general.css">
+        <link rel="stylesheet" href="../css/chrome.css">
+        <link rel="stylesheet" href="../css/print.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="../fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="../highlight.css">
+        <link rel="stylesheet" href="../tomorrow-night.css">
+        <link rel="stylesheet" href="../ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+        <link rel="stylesheet" href="../theme/pagetoc.css">
+
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "../";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded affix "><a href="../copyright.html">Copyright</a></li><li class="chapter-item expanded affix "><a href="../dedication.html">Dedication</a></li><li class="chapter-item expanded affix "><a href="../preface.html">Preface</a></li><li class="chapter-item expanded "><a href="../api/index.html"><strong aria-hidden="true">1.</strong> API Reference</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../api/msg.html"><strong aria-hidden="true">1.1.</strong> Messages</a></li><li class="chapter-item expanded "><a href="../api/memory.html"><strong aria-hidden="true">1.2.</strong> Memory</a></li><li class="chapter-item expanded "><a href="../api/time.html"><strong aria-hidden="true">1.3.</strong> Time</a></li><li class="chapter-item expanded "><a href="../api/url.html"><strong aria-hidden="true">1.4.</strong> URLs</a></li><li class="chapter-item expanded "><a href="../api/aio.html"><strong aria-hidden="true">1.5.</strong> Asynchronous I/O</a></li><li class="chapter-item expanded "><a href="../api/synch.html"><strong aria-hidden="true">1.6.</strong> Synchronization</a></li><li class="chapter-item expanded "><a href="../api/thread.html"><strong aria-hidden="true">1.7.</strong> Threads</a></li><li class="chapter-item expanded "><a href="../api/logging.html"><strong aria-hidden="true">1.8.</strong> Logging</a></li><li class="chapter-item expanded "><a href="../api/stats.html"><strong aria-hidden="true">1.9.</strong> Statistics</a></li><li class="chapter-item expanded "><a href="../api/errors.html"><strong aria-hidden="true">1.10.</strong> Errors</a></li><li class="chapter-item expanded "><a href="../api/misc.html" class="active"><strong aria-hidden="true">1.11.</strong> Miscellaneous</a></li><li class="chapter-item expanded "><a href="../api/id_map.html"><strong aria-hidden="true">1.12.</strong> ID Map</a></li><li class="chapter-item expanded "><a href="../api/cmd_opts.html"><strong aria-hidden="true">1.13.</strong> Command Options</a></li></ol></li><li class="chapter-item expanded "><a href="../proto/index.html"><strong aria-hidden="true">2.</strong> Protocols</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../proto/bus.html"><strong aria-hidden="true">2.1.</strong> BUS Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pair.html"><strong aria-hidden="true">2.2.</strong> PAIR Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pub.html"><strong aria-hidden="true">2.3.</strong> PUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pull.html"><strong aria-hidden="true">2.4.</strong> PULL Protocol</a></li><li class="chapter-item expanded "><a href="../proto/push.html"><strong aria-hidden="true">2.5.</strong> PUSH Protocol</a></li><li class="chapter-item expanded "><a href="../proto/rep.html"><strong aria-hidden="true">2.6.</strong> REP Protocol</a></li><li class="chapter-item expanded "><a href="../proto/req.html"><strong aria-hidden="true">2.7.</strong> REQ Protocol</a></li><li class="chapter-item expanded "><a href="../proto/respondent.html"><strong aria-hidden="true">2.8.</strong> RESPONDENT Protocol</a></li><li class="chapter-item expanded "><a href="../proto/sub.html"><strong aria-hidden="true">2.9.</strong> SUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/surveyor.html"><strong aria-hidden="true">2.10.</strong> SURVEYOR Protocol</a></li></ol></li><li class="chapter-item expanded "><a href="../tran/index.html"><strong aria-hidden="true">3.</strong> Transports</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../tran/inproc.html"><strong aria-hidden="true">3.1.</strong> Intra-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/ipc.html"><strong aria-hidden="true">3.2.</strong> Inter-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/socket.html"><strong aria-hidden="true">3.3.</strong> BSD Socket (Experimental)</a></li><li class="chapter-item expanded "><a href="../tran/udp.html"><strong aria-hidden="true">3.4.</strong> UDP Transport (Experimental)</a></li></ol></li><li class="chapter-item expanded "><a href="../migrate/index.html"><strong aria-hidden="true">4.</strong> Migration Guides</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../migrate/nng1.html"><strong aria-hidden="true">4.1.</strong> Migrating from NNG 1.x</a></li><li class="chapter-item expanded "><a href="../migrate/nanomsg.html"><strong aria-hidden="true">4.2.</strong> Migrating from libnanomsg</a></li></ol></li><li class="chapter-item expanded "><a href="../indexing.html">Index</a></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
+                <div class="sidebar-resize-indicator"></div>
+            </div>
+        </nav>
+
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">NNG Reference Manual (DRAFT)</h1>
+
+                    <div class="right-buttons">
+                        <a href="../print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <style>
+.mdbook-alerts {
+  padding: 8px 16px;
+  margin-bottom: 16px;
+  border-left: 0.25em solid var(--mdbook-alerts-color);
+}
+
+.mdbook-alerts > *:first-child {
+  margin-top: 0;
+}
+
+.mdbook-alerts > *:last-child {
+  margin-bottom: 0;
+}
+
+.mdbook-alerts-title {
+  display: flex;
+  font-weight: 600;
+  align-items: center;
+  line-height: 1;
+  color: var(--mdbook-alerts-color);
+  text-transform: capitalize;
+}
+
+.mdbook-alerts-icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  margin-right: 0.2em;
+  background-color: currentColor;
+  -webkit-mask: no-repeat center / 100%;
+  mask: no-repeat center / 100%;
+  -webkit-mask-image: var(--mdbook-alerts-icon);
+  mask-image: var(--mdbook-alerts-icon);
+}
+
+.mdbook-alerts-note {
+  --mdbook-alerts-color: rgb(9, 105, 218);
+  /* https://icon-sets.iconify.design/material-symbols/info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16v-4q0-.425-.288-.712T12 11q-.425 0-.712.288T11 12v4q0 .425.288.713T12 17m0-8q.425 0 .713-.288T13 8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8q0 .425.288.713T12 9m0 13q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12q0-3.35-2.325-5.675T12 4Q8.65 4 6.325 6.325T4 12q0 3.35 2.325 5.675T12 20m0-8"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-tip {
+  --mdbook-alerts-color: rgb(26, 127, 55);
+  /* https://icon-sets.iconify.design/material-symbols/lightbulb-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 22q-.825 0-1.412-.587T10 20h4q0 .825-.587 1.413T12 22m-3-3q-.425 0-.712-.288T8 18q0-.425.288-.712T9 17h6q.425 0 .713.288T16 18q0 .425-.288.713T15 19zm-.75-3q-1.725-1.025-2.738-2.75T4.5 9.5q0-3.125 2.188-5.312T12 2q3.125 0 5.313 2.188T19.5 9.5q0 2.025-1.012 3.75T15.75 16zm.6-2h6.3q1.125-.8 1.738-1.975T17.5 9.5q0-2.3-1.6-3.9T12 4Q9.7 4 8.1 5.6T6.5 9.5q0 1.35.613 2.525T8.85 14M12 14"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-important {
+  --mdbook-alerts-color: rgb(130, 80, 223);
+  /* https://icon-sets.iconify.design/material-symbols/chat-info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 7q.425 0 .713-.288T13 6q0-.425-.288-.712T12 5q-.425 0-.712.288T11 6q0 .425.288.713T12 7m0 8q.425 0 .713-.288T13 14v-4q0-.425-.288-.712T12 9q-.425 0-.712.288T11 10v4q0 .425.288.713T12 15m-6 3l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-warning {
+  --mdbook-alerts-color: rgb(154, 103, 0);
+  /* https://icon-sets.iconify.design/material-symbols/warning-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M2.725 21q-.275 0-.5-.137t-.35-.363q-.125-.225-.137-.488t.137-.512l9.25-16q.15-.25.388-.375T12 3q.25 0 .488.125t.387.375l9.25 16q.15.25.138.513t-.138.487q-.125.225-.35.363t-.5.137zm1.725-2h15.1L12 6zM12 18q.425 0 .713-.288T13 17q0-.425-.288-.712T12 16q-.425 0-.712.288T11 17q0 .425.288.713T12 18m0-3q.425 0 .713-.288T13 14v-3q0-.425-.288-.712T12 10q-.425 0-.712.288T11 11v3q0 .425.288.713T12 15m0-2.5"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-caution {
+  --mdbook-alerts-color: rgb(207, 34, 46);
+  /* https://icon-sets.iconify.design/material-symbols/brightness-alert-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16q0-.425-.288-.712T12 15q-.425 0-.712.288T11 16q0 .425.288.713T12 17m0-4q.425 0 .713-.288T13 12V8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8v4q0 .425.288.713T12 13m-3.35 7H6q-.825 0-1.412-.587T4 18v-2.65L2.075 13.4q-.275-.3-.425-.662T1.5 12q0-.375.15-.737t.425-.663L4 8.65V6q0-.825.588-1.412T6 4h2.65l1.95-1.925q.3-.275.663-.425T12 1.5q.375 0 .738.15t.662.425L15.35 4H18q.825 0 1.413.588T20 6v2.65l1.925 1.95q.275.3.425.663t.15.737q0 .375-.15.738t-.425.662L20 15.35V18q0 .825-.587 1.413T18 20h-2.65l-1.95 1.925q-.3.275-.662.425T12 22.5q-.375 0-.737-.15t-.663-.425zm.85-2l2.5 2.5l2.5-2.5H18v-3.5l2.5-2.5L18 9.5V6h-3.5L12 3.5L9.5 6H6v3.5L3.5 12L6 14.5V18zm2.5-6"%2F%3E%3C%2Fsvg%3E');
+}
+
+</style>
+<h1 id="miscellaneous"><a class="header" href="#miscellaneous">Miscellaneous</a></h1>
+<p>This chapter discusses some interfaces that don’t really
+fit anywhere else.</p>
+<h2 id="get-random-number"><a class="header" href="#get-random-number">Get Random Number</a></h2>
+<pre><code class="language-c">uint32_t nng_random(void);
+</code></pre>
+<p>The <a name="a001"></a><code>nng_random</code> returns a <a name="a002"></a>random number.
+The value returned is suitable for use with cryptographic functions such as
+key generation, and is obtained using platform-specific cryptographically strong random
+number facilities when available.</p>
+<h2 id="create-socket-pair"><a class="header" href="#create-socket-pair">Create Socket Pair</a></h2>
+<pre><code class="language-c">int nng_socket_pair(int fds[2]);
+</code></pre>
+<p>The <code>nng_socket_pair</code> function creates a pair of connected file descriptors.
+These file descriptors, which are returned in the <em>fds</em> array, are suitable for
+use with the <a href="/tran/socket.html">Socket transport</a>.</p>
+<p>On POSIX platforms, this is a thin wrapper around the standard <code>socketpair</code> function,
+using the <a name="a003"></a><code>AF_UNIX</code> family and the <code>SOCK_STREAM</code> socket type.
+<sup><a name="to-footnote-1"><a href="#footnote-1">1</a></a></sup></p>
+<p>This will return zero on success, or an error number. On platforms that lack this
+capability, such as Windows, it will return <code>NNG_ENOTSUP</code>.</p>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  tip
+</p>
+<p>This function may be useful for creating a shared connection between a parent process and
+a child process on UNIX platforms, without requiring the processes use a shared filesystem or TCP connection.</p>
+</div>
+<h2 id="report-library-version"><a class="header" href="#report-library-version">Report Library Version</a></h2>
+<pre><code class="language-c">const char * nng_version(void);
+</code></pre>
+<p>The <a name="a004"></a><code>nng_version</code> function returns a human readable <a name="a005"></a>version number
+for <em>NNG</em>, formatted as a <code>NUL</code>-terminated string.</p>
+<p>Additionally, compile time version information is available
+via some predefined macros:</p>
+<ul>
+<li><a name="a006"></a><code>NNG_MAJOR_VERSION</code>: Major version number.</li>
+<li><a name="a007"></a><code>NNG_MINOR_VERSION</code>: Minor version number.</li>
+<li><a name="a008"></a><code>NNG_PATCH_VERSION</code>: Patch version number.</li>
+</ul>
+<p><em>NNG</em> is developed and released using
+<a href="http://www.semver.org">Semantic Versioning 2.0</a>, and
+the version numbers reported refer to both the API and the library itself.
+(The <a name="a009"></a>ABI – <a name="a010"></a>application binary interface – between the
+library and the application is controlled in a similar, but different
+manner depending upon the link options and how the library is built.)</p>
+<!-- Symbol cross reference -->
+<!-- Macros -->
+<!-- Protocols -->
+<!-- Transports -->
+<!-- Concept index -->
+<p><hr/>
+<p><a name="footnote-1"><a href="#to-footnote-1">1</a></a>: At present only POSIX platforms implementing <code>socketpair</code> support this function.</p>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../api/errors.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+
+                            <a rel="next prefetch" href="../api/id_map.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="../api/errors.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+
+                    <a rel="next prefetch" href="../api/id_map.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="../elasticlunr.min.js"></script>
+        <script src="../mark.min.js"></script>
+        <script src="../searcher.js"></script>
+
+        <script src="../clipboard.min.js"></script>
+        <script src="../highlight.js"></script>
+        <script src="../book.js"></script>
+
+        <!-- Custom JS scripts -->
+        <script src="../theme/pagetoc.js"></script>
+
+
+    </div>
+    </body>
+</html>
diff --git a/ref/api/msg.html b/ref/api/msg.html
new file mode 100644
index 00000000..ff9a1cad
--- /dev/null
+++ b/ref/api/msg.html
@@ -0,0 +1,511 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>Messages - NNG Reference Manual (DRAFT)</title>
+
+
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="../favicon.svg">
+        <link rel="shortcut icon" href="../favicon.png">
+        <link rel="stylesheet" href="../css/variables.css">
+        <link rel="stylesheet" href="../css/general.css">
+        <link rel="stylesheet" href="../css/chrome.css">
+        <link rel="stylesheet" href="../css/print.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="../fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="../highlight.css">
+        <link rel="stylesheet" href="../tomorrow-night.css">
+        <link rel="stylesheet" href="../ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+        <link rel="stylesheet" href="../theme/pagetoc.css">
+
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "../";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded affix "><a href="../copyright.html">Copyright</a></li><li class="chapter-item expanded affix "><a href="../dedication.html">Dedication</a></li><li class="chapter-item expanded affix "><a href="../preface.html">Preface</a></li><li class="chapter-item expanded "><a href="../api/index.html"><strong aria-hidden="true">1.</strong> API Reference</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../api/msg.html" class="active"><strong aria-hidden="true">1.1.</strong> Messages</a></li><li class="chapter-item expanded "><a href="../api/memory.html"><strong aria-hidden="true">1.2.</strong> Memory</a></li><li class="chapter-item expanded "><a href="../api/time.html"><strong aria-hidden="true">1.3.</strong> Time</a></li><li class="chapter-item expanded "><a href="../api/url.html"><strong aria-hidden="true">1.4.</strong> URLs</a></li><li class="chapter-item expanded "><a href="../api/aio.html"><strong aria-hidden="true">1.5.</strong> Asynchronous I/O</a></li><li class="chapter-item expanded "><a href="../api/synch.html"><strong aria-hidden="true">1.6.</strong> Synchronization</a></li><li class="chapter-item expanded "><a href="../api/thread.html"><strong aria-hidden="true">1.7.</strong> Threads</a></li><li class="chapter-item expanded "><a href="../api/logging.html"><strong aria-hidden="true">1.8.</strong> Logging</a></li><li class="chapter-item expanded "><a href="../api/stats.html"><strong aria-hidden="true">1.9.</strong> Statistics</a></li><li class="chapter-item expanded "><a href="../api/errors.html"><strong aria-hidden="true">1.10.</strong> Errors</a></li><li class="chapter-item expanded "><a href="../api/misc.html"><strong aria-hidden="true">1.11.</strong> Miscellaneous</a></li><li class="chapter-item expanded "><a href="../api/id_map.html"><strong aria-hidden="true">1.12.</strong> ID Map</a></li><li class="chapter-item expanded "><a href="../api/cmd_opts.html"><strong aria-hidden="true">1.13.</strong> Command Options</a></li></ol></li><li class="chapter-item expanded "><a href="../proto/index.html"><strong aria-hidden="true">2.</strong> Protocols</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../proto/bus.html"><strong aria-hidden="true">2.1.</strong> BUS Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pair.html"><strong aria-hidden="true">2.2.</strong> PAIR Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pub.html"><strong aria-hidden="true">2.3.</strong> PUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pull.html"><strong aria-hidden="true">2.4.</strong> PULL Protocol</a></li><li class="chapter-item expanded "><a href="../proto/push.html"><strong aria-hidden="true">2.5.</strong> PUSH Protocol</a></li><li class="chapter-item expanded "><a href="../proto/rep.html"><strong aria-hidden="true">2.6.</strong> REP Protocol</a></li><li class="chapter-item expanded "><a href="../proto/req.html"><strong aria-hidden="true">2.7.</strong> REQ Protocol</a></li><li class="chapter-item expanded "><a href="../proto/respondent.html"><strong aria-hidden="true">2.8.</strong> RESPONDENT Protocol</a></li><li class="chapter-item expanded "><a href="../proto/sub.html"><strong aria-hidden="true">2.9.</strong> SUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/surveyor.html"><strong aria-hidden="true">2.10.</strong> SURVEYOR Protocol</a></li></ol></li><li class="chapter-item expanded "><a href="../tran/index.html"><strong aria-hidden="true">3.</strong> Transports</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../tran/inproc.html"><strong aria-hidden="true">3.1.</strong> Intra-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/ipc.html"><strong aria-hidden="true">3.2.</strong> Inter-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/socket.html"><strong aria-hidden="true">3.3.</strong> BSD Socket (Experimental)</a></li><li class="chapter-item expanded "><a href="../tran/udp.html"><strong aria-hidden="true">3.4.</strong> UDP Transport (Experimental)</a></li></ol></li><li class="chapter-item expanded "><a href="../migrate/index.html"><strong aria-hidden="true">4.</strong> Migration Guides</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../migrate/nng1.html"><strong aria-hidden="true">4.1.</strong> Migrating from NNG 1.x</a></li><li class="chapter-item expanded "><a href="../migrate/nanomsg.html"><strong aria-hidden="true">4.2.</strong> Migrating from libnanomsg</a></li></ol></li><li class="chapter-item expanded "><a href="../indexing.html">Index</a></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
+                <div class="sidebar-resize-indicator"></div>
+            </div>
+        </nav>
+
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">NNG Reference Manual (DRAFT)</h1>
+
+                    <div class="right-buttons">
+                        <a href="../print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <style>
+.mdbook-alerts {
+  padding: 8px 16px;
+  margin-bottom: 16px;
+  border-left: 0.25em solid var(--mdbook-alerts-color);
+}
+
+.mdbook-alerts > *:first-child {
+  margin-top: 0;
+}
+
+.mdbook-alerts > *:last-child {
+  margin-bottom: 0;
+}
+
+.mdbook-alerts-title {
+  display: flex;
+  font-weight: 600;
+  align-items: center;
+  line-height: 1;
+  color: var(--mdbook-alerts-color);
+  text-transform: capitalize;
+}
+
+.mdbook-alerts-icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  margin-right: 0.2em;
+  background-color: currentColor;
+  -webkit-mask: no-repeat center / 100%;
+  mask: no-repeat center / 100%;
+  -webkit-mask-image: var(--mdbook-alerts-icon);
+  mask-image: var(--mdbook-alerts-icon);
+}
+
+.mdbook-alerts-note {
+  --mdbook-alerts-color: rgb(9, 105, 218);
+  /* https://icon-sets.iconify.design/material-symbols/info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16v-4q0-.425-.288-.712T12 11q-.425 0-.712.288T11 12v4q0 .425.288.713T12 17m0-8q.425 0 .713-.288T13 8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8q0 .425.288.713T12 9m0 13q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12q0-3.35-2.325-5.675T12 4Q8.65 4 6.325 6.325T4 12q0 3.35 2.325 5.675T12 20m0-8"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-tip {
+  --mdbook-alerts-color: rgb(26, 127, 55);
+  /* https://icon-sets.iconify.design/material-symbols/lightbulb-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 22q-.825 0-1.412-.587T10 20h4q0 .825-.587 1.413T12 22m-3-3q-.425 0-.712-.288T8 18q0-.425.288-.712T9 17h6q.425 0 .713.288T16 18q0 .425-.288.713T15 19zm-.75-3q-1.725-1.025-2.738-2.75T4.5 9.5q0-3.125 2.188-5.312T12 2q3.125 0 5.313 2.188T19.5 9.5q0 2.025-1.012 3.75T15.75 16zm.6-2h6.3q1.125-.8 1.738-1.975T17.5 9.5q0-2.3-1.6-3.9T12 4Q9.7 4 8.1 5.6T6.5 9.5q0 1.35.613 2.525T8.85 14M12 14"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-important {
+  --mdbook-alerts-color: rgb(130, 80, 223);
+  /* https://icon-sets.iconify.design/material-symbols/chat-info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 7q.425 0 .713-.288T13 6q0-.425-.288-.712T12 5q-.425 0-.712.288T11 6q0 .425.288.713T12 7m0 8q.425 0 .713-.288T13 14v-4q0-.425-.288-.712T12 9q-.425 0-.712.288T11 10v4q0 .425.288.713T12 15m-6 3l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-warning {
+  --mdbook-alerts-color: rgb(154, 103, 0);
+  /* https://icon-sets.iconify.design/material-symbols/warning-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M2.725 21q-.275 0-.5-.137t-.35-.363q-.125-.225-.137-.488t.137-.512l9.25-16q.15-.25.388-.375T12 3q.25 0 .488.125t.387.375l9.25 16q.15.25.138.513t-.138.487q-.125.225-.35.363t-.5.137zm1.725-2h15.1L12 6zM12 18q.425 0 .713-.288T13 17q0-.425-.288-.712T12 16q-.425 0-.712.288T11 17q0 .425.288.713T12 18m0-3q.425 0 .713-.288T13 14v-3q0-.425-.288-.712T12 10q-.425 0-.712.288T11 11v3q0 .425.288.713T12 15m0-2.5"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-caution {
+  --mdbook-alerts-color: rgb(207, 34, 46);
+  /* https://icon-sets.iconify.design/material-symbols/brightness-alert-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16q0-.425-.288-.712T12 15q-.425 0-.712.288T11 16q0 .425.288.713T12 17m0-4q.425 0 .713-.288T13 12V8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8v4q0 .425.288.713T12 13m-3.35 7H6q-.825 0-1.412-.587T4 18v-2.65L2.075 13.4q-.275-.3-.425-.662T1.5 12q0-.375.15-.737t.425-.663L4 8.65V6q0-.825.588-1.412T6 4h2.65l1.95-1.925q.3-.275.663-.425T12 1.5q.375 0 .738.15t.662.425L15.35 4H18q.825 0 1.413.588T20 6v2.65l1.925 1.95q.275.3.425.663t.15.737q0 .375-.15.738t-.425.662L20 15.35V18q0 .825-.587 1.413T18 20h-2.65l-1.95 1.925q-.3.275-.662.425T12 22.5q-.375 0-.737-.15t-.663-.425zm.85-2l2.5 2.5l2.5-2.5H18v-3.5l2.5-2.5L18 9.5V6h-3.5L12 3.5L9.5 6H6v3.5L3.5 12L6 14.5V18zm2.5-6"%2F%3E%3C%2Fsvg%3E');
+}
+
+</style>
+<h1 id="messages"><a class="header" href="#messages">Messages</a></h1>
+<p>Messages <a name="a001"></a> in Scalability Protocols are the fundamental unit of
+transmission and reception, as these protocols are fundamentally message-oriented.</p>
+<p>Messages have a [body][nng_msg_body]<a name="a002"></a>, containing the application-supplied
+payload, and a [header][nng_msg_header]<a name="a003"></a>, containing protocol specific routing and similar
+related information.</p>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  tip
+</p>
+<p>Only applications using <a href="/TODO.html">raw mode</a> need to access the message header.
+Very few <em>NNG</em> applications do this.</p>
+</div>
+<h2 id="message-structure"><a class="header" href="#message-structure">Message Structure</a></h2>
+<pre><code class="language-c">typedef struct nng_msg nng_msg;
+</code></pre>
+<p>The <a name="a004"></a><code>nng_msg</code> structure represents a single message. It carries a body
+and a header.</p>
+<h3 id="create-a-message"><a class="header" href="#create-a-message">Create a Message</a></h3>
+<pre><code class="language-c">int nng_msg_alloc(nng_msg **msgp, size_t size);
+</code></pre>
+<p>The <a name="a005"></a><code>nng_msg_alloc</code> function allocates a new message.
+It takes a <em>size</em> argument, and returns a message
+with a preallocated body of that size in the <em>msgp</em> parameter.</p>
+<p>If it succeeds, it returns zero, otherwise this function may return <a href="/api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>,
+indicating that insufficient memory is available to allocate a new message.</p>
+<h3 id="destroy-a-message"><a class="header" href="#destroy-a-message">Destroy a Message</a></h3>
+<pre><code class="language-c">void nng_msg_free(nng_msg *msg);
+</code></pre>
+<p>The <a name="a006"></a><code>nng_msg_free</code> function deallocates a message.</p>
+<h3 id="duplicate-a-message"><a class="header" href="#duplicate-a-message">Duplicate a Message</a></h3>
+<pre><code class="language-c">int nng_msg_dup(nng_msg **dup, nng_msg *msg);
+</code></pre>
+<p>The <a name="a007"></a><code>nng_msg_dup</code> function duplicates the message <em>msg</em>, storing a pointer
+to the new duplicate in <em>dup</em>. This function also returns zero on succes, or <a href="/api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>
+if memory is exhausted.</p>
+<h2 id="message-size-and-capacity"><a class="header" href="#message-size-and-capacity">Message Size and Capacity</a></h2>
+<pre><code class="language-c">size_t nng_msg_capacity(nng_msg *msg);
+int nng_msg_realloc(nng_msg *msg, size_t size);
+int nng_msg_reserve(nng_msg *msg, size_t capacity);
+</code></pre>
+<p>Messages have a certain amount of pre-reserved space, which may exceed the total
+size of the message. This allows for content to be added to the message later,
+without necessarily performing a reallocation.</p>
+<p>The <a name="a008"></a><code>nng_msg_capacity</code> function returns the amount of prereserved space.
+If a message size change is required, and the new size will fit within the capacity
+reported by this function, then change will be done without a reallocation, and
+likely without a data copy as well.</p>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  tip
+</p>
+<p>The capacity reported by <code>nng_msg_capacity</code> may not include reserved headroom, which
+is present to allow a very limited amount of content to be inserted in front of the
+message without requiring the rest of the message to be copied.</p>
+</div>
+<p>The message size may be changed by use of the <a name="a009"></a><code>nng_msg_realloc</code> function. This
+function will reallocate the underlying memory for the message <em>msg</em>,
+preserving contents while doing so.
+If the new size is smaller than the original message, it will
+truncate the message, but not perform any allocations.
+If reallocation fails due to insufficient memory, then the original is left intact.</p>
+<p>The <a name="a010"></a><code>nng_msg_reserve</code> function ensures that the total message capacity
+is at least <em>capacity</em> bytes. Use of this function to ensure the total anticipated
+capacity is present in the message may help prevent many small allocations.</p>
+<p>Both <code>nng_msg_realloc</code> and <code>nng_msg_reserve</code> return zero on success, or may return
+<a href="/api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a> if insufficient memory exists to preform allocation.</p>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
+<p>Any pointers to message content obtained before a call to <code>nng_msg_realloc</code> or
+<code>nng_msg_reserve</code> (or any other function that changes the message size) should be
+treated as invalid, as the locations pointed to may be deallocated by these functions.</p>
+</div>
+<h2 id="message-body"><a class="header" href="#message-body">Message Body</a></h2>
+<pre><code class="language-c">void *nng_msg_body(nng_msg *msg);
+size_t nng_msg_len(nng_msg *msg);
+</code></pre>
+<p>The body and body length of <em>msg</em> are returned by <a name="a011"></a><code>nng_msg_body</code> and
+<a name="a012"></a><code>nng_msg_len</code>, respectively.</p>
+<h3 id="clear-the-body"><a class="header" href="#clear-the-body">Clear the Body</a></h3>
+<pre><code class="language-c">void *nng_msg_clear(nng_msg *msg);
+</code></pre>
+<p>The <a name="a013"></a><code>nng_msg_clear</code> simply resets the total message body length to zero, but does
+not affect the capacity. It does not change the underlying bytes of the message.</p>
+<h3 id="add-to-body"><a class="header" href="#add-to-body">Add to Body</a></h3>
+<pre><code class="language-c">int nng_msg_append(nng_msg *msg, const void *val, size_t size);
+int nng_msg_append_u16(nng_msg *msg, uint16_t val16);
+int nng_msg_append_u32(nng_msg *msg, uint32_t val32);
+int nng_msg_append_u64(nng_msg *msg, uint64_t val64);
+
+int nng_msg_insert(nng_msg *msg, const void *val, size_t size);
+int nng_msg_insert_u16(nng_msg *msg, uint16_t val16);
+int nng_msg_insert_u32(nng_msg *msg, uint32_t val32);
+int nng_msg_insert_u64(nng_msg *msg, uint64_t val64);
+</code></pre>
+<p>Appending data to a message body is done by using the <a name="a014"></a><code>nng_msg_append</code> functions.
+The base <code>nng_msg_append</code> function appends <em>size</em> bytes of untyped data to the end of the
+message.</p>
+<p>Use of the typed versions, ending in suffixes <code>_u16</code>, <code>_u32</code>, and <code>_u64</code> allows
+for unsigned integers to be appended directly. The integers are encoded in network byte order, with
+the most significant byte appearing first. The message body will by two, four, or eight
+bytes accordingly.</p>
+<p>Data may inserted before the rest of the message body by using the <a name="a015"></a><code>nng_msg_insert</code> functions.
+This will attempt to use “headroom” in the message to avoid a data copy.
+Otherwise they are like the <code>nng_msg_append</code> functions except that the put the data in front
+of the messages instead of at the end.</p>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  tip
+</p>
+<p>Message headroom is limited, so <code>nng_msg_insert</code> is best used sparingly.
+It is much more efficient to build the message content from start to end
+using <code>nng_msg_append</code>.</p>
+</div>
+<h3 id="consume-from-body"><a class="header" href="#consume-from-body">Consume From Body</a></h3>
+<pre><code class="language-c">int nng_msg_chop(nng_msg *msg, size_t size);
+int nng_msg_chop_u16(nng_msg *msg, uint16_t *val16);
+int nng_msg_chop_u32(nng_msg *msg, uint32_t *val32);
+int nng_msg_chop_u64(nng_msg *msg, uint64_t *val64);
+
+int nng_msg_trim(nng_msg *msg, size_t size);
+int nng_msg_trim_u16(nng_msg *msg, uint16_t *val16);
+int nng_msg_trim_u32(nng_msg *msg, uint32_t *val32);
+int nng_msg_trim_u64(nng_msg *msg, uint64_t *val64);
+</code></pre>
+<p>The <a name="a016"></a><code>nng_msg_chop</code> functions remove data from the end of the body of message <em>msg</em>,
+reducing the message length by either <em>size</em>, or the appropriate value size.</p>
+<p>The <a name="a017"></a><code>nng_msg_trim</code> functions remove data from the beginning of the message body of <em>msg</em>.
+but are otherwise just like the <code>nng_msg_chop</code> functions.</p>
+<p>If the message is not big enough to remove requisite amount of bytes, these functions
+return <code>NNG_EINVAL</code>. Otherwise they return zero.</p>
+<p>Additionally, functions with typed suffixes (<code>_u16</code>, <code>_u32</code>, <code>_u64</code>) decode the data and return it
+through the appropriate <em>val</em> pointer.</p>
+<p>The data is assumed to have been in network byte order in the message, but is returned in
+the native machine byte order. The appropriate number of bytes is consumed for each of these types,
+so two bytes for <code>_u16</code>, four bytes for <code>_u32</code>, and eight bytes for <code>_u64</code>.</p>
+<h2 id="message-header"><a class="header" href="#message-header">Message Header</a></h2>
+<pre><code class="language-c">void *nng_msg_header(nng_msg *msg);
+size_t nng_msg_header_len(nng_msg *msg);
+</code></pre>
+<p>The header and header length of <em>msg</em> are returned by <a name="a018"></a><code>nng_msg_header</code> and
+<a name="a019"></a><code>nng_msg_header_len</code>, respectively.</p>
+<p>The message headers are generally intended for limited use, to store protocol headers.</p>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
+<p>The message headers are for protocol and transport headers, and not for general
+application payloads. Misuse of the header may prevent the application from functioning
+properly.</p>
+</div>
+<h3 id="clear-the-header"><a class="header" href="#clear-the-header">Clear the Header</a></h3>
+<pre><code class="language-c">void *nng_msg_header_clear(nng_msg *msg);
+</code></pre>
+<p>The <a name="a020"></a><code>nng_msg_header_clear</code> simply resets the total message header length to zero.</p>
+<h3 id="append-or-insert-header"><a class="header" href="#append-or-insert-header">Append or Insert Header</a></h3>
+<p>Appending data to a message header is done by using the <a name="a021"></a><code>nng_msg_header_append</code> functions,
+and inserting data in the header is done using the <a name="a022"></a><code>nng_msg_header_insert</code> functions.</p>
+<p>These functions act just like the <a href="/api/msg.html#add-to-body"><code>nng_msg_append</code></a> and <a href="/api/msg.html#add-to-body"><code>nng_msg_insert</code></a> functions,
+except that they operate on the message header rather than the message body.</p>
+<h3 id="consume-from-header"><a class="header" href="#consume-from-header">Consume from Header</a></h3>
+<p>The <a name="a023"></a><code>nng_msg_header_trim</code> functions remove data from the beginning of the message header,
+and the <a name="a024"></a><code>nng_msg_header_chop</code> functions remove data from the end of the message header.</p>
+<p>These functions act just like the <a href="/api/msg.html#consume-from-body"><code>nng_msg_trim</code></a> and <a href="/api/msg.html#consume-from-body"><code>nng_msg_chop</code></a> functions,
+except that they operate the message header rather than the message body.</p>
+<h2 id="message-pipe"><a class="header" href="#message-pipe">Message Pipe</a></h2>
+<pre><code class="language-c">nng_pipe nng_msg_get_pipe(nng_msg *msg);
+void nng_msg_get_pipe(nng_msg *msg, nng_pipe p);
+</code></pre>
+<p>The <a name="a025"></a><code>nng_msg_set_pipe</code> function sets the <a href="/TODO.html">pipe</a> associated with <em>msg</em> to <em>p</em>.
+This is most often useful when used with protocols that support directing
+a message to a specific peer.
+For example the <a href="/proto/pair.html"><em>PAIR</em></a> version 1 protocol can do
+this when <code>NNG_OPT_PAIR1_POLY</code> mode is set.</p>
+<p>The <a name="a026"></a><code>nng_msg_get_pipe</code> function returns the pipe that was previously set on the message <em>m</em>,
+either directly by the application, or when the message was received by the protocol.</p>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  note
+</p>
+<p>Not all protocols support overriding the destination pipe.</p>
+</div>
+<h2 id="examples"><a class="header" href="#examples">Examples</a></h2>
+<h3 id="example-1-preparing-a-message-for-use"><a class="header" href="#example-1-preparing-a-message-for-use">Example 1: Preparing a message for use</a></h3>
+<pre><code class="language-c">    #include &lt;nng/nng.h&gt;
+
+    nng_msg *m;
+    if (nng_msg_alloc(&amp;m, strlen("content") + 1) != 0) {
+       // handle error
+    }
+    strcpy(nng_msg_body(m), "content");
+</code></pre>
+<h3 id="example-2-preallocating-message-content"><a class="header" href="#example-2-preallocating-message-content">Example 2: Preallocating message content</a></h3>
+<pre><code class="language-c">    if (nng_msg_alloc(&amp;m, 1024) != 0) {
+        // handle error
+    }
+    while ((val64 = next_datum()) != 0) P
+        if (nng_msg_append_u64(m, val64) != 0) {
+            // handle error
+        }
+    }
+</code></pre>
+<!-- Symbol cross reference -->
+<!-- Macros -->
+<!-- Protocols -->
+<!-- Transports -->
+<!-- Concept index -->
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../api/index.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+
+                            <a rel="next prefetch" href="../api/memory.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="../api/index.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+
+                    <a rel="next prefetch" href="../api/memory.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="../elasticlunr.min.js"></script>
+        <script src="../mark.min.js"></script>
+        <script src="../searcher.js"></script>
+
+        <script src="../clipboard.min.js"></script>
+        <script src="../highlight.js"></script>
+        <script src="../book.js"></script>
+
+        <!-- Custom JS scripts -->
+        <script src="../theme/pagetoc.js"></script>
+
+
+    </div>
+    </body>
+</html>
diff --git a/ref/api/stats.html b/ref/api/stats.html
new file mode 100644
index 00000000..6c483ac6
--- /dev/null
+++ b/ref/api/stats.html
@@ -0,0 +1,471 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>Statistics - NNG Reference Manual (DRAFT)</title>
+
+
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="../favicon.svg">
+        <link rel="shortcut icon" href="../favicon.png">
+        <link rel="stylesheet" href="../css/variables.css">
+        <link rel="stylesheet" href="../css/general.css">
+        <link rel="stylesheet" href="../css/chrome.css">
+        <link rel="stylesheet" href="../css/print.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="../fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="../highlight.css">
+        <link rel="stylesheet" href="../tomorrow-night.css">
+        <link rel="stylesheet" href="../ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+        <link rel="stylesheet" href="../theme/pagetoc.css">
+
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "../";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded affix "><a href="../copyright.html">Copyright</a></li><li class="chapter-item expanded affix "><a href="../dedication.html">Dedication</a></li><li class="chapter-item expanded affix "><a href="../preface.html">Preface</a></li><li class="chapter-item expanded "><a href="../api/index.html"><strong aria-hidden="true">1.</strong> API Reference</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../api/msg.html"><strong aria-hidden="true">1.1.</strong> Messages</a></li><li class="chapter-item expanded "><a href="../api/memory.html"><strong aria-hidden="true">1.2.</strong> Memory</a></li><li class="chapter-item expanded "><a href="../api/time.html"><strong aria-hidden="true">1.3.</strong> Time</a></li><li class="chapter-item expanded "><a href="../api/url.html"><strong aria-hidden="true">1.4.</strong> URLs</a></li><li class="chapter-item expanded "><a href="../api/aio.html"><strong aria-hidden="true">1.5.</strong> Asynchronous I/O</a></li><li class="chapter-item expanded "><a href="../api/synch.html"><strong aria-hidden="true">1.6.</strong> Synchronization</a></li><li class="chapter-item expanded "><a href="../api/thread.html"><strong aria-hidden="true">1.7.</strong> Threads</a></li><li class="chapter-item expanded "><a href="../api/logging.html"><strong aria-hidden="true">1.8.</strong> Logging</a></li><li class="chapter-item expanded "><a href="../api/stats.html" class="active"><strong aria-hidden="true">1.9.</strong> Statistics</a></li><li class="chapter-item expanded "><a href="../api/errors.html"><strong aria-hidden="true">1.10.</strong> Errors</a></li><li class="chapter-item expanded "><a href="../api/misc.html"><strong aria-hidden="true">1.11.</strong> Miscellaneous</a></li><li class="chapter-item expanded "><a href="../api/id_map.html"><strong aria-hidden="true">1.12.</strong> ID Map</a></li><li class="chapter-item expanded "><a href="../api/cmd_opts.html"><strong aria-hidden="true">1.13.</strong> Command Options</a></li></ol></li><li class="chapter-item expanded "><a href="../proto/index.html"><strong aria-hidden="true">2.</strong> Protocols</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../proto/bus.html"><strong aria-hidden="true">2.1.</strong> BUS Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pair.html"><strong aria-hidden="true">2.2.</strong> PAIR Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pub.html"><strong aria-hidden="true">2.3.</strong> PUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pull.html"><strong aria-hidden="true">2.4.</strong> PULL Protocol</a></li><li class="chapter-item expanded "><a href="../proto/push.html"><strong aria-hidden="true">2.5.</strong> PUSH Protocol</a></li><li class="chapter-item expanded "><a href="../proto/rep.html"><strong aria-hidden="true">2.6.</strong> REP Protocol</a></li><li class="chapter-item expanded "><a href="../proto/req.html"><strong aria-hidden="true">2.7.</strong> REQ Protocol</a></li><li class="chapter-item expanded "><a href="../proto/respondent.html"><strong aria-hidden="true">2.8.</strong> RESPONDENT Protocol</a></li><li class="chapter-item expanded "><a href="../proto/sub.html"><strong aria-hidden="true">2.9.</strong> SUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/surveyor.html"><strong aria-hidden="true">2.10.</strong> SURVEYOR Protocol</a></li></ol></li><li class="chapter-item expanded "><a href="../tran/index.html"><strong aria-hidden="true">3.</strong> Transports</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../tran/inproc.html"><strong aria-hidden="true">3.1.</strong> Intra-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/ipc.html"><strong aria-hidden="true">3.2.</strong> Inter-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/socket.html"><strong aria-hidden="true">3.3.</strong> BSD Socket (Experimental)</a></li><li class="chapter-item expanded "><a href="../tran/udp.html"><strong aria-hidden="true">3.4.</strong> UDP Transport (Experimental)</a></li></ol></li><li class="chapter-item expanded "><a href="../migrate/index.html"><strong aria-hidden="true">4.</strong> Migration Guides</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../migrate/nng1.html"><strong aria-hidden="true">4.1.</strong> Migrating from NNG 1.x</a></li><li class="chapter-item expanded "><a href="../migrate/nanomsg.html"><strong aria-hidden="true">4.2.</strong> Migrating from libnanomsg</a></li></ol></li><li class="chapter-item expanded "><a href="../indexing.html">Index</a></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
+                <div class="sidebar-resize-indicator"></div>
+            </div>
+        </nav>
+
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">NNG Reference Manual (DRAFT)</h1>
+
+                    <div class="right-buttons">
+                        <a href="../print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <style>
+.mdbook-alerts {
+  padding: 8px 16px;
+  margin-bottom: 16px;
+  border-left: 0.25em solid var(--mdbook-alerts-color);
+}
+
+.mdbook-alerts > *:first-child {
+  margin-top: 0;
+}
+
+.mdbook-alerts > *:last-child {
+  margin-bottom: 0;
+}
+
+.mdbook-alerts-title {
+  display: flex;
+  font-weight: 600;
+  align-items: center;
+  line-height: 1;
+  color: var(--mdbook-alerts-color);
+  text-transform: capitalize;
+}
+
+.mdbook-alerts-icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  margin-right: 0.2em;
+  background-color: currentColor;
+  -webkit-mask: no-repeat center / 100%;
+  mask: no-repeat center / 100%;
+  -webkit-mask-image: var(--mdbook-alerts-icon);
+  mask-image: var(--mdbook-alerts-icon);
+}
+
+.mdbook-alerts-note {
+  --mdbook-alerts-color: rgb(9, 105, 218);
+  /* https://icon-sets.iconify.design/material-symbols/info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16v-4q0-.425-.288-.712T12 11q-.425 0-.712.288T11 12v4q0 .425.288.713T12 17m0-8q.425 0 .713-.288T13 8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8q0 .425.288.713T12 9m0 13q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12q0-3.35-2.325-5.675T12 4Q8.65 4 6.325 6.325T4 12q0 3.35 2.325 5.675T12 20m0-8"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-tip {
+  --mdbook-alerts-color: rgb(26, 127, 55);
+  /* https://icon-sets.iconify.design/material-symbols/lightbulb-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 22q-.825 0-1.412-.587T10 20h4q0 .825-.587 1.413T12 22m-3-3q-.425 0-.712-.288T8 18q0-.425.288-.712T9 17h6q.425 0 .713.288T16 18q0 .425-.288.713T15 19zm-.75-3q-1.725-1.025-2.738-2.75T4.5 9.5q0-3.125 2.188-5.312T12 2q3.125 0 5.313 2.188T19.5 9.5q0 2.025-1.012 3.75T15.75 16zm.6-2h6.3q1.125-.8 1.738-1.975T17.5 9.5q0-2.3-1.6-3.9T12 4Q9.7 4 8.1 5.6T6.5 9.5q0 1.35.613 2.525T8.85 14M12 14"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-important {
+  --mdbook-alerts-color: rgb(130, 80, 223);
+  /* https://icon-sets.iconify.design/material-symbols/chat-info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 7q.425 0 .713-.288T13 6q0-.425-.288-.712T12 5q-.425 0-.712.288T11 6q0 .425.288.713T12 7m0 8q.425 0 .713-.288T13 14v-4q0-.425-.288-.712T12 9q-.425 0-.712.288T11 10v4q0 .425.288.713T12 15m-6 3l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-warning {
+  --mdbook-alerts-color: rgb(154, 103, 0);
+  /* https://icon-sets.iconify.design/material-symbols/warning-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M2.725 21q-.275 0-.5-.137t-.35-.363q-.125-.225-.137-.488t.137-.512l9.25-16q.15-.25.388-.375T12 3q.25 0 .488.125t.387.375l9.25 16q.15.25.138.513t-.138.487q-.125.225-.35.363t-.5.137zm1.725-2h15.1L12 6zM12 18q.425 0 .713-.288T13 17q0-.425-.288-.712T12 16q-.425 0-.712.288T11 17q0 .425.288.713T12 18m0-3q.425 0 .713-.288T13 14v-3q0-.425-.288-.712T12 10q-.425 0-.712.288T11 11v3q0 .425.288.713T12 15m0-2.5"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-caution {
+  --mdbook-alerts-color: rgb(207, 34, 46);
+  /* https://icon-sets.iconify.design/material-symbols/brightness-alert-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16q0-.425-.288-.712T12 15q-.425 0-.712.288T11 16q0 .425.288.713T12 17m0-4q.425 0 .713-.288T13 12V8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8v4q0 .425.288.713T12 13m-3.35 7H6q-.825 0-1.412-.587T4 18v-2.65L2.075 13.4q-.275-.3-.425-.662T1.5 12q0-.375.15-.737t.425-.663L4 8.65V6q0-.825.588-1.412T6 4h2.65l1.95-1.925q.3-.275.663-.425T12 1.5q.375 0 .738.15t.662.425L15.35 4H18q.825 0 1.413.588T20 6v2.65l1.925 1.95q.275.3.425.663t.15.737q0 .375-.15.738t-.425.662L20 15.35V18q0 .825-.587 1.413T18 20h-2.65l-1.95 1.925q-.3.275-.662.425T12 22.5q-.375 0-.737-.15t-.663-.425zm.85-2l2.5 2.5l2.5-2.5H18v-3.5l2.5-2.5L18 9.5V6h-3.5L12 3.5L9.5 6H6v3.5L3.5 12L6 14.5V18zm2.5-6"%2F%3E%3C%2Fsvg%3E');
+}
+
+</style>
+<h1 id="statistics"><a class="header" href="#statistics">Statistics</a></h1>
+<p>To facilitate debugging and support situations, the <em>NNG</em> library
+provides for collection and reporting of numerous <a name="a001"></a>statistics.</p>
+<p>These statistics are organized in a tree, and include both values,
+and metadata describing the statistics. In order to be efficient and
+minimize the impact of maintaining statistics, an explicit snapshot
+of statistics must be taken, and that snapshot can then be processed.</p>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  note
+</p>
+<p>Statistics may be disabled by build-time configuration options,
+in order to reduce program size and run-time overheads.</p>
+</div>
+<h2 id="statistic-structure"><a class="header" href="#statistic-structure">Statistic Structure</a></h2>
+<pre><code class="language-c">typedef struct nng_stat nng_stat;
+</code></pre>
+<p>The <a name="a002"></a><code>nng_stat</code> structure represents a statistic, which is a single value
+collected at a specific point in time.</p>
+<p>This structure has meta-data describing the value, the value itself, and links
+to any sibling or child statistics.</p>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  note
+</p>
+<p>The presence, name, and semantics of any given statistic are
+subject to change at any time and without notice.</p>
+</div>
+<h2 id="collecting-a-snapshot"><a class="header" href="#collecting-a-snapshot">Collecting a Snapshot</a></h2>
+<pre><code class="language-c">int nng_stats_get(nng_stat **statsp);
+</code></pre>
+<p>The <a name="a003"></a><code>nng_stats_get</code> function takes a snapshot of the statistics for
+the system and returns it through the pointer <em>statsp</em>.
+This function may return <a href="/api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a> if memory is exhausted, or <a href="/api/errors.html#NNG_ENOTSUP"><code>NNG_ENOTSUP</code></a> if the statistics
+support is not enabled in the build, but is otherwise expected to return zero.</p>
+<h2 id="freeing-a-snapshot"><a class="header" href="#freeing-a-snapshot">Freeing a Snapshot</a></h2>
+<pre><code class="language-c">void nng_stats_free(nng_stat *stat);
+</code></pre>
+<p>The <a name="a004"></a><code>nng_stats_free</code> function deallocates the snapshot referenced by <em>stat</em>.</p>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
+<p>The <em>stat</em> must be root of the statistics tree, i.e. the value that was returned
+through <em>statsp</em> using the function <code>nng_stats_get</code>.</p>
+</div>
+<h2 id="traversing-the-tree"><a class="header" href="#traversing-the-tree">Traversing the Tree</a></h2>
+<pre><code class="language-c">const nng_stat *nng_stat_child(const nng_stat *stat);
+const nng_stat *nng_stat_next(const nng_stat *stat);
+</code></pre>
+<p>Traversing the tree of statistics is done using the <a name="a005"></a><code>nng_stat_child</code> and
+<a name="a006"></a><code>nng_stat_next</code> functions.</p>
+<p>The <code>nng_stat_child</code> function returns either the first child of <em>stat</em>,
+or <code>NULL</code> if the <em>stat</em> has no children.</p>
+<p>The <code>nng_stat_next</code> function returns the nearest sibling to the right of <em>stat</em>,
+or <code>NULL</code> if <em>stat</em> has no more siblings to the right.</p>
+<h2 id="finding-a-statistic"><a class="header" href="#finding-a-statistic">Finding a Statistic</a></h2>
+<pre><code class="language-c">const nng_stat *nng_stat_find(const nng_stat *stat, const char *name);
+const nng_stat *nng_stat_find_dialer(const nng_stat *stat, nng_dialer dialer);
+const nng_stat *nng_stat_find_listener(const nng_stat *stat, nng_dialer listener);
+const nng_stat *nng_stat_find_socket(const nng_stat *stat, nng_dialer socket);
+</code></pre>
+<p>Sometimes it is easiest to search for a specific statistic, matching by name,
+or possibly to find the tree of statistics associated iwth a specific <a href="/TODO.html">socket</a>,
+<a href="/TODO.html">dialer</a>, or <a href="/TODO.html">listener</a>.</p>
+<p>The <code>nng_stat_find</code> functions are provided for this purpose.</p>
+<p>The <a name="a007"></a><code>nng_stat_find</code> function returns the first statistic within the subtree of
+statistics <em>stat</em>, with the given <em>name</em>. If no such statistic can be found, <code>NULL</code>
+is returned.</p>
+<p>The <a name="a008"></a><code>nng_stat_find_dialer</code>, <a name="a009"></a><code>nng_stat_find_listener</code>, and <a name="a010"></a><code>nng_stat_find_socket</code>
+return the statistics subtree for the given dialer, listener, or socket object. If no such
+statistic can be found, then they return <code>NULL</code>.
+These functions should be provided the root of the statistic tree, in order to ensure
+that they can find the desired object.</p>
+<h2 id="statistic-identification"><a class="header" href="#statistic-identification">Statistic Identification</a></h2>
+<pre><code class="language-c">const char *nng_stat_name(const nng_stat *stat);
+const char *nng_stat_desc(const nng_stat *stat);
+</code></pre>
+<p>Every statistic has a name, returned by <a name="a011"></a><code>nng_stat_name</code>, and a description, returned by
+<a name="a012"></a><code>nng_stat_desc</code>. Descriptions are human-readable text, which might be useful for display.</p>
+<h2 id="statistic-type"><a class="header" href="#statistic-type">Statistic Type</a></h2>
+<pre><code class="language-c">int nng_stat_type(const nng_stat *stat);
+</code></pre>
+<p>The function <a name="a013"></a><code>nng_stat_type</code> returns the type of the statistic.
+The type of a statistic determines the nature of the value, and which
+function can be used to obtain that value.</p>
+<ul>
+<li>
+<p><a name="a014"></a><code>NNG_STAT_SCOPE</code>: <a name="NNG_STAT_SCOPE"></a>
+The statistic does not carry any real value, but is
+used for grouping related statistics together. This is a nexus in the
+statistics tree.</p>
+</li>
+<li>
+<p><a name="a015"></a><code>NNG_STAT_COUNTER</code>: <a name="NNG_STAT_COUNTER"></a>
+The statistic is a counter that only increments.
+Usually the change in the value of the statistic is more interesting
+(as a rate) than the absolute value at any given time. The value should
+be obtained using <a href="/api/stats.html#statistic-value"><code>nng_stat_value</code></a>.
+The units will be given by the value returned from <a href="/api/stats.html#statistic-units"><code>nng_stat_unit</code></a>.</p>
+</li>
+<li>
+<p><a name="a016"></a><code>NNG_STAT_LEVEL</code>: <a name="NNG_STAT_LEVEL"></a>
+The statistic represnts a measured value which corresponds
+to a specific value at a specific time. For example, this may represent the
+number of messages currently queued for some operation, or the link speed
+of a network interface. Most often the absolute value is more interesting
+than the change in the value over time. Again the value can be obtained with
+<a href="/api/stats.html#statistic-value"><code>nng_stat_value</code></a>, and any appropriate unit of measurement
+with <a href="/api/stats.html#statistic-units"><code>nng_stat_unit</code></a>.</p>
+</li>
+<li>
+<p><a name="a017"></a><code>NNG_STAT_STRING</code>: <a name="NNG_STAT_STRING"></a>
+The statistic is a string, such as a name. The value
+of the string can be obtained with <a href="/api/stats.html#statistic-value"><code>nng_stat_string</code></a>.
+The value of this string
+will remain valid until the snapshot is deallocated with <a href="/api/stats.html#freeing-a-snapshot"><code>nng_stats_free</code></a>.</p>
+</li>
+<li>
+<p><a name="a018"></a><code>NNG_STAT_BOOLEAN</code>: <a name="NNG_STAT_BOOLEAN"></a>
+The value of the statistic is a truth value (either <code>true</code>
+or <code>false</code>) and can be obtained with <a href="/api/stats.html#statistic-value"><code>nng_stat_bool</code></a>.</p>
+</li>
+<li>
+<p><a name="a019"></a><code>NNG_STAT_ID</code>: <a name="NNG_STAT_ID"></a>
+The value of the statistic is a numeric identifier, such as a socket
+identifier. The value can be obtained with <a href="/api/stats.html#statistic-value"><code>nng_stat_value</code></a>,
+and will be fixed for the life of the statistic.</p>
+</li>
+</ul>
+<h2 id="statistic-value"><a class="header" href="#statistic-value">Statistic Value</a></h2>
+<pre><code class="language-c">uint64_t nng_stat_value(const nng_stat *stat);
+const char *nng_stat_string(const nng_stat *stat);
+bool nng_stat_bool(const nng_stat *stat);
+</code></pre>
+<p>These functions return the value associated with the statistic.</p>
+<p>The <a name="a020"></a><code>nng_stat_value</code> function returns the the numeric value for the statistic <em>stat</em>
+of type <a href="/api/stats.html#NNG_STAT_COUNTER"><code>NNG_STAT_COUNTER</code></a>, <a href="/api/stats.html#NNG_STAT_LEVEL"><code>NNG_STAT_LEVEL</code></a>, or <a href="/api/stats.html#NNG_STAT_ID"><code>NNG_STAT_ID</code></a>.
+If <em>stat</em> is not one of these types, then it returns zero.</p>
+<p>The <a name="a021"></a><code>nng_stat_bool</code> function returns the Boolean value (either <code>true</code> or <code>false</code>) for the statistic <em>stat</em> of
+type <a href="/api/stats.html#NNG_STAT_BOOLEAN"><code>NNG_STAT_BOOLEAN</code></a>. If the statistics is not of this type, then it returns <code>false</code>.</p>
+<p>The <a name="a022"></a><code>nng_stat_string</code> function returns a pointer to a string value for the statistic <em>stat</em>,
+of type <a href="/api/stats.html#statistic-value"><code>NNG_STAT_STRING</code></a>. This string will remain valud until the snapshot that
+<em>stat</em> was collected with is deallocated with <a href="/api/stats.html#freeing-a-snapshot"><code>nng_stats_free</code></a>. If the statistic
+is not of type <code>NNG_STAT_STRING</code>, then <code>NULL</code> is returned.</p>
+<h2 id="statistic-units"><a class="header" href="#statistic-units">Statistic Units</a></h2>
+<pre><code class="language-c">int nng_stat_unit(const nng_stat *stat);
+</code></pre>
+<p>For statistics of type <a href="/api/stats.html#NNG_STAT_COUNTER"><code>NNG_STAT_COUNTER</code></a> or <a href="/api/stats.html#NNG_STAT_LEVEL"><code>NNG_STAT_LEVEL</code></a>,
+it is often useful to know what that quantity being reported measures.
+The following units may be returned from <a name="a023"></a><code>nng_stat_unit</code> for such a statistic:</p>
+<ul>
+<li><a name="a024"></a><code>NNG_UNIT_NONE</code>: No unit is known or applies.</li>
+<li><a name="a025"></a><code>NNG_UNIT_BYTES</code>: A count of bytes.</li>
+<li><a name="a026"></a><code>NNG_UNIT_MESSAGES</code>: A count of messages.</li>
+<li><a name="a027"></a><code>NNG_UNIT_MILLIS</code>: A count of milliseconds.</li>
+<li><a name="a028"></a><code>NNG_UNIT_EVENTS</code>: A count of events of some type.</li>
+</ul>
+<h2 id="statistic-timestamp"><a class="header" href="#statistic-timestamp">Statistic Timestamp</a></h2>
+<pre><code class="language-c">uint64_t nng_stat_timestamp(const nng_stat *stat);
+</code></pre>
+<p>Statistics have a timestamp indicating when the value was sampled,
+obtained via <a name="a029"></a><code>nng_stat_timestamp</code>. The timestamp is given in
+in milliseconds since a reference time, and the reference time used
+here is the same reference time used for <a href="/api/time.html#get-the-current-time"><code>nng_clock</code></a>.</p>
+<h2 id="see-also"><a class="header" href="#see-also">See Also</a></h2>
+<p><a href="/api/time.html#get-the-current-time"><code>nng_clock</code></a></p>
+<!-- Symbol cross reference -->
+<!-- Macros -->
+<!-- Protocols -->
+<!-- Transports -->
+<!-- Concept index -->
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../api/logging.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+
+                            <a rel="next prefetch" href="../api/errors.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="../api/logging.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+
+                    <a rel="next prefetch" href="../api/errors.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="../elasticlunr.min.js"></script>
+        <script src="../mark.min.js"></script>
+        <script src="../searcher.js"></script>
+
+        <script src="../clipboard.min.js"></script>
+        <script src="../highlight.js"></script>
+        <script src="../book.js"></script>
+
+        <!-- Custom JS scripts -->
+        <script src="../theme/pagetoc.js"></script>
+
+
+    </div>
+    </body>
+</html>
diff --git a/ref/api/synch.html b/ref/api/synch.html
new file mode 100644
index 00000000..1ac1cd57
--- /dev/null
+++ b/ref/api/synch.html
@@ -0,0 +1,438 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>Synchronization - NNG Reference Manual (DRAFT)</title>
+
+
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="../favicon.svg">
+        <link rel="shortcut icon" href="../favicon.png">
+        <link rel="stylesheet" href="../css/variables.css">
+        <link rel="stylesheet" href="../css/general.css">
+        <link rel="stylesheet" href="../css/chrome.css">
+        <link rel="stylesheet" href="../css/print.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="../fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="../highlight.css">
+        <link rel="stylesheet" href="../tomorrow-night.css">
+        <link rel="stylesheet" href="../ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+        <link rel="stylesheet" href="../theme/pagetoc.css">
+
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "../";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded affix "><a href="../copyright.html">Copyright</a></li><li class="chapter-item expanded affix "><a href="../dedication.html">Dedication</a></li><li class="chapter-item expanded affix "><a href="../preface.html">Preface</a></li><li class="chapter-item expanded "><a href="../api/index.html"><strong aria-hidden="true">1.</strong> API Reference</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../api/msg.html"><strong aria-hidden="true">1.1.</strong> Messages</a></li><li class="chapter-item expanded "><a href="../api/memory.html"><strong aria-hidden="true">1.2.</strong> Memory</a></li><li class="chapter-item expanded "><a href="../api/time.html"><strong aria-hidden="true">1.3.</strong> Time</a></li><li class="chapter-item expanded "><a href="../api/url.html"><strong aria-hidden="true">1.4.</strong> URLs</a></li><li class="chapter-item expanded "><a href="../api/aio.html"><strong aria-hidden="true">1.5.</strong> Asynchronous I/O</a></li><li class="chapter-item expanded "><a href="../api/synch.html" class="active"><strong aria-hidden="true">1.6.</strong> Synchronization</a></li><li class="chapter-item expanded "><a href="../api/thread.html"><strong aria-hidden="true">1.7.</strong> Threads</a></li><li class="chapter-item expanded "><a href="../api/logging.html"><strong aria-hidden="true">1.8.</strong> Logging</a></li><li class="chapter-item expanded "><a href="../api/stats.html"><strong aria-hidden="true">1.9.</strong> Statistics</a></li><li class="chapter-item expanded "><a href="../api/errors.html"><strong aria-hidden="true">1.10.</strong> Errors</a></li><li class="chapter-item expanded "><a href="../api/misc.html"><strong aria-hidden="true">1.11.</strong> Miscellaneous</a></li><li class="chapter-item expanded "><a href="../api/id_map.html"><strong aria-hidden="true">1.12.</strong> ID Map</a></li><li class="chapter-item expanded "><a href="../api/cmd_opts.html"><strong aria-hidden="true">1.13.</strong> Command Options</a></li></ol></li><li class="chapter-item expanded "><a href="../proto/index.html"><strong aria-hidden="true">2.</strong> Protocols</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../proto/bus.html"><strong aria-hidden="true">2.1.</strong> BUS Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pair.html"><strong aria-hidden="true">2.2.</strong> PAIR Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pub.html"><strong aria-hidden="true">2.3.</strong> PUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pull.html"><strong aria-hidden="true">2.4.</strong> PULL Protocol</a></li><li class="chapter-item expanded "><a href="../proto/push.html"><strong aria-hidden="true">2.5.</strong> PUSH Protocol</a></li><li class="chapter-item expanded "><a href="../proto/rep.html"><strong aria-hidden="true">2.6.</strong> REP Protocol</a></li><li class="chapter-item expanded "><a href="../proto/req.html"><strong aria-hidden="true">2.7.</strong> REQ Protocol</a></li><li class="chapter-item expanded "><a href="../proto/respondent.html"><strong aria-hidden="true">2.8.</strong> RESPONDENT Protocol</a></li><li class="chapter-item expanded "><a href="../proto/sub.html"><strong aria-hidden="true">2.9.</strong> SUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/surveyor.html"><strong aria-hidden="true">2.10.</strong> SURVEYOR Protocol</a></li></ol></li><li class="chapter-item expanded "><a href="../tran/index.html"><strong aria-hidden="true">3.</strong> Transports</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../tran/inproc.html"><strong aria-hidden="true">3.1.</strong> Intra-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/ipc.html"><strong aria-hidden="true">3.2.</strong> Inter-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/socket.html"><strong aria-hidden="true">3.3.</strong> BSD Socket (Experimental)</a></li><li class="chapter-item expanded "><a href="../tran/udp.html"><strong aria-hidden="true">3.4.</strong> UDP Transport (Experimental)</a></li></ol></li><li class="chapter-item expanded "><a href="../migrate/index.html"><strong aria-hidden="true">4.</strong> Migration Guides</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../migrate/nng1.html"><strong aria-hidden="true">4.1.</strong> Migrating from NNG 1.x</a></li><li class="chapter-item expanded "><a href="../migrate/nanomsg.html"><strong aria-hidden="true">4.2.</strong> Migrating from libnanomsg</a></li></ol></li><li class="chapter-item expanded "><a href="../indexing.html">Index</a></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
+                <div class="sidebar-resize-indicator"></div>
+            </div>
+        </nav>
+
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">NNG Reference Manual (DRAFT)</h1>
+
+                    <div class="right-buttons">
+                        <a href="../print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <style>
+.mdbook-alerts {
+  padding: 8px 16px;
+  margin-bottom: 16px;
+  border-left: 0.25em solid var(--mdbook-alerts-color);
+}
+
+.mdbook-alerts > *:first-child {
+  margin-top: 0;
+}
+
+.mdbook-alerts > *:last-child {
+  margin-bottom: 0;
+}
+
+.mdbook-alerts-title {
+  display: flex;
+  font-weight: 600;
+  align-items: center;
+  line-height: 1;
+  color: var(--mdbook-alerts-color);
+  text-transform: capitalize;
+}
+
+.mdbook-alerts-icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  margin-right: 0.2em;
+  background-color: currentColor;
+  -webkit-mask: no-repeat center / 100%;
+  mask: no-repeat center / 100%;
+  -webkit-mask-image: var(--mdbook-alerts-icon);
+  mask-image: var(--mdbook-alerts-icon);
+}
+
+.mdbook-alerts-note {
+  --mdbook-alerts-color: rgb(9, 105, 218);
+  /* https://icon-sets.iconify.design/material-symbols/info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16v-4q0-.425-.288-.712T12 11q-.425 0-.712.288T11 12v4q0 .425.288.713T12 17m0-8q.425 0 .713-.288T13 8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8q0 .425.288.713T12 9m0 13q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12q0-3.35-2.325-5.675T12 4Q8.65 4 6.325 6.325T4 12q0 3.35 2.325 5.675T12 20m0-8"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-tip {
+  --mdbook-alerts-color: rgb(26, 127, 55);
+  /* https://icon-sets.iconify.design/material-symbols/lightbulb-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 22q-.825 0-1.412-.587T10 20h4q0 .825-.587 1.413T12 22m-3-3q-.425 0-.712-.288T8 18q0-.425.288-.712T9 17h6q.425 0 .713.288T16 18q0 .425-.288.713T15 19zm-.75-3q-1.725-1.025-2.738-2.75T4.5 9.5q0-3.125 2.188-5.312T12 2q3.125 0 5.313 2.188T19.5 9.5q0 2.025-1.012 3.75T15.75 16zm.6-2h6.3q1.125-.8 1.738-1.975T17.5 9.5q0-2.3-1.6-3.9T12 4Q9.7 4 8.1 5.6T6.5 9.5q0 1.35.613 2.525T8.85 14M12 14"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-important {
+  --mdbook-alerts-color: rgb(130, 80, 223);
+  /* https://icon-sets.iconify.design/material-symbols/chat-info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 7q.425 0 .713-.288T13 6q0-.425-.288-.712T12 5q-.425 0-.712.288T11 6q0 .425.288.713T12 7m0 8q.425 0 .713-.288T13 14v-4q0-.425-.288-.712T12 9q-.425 0-.712.288T11 10v4q0 .425.288.713T12 15m-6 3l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-warning {
+  --mdbook-alerts-color: rgb(154, 103, 0);
+  /* https://icon-sets.iconify.design/material-symbols/warning-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M2.725 21q-.275 0-.5-.137t-.35-.363q-.125-.225-.137-.488t.137-.512l9.25-16q.15-.25.388-.375T12 3q.25 0 .488.125t.387.375l9.25 16q.15.25.138.513t-.138.487q-.125.225-.35.363t-.5.137zm1.725-2h15.1L12 6zM12 18q.425 0 .713-.288T13 17q0-.425-.288-.712T12 16q-.425 0-.712.288T11 17q0 .425.288.713T12 18m0-3q.425 0 .713-.288T13 14v-3q0-.425-.288-.712T12 10q-.425 0-.712.288T11 11v3q0 .425.288.713T12 15m0-2.5"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-caution {
+  --mdbook-alerts-color: rgb(207, 34, 46);
+  /* https://icon-sets.iconify.design/material-symbols/brightness-alert-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16q0-.425-.288-.712T12 15q-.425 0-.712.288T11 16q0 .425.288.713T12 17m0-4q.425 0 .713-.288T13 12V8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8v4q0 .425.288.713T12 13m-3.35 7H6q-.825 0-1.412-.587T4 18v-2.65L2.075 13.4q-.275-.3-.425-.662T1.5 12q0-.375.15-.737t.425-.663L4 8.65V6q0-.825.588-1.412T6 4h2.65l1.95-1.925q.3-.275.663-.425T12 1.5q.375 0 .738.15t.662.425L15.35 4H18q.825 0 1.413.588T20 6v2.65l1.925 1.95q.275.3.425.663t.15.737q0 .375-.15.738t-.425.662L20 15.35V18q0 .825-.587 1.413T18 20h-2.65l-1.95 1.925q-.3.275-.662.425T12 22.5q-.375 0-.737-.15t-.663-.425zm.85-2l2.5 2.5l2.5-2.5H18v-3.5l2.5-2.5L18 9.5V6h-3.5L12 3.5L9.5 6H6v3.5L3.5 12L6 14.5V18zm2.5-6"%2F%3E%3C%2Fsvg%3E');
+}
+
+</style>
+<h1 id="synchronization-primitives"><a class="header" href="#synchronization-primitives">Synchronization Primitives</a></h1>
+<p>In order to allow safely accessing shared state, or to allow coordination between
+different <a href="/api/thread.html">threads</a>, <em>NNG</em> provides <a name="a001"></a>synchronization primitives in the
+form of mutual exclusion locks and condition variables.</p>
+<p>Correct use of these primitives will be needed when accessing shared state from
+threads, or from callback functions associated with <a href="/api/aio.html">asynchronous operations</a>.
+(The need to do this in callbacks is because the callback may be executed under
+a task thread other than the submitting thread.)</p>
+<h2 id="mutual-exclusion-lock"><a class="header" href="#mutual-exclusion-lock">Mutual Exclusion Lock</a></h2>
+<pre><code class="language-c">typedef struct nng_mtx nng_mtx;
+</code></pre>
+<p>Mutual exclusion locks, or <a name="a002"></a>mutex locks, represented by the <a name="a003"></a><code>nng_mtx</code> structure,
+allow only a single <a href="/api/thread.html">thread</a> to lock “own” the lock, acquired by <a href="/api/synch.html#acquiring-a-mutex"><code>nng_mtx_lock</code></a>.
+Any other thread trying to acquire the same mutex will wait until the owner has released the mutex
+by calling <a href="/api/synch.html#releasing-a-mutex"><code>nng_mtx_unlock</code></a>.</p>
+<h3 id="creating-a-mutex"><a class="header" href="#creating-a-mutex">Creating a Mutex</a></h3>
+<pre><code class="language-c">int nng_mutx_alloc(nng_mt **mtxp);
+</code></pre>
+<p>A mutex can be created by allocating one with <a name="a004"></a><code>nng_mtx_lock</code>.
+On success, a pointer to the mutex is returned through <em>mtxp</em>.
+This function can fail due to insufficient memory or resources, in which
+case it will return <a href="/api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>. Otherwise it will succceed and return zero.</p>
+<h3 id="destroying-a-mutex"><a class="header" href="#destroying-a-mutex">Destroying a Mutex</a></h3>
+<pre><code class="language-c">void nng_mtx_free(nng_mtx *mtx);
+</code></pre>
+<p>When no longer needed, a mutex can be deallocated and its resources returned
+to the caller, by calling <a name="a005"></a><code>nng_mtx_free</code>. The mutex must not be locked
+by any <a href="/api/thread.html">thread</a> when calling this function.</p>
+<h3 id="acquiring-a-mutex"><a class="header" href="#acquiring-a-mutex">Acquiring a Mutex</a></h3>
+<pre><code class="language-c">void nng_mtx_lock(nng_mtx *mtx);
+</code></pre>
+<p>The <a name="a006"></a><code>nng_mtx_lock</code> function acquires ownership of a mutex, waiting for it to
+unowned by any other threads if necessary.</p>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
+<p>A thread must not attempt to reqacuire the same mutex while it already “owns” the mutex.
+If it does attempt to do so, the result will be a single party deadlock.</p>
+</div>
+<h3 id="releasing-a-mutex"><a class="header" href="#releasing-a-mutex">Releasing a Mutex</a></h3>
+<pre><code class="language-c">void nng_mtx_unlock(nng_mtx *mtx);
+</code></pre>
+<p>The <a name="a007"></a><code>nng_mtx_unlock</code> function releases a mutex that the calling thread has previously
+acquired with <a href="/api/synch.html#acquiring-a-mutex"><code>nng_mtx_lock</code></a>.</p>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
+<p>A thread must not attempt to release (unlock) a mutex if it was not the thread
+that acquired the mutex to begin with.</p>
+</div>
+<h2 id="condition-variable"><a class="header" href="#condition-variable">Condition Variable</a></h2>
+<pre><code class="language-c">typedef struct nng_cv nng_cv;
+</code></pre>
+<p>The <a name="a008"></a><code>nng_cv</code> structure implements a <a name="a009"></a>condition variable, associated with the
+the <a href="/api/synch.html#mutual-exclusion-lock">mutex</a> <em>mtx</em> which was supplied when it was created.</p>
+<p>Condition variables provide for a way to wait on an arbitrary condition, and to be woken
+when the condition is signaled.
+The mutex is dropped while the caller is asleep, and reacquired atomically when the caller
+is woken.</p>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
+<p>The caller of <code>nng_cv_until</code>, <code>nng_cv_wait</code>, <code>nng_cv_wake</code>, and <code>nng_cv_wake1</code> <em>must</em>
+have ownership of the mutex <em>mtx</em> when calling these functions.</p>
+</div>
+<h3 id="creating-a-condition-variable"><a class="header" href="#creating-a-condition-variable">Creating a Condition Variable</a></h3>
+<pre><code class="language-c">int nng_cv_alloc(nng_cv **cvp, nng_mtx *mtx);
+</code></pre>
+<p>The <a name="a010"></a><code>nng_cv_alloc</code> function allocates a condition variable, and associated with the mutex <em>mtx</em>,
+and returns a pointer to it in <em>cvp</em>.</p>
+<h3 id="destroy-a-condition-variable"><a class="header" href="#destroy-a-condition-variable">Destroy a Condition Variable</a></h3>
+<pre><code class="language-c">void nng_cv_free(nng_cv *cv);
+</code></pre>
+<p>The <a name="a011"></a><code>nng_cv_free</code> function deallocates the condition variable <em>cv</em>.</p>
+<h3 id="waiting-for-the-condition"><a class="header" href="#waiting-for-the-condition">Waiting for the Condition</a></h3>
+<pre><code class="language-c">int nng_cv_until(nng_cv *cv, nng_time when);
+void nng_cv_wait(nng_cv *cv);
+</code></pre>
+<p>The <a name="a012"></a><code>nng_cv_until</code> and <a name="a013"></a><code>nng_cv_wait</code> functions put the caller to sleep until the condition
+variable <em>cv</em> is signaled, or (in the case of <code>nng_cv_until</code>), the specified time <em>when</em>
+(as determined by <a href="/api/time.html#get-the-current-time"><code>nng_clock</code></a> is reached.</p>
+<p>While <code>nng_cv_wait</code> never fails and so has no return value, the <code>nng_cv_until</code> function can
+return <a href="/api/errors.html#NNG_ETIMEDOUT"><code>NNG_ETIMEDOUT</code></a> if the time is reached before condition <em>cv</em> is signaled by
+either <a href="/api/synch.html#signaling-the-condition"><code>nng_cv_wake</code></a> or <a href="/api/synch.html#signaling-the-condition"><code>nng_cv_wake1</code></a>.</p>
+<h3 id="signaling-the-condition"><a class="header" href="#signaling-the-condition">Signaling the Condition</a></h3>
+<pre><code class="language-c">void nng_cv_wake(nng_cv *cv);
+void nng_cv_wake1(nng_cv *cv);
+</code></pre>
+<p>The <a name="a014"></a><code>nng_cv_wake</code> and <a name="a015"></a><code>nng_cv_wake1</code> functions wake threads waiting in
+<a href="/api/synch.html#waiting-for-the-condition"><code>nng_cv_until</code></a> or <a href="/api/synch.html#waiting-for-the-condition"><code>nng_cv_wait</code></a>.
+The difference between these functions is that
+<code>nng_cv_wake</code> will wake <em>every</em> thread, whereas <code>nng_cv_wake1</code> will wake up exactly
+one thread (which may be chosen randomly).</p>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  tip
+</p>
+<p>Use of <code>nng_cv_wake1</code> may be used to reduce the “<a name="a016"></a>thundering herd” syndrom of waking
+all threads concurrently, but should only be used in circumstances where the application
+does not depend on <em>which</em> thread will be woken. When in doubt, <code>nng_cv_wake</code> is safer.</p>
+</div>
+<h2 id="examples"><a class="header" href="#examples">Examples</a></h2>
+<h3 id="example-1-allocating-the-condition-variable"><a class="header" href="#example-1-allocating-the-condition-variable">Example 1: Allocating the condition variable</a></h3>
+<pre><code class="language-c">	nng_mtx *m;
+	nng_cv *cv;
+	nng_mtx_alloc(&amp;m); // error checks elided
+	nng_cv_alloc(&amp;cv, m);
+</code></pre>
+<h3 id="example-2-waiting-for-the-condition"><a class="header" href="#example-2-waiting-for-the-condition">Example 2: Waiting for the condition</a></h3>
+<pre><code class="language-c">    expire = nng_clock() + 1000; // 1 second in the future
+    nng_mtx_lock(m);  // assume cv was allocated using m
+    while (!condition_true) {
+        if (nng_cv_until(cv, expire) == NNG_ETIMEDOUT) {
+            printf("Time out reached!\n");
+            break;
+        }
+    }
+    // condition_true is true
+    nng_mtx_unlock(m);
+</code></pre>
+<h3 id="example-3-signaling-the-condition"><a class="header" href="#example-3-signaling-the-condition">Example 3: Signaling the condition</a></h3>
+<pre><code class="language-c">    nng_mtx_lock(m);
+    condition_true = true;
+    nng_cv_wake(cv);
+    nng_mtx_unlock(m);
+</code></pre>
+<!-- Symbol cross reference -->
+<!-- Macros -->
+<!-- Protocols -->
+<!-- Transports -->
+<!-- Concept index -->
+<h2 id="see-also"><a class="header" href="#see-also">See Also</a></h2>
+<p><a href="/api/thread.html">Threads</a>,
+<a href="/api/time.html">Time</a>,
+<a href="/api/aio.html">Asynchronous I/O</a></p>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../api/aio.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+
+                            <a rel="next prefetch" href="../api/thread.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="../api/aio.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+
+                    <a rel="next prefetch" href="../api/thread.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="../elasticlunr.min.js"></script>
+        <script src="../mark.min.js"></script>
+        <script src="../searcher.js"></script>
+
+        <script src="../clipboard.min.js"></script>
+        <script src="../highlight.js"></script>
+        <script src="../book.js"></script>
+
+        <!-- Custom JS scripts -->
+        <script src="../theme/pagetoc.js"></script>
+
+
+    </div>
+    </body>
+</html>
diff --git a/ref/api/thread.html b/ref/api/thread.html
new file mode 100644
index 00000000..0f9e0ac7
--- /dev/null
+++ b/ref/api/thread.html
@@ -0,0 +1,374 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>Threads - NNG Reference Manual (DRAFT)</title>
+
+
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="../favicon.svg">
+        <link rel="shortcut icon" href="../favicon.png">
+        <link rel="stylesheet" href="../css/variables.css">
+        <link rel="stylesheet" href="../css/general.css">
+        <link rel="stylesheet" href="../css/chrome.css">
+        <link rel="stylesheet" href="../css/print.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="../fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="../highlight.css">
+        <link rel="stylesheet" href="../tomorrow-night.css">
+        <link rel="stylesheet" href="../ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+        <link rel="stylesheet" href="../theme/pagetoc.css">
+
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "../";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded affix "><a href="../copyright.html">Copyright</a></li><li class="chapter-item expanded affix "><a href="../dedication.html">Dedication</a></li><li class="chapter-item expanded affix "><a href="../preface.html">Preface</a></li><li class="chapter-item expanded "><a href="../api/index.html"><strong aria-hidden="true">1.</strong> API Reference</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../api/msg.html"><strong aria-hidden="true">1.1.</strong> Messages</a></li><li class="chapter-item expanded "><a href="../api/memory.html"><strong aria-hidden="true">1.2.</strong> Memory</a></li><li class="chapter-item expanded "><a href="../api/time.html"><strong aria-hidden="true">1.3.</strong> Time</a></li><li class="chapter-item expanded "><a href="../api/url.html"><strong aria-hidden="true">1.4.</strong> URLs</a></li><li class="chapter-item expanded "><a href="../api/aio.html"><strong aria-hidden="true">1.5.</strong> Asynchronous I/O</a></li><li class="chapter-item expanded "><a href="../api/synch.html"><strong aria-hidden="true">1.6.</strong> Synchronization</a></li><li class="chapter-item expanded "><a href="../api/thread.html" class="active"><strong aria-hidden="true">1.7.</strong> Threads</a></li><li class="chapter-item expanded "><a href="../api/logging.html"><strong aria-hidden="true">1.8.</strong> Logging</a></li><li class="chapter-item expanded "><a href="../api/stats.html"><strong aria-hidden="true">1.9.</strong> Statistics</a></li><li class="chapter-item expanded "><a href="../api/errors.html"><strong aria-hidden="true">1.10.</strong> Errors</a></li><li class="chapter-item expanded "><a href="../api/misc.html"><strong aria-hidden="true">1.11.</strong> Miscellaneous</a></li><li class="chapter-item expanded "><a href="../api/id_map.html"><strong aria-hidden="true">1.12.</strong> ID Map</a></li><li class="chapter-item expanded "><a href="../api/cmd_opts.html"><strong aria-hidden="true">1.13.</strong> Command Options</a></li></ol></li><li class="chapter-item expanded "><a href="../proto/index.html"><strong aria-hidden="true">2.</strong> Protocols</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../proto/bus.html"><strong aria-hidden="true">2.1.</strong> BUS Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pair.html"><strong aria-hidden="true">2.2.</strong> PAIR Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pub.html"><strong aria-hidden="true">2.3.</strong> PUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pull.html"><strong aria-hidden="true">2.4.</strong> PULL Protocol</a></li><li class="chapter-item expanded "><a href="../proto/push.html"><strong aria-hidden="true">2.5.</strong> PUSH Protocol</a></li><li class="chapter-item expanded "><a href="../proto/rep.html"><strong aria-hidden="true">2.6.</strong> REP Protocol</a></li><li class="chapter-item expanded "><a href="../proto/req.html"><strong aria-hidden="true">2.7.</strong> REQ Protocol</a></li><li class="chapter-item expanded "><a href="../proto/respondent.html"><strong aria-hidden="true">2.8.</strong> RESPONDENT Protocol</a></li><li class="chapter-item expanded "><a href="../proto/sub.html"><strong aria-hidden="true">2.9.</strong> SUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/surveyor.html"><strong aria-hidden="true">2.10.</strong> SURVEYOR Protocol</a></li></ol></li><li class="chapter-item expanded "><a href="../tran/index.html"><strong aria-hidden="true">3.</strong> Transports</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../tran/inproc.html"><strong aria-hidden="true">3.1.</strong> Intra-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/ipc.html"><strong aria-hidden="true">3.2.</strong> Inter-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/socket.html"><strong aria-hidden="true">3.3.</strong> BSD Socket (Experimental)</a></li><li class="chapter-item expanded "><a href="../tran/udp.html"><strong aria-hidden="true">3.4.</strong> UDP Transport (Experimental)</a></li></ol></li><li class="chapter-item expanded "><a href="../migrate/index.html"><strong aria-hidden="true">4.</strong> Migration Guides</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../migrate/nng1.html"><strong aria-hidden="true">4.1.</strong> Migrating from NNG 1.x</a></li><li class="chapter-item expanded "><a href="../migrate/nanomsg.html"><strong aria-hidden="true">4.2.</strong> Migrating from libnanomsg</a></li></ol></li><li class="chapter-item expanded "><a href="../indexing.html">Index</a></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
+                <div class="sidebar-resize-indicator"></div>
+            </div>
+        </nav>
+
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">NNG Reference Manual (DRAFT)</h1>
+
+                    <div class="right-buttons">
+                        <a href="../print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <style>
+.mdbook-alerts {
+  padding: 8px 16px;
+  margin-bottom: 16px;
+  border-left: 0.25em solid var(--mdbook-alerts-color);
+}
+
+.mdbook-alerts > *:first-child {
+  margin-top: 0;
+}
+
+.mdbook-alerts > *:last-child {
+  margin-bottom: 0;
+}
+
+.mdbook-alerts-title {
+  display: flex;
+  font-weight: 600;
+  align-items: center;
+  line-height: 1;
+  color: var(--mdbook-alerts-color);
+  text-transform: capitalize;
+}
+
+.mdbook-alerts-icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  margin-right: 0.2em;
+  background-color: currentColor;
+  -webkit-mask: no-repeat center / 100%;
+  mask: no-repeat center / 100%;
+  -webkit-mask-image: var(--mdbook-alerts-icon);
+  mask-image: var(--mdbook-alerts-icon);
+}
+
+.mdbook-alerts-note {
+  --mdbook-alerts-color: rgb(9, 105, 218);
+  /* https://icon-sets.iconify.design/material-symbols/info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16v-4q0-.425-.288-.712T12 11q-.425 0-.712.288T11 12v4q0 .425.288.713T12 17m0-8q.425 0 .713-.288T13 8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8q0 .425.288.713T12 9m0 13q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12q0-3.35-2.325-5.675T12 4Q8.65 4 6.325 6.325T4 12q0 3.35 2.325 5.675T12 20m0-8"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-tip {
+  --mdbook-alerts-color: rgb(26, 127, 55);
+  /* https://icon-sets.iconify.design/material-symbols/lightbulb-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 22q-.825 0-1.412-.587T10 20h4q0 .825-.587 1.413T12 22m-3-3q-.425 0-.712-.288T8 18q0-.425.288-.712T9 17h6q.425 0 .713.288T16 18q0 .425-.288.713T15 19zm-.75-3q-1.725-1.025-2.738-2.75T4.5 9.5q0-3.125 2.188-5.312T12 2q3.125 0 5.313 2.188T19.5 9.5q0 2.025-1.012 3.75T15.75 16zm.6-2h6.3q1.125-.8 1.738-1.975T17.5 9.5q0-2.3-1.6-3.9T12 4Q9.7 4 8.1 5.6T6.5 9.5q0 1.35.613 2.525T8.85 14M12 14"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-important {
+  --mdbook-alerts-color: rgb(130, 80, 223);
+  /* https://icon-sets.iconify.design/material-symbols/chat-info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 7q.425 0 .713-.288T13 6q0-.425-.288-.712T12 5q-.425 0-.712.288T11 6q0 .425.288.713T12 7m0 8q.425 0 .713-.288T13 14v-4q0-.425-.288-.712T12 9q-.425 0-.712.288T11 10v4q0 .425.288.713T12 15m-6 3l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-warning {
+  --mdbook-alerts-color: rgb(154, 103, 0);
+  /* https://icon-sets.iconify.design/material-symbols/warning-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M2.725 21q-.275 0-.5-.137t-.35-.363q-.125-.225-.137-.488t.137-.512l9.25-16q.15-.25.388-.375T12 3q.25 0 .488.125t.387.375l9.25 16q.15.25.138.513t-.138.487q-.125.225-.35.363t-.5.137zm1.725-2h15.1L12 6zM12 18q.425 0 .713-.288T13 17q0-.425-.288-.712T12 16q-.425 0-.712.288T11 17q0 .425.288.713T12 18m0-3q.425 0 .713-.288T13 14v-3q0-.425-.288-.712T12 10q-.425 0-.712.288T11 11v3q0 .425.288.713T12 15m0-2.5"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-caution {
+  --mdbook-alerts-color: rgb(207, 34, 46);
+  /* https://icon-sets.iconify.design/material-symbols/brightness-alert-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16q0-.425-.288-.712T12 15q-.425 0-.712.288T11 16q0 .425.288.713T12 17m0-4q.425 0 .713-.288T13 12V8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8v4q0 .425.288.713T12 13m-3.35 7H6q-.825 0-1.412-.587T4 18v-2.65L2.075 13.4q-.275-.3-.425-.662T1.5 12q0-.375.15-.737t.425-.663L4 8.65V6q0-.825.588-1.412T6 4h2.65l1.95-1.925q.3-.275.663-.425T12 1.5q.375 0 .738.15t.662.425L15.35 4H18q.825 0 1.413.588T20 6v2.65l1.925 1.95q.275.3.425.663t.15.737q0 .375-.15.738t-.425.662L20 15.35V18q0 .825-.587 1.413T18 20h-2.65l-1.95 1.925q-.3.275-.662.425T12 22.5q-.375 0-.737-.15t-.663-.425zm.85-2l2.5 2.5l2.5-2.5H18v-3.5l2.5-2.5L18 9.5V6h-3.5L12 3.5L9.5 6H6v3.5L3.5 12L6 14.5V18zm2.5-6"%2F%3E%3C%2Fsvg%3E');
+}
+
+</style>
+<h1 id="threads"><a class="header" href="#threads">Threads</a></h1>
+<p>Threads <a name="a001"></a> provide a means of representing multiple parallel execution contexts.
+<em>NNG</em> makes use of this concept internally, but also provides for user applications
+to utilize the same thread facilities. This allows one form of <a name="a002"></a>concurrency for
+applications.</p>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  note
+</p>
+<p>Threads in <em>NNG</em> are built upon platform support, which may be based upon operating
+system supplied threads, process, or coroutines. The appearance of concurrency does
+not guarantee true concurrency, and scheduling between threads may not necessarily be
+pre-emptive. While this will not adversely impact applications that use this facility
+for I/O bound concurrency, it may not provide good results for purely <a name="a003"></a>CPU-bound operations.</p>
+</div>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
+<p>Thread objects created by this function may not be real system-level
+threads capable of performing blocking I/O operations using normal blocking system calls.
+If use of blocking system calls is required (not including APIs provided
+by the <em>NNG</em> library itself of course), then real OS-specific threads
+should be created instead (such as with <code>pthread_create</code> or similar functions.)
+Blocking <em>NNG</em> library calls can however be made safely from <em>NNG</em> threads.</p>
+</div>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  tip
+</p>
+<p>The system may impose limits on the number of threads that can be created.
+Typically applications should not create more than a dozen of these.
+If greater concurrency or scalability is needed, consider instead using
+an asynchronous model using <a href="/TODO.html"><code>nng_aio</code></a> structures.</p>
+</div>
+<h2 id="thread-structure"><a class="header" href="#thread-structure">Thread Structure</a></h2>
+<pre><code class="language-c">typedef struct nng_thread nng_thread;
+</code></pre>
+<p>The <a name="a004"></a><code>nng_thread</code> structure represnts a thread, which is a single execution context.
+A given thread will have its own stack, and CPU registers. However global state, as well
+as values allocated on the heap, will be shared and accessible to all threads in the system
+(See the <a href="/api/synch.html">Synchronization</a> chapter for functions to help with data sharing between different threads.)</p>
+<p>Multiple threads can be thought of as running concurrently, even though
+they might not actually do so.</p>
+<p>I/O operations that block (i.e. wait for completion) will block the
+thread, while allowing other threads to proceed.</p>
+<h2 id="creating-a-thread"><a class="header" href="#creating-a-thread">Creating a Thread</a></h2>
+<pre><code class="language-c">int nng_thread_create(nng_thread **thrp, void (*func)(void *), void *arg);
+</code></pre>
+<p>The <a name="a005"></a><code>nng_thread_create</code> function creates a thread, which will execute <em>func</em>, with
+the given argument <em>arg</em>, and returns a pointer to it in <em>thrp</em>.</p>
+<p>The thread may begin execution immediately.</p>
+<p>The thread will persist until <em>func</em> returns.</p>
+<p>This function returns zero on success, but may return <code>NNG_ENOMEM</code> if insufficient
+resources to create a thread are available.</p>
+<h2 id="destroying-a-thread"><a class="header" href="#destroying-a-thread">Destroying a Thread</a></h2>
+<pre><code class="language-c">void nng_thread_destroy(nng_thread *thr);
+</code></pre>
+<p>The <a name="a006"></a><code>nng_thread_destroy</code> function waits for the thread <em>thr</em> to finish execution.
+This function should be called to reclaim any resources associated with the thread when done.
+It also has the effect of blocking execution in the caller until <em>thr</em> has completed executing.</p>
+<h2 id="thread-names"><a class="header" href="#thread-names">Thread Names</a></h2>
+<pre><code class="language-c">void nng_thread_set_name(nng_thread *thr, const char *name);
+</code></pre>
+<p>In order to facilitate debugging, <a name="a007"></a><code>nng_thread_set_name</code> may be called
+to provide a name for the thread. This may change how the thread is represented
+in debuggers. Not all platforms support setting the thread name.</p>
+<h2 id="see-also"><a class="header" href="#see-also">See Also</a></h2>
+<p><a href="/api/synch.html">Synchronization</a>,
+<a href="/api/aio.html">Asynchronous Operations</a></p>
+<!-- Symbol cross reference -->
+<!-- Macros -->
+<!-- Protocols -->
+<!-- Transports -->
+<!-- Concept index -->
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../api/synch.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+
+                            <a rel="next prefetch" href="../api/logging.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="../api/synch.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+
+                    <a rel="next prefetch" href="../api/logging.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="../elasticlunr.min.js"></script>
+        <script src="../mark.min.js"></script>
+        <script src="../searcher.js"></script>
+
+        <script src="../clipboard.min.js"></script>
+        <script src="../highlight.js"></script>
+        <script src="../book.js"></script>
+
+        <!-- Custom JS scripts -->
+        <script src="../theme/pagetoc.js"></script>
+
+
+    </div>
+    </body>
+</html>
diff --git a/ref/api/time.html b/ref/api/time.html
new file mode 100644
index 00000000..f3bf9685
--- /dev/null
+++ b/ref/api/time.html
@@ -0,0 +1,381 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>Time - NNG Reference Manual (DRAFT)</title>
+
+
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="../favicon.svg">
+        <link rel="shortcut icon" href="../favicon.png">
+        <link rel="stylesheet" href="../css/variables.css">
+        <link rel="stylesheet" href="../css/general.css">
+        <link rel="stylesheet" href="../css/chrome.css">
+        <link rel="stylesheet" href="../css/print.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="../fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="../highlight.css">
+        <link rel="stylesheet" href="../tomorrow-night.css">
+        <link rel="stylesheet" href="../ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+        <link rel="stylesheet" href="../theme/pagetoc.css">
+
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "../";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded affix "><a href="../copyright.html">Copyright</a></li><li class="chapter-item expanded affix "><a href="../dedication.html">Dedication</a></li><li class="chapter-item expanded affix "><a href="../preface.html">Preface</a></li><li class="chapter-item expanded "><a href="../api/index.html"><strong aria-hidden="true">1.</strong> API Reference</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../api/msg.html"><strong aria-hidden="true">1.1.</strong> Messages</a></li><li class="chapter-item expanded "><a href="../api/memory.html"><strong aria-hidden="true">1.2.</strong> Memory</a></li><li class="chapter-item expanded "><a href="../api/time.html" class="active"><strong aria-hidden="true">1.3.</strong> Time</a></li><li class="chapter-item expanded "><a href="../api/url.html"><strong aria-hidden="true">1.4.</strong> URLs</a></li><li class="chapter-item expanded "><a href="../api/aio.html"><strong aria-hidden="true">1.5.</strong> Asynchronous I/O</a></li><li class="chapter-item expanded "><a href="../api/synch.html"><strong aria-hidden="true">1.6.</strong> Synchronization</a></li><li class="chapter-item expanded "><a href="../api/thread.html"><strong aria-hidden="true">1.7.</strong> Threads</a></li><li class="chapter-item expanded "><a href="../api/logging.html"><strong aria-hidden="true">1.8.</strong> Logging</a></li><li class="chapter-item expanded "><a href="../api/stats.html"><strong aria-hidden="true">1.9.</strong> Statistics</a></li><li class="chapter-item expanded "><a href="../api/errors.html"><strong aria-hidden="true">1.10.</strong> Errors</a></li><li class="chapter-item expanded "><a href="../api/misc.html"><strong aria-hidden="true">1.11.</strong> Miscellaneous</a></li><li class="chapter-item expanded "><a href="../api/id_map.html"><strong aria-hidden="true">1.12.</strong> ID Map</a></li><li class="chapter-item expanded "><a href="../api/cmd_opts.html"><strong aria-hidden="true">1.13.</strong> Command Options</a></li></ol></li><li class="chapter-item expanded "><a href="../proto/index.html"><strong aria-hidden="true">2.</strong> Protocols</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../proto/bus.html"><strong aria-hidden="true">2.1.</strong> BUS Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pair.html"><strong aria-hidden="true">2.2.</strong> PAIR Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pub.html"><strong aria-hidden="true">2.3.</strong> PUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pull.html"><strong aria-hidden="true">2.4.</strong> PULL Protocol</a></li><li class="chapter-item expanded "><a href="../proto/push.html"><strong aria-hidden="true">2.5.</strong> PUSH Protocol</a></li><li class="chapter-item expanded "><a href="../proto/rep.html"><strong aria-hidden="true">2.6.</strong> REP Protocol</a></li><li class="chapter-item expanded "><a href="../proto/req.html"><strong aria-hidden="true">2.7.</strong> REQ Protocol</a></li><li class="chapter-item expanded "><a href="../proto/respondent.html"><strong aria-hidden="true">2.8.</strong> RESPONDENT Protocol</a></li><li class="chapter-item expanded "><a href="../proto/sub.html"><strong aria-hidden="true">2.9.</strong> SUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/surveyor.html"><strong aria-hidden="true">2.10.</strong> SURVEYOR Protocol</a></li></ol></li><li class="chapter-item expanded "><a href="../tran/index.html"><strong aria-hidden="true">3.</strong> Transports</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../tran/inproc.html"><strong aria-hidden="true">3.1.</strong> Intra-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/ipc.html"><strong aria-hidden="true">3.2.</strong> Inter-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/socket.html"><strong aria-hidden="true">3.3.</strong> BSD Socket (Experimental)</a></li><li class="chapter-item expanded "><a href="../tran/udp.html"><strong aria-hidden="true">3.4.</strong> UDP Transport (Experimental)</a></li></ol></li><li class="chapter-item expanded "><a href="../migrate/index.html"><strong aria-hidden="true">4.</strong> Migration Guides</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../migrate/nng1.html"><strong aria-hidden="true">4.1.</strong> Migrating from NNG 1.x</a></li><li class="chapter-item expanded "><a href="../migrate/nanomsg.html"><strong aria-hidden="true">4.2.</strong> Migrating from libnanomsg</a></li></ol></li><li class="chapter-item expanded "><a href="../indexing.html">Index</a></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
+                <div class="sidebar-resize-indicator"></div>
+            </div>
+        </nav>
+
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">NNG Reference Manual (DRAFT)</h1>
+
+                    <div class="right-buttons">
+                        <a href="../print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <style>
+.mdbook-alerts {
+  padding: 8px 16px;
+  margin-bottom: 16px;
+  border-left: 0.25em solid var(--mdbook-alerts-color);
+}
+
+.mdbook-alerts > *:first-child {
+  margin-top: 0;
+}
+
+.mdbook-alerts > *:last-child {
+  margin-bottom: 0;
+}
+
+.mdbook-alerts-title {
+  display: flex;
+  font-weight: 600;
+  align-items: center;
+  line-height: 1;
+  color: var(--mdbook-alerts-color);
+  text-transform: capitalize;
+}
+
+.mdbook-alerts-icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  margin-right: 0.2em;
+  background-color: currentColor;
+  -webkit-mask: no-repeat center / 100%;
+  mask: no-repeat center / 100%;
+  -webkit-mask-image: var(--mdbook-alerts-icon);
+  mask-image: var(--mdbook-alerts-icon);
+}
+
+.mdbook-alerts-note {
+  --mdbook-alerts-color: rgb(9, 105, 218);
+  /* https://icon-sets.iconify.design/material-symbols/info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16v-4q0-.425-.288-.712T12 11q-.425 0-.712.288T11 12v4q0 .425.288.713T12 17m0-8q.425 0 .713-.288T13 8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8q0 .425.288.713T12 9m0 13q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12q0-3.35-2.325-5.675T12 4Q8.65 4 6.325 6.325T4 12q0 3.35 2.325 5.675T12 20m0-8"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-tip {
+  --mdbook-alerts-color: rgb(26, 127, 55);
+  /* https://icon-sets.iconify.design/material-symbols/lightbulb-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 22q-.825 0-1.412-.587T10 20h4q0 .825-.587 1.413T12 22m-3-3q-.425 0-.712-.288T8 18q0-.425.288-.712T9 17h6q.425 0 .713.288T16 18q0 .425-.288.713T15 19zm-.75-3q-1.725-1.025-2.738-2.75T4.5 9.5q0-3.125 2.188-5.312T12 2q3.125 0 5.313 2.188T19.5 9.5q0 2.025-1.012 3.75T15.75 16zm.6-2h6.3q1.125-.8 1.738-1.975T17.5 9.5q0-2.3-1.6-3.9T12 4Q9.7 4 8.1 5.6T6.5 9.5q0 1.35.613 2.525T8.85 14M12 14"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-important {
+  --mdbook-alerts-color: rgb(130, 80, 223);
+  /* https://icon-sets.iconify.design/material-symbols/chat-info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 7q.425 0 .713-.288T13 6q0-.425-.288-.712T12 5q-.425 0-.712.288T11 6q0 .425.288.713T12 7m0 8q.425 0 .713-.288T13 14v-4q0-.425-.288-.712T12 9q-.425 0-.712.288T11 10v4q0 .425.288.713T12 15m-6 3l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-warning {
+  --mdbook-alerts-color: rgb(154, 103, 0);
+  /* https://icon-sets.iconify.design/material-symbols/warning-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M2.725 21q-.275 0-.5-.137t-.35-.363q-.125-.225-.137-.488t.137-.512l9.25-16q.15-.25.388-.375T12 3q.25 0 .488.125t.387.375l9.25 16q.15.25.138.513t-.138.487q-.125.225-.35.363t-.5.137zm1.725-2h15.1L12 6zM12 18q.425 0 .713-.288T13 17q0-.425-.288-.712T12 16q-.425 0-.712.288T11 17q0 .425.288.713T12 18m0-3q.425 0 .713-.288T13 14v-3q0-.425-.288-.712T12 10q-.425 0-.712.288T11 11v3q0 .425.288.713T12 15m0-2.5"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-caution {
+  --mdbook-alerts-color: rgb(207, 34, 46);
+  /* https://icon-sets.iconify.design/material-symbols/brightness-alert-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16q0-.425-.288-.712T12 15q-.425 0-.712.288T11 16q0 .425.288.713T12 17m0-4q.425 0 .713-.288T13 12V8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8v4q0 .425.288.713T12 13m-3.35 7H6q-.825 0-1.412-.587T4 18v-2.65L2.075 13.4q-.275-.3-.425-.662T1.5 12q0-.375.15-.737t.425-.663L4 8.65V6q0-.825.588-1.412T6 4h2.65l1.95-1.925q.3-.275.663-.425T12 1.5q.375 0 .738.15t.662.425L15.35 4H18q.825 0 1.413.588T20 6v2.65l1.925 1.95q.275.3.425.663t.15.737q0 .375-.15.738t-.425.662L20 15.35V18q0 .825-.587 1.413T18 20h-2.65l-1.95 1.925q-.3.275-.662.425T12 22.5q-.375 0-.737-.15t-.663-.425zm.85-2l2.5 2.5l2.5-2.5H18v-3.5l2.5-2.5L18 9.5V6h-3.5L12 3.5L9.5 6H6v3.5L3.5 12L6 14.5V18zm2.5-6"%2F%3E%3C%2Fsvg%3E');
+}
+
+</style>
+<h1 id="time"><a class="header" href="#time">Time</a></h1>
+<p><em>NNG</em> supports has support for time in the form of access to a
+system clock, and supporting timeouts for certain operations.</p>
+<h2 id="time-type"><a class="header" href="#time-type">Time Type</a></h2>
+<pre><code class="language-c">typedef uint64_t nng_time;
+</code></pre>
+<p>The <a name="a001"></a><code>nng_time</code> type is used to represent a clock offset from a common base time,
+measured in milliseconds.</p>
+<p>The reference, or zero value, is some arbitrary point in time, most often sytem boot, but can
+be process start time or any other convenient reference.</p>
+<p>All threads within a process will use the same reference time, but be aware that different processes
+may use a different reference time.</p>
+<h2 id="duration-type"><a class="header" href="#duration-type">Duration Type</a></h2>
+<pre><code class="language-c">typedef int64_t nng_duration;
+
+#define NNG_DURATION_INFINITE (-1)
+#define NNG_DURATION_DEFAULT  (-2)
+#define NNG_DURATION_ZERO     (0)
+</code></pre>
+<p>The <a name="a002"></a><code>nng_duration</code> time measures a time <a name="a003"></a>duration in milliseconds.
+Normally durations are positive, but some specific negative values are reserved.</p>
+<ul>
+<li>
+<p><a name="a004"></a><code>NNG_DURATION_INFINITE</code>: The duration essentially means forever.
+This is most often used with a timeout to indicate that there is no timeout, the
+operation should wait until it is complete, even forever.</p>
+</li>
+<li>
+<p><a name="a005"></a><code>NNG_DURATION_DEFAULT</code>: This special value is used in some circumstances to
+prevent overriding a default timeout. Some operations have a default maximum time,
+and this value means that the previously established default should be used.
+The precise meaning is context-specific.</p>
+</li>
+<li>
+<p><a name="a006"></a><code>NNG_DURATION_ZERO</code>: A zero length duration is used to performan an immediate
+poll.</p>
+</li>
+</ul>
+<h2 id="get-the-current-time"><a class="header" href="#get-the-current-time">Get the Current Time</a></h2>
+<pre><code class="language-c">nng_time nng_clock(void);
+</code></pre>
+<p>The <a name="a007"></a><code>nng_clock</code><a name="a008"></a> function returns the number of elapsed
+milliseconds since some arbitrary time in the past.
+The resolution of the clock depends on the underlying timing facilities of the system.
+This function may be used for timing, but applications should not expect
+very fine-grained values.</p>
+<h2 id="wait-for-duration"><a class="header" href="#wait-for-duration">Wait for Duration</a></h2>
+<pre><code class="language-c">void nng_msleep(nng_duration msec);
+</code></pre>
+<p>The <a name="a009"></a><code>nng_msleep</code> function blocks the calling thread for at least the specified
+number of milliseconds.</p>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  tip
+</p>
+<p>This function may block for longer than requested.
+The actual wait time is determined by the capabilities of the
+underlying system.</p>
+</div>
+<h2 id="wait-asynchronously"><a class="header" href="#wait-asynchronously">Wait Asynchronously</a></h2>
+<pre><code class="language-c">void nng_sleep_aio(nng_duration msec, nng_aio *aio);
+</code></pre>
+<p>It is possible to wait as the action on an <a href="/TODO.html"><code>nng_aio</code></a>, which in effect
+acts like <a name="a010"></a>scheduling a callback to run after a specified period of time.</p>
+<p>The <a name="a011"></a><code>nng_sleep_aio</code> function provides this capability.
+After <em>msec</em> milliseconds have passed, then <em>aio</em>’s callback will be executed.
+If this sleep waits without interruption, and then completes, the result from
+<a href="/api/api.html#result-of-operation"><code>nng_aio_result</code></a> will be zero.</p>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  note
+</p>
+<p>If a timeout shorter than <em>msec</em> is set on <em>aio</em> using <a href="/TODO.html"><code>nng_aio_set_timeout</code></a>,
+then the sleep will wake up early, with a result code of <a href="/api/errors.html#NNG_ETIMEDOUT"><code>NNG_ETIMEDOUT</code></a>.</p>
+</div>
+<h2 id="see-also"><a class="header" href="#see-also">See Also</a></h2>
+<p><a href="/api/aio.html">Asynchronous Operations</a>,
+<a href="/api/synch.html">Synchronization</a></p>
+<!-- Symbol cross reference -->
+<!-- Macros -->
+<!-- Protocols -->
+<!-- Transports -->
+<!-- Concept index -->
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../api/memory.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+
+                            <a rel="next prefetch" href="../api/url.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="../api/memory.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+
+                    <a rel="next prefetch" href="../api/url.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="../elasticlunr.min.js"></script>
+        <script src="../mark.min.js"></script>
+        <script src="../searcher.js"></script>
+
+        <script src="../clipboard.min.js"></script>
+        <script src="../highlight.js"></script>
+        <script src="../book.js"></script>
+
+        <!-- Custom JS scripts -->
+        <script src="../theme/pagetoc.js"></script>
+
+
+    </div>
+    </body>
+</html>
diff --git a/ref/api/url.html b/ref/api/url.html
new file mode 100644
index 00000000..3f13797f
--- /dev/null
+++ b/ref/api/url.html
@@ -0,0 +1,370 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>URLs - NNG Reference Manual (DRAFT)</title>
+
+
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="../favicon.svg">
+        <link rel="shortcut icon" href="../favicon.png">
+        <link rel="stylesheet" href="../css/variables.css">
+        <link rel="stylesheet" href="../css/general.css">
+        <link rel="stylesheet" href="../css/chrome.css">
+        <link rel="stylesheet" href="../css/print.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="../fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="../highlight.css">
+        <link rel="stylesheet" href="../tomorrow-night.css">
+        <link rel="stylesheet" href="../ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+        <link rel="stylesheet" href="../theme/pagetoc.css">
+
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "../";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded affix "><a href="../copyright.html">Copyright</a></li><li class="chapter-item expanded affix "><a href="../dedication.html">Dedication</a></li><li class="chapter-item expanded affix "><a href="../preface.html">Preface</a></li><li class="chapter-item expanded "><a href="../api/index.html"><strong aria-hidden="true">1.</strong> API Reference</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../api/msg.html"><strong aria-hidden="true">1.1.</strong> Messages</a></li><li class="chapter-item expanded "><a href="../api/memory.html"><strong aria-hidden="true">1.2.</strong> Memory</a></li><li class="chapter-item expanded "><a href="../api/time.html"><strong aria-hidden="true">1.3.</strong> Time</a></li><li class="chapter-item expanded "><a href="../api/url.html" class="active"><strong aria-hidden="true">1.4.</strong> URLs</a></li><li class="chapter-item expanded "><a href="../api/aio.html"><strong aria-hidden="true">1.5.</strong> Asynchronous I/O</a></li><li class="chapter-item expanded "><a href="../api/synch.html"><strong aria-hidden="true">1.6.</strong> Synchronization</a></li><li class="chapter-item expanded "><a href="../api/thread.html"><strong aria-hidden="true">1.7.</strong> Threads</a></li><li class="chapter-item expanded "><a href="../api/logging.html"><strong aria-hidden="true">1.8.</strong> Logging</a></li><li class="chapter-item expanded "><a href="../api/stats.html"><strong aria-hidden="true">1.9.</strong> Statistics</a></li><li class="chapter-item expanded "><a href="../api/errors.html"><strong aria-hidden="true">1.10.</strong> Errors</a></li><li class="chapter-item expanded "><a href="../api/misc.html"><strong aria-hidden="true">1.11.</strong> Miscellaneous</a></li><li class="chapter-item expanded "><a href="../api/id_map.html"><strong aria-hidden="true">1.12.</strong> ID Map</a></li><li class="chapter-item expanded "><a href="../api/cmd_opts.html"><strong aria-hidden="true">1.13.</strong> Command Options</a></li></ol></li><li class="chapter-item expanded "><a href="../proto/index.html"><strong aria-hidden="true">2.</strong> Protocols</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../proto/bus.html"><strong aria-hidden="true">2.1.</strong> BUS Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pair.html"><strong aria-hidden="true">2.2.</strong> PAIR Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pub.html"><strong aria-hidden="true">2.3.</strong> PUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/pull.html"><strong aria-hidden="true">2.4.</strong> PULL Protocol</a></li><li class="chapter-item expanded "><a href="../proto/push.html"><strong aria-hidden="true">2.5.</strong> PUSH Protocol</a></li><li class="chapter-item expanded "><a href="../proto/rep.html"><strong aria-hidden="true">2.6.</strong> REP Protocol</a></li><li class="chapter-item expanded "><a href="../proto/req.html"><strong aria-hidden="true">2.7.</strong> REQ Protocol</a></li><li class="chapter-item expanded "><a href="../proto/respondent.html"><strong aria-hidden="true">2.8.</strong> RESPONDENT Protocol</a></li><li class="chapter-item expanded "><a href="../proto/sub.html"><strong aria-hidden="true">2.9.</strong> SUB Protocol</a></li><li class="chapter-item expanded "><a href="../proto/surveyor.html"><strong aria-hidden="true">2.10.</strong> SURVEYOR Protocol</a></li></ol></li><li class="chapter-item expanded "><a href="../tran/index.html"><strong aria-hidden="true">3.</strong> Transports</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../tran/inproc.html"><strong aria-hidden="true">3.1.</strong> Intra-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/ipc.html"><strong aria-hidden="true">3.2.</strong> Inter-Process Transport</a></li><li class="chapter-item expanded "><a href="../tran/socket.html"><strong aria-hidden="true">3.3.</strong> BSD Socket (Experimental)</a></li><li class="chapter-item expanded "><a href="../tran/udp.html"><strong aria-hidden="true">3.4.</strong> UDP Transport (Experimental)</a></li></ol></li><li class="chapter-item expanded "><a href="../migrate/index.html"><strong aria-hidden="true">4.</strong> Migration Guides</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../migrate/nng1.html"><strong aria-hidden="true">4.1.</strong> Migrating from NNG 1.x</a></li><li class="chapter-item expanded "><a href="../migrate/nanomsg.html"><strong aria-hidden="true">4.2.</strong> Migrating from libnanomsg</a></li></ol></li><li class="chapter-item expanded "><a href="../indexing.html">Index</a></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
+                <div class="sidebar-resize-indicator"></div>
+            </div>
+        </nav>
+
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">NNG Reference Manual (DRAFT)</h1>
+
+                    <div class="right-buttons">
+                        <a href="../print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <style>
+.mdbook-alerts {
+  padding: 8px 16px;
+  margin-bottom: 16px;
+  border-left: 0.25em solid var(--mdbook-alerts-color);
+}
+
+.mdbook-alerts > *:first-child {
+  margin-top: 0;
+}
+
+.mdbook-alerts > *:last-child {
+  margin-bottom: 0;
+}
+
+.mdbook-alerts-title {
+  display: flex;
+  font-weight: 600;
+  align-items: center;
+  line-height: 1;
+  color: var(--mdbook-alerts-color);
+  text-transform: capitalize;
+}
+
+.mdbook-alerts-icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  margin-right: 0.2em;
+  background-color: currentColor;
+  -webkit-mask: no-repeat center / 100%;
+  mask: no-repeat center / 100%;
+  -webkit-mask-image: var(--mdbook-alerts-icon);
+  mask-image: var(--mdbook-alerts-icon);
+}
+
+.mdbook-alerts-note {
+  --mdbook-alerts-color: rgb(9, 105, 218);
+  /* https://icon-sets.iconify.design/material-symbols/info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16v-4q0-.425-.288-.712T12 11q-.425 0-.712.288T11 12v4q0 .425.288.713T12 17m0-8q.425 0 .713-.288T13 8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8q0 .425.288.713T12 9m0 13q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12q0-3.35-2.325-5.675T12 4Q8.65 4 6.325 6.325T4 12q0 3.35 2.325 5.675T12 20m0-8"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-tip {
+  --mdbook-alerts-color: rgb(26, 127, 55);
+  /* https://icon-sets.iconify.design/material-symbols/lightbulb-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 22q-.825 0-1.412-.587T10 20h4q0 .825-.587 1.413T12 22m-3-3q-.425 0-.712-.288T8 18q0-.425.288-.712T9 17h6q.425 0 .713.288T16 18q0 .425-.288.713T15 19zm-.75-3q-1.725-1.025-2.738-2.75T4.5 9.5q0-3.125 2.188-5.312T12 2q3.125 0 5.313 2.188T19.5 9.5q0 2.025-1.012 3.75T15.75 16zm.6-2h6.3q1.125-.8 1.738-1.975T17.5 9.5q0-2.3-1.6-3.9T12 4Q9.7 4 8.1 5.6T6.5 9.5q0 1.35.613 2.525T8.85 14M12 14"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-important {
+  --mdbook-alerts-color: rgb(130, 80, 223);
+  /* https://icon-sets.iconify.design/material-symbols/chat-info-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 7q.425 0 .713-.288T13 6q0-.425-.288-.712T12 5q-.425 0-.712.288T11 6q0 .425.288.713T12 7m0 8q.425 0 .713-.288T13 14v-4q0-.425-.288-.712T12 9q-.425 0-.712.288T11 10v4q0 .425.288.713T12 15m-6 3l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-warning {
+  --mdbook-alerts-color: rgb(154, 103, 0);
+  /* https://icon-sets.iconify.design/material-symbols/warning-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M2.725 21q-.275 0-.5-.137t-.35-.363q-.125-.225-.137-.488t.137-.512l9.25-16q.15-.25.388-.375T12 3q.25 0 .488.125t.387.375l9.25 16q.15.25.138.513t-.138.487q-.125.225-.35.363t-.5.137zm1.725-2h15.1L12 6zM12 18q.425 0 .713-.288T13 17q0-.425-.288-.712T12 16q-.425 0-.712.288T11 17q0 .425.288.713T12 18m0-3q.425 0 .713-.288T13 14v-3q0-.425-.288-.712T12 10q-.425 0-.712.288T11 11v3q0 .425.288.713T12 15m0-2.5"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-caution {
+  --mdbook-alerts-color: rgb(207, 34, 46);
+  /* https://icon-sets.iconify.design/material-symbols/brightness-alert-outline-rounded/ */
+  --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16q0-.425-.288-.712T12 15q-.425 0-.712.288T11 16q0 .425.288.713T12 17m0-4q.425 0 .713-.288T13 12V8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8v4q0 .425.288.713T12 13m-3.35 7H6q-.825 0-1.412-.587T4 18v-2.65L2.075 13.4q-.275-.3-.425-.662T1.5 12q0-.375.15-.737t.425-.663L4 8.65V6q0-.825.588-1.412T6 4h2.65l1.95-1.925q.3-.275.663-.425T12 1.5q.375 0 .738.15t.662.425L15.35 4H18q.825 0 1.413.588T20 6v2.65l1.925 1.95q.275.3.425.663t.15.737q0 .375-.15.738t-.425.662L20 15.35V18q0 .825-.587 1.413T18 20h-2.65l-1.95 1.925q-.3.275-.662.425T12 22.5q-.375 0-.737-.15t-.663-.425zm.85-2l2.5 2.5l2.5-2.5H18v-3.5l2.5-2.5L18 9.5V6h-3.5L12 3.5L9.5 6H6v3.5L3.5 12L6 14.5V18zm2.5-6"%2F%3E%3C%2Fsvg%3E');
+}
+
+</style>
+<h1 id="urls"><a class="header" href="#urls">URLs</a></h1>
+<p><a name="a001"></a>Universal Resource Locators, or <a name="a002"></a>URLs for short, are a standardized
+way of representing a network resource,
+defined in <a href="https://datatracker.ietf.org/doc/html/rfc1738">RFC 1738</a>,
+and <a href="https://datatracker.ietf.org/doc/html/rfc3986">RFC 3968</a>.</p>
+<p>In Scalability Protocols, this concept is extended, although it includes schemes
+that are not part of the IETF standards.</p>
+<h2 id="url-structure"><a class="header" href="#url-structure">URL Structure</a></h2>
+<pre><code class="language-c">typedef struct nng_url {
+    char *u_rawurl;
+    char *u_scheme;
+    char *u_userinfo;
+    char *u_host;
+    char *u_hostname;
+    char *u_port;
+    char *u_path;
+    char *u_query;
+    char *u_fragment;
+    char *u_requri;
+} nng_url;
+</code></pre>
+<h3 id="url-fields"><a class="header" href="#url-fields">URL Fields</a></h3>
+<p>Applications may access individual fields, but must not free or
+alter them, as the underlying memory is managed by the library.</p>
+<p>The fields of an <code>nng_url</code> object are as follows:</p>
+<ul>
+<li><code>u_rawurl</code>: The unparsed URL string. This will never be <code>NULL</code>.</li>
+<li><code>u_scheme</code>: The URL scheme, such as “http” or “inproc”. Always lower case. This will never be <code>NULL</code>.</li>
+<li><code>u_userinfo</code>: This username and password if supplied in the URL string. Will be <code>NULL</code> when not present.</li>
+<li><code>u_host</code>: The full host part of the URL, including the port if present (separated by a colon.)</li>
+<li><code>u_hostname</code>: The name of the host, and may be the empty string in some cases.</li>
+<li><code>u_port</code>: The port. May be empty if irrelevant or not specified.</li>
+<li><code>u_path</code>: The path, typically used with HTTP or WebSockets. Will be empty string if not specified.</li>
+<li><code>u_query</code>: The query info (typically following <code>?</code> in the URL.) Will be <code>NULL</code> if not present.</li>
+<li><code>u_fragment</code>: This is used for specifying an anchor, the part after <code>#</code> in a URL. Will be <code>NULL</code> if not present.</li>
+<li><code>u_requri</code>: The full Request-URI. Will be the empty string if not specified.</li>
+</ul>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  note
+</p>
+<p>Other fields may also be present, but only those documented here are safe for application use.</p>
+</div>
+<h2 id="parse-a-url"><a class="header" href="#parse-a-url">Parse a URL</a></h2>
+<pre><code class="language-c">int nng_url_parse(nng_url **urlp, const char *str);
+</code></pre>
+<p>The <a name="a003"></a><code>nng_url_parse</code> function parses a URL string (in <em>str</em>),
+and creates a dynamically allocated <code>nng_url</code>, returning it in <em>urlp</em>.</p>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
+<p>Only <a href="/api/url.html#destroy-a-url"><code>nng_url_free</code></a> should be used to deallocate <code>nng_url</code> objects.</p>
+</div>
+<h2 id="clone-a-url"><a class="header" href="#clone-a-url">Clone a URL</a></h2>
+<pre><code class="language-c">int nng_url_clone(nng_url **dup, nng_url *url);
+</code></pre>
+<p>The <a name="a004"></a><code>nng_url_clone</code> function creates a copy of <em>url</em>, and returns it in <em>dup</em>.</p>
+<h2 id="destroy-a-url"><a class="header" href="#destroy-a-url">Destroy a URL</a></h2>
+<pre><code class="language-c">void nng_url_free(nng_url *url);
+</code></pre>
+<p>The <a name="a005"></a><code>nng_url_free</code> function destroy an <code>nng_url</code> object created with
+either <a href="/api/url.html#parse-a-url"><code>nng_url_parse</code></a> or <a href="/api/url.html#destroy-a-url"><code>nng_url_free</code></a>.</p>
+<p>This is the only correct way to destroy an <a href="/api/url.html#url-structure"><code>nng_url</code></a> object.</p>
+<h2 id="see-also"><a class="header" href="#see-also">See Also</a></h2>
+<p>More information about Universal Resource Locators can be found in
+<a href="https://tools.ietf.org/html/rfc3986">RFC 3986</a>.</p>
+<!-- Symbol cross reference -->
+<!-- Macros -->
+<!-- Protocols -->
+<!-- Transports -->
+<!-- Concept index -->
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../api/time.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+
+                            <a rel="next prefetch" href="../api/aio.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="../api/time.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+
+                    <a rel="next prefetch" href="../api/aio.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="../elasticlunr.min.js"></script>
+        <script src="../mark.min.js"></script>
+        <script src="../searcher.js"></script>
+
+        <script src="../clipboard.min.js"></script>
+        <script src="../highlight.js"></script>
+        <script src="../book.js"></script>
+
+        <!-- Custom JS scripts -->
+        <script src="../theme/pagetoc.js"></script>
+
+
+    </div>
+    </body>
+</html>
author	gdamore <gdamore@users.noreply.github.com>	2024-10-27 18:55:51 +0000
committer	gdamore <gdamore@users.noreply.github.com>	2024-10-27 18:55:51 +0000
commit	45ac4fa56b6e5c31a28fd08eaad14a09bf3934f6 (patch)
tree	e0ed7b8907d4f6ac5651fb6c9d38556ec46b231a /ref/api
parent	b83fdb3ff1327e4376acd0ca24479b16b24f7e0b (diff)
download	nng-45ac4fa56b6e5c31a28fd08eaad14a09bf3934f6.tar.gz nng-45ac4fa56b6e5c31a28fd08eaad14a09bf3934f6.tar.bz2 nng-45ac4fa56b6e5c31a28fd08eaad14a09bf3934f6.zip