From 3971d119c129bf5685f9fd14d0f1f785581c3565 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Tue, 7 Oct 2025 20:03:32 -0700
Subject: options: string options are passed by reference

This avoids needless allocations, and we offer for pipes (which need
this because they might be ephemeral) the get_strdup, get_strcpy,
and get_strlen forms. (Those do the copying or allocations while holding
the pipe reference.)
---
 docs/ref/api/pipe.md | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

(limited to 'docs/ref/api/pipe.md')

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
 
-- 
cgit v1.2.3-70-g09d2