deploy: af596b6ccf14b4d2fc2f5c6ef04870186d99d828

3 files changed, 29 insertions, 16 deletions

diff --git a/ref/api/http.html b/ref/api/http.html
index aac5ec43..67c7048e 100644
--- a/ref/api/http.html
+++ b/ref/api/http.html
@@ -410,7 +410,7 @@ for display to users.</p>
 </div>
 <h3 id="retrieving-headers"><a class="header" href="#retrieving-headers">Retrieving Headers</a></h3>
 <pre><code class="language-c">const char *nng_http_get_header(nng_http *conn, const char *key);
-bool nng_next_header(nng_http *conn, const char **keyp, const char **valuep, void **next);
+bool nng_http_next_header(nng_http *conn, const char **keyp, const char **valuep, void **next);
 </code></pre>
 <p>The <a name="a013"></a><code>nng_http_get_header</code> returns the header value matching <em>key</em> that was received over <em>conn</em>,
 or <code>NULL</code> if no such header exists.</p>
@@ -776,7 +776,8 @@ final argument is the <a href="/api/aio.html#asynchronous-io-handle"><code>nng_a
 it may simply let the framework do so on its behalf. The server will perform
 this step if the callback has not already done so.</p>
 <p>Response headers may be set using <a href="/api/http.html#modifying-headers"><code>nng_http_set_header</code></a>, and request headers
-may be accessed by using <a href="/api/http.html#retrieving-headers"><code>nng_http_get_header</code></a>.</p>
+may be accessed by using <a href="/api/http.html#retrieving-headers"><code>nng_http_get_header</code></a>. They can also be iterated
+over using <a href="/api/http.html#retrieving-headers"><code>nng_http_next_header</code></a></p>
 <p>Likewise the request body may be accessed, using <a href="/api/http.html#retrieving-body-content"><code>nng_http_get_body</code></a>, and
 the response body may be set using either <a href="/api/http.html#storing-body-content"><code>nng_http_set_body</code></a> or <a href="/api/http.html#storing-body-content"><code>nng_http_copy_body</code></a>.</p>
 <div class="mdbook-alerts mdbook-alerts-note">
diff --git a/ref/api/pipe.html b/ref/api/pipe.html
index 8167c9f4..5f7f5efd 100644
--- a/ref/api/pipe.html
+++ b/ref/api/pipe.html
@@ -331,7 +331,10 @@ nng_err nng_pipe_get_int(nng_pipe p, const char *opt, int *valp);
 nng_err nng_pipe_get_ms(nng_pipe p, const char *opt, nng_duration *valp);
 nng_err nng_pipe_get_size(nng_pipe p, const char *opt, size_t *valp);
 nng_err nng_pipe_get_addr(nng_pipe p, const char *opt, nng_sockaddr *valp);
-nng_err nng_pipe_get_string(nng_pipe p, const char *opt, char **valp);
+nng_err nng_pipe_get_string(nng_pipe p, const char *opt, const char **valp);
+nng_err nng_pipe_get_strcpy(nng_pipe p, const char *opt, char *val, size_t len);
+nng_err nng_pipe_get_strdup(nng_pipe p, const char *opt, char **valp);
+nng_err nng_pipe_get_strlen(nng_pipe p, const char *opt, size_t *lenp);
 </code></pre>
 <p><a name="a010"></a>
 <a name="a011"></a>
@@ -339,12 +342,21 @@ nng_err nng_pipe_get_string(nng_pipe p, const char *opt, char **valp);
 <a name="a013"></a>
 <a name="a014"></a>
 <a name="a015"></a>
+<a name="a016"></a>
+<a name="a017"></a>
 These functions are used to obtain value of an option named <em>opt</em> from the pipe <em>p</em>, and store it in the location
 referenced by <em>valp</em>.</p>
 <p>These functions access an option as a specific type. The transport layer will have details about which options
 are available, and which type they may be accessed using.</p>
-<p>In the case of <code>nng_pipe_get_string</code>, the string is created as if by <a href="/api/memory.html#duplicate-string"><code>nng_strdup</code></a>, and must be freed by
-the caller using <a href="/api/memory.html#free-string"><code>nng_strfree</code></a> when no longer needed.</p>
+<p>In the case of <code>nng_pipe_get_string</code>, the underlying string may only be valid for as long as the pipe is valid.
+Thus, this function can only be safely called in a pipe event callback set up with <a href="/api/pipe.html#pipe-notifications"><code>nng_pipe_notify</code></a>.</p>
+<p>The <code>nng_pipe_get_strdup</code> function is like <code>nng_pipe_get_string</code>, but makes a copy into a newly allocated buffer, so that the string must be freed by the caller using <a href="/api/memory.html#free-string"><code>nng_strfree</code></a>.</p>
+<p>The <code>nng_pipe_get_strcpy</code> function is also like <code>nng_pipe_get_string</code>, but it makes a copy into a buffer
+supplied by the caller. The buffer is passed in <em>val</em>, and the size of the buffer is passed in <em>len</em>.
+The value of <em>len</em> must be large enough to hold the string and the terminating zero byte.</p>
+<p>The <code>nng_pipe_get_strlen</code> function is used to obtain the length of the string. This can be useful
+to find the size of the buffer needed by the <code>nng_pipe_get_strcpy</code> function for a property.
+Note that like <code>strlen</code>, this size does not account for the zero byte to terminate the string.</p>
 <h2 id="pipe-notifications"><a class="header" href="#pipe-notifications">Pipe Notifications</a></h2>
 <pre><code class="language-c">typedef enum {
         NNG_PIPE_EV_ADD_PRE,
@@ -356,7 +368,7 @@ typedef void (*nng_pipe_cb)(nng_pipe, nng_pipe_ev, void *);
 
 nng_err nng_pipe_notify(nng_socket s, nng_pipe_ev ev, nng_pipe_cb cb, void *arg);
 </code></pre>
-<p>The <a name="a016"></a><code>nng_pipe_notify</code> function registers the callback function <em>cb</em>
+<p>The <a name="a018"></a><code>nng_pipe_notify</code> function registers the callback function <em>cb</em>
 to be called whenever the pipe event specified by
 <em>ev</em> occurs on the socket <em>s</em>.
 The callback <em>cb</em> will be passed <em>arg</em> as its final argument.</p>
@@ -365,9 +377,9 @@ Each event may have at most one callback registered.
 Registering a callback implicitly unregisters any previously registered.</p>
 <p>The following pipe events are supported:</p>
 <div class="table-wrapper"><table><thead><tr><th>Event</th><th>Description</th></tr></thead><tbody>
-<tr><td><a name="a017"></a><code>NNG_PIPE_EV_ADD_PRE</code><a name="NNG_PIPE_EV_ADD_PRE"></a></td><td>This event occurs after a connection and negotiation has completed, but before the pipe is added to the socket. If the pipe is closed (using <a href="/api/pipe.html#closing-a-pipe"><code>nng_pipe_close</code></a>) at this point, the socket will never see the pipe, and no further events will occur for the given pipe.</td></tr>
-<tr><td><a name="a018"></a><code>NNG_PIPE_EV_ADD_POST</code><a name="NNG_PIPE_EV_ADD_POST"></a></td><td>This event occurs after the pipe is fully added to the socket. Prior to this time, it is not possible to communicate over the pipe with the socket.</td></tr>
-<tr><td><a name="a019"></a><code>NNG_PIPE_EV_REM_POST</code><a name="NNG_PIPE_EV_REM_POST"></a></td><td>This event occurs after the pipe has been removed from the socket. The underlying transport may be closed at this point, and it is not possible communicate using this pipe.</td></tr>
+<tr><td><a name="a019"></a><code>NNG_PIPE_EV_ADD_PRE</code><a name="NNG_PIPE_EV_ADD_PRE"></a></td><td>This event occurs after a connection and negotiation has completed, but before the pipe is added to the socket. If the pipe is closed (using <a href="/api/pipe.html#closing-a-pipe"><code>nng_pipe_close</code></a>) at this point, the socket will never see the pipe, and no further events will occur for the given pipe.</td></tr>
+<tr><td><a name="a020"></a><code>NNG_PIPE_EV_ADD_POST</code><a name="NNG_PIPE_EV_ADD_POST"></a></td><td>This event occurs after the pipe is fully added to the socket. Prior to this time, it is not possible to communicate over the pipe with the socket.</td></tr>
+<tr><td><a name="a021"></a><code>NNG_PIPE_EV_REM_POST</code><a name="NNG_PIPE_EV_REM_POST"></a></td><td>This event occurs after the pipe has been removed from the socket. The underlying transport may be closed at this point, and it is not possible communicate using this pipe.</td></tr>
 </tbody></table>
 </div><div class="mdbook-alerts mdbook-alerts-warning">
 <p class="mdbook-alerts-title">
diff --git a/ref/api/stream.html b/ref/api/stream.html
index eba3053f..a39434c5 100644
--- a/ref/api/stream.html
+++ b/ref/api/stream.html
@@ -318,7 +318,7 @@ nng_err nng_stream_get_int(nng_stream *s, const char *opt, int *valp);
 nng_err nng_stream_get_ms(nng_stream *s, const char *opt, nng_duration *valp);
 nng_err nng_stream_get_size(nng_stream *s, const char *opt, size_t *valp);
 nng_err nng_stream_get_addr(nng_stream *s, const char *opt, nng_sockaddr *valp);
-nng_err nng_stream_get_string(nng_stream *s, const char *opt, char **valp);
+nng_err nng_stream_get_string(nng_stream *s, const char *opt, const char **valp);
 </code></pre>
 <p><a name="a008"></a>
 <a name="a009"></a>
@@ -330,8 +330,8 @@ These functions are used to obtain value of an option named <em>opt</em> from th
 referenced by <em>valp</em>.</p>
 <p>These functions access an option as a specific type. The transport layer will have details about which options
 are available, and which type they may be accessed using.</p>
-<p>In the case of <code>nng_stream_get_string</code>, the string is created as if by <a href="/api/memory.html#duplicate-string"><code>nng_strdup</code></a>, and must be freed by
-the caller using <a href="/api/memory.html#free-string"><code>nng_strfree</code></a> when no longer needed.</p>
+<p>In the case of <code>nng_stream_get_string</code>, the string pointer is only guaranteed to be valid while the
+stream exists. Callers should make a copy of the data if required before closing the stream.</p>
 <h2 id="stream-factories"><a class="header" href="#stream-factories">Stream Factories</a></h2>
 <pre><code class="language-c">typedef struct nng_stream_dialer nng_stream_dialer;
 typedef struct nng_stream_listener nng_stream_listener;
@@ -459,14 +459,14 @@ nng_err nng_stream_dialer_get_bool(nng_stream_dialer *dialer, const char *opt, b
 nng_err nng_stream_dialer_get_int(nng_stream_dialer *dialer, const char *opt, int *valp);
 nng_err nng_stream_dialer_get_ms(nng_stream_dialer *dialer, const char *opt, nng_duration *valp);
 nng_err nng_stream_dialer_get_size(nng_stream_dialer *dialer, const char *opt, size_t *valp);
-nng_err nng_stream_dialer_get_string(nng_stream_dialer *dialer, const char *opt, char **valp);
+nng_err nng_stream_dialer_get_string(nng_stream_dialer *dialer, const char *opt, const char **valp);
 
 nng_err nng_stream_listener_get_addr(nng_stream_listener *listener, const char *opt, nng_sockaddr *valp);
 nng_err nng_stream_listener_get_bool(nng_stream_listener *listener, const char *opt, bool *valp);
 nng_err nng_stream_listener_get_int(nng_stream_listener *listener, const char *opt, int *valp);
 nng_err nng_stream_listener_get_ms(nng_stream_listener *listener, const char *opt, nng_duration *valp);
 nng_err nng_stream_listener_get_size(nng_stream_listener *listener, const char *opt, size_t *valp);
-nng_err nng_stream_listener_get_string(nng_stream_listener *listener, const char *opt, char **valp);
+nng_err nng_stream_listener_get_string(nng_stream_listener *listener, const char *opt, const char **valp);
 
 nng_err nng_stream_dialer_set_addr(nng_stream_dialer *dialer, const char *opt, const nng_sockaddr *val);
 nng_err nng_stream_dialer_set_bool(nng_stream_dialer *dialer, const char *opt, bool val);
@@ -511,8 +511,8 @@ The <code>nng_stream_dialer_get_</code> and <code>nng_stream_listener_get_</code
 The <code>nng_stream_dialer_set_</code> and <code>nng_stream_listener_set_</code> function families change the value for the <em>dialer</em> or <em>listener</em>, taking it from <em>val</em>.</p>
 <p>These functions access an option as a specific type. The transport layer will have details about which options
 are available, and which type they may be accessed using.</p>
-<p>In the case of <code>nng_stream_dialer_get_string</code> and <code>nng_stream_listener_get_string</code>, the string is created as if by <a href="/api/memory.html#duplicate-string"><code>nng_strdup</code></a>, and must be freed by
-the caller using <a href="/api/memory.html#free-string"><code>nng_strfree</code></a> when no longer needed.</p>
+<p>In the case of <code>nng_stream_dialer_get_string</code> and <code>nng_stream_listener_get_string</code>, the memory holding
+the string is only valid as long as the associated object remains open.</p>
 <p>In the case of <code>nng_stream_dialer_set_string</code> and <code>nng_stream_listener_set_string</code>, the string contents are copied if necessary, so that the caller
 need not retain the value referenced once the function returns.</p>
 <p>In the case of <code>nng_stream_dialer_set_addr</code> and <code>nng_stream_listener_set_addr</code>, the contents of <em>addr</em> are copied if necessary, so that the caller