4 files changed, 27 insertions, 18 deletions
diff --git a/docs/man/nng_dialer_get.3.adoc b/docs/man/nng_dialer_get.3.adoc
index 9b1e6577..575db971 100644
--- a/docs/man/nng_dialer_get.3.adoc
+++ b/docs/man/nng_dialer_get.3.adoc
@@ -29,7 +29,7 @@ int nng_dialer_get_size(nng_dialer d, const char *opt, size_t *zp);
 
 int nng_dialer_get_addr(nng_dialer d, const char *opt, nng_sockaddr *sap);
 
-int nng_dialer_get_string(nng_dialer d, const char *opt, char **strp);
+int nng_dialer_get_string(nng_dialer d, const char *opt, const char **strp);
 
 int nng_dialer_get_uint64(nng_dialer d, const char *opt, uint64_t *u64p);
 
@@ -77,9 +77,6 @@ into the value referenced by _sap_.
 
 `nng_dialer_get_string()`::
 This function is used to retrieve a string into _strp_.
-This string is created from the source using xref:nng_strdup.3.adoc[`nng_strdup()`]
-and consequently must be freed by the caller using
-xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed.
 
 `nng_dialer_get_uint64()`::
 This function is used to retrieve a 64-bit unsigned value into the value
diff --git a/docs/man/nng_listener_get.3.adoc b/docs/man/nng_listener_get.3.adoc
index a5df826d..4c4de6b4 100644
--- a/docs/man/nng_listener_get.3.adoc
+++ b/docs/man/nng_listener_get.3.adoc
@@ -29,7 +29,7 @@ int nng_listener_get_size(nng_listener l, const char *opt, size_t *zp);
 
 int nng_listener_get_addr(nng_listener l, const char *opt, nng_sockaddr *sap);
 
-int nng_listener_get_string(nng_listener l, const char *opt, char **strp);
+int nng_listener_get_string(nng_listener l, const char *opt, const char **strp);
 
 int nng_listener_get_uint64(nng_listener l, const char *opt, uint64_t *u64p);
 
@@ -75,9 +75,6 @@ into the value referenced by _sap_.
 
 `nng_listener_get_string()`::
 This function is used to retrieve a string into _strp_.
-This string is created from the source using xref:nng_strdup.3.adoc[`nng_strdup()`]
-and consequently must be freed by the caller using
-xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed.
 
 `nng_listener_get_uint64()`::
 This function is used to retrieve a 64-bit unsigned value into the value
diff --git a/docs/ref/api/pipe.md b/docs/ref/api/pipe.md
index fbd89120..4fae1d06 100644
--- a/docs/ref/api/pipe.md
+++ b/docs/ref/api/pipe.md
@@ -92,7 +92,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);
 ```
 
 {{hi:`nng_pipe_get_bool`}}
@@ -101,14 +104,26 @@ nng_err nng_pipe_get_string(nng_pipe p, const char *opt, char **valp);
 {{hi:`nng_pipe_get_size`}}
 {{hi:`nng_pipe_get_addr`}}
 {{hi:`nng_pipe_get_string`}}
+{{hi:`nng_pipe_get_strcpy`}}
+{{hi:`nng_pipe_get_strdup`}}
 These functions are used to obtain value of an option named _opt_ from the pipe _p_, and store it in the location
 referenced by _valp_.
 
 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.
 
-In the case of `nng_pipe_get_string`, the string is created as if by [`nng_strdup`], and must be freed by
-the caller using [`nng_strfree`] when no longer needed.
+In the case of `nng_pipe_get_string`, 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 [`nng_pipe_notify`].
+
+The `nng_pipe_get_strdup` function is like `nng_pipe_get_string`, but makes a copy into a newly allocated buffer, so that the string must be freed by the caller using [`nng_strfree`].
+
+The `nng_pipe_get_strcpy` function is also like `nng_pipe_get_string`, but it makes a copy into a buffer
+supplied by the caller. The buffer is passed in _val_, and the size of the buffer is passed in _len_.
+The value of _len_ must be large enough to hold the string and the terminating zero byte.
+
+The `nng_pipe_get_strlen` function is used to obtain the length of the string. This can be useful
+to find the size of the buffer needed by the `nng_pipe_get_strcpy` function for a property.
+Note that like `strlen`, this size does not account for the zero byte to terminate the string.
 
 ## Pipe Notifications
 
diff --git a/docs/ref/api/stream.md b/docs/ref/api/stream.md
index 5715990f..a2427a70 100644
--- a/docs/ref/api/stream.md
+++ b/docs/ref/api/stream.md
@@ -84,7 +84,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);
 ```
 
 {{hi:`nng_stream_get_bool`}}
@@ -99,8 +99,8 @@ referenced by _valp_.
 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.
 
-In the case of `nng_stream_get_string`, the string is created as if by [`nng_strdup`], and must be freed by
-the caller using [`nng_strfree`] when no longer needed.
+In the case of `nng_stream_get_string`, 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.
 
 ## Stream Factories
 
@@ -261,14 +261,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);
@@ -316,8 +316,8 @@ The `nng_stream_dialer_set_` and `nng_stream_listener_set_` function families ch
 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.
 
-In the case of `nng_stream_dialer_get_string` and `nng_stream_listener_get_string`, the string is created as if by [`nng_strdup`], and must be freed by
-the caller using [`nng_strfree`] when no longer needed.
+In the case of `nng_stream_dialer_get_string` and `nng_stream_listener_get_string`, the memory holding
+the string is only valid as long as the associated object remains open.
 
 In the case of `nng_stream_dialer_set_string` and `nng_stream_listener_set_string`, the string contents are copied if necessary, so that the caller
 need not retain the value referenced once the function returns.