deploy: af596b6ccf14b4d2fc2f5c6ef04870186d99d828

1 files changed, 19 insertions, 7 deletions

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">