Converted some utility pages

14 files changed, 257 insertions, 427 deletions

diff --git a/docs/man/nng_alloc.3.adoc b/docs/man/nng_alloc.3.adoc
deleted file mode 100644
index 93c03111..00000000
--- a/docs/man/nng_alloc.3.adoc
+++ /dev/null
@@ -1,56 +0,0 @@
-= nng_alloc(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_alloc - allocate memory
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-void *nng_alloc(size_t size);
-----
-
-== DESCRIPTION
-
-The `nng_alloc()` function allocates a contiguous memory region of
-at least _size_ bytes.
-The memory will be 64-bit aligned.
-
-The returned memory can be used to hold message buffers, in which
-case it can be directly passed to xref:nng_send.3.adoc[`nng_send()`] using
-the flag `NNG_FLAG_ALLOC`.  Alternatively, it can be freed when no
-longer needed using xref:nng_free.3.adoc[`nng_free()`].
-
-IMPORTANT: Do not use the system `free()` function to release this memory.
-On some platforms this may work, but it is not guaranteed and may lead
-to a crash or other undesirable and unpredictable behavior.
-
-== RETURN VALUES
-
-This function returns a pointer to the allocated memory on success,
-and `NULL` otherwise.
-
-== ERRORS
-
-No errors are returned, but a `NULL` return value should be
-treated the same as `NNG_ENOMEM`.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_free.3.adoc[nng_free(3)],
-xref:nng_send.3.adoc[nng_send(3)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_clock.3supp.adoc b/docs/man/nng_clock.3supp.adoc
deleted file mode 100644
index d413f1b2..00000000
--- a/docs/man/nng_clock.3supp.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-= nng_clock(3supp)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_clock - get time
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-#include <nng/supplemental/util/platform.h>
-
-typedef uint64_t nng_time;
-
-nng_time nng_clock(void);
-----
-
-== DESCRIPTION
-
-The `nng_clock()` 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.
-
-IMPORTANT: The reference time will be the same for a given program,
-but different programs may have different references.
-
-TIP: This function is intended mostly to help with setting appropriate
-timeouts using xref:nng_cv_until.3supp.adoc[`nng_cv_until()`].
-
-== RETURN VALUES
-
-Milliseconds since reference time.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_sleep_aio.3.adoc[nng_sleep_aio(3)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)],
-xref:nng_msleep.3supp.adoc[nng_msleep(3supp)],
-xref:nng_duration.5.adoc[nng_duration(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_free.3.adoc b/docs/man/nng_free.3.adoc
deleted file mode 100644
index b4fdc249..00000000
--- a/docs/man/nng_free.3.adoc
+++ /dev/null
@@ -1,53 +0,0 @@
-= nng_free(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_free - free memory
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-void nng_free(void *ptr, size_t size);
-----
-
-== DESCRIPTION
-
-The `nng_free()` function deallocates a memory region of size _size_,
-that was previously allocated by xref:nng_alloc.3.adoc[`nng_alloc()`] or
-xref:nng_recv.3.adoc[`nng_recv()`] with the `NNG_FLAG_ALLOC` flag.
-
-IMPORTANT: It is very important that _size_ match the allocation size
-used to allocate the memory.
-
-IMPORTANT: Do not attempt to use this function to deallocate memory
-obtained by a call to the system `malloc()` or `calloc()` functions,
-or the {cpp} `new` operator.
-Doing so may result in unpredictable
-behavior, including corruption of application memory.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_alloc.3.adoc[nng_alloc(3)],
-xref:nng_recv.3.adoc[nng_recv(3)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_id_map.3supp.adoc b/docs/man/nng_id_map.3supp.adoc
deleted file mode 100644
index 343c0667..00000000
--- a/docs/man/nng_id_map.3supp.adoc
+++ /dev/null
@@ -1,100 +0,0 @@
-= nng_id_map(3supp)
-//
-// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_id_map - identifier based mapping table
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-#include <nng/supplemental/util/idhash.h>
-
-typedef struct nng_id_map_s nng_id_map;
-
-#define NNG_MAP_RANDOM 1
-
-int   nng_id_map_alloc(nng_id_map **map_p, uint64_t lo, uint64_t hi, int flags);
-void  nng_id_map_free(nng_id_map *map);
-void *nng_id_get(nng_id_map *map, uint64_t id);
-int   nng_id_set(nng_id_map *map, uint64_t, void *value);
-int   nng_id_alloc(nng_id_map *map, uint64_t *id_p, void *value);
-int   nng_id_remove(nng_id_map *map, uint64_t id);
-
-----
-
-== DESCRIPTION
-
-These functions provide support for managing tables of data based on
-identifiers, ensuring that identifiers are allocated uniquely and within
-specified range limits.
-
-The table stores data pointers (which must not be `NULL`) at a logical numeric index.
-It does so efficiently, even if large gaps exist, and it provides a means to efficiently
-allocate a numeric identifier from a pool of unused identifiers.
-
-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 to order the availability of identifiers based on when they were freed is made.
-
-An initial table is allocated with `nng_id_map_alloc()`, which takes the lowest legal identifier in _lo_,
-and the largest legal identifier in _hi_.
-The new table is returned in _map_p_, and should be used as the _map_ argument to the rest of these functions.
-
-****
-As a special convenience, if these are specified as zero, then a full range of 32-bit identifiers is assumed.
-If identifiers larger than or equal to 2^32^ are required, then both _lo_ and _hi_ must be specified with the
-exact values desired.
-****
-
-The _flags_ argument is a bit mask of flags for the table.
-If `NNG_MAP_RANDOM` is specified, then the starting point for allocations is randomized, but subsequent allocations will then be monotonically increasing.
-This is useful to reduce the odds of different instances of an application using the same identifiers at the same time.
-
-The `nng_id_get()` function returns the value previously stored with the given identifier.
-If no value is currently associated with the identifer, it returns `NULL`.
-
-The `nng_id_set()` function sets the value with the associated identifier.
-This can be used to replace a previously allocated identifier.
-If the identifier was not previously allocated, then it is allocated as part of the call.
-This function does not necessarily honor the identifier range limits set for the map when it was allocated.
-
-The `nng_id_alloc()` function allocates a new identifier from the range for the map, and associates it with
-the supplied _value_.
-
-The `nng_id_remove()` function removes the identifier and its associated value from the table.
-
-NOTE: These functions are limited to storing at most 2^32^ identifiers, even though the identifers may
-themselves be larger than 2^32^.
-
-IMPORTANT: These functions are *not* thread-safe.
-Callers should use a xref:nng_mtx_lock.3supp[mutex] or similar approach when thread-safety is needed.
-
-== RETURN VALUES
-
-The `nng_id_map_alloc()`, `nng_id_set()`, `nng_id_alloc()`, and `nng_id_remove()` functions
-return 0 on success, or -1 on failure.
-
-The `nng_id_map_get()` function returns the requested data pointer, or `NULL` if the identifier was not found.
-
-== ERRORS
-
-[horizontal]
-`NNG_ENOENT`:: The _id_ does not exist in the table.
-`NNG_ENOMEM`:: Insufficient memory is available, or the table is full.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_mtx_lock.3supp.adoc[nng(7)]
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_random.3supp.adoc b/docs/man/nng_random.3supp.adoc
deleted file mode 100644
index 3f8ac39e..00000000
--- a/docs/man/nng_random.3supp.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-= nng_random(3supp)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_random - get random number
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-#include <nng/supplemental/util/platform.h>
-
-uint32_t nng_random(void);
-----
-
-== DESCRIPTION
-
-The `nng_random()` returns a random number.
-The value returned is suitable for use with cryptographic functions such as
-key generation.
-The value is obtained using platform specific cryptographically strong random
-number facilities when available.
-
-== RETURN VALUES
-
-Random number.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_strdup.3.adoc b/docs/man/nng_strdup.3.adoc
deleted file mode 100644
index 91c4854d..00000000
--- a/docs/man/nng_strdup.3.adoc
+++ /dev/null
@@ -1,56 +0,0 @@
-= nng_strdup(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_strdup - duplicate string
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-char *nng_strdup(const char *src);
-----
-
-== DESCRIPTION
-
-The `nng_strdup()` duplicates the string _src_ and returns it.
-
-This is logically equivalent to using xref:nng_alloc.3.adoc[`nng_alloc()`]
-to allocate a region of memory of `strlen(s) + 1` bytes, and then
-using `strcpy()` to copy the string into the destination before
-returning it.
-
-The returned string should be deallocated with
-xref:nng_strfree.3.adoc[`nng_strfree()`], or may be deallocated using the
-xref:nng_free.3.adoc[`nng_free()`] using the length of the returned string plus
-one (for the `NUL` terminating byte).
-
-IMPORTANT: Do not use the system `free()` or similar functions to deallocate
-the string, since those may use a different memory arena!
-
-== RETURN VALUES
-
-This function returns the new string on success, and `NULL` on failure.
-
-== ERRORS
-
-No errors are returned, but a `NULL` return value should be
-treated the same as `NNG_ENOMEM`.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_alloc.3.adoc[nng_alloc(3)],
-xref:nng_free.3.adoc[nng_free(3)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_strfree.3.adoc b/docs/man/nng_strfree.3.adoc
deleted file mode 100644
index 9250b834..00000000
--- a/docs/man/nng_strfree.3.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-= nng_strfree(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_strfree - free memory
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-void nng_strfree(char *str);
-----
-
-== DESCRIPTION
-
-The `nng_strfree()` function deallocates the string _str_.
-This is equivalent to using xref:nng_free.3.adoc[`nng_free()`] with
-the length of _str_ plus one (for the `NUL` terminating byte) as
-the size.
-
-IMPORTANT: This should only be used with strings that were allocated
-by xref:nng_strdup.3.adoc[`nng_strdup()`] or
-xref:nng_alloc.3.adoc[`nng_alloc()`].
-In all cases, the allocation size of the string must be the same
-as `strlen(__str__) + 1`.
-
-IMPORTANT: Consequently, if the a string created with
-xref:nng_strdup.3.adoc[`nng_strdup()`] is modified to be shorter, then
-it is incorrect to call this function.
-(The xref:nng_free.3.adoc[`nng_free()`] function can be used instead in that
-case, using the length of the original string plus one for the size.)
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_alloc.3.adoc[nng_alloc(3)],
-xref:nng_free.3.adoc[nng_free(3)],
-xref:nng_strdup.3.adoc[nng_strdup(3)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/ref/util/nng_alloc.adoc b/docs/ref/util/nng_alloc.adoc
new file mode 100644
index 00000000..61a79085
--- /dev/null
+++ b/docs/ref/util/nng_alloc.adoc
@@ -0,0 +1,35 @@
+## nng_alloc
+
+Allocate memory.
+
+### Synopsis
+
+```c
+#include <nng/nng.h>
+
+void *nng_alloc(size_t size);
+```
+
+### Description
+
+The `nng_alloc` function allocates a contiguous memory region of at least _size_ bytes.
+The memory will be 64-bit aligned.
+
+The returned memory can be used to hold message buffers, in which case it can be directly passed to xref:../nng_send.adoc[`nng_send`] using the flag ((`NNG_FLAG_ALLOC`)).
+Alternatively, it can be freed when no longer needed using xref:nng_free.adoc[`nng_free`].
+
+IMPORTANT: Do not use the system `free` function to release this memory.
+Doing so may lead to a crash or other undesirable and unpredictable behavior.
+
+### Return Values
+
+This function returns a pointer to the allocated memory on success, and `NULL` otherwise.
+
+### Errors
+
+No errors are returned, but a `NULL` return value should be treated the same as `NNG_ENOMEM`.
+
+### See Also
+
+xref:nng_free.adoc[nng_free],
+xref:../sock/nng_send.adoc[nng_send]
diff --git a/docs/ref/util/nng_clock.adoc b/docs/ref/util/nng_clock.adoc
new file mode 100644
index 00000000..0f43e3a4
--- /dev/null
+++ b/docs/ref/util/nng_clock.adoc
@@ -0,0 +1,34 @@
+## nng_clock
+
+Get time.
+
+### Synopsis
+
+```c
+#include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+typedef uint64_t nng_time;
+
+nng_time nng_clock(void);
+```
+
+### Description
+
+The `nng_clock` 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.
+
+NOTE: The reference time will be the same for a given program, but different programs may have different references.
+
+TIP: This function is intended to assist in setting appropriate timeouts.
+
+### Return Values
+
+Milliseconds since reference time.
+
+### See Also
+
+xref:../aio/nng_sleep_aio.adoc[nng_sleep_aio],
+xref:../aio/nng_cv_until.adoc[nng_cv_until],
+xref:nng_msleep.adoc[nng_msleep]
diff --git a/docs/ref/util/nng_free.adoc b/docs/ref/util/nng_free.adoc
new file mode 100644
index 00000000..60be4bfd
--- /dev/null
+++ b/docs/ref/util/nng_free.adoc
@@ -0,0 +1,25 @@
+## nng_free
+
+Free memory.
+
+### Synopsis
+
+```c
+#include <nng/nng.h>
+
+void nng_free(void *ptr, size_t size);
+```
+
+### Description
+
+The `nng_free` function deallocates a memory region of size _size_, that was previously allocated by xref:nng_alloc.adoc[`nng_alloc`] or xref:nng_recv.adoc[`nng_recv`] with the ((`NNG_FLAG_ALLOC`)) flag.
+
+IMPORTANT: It is very important that _size_ match the allocation size used to allocate the memory.
+
+IMPORTANT: Do not attempt to use this function to deallocate memory obtained by a call to the system `malloc` or `calloc` functions, or the {cpp} `new` operator.
+Doing so may result in unpredictable behavior, including corruption of application memory.
+
+### See Also
+
+xref:nng_alloc.adoc[nng_alloc],
+xref:nng_recv.adoc[nng_recv]
diff --git a/docs/ref/util/nng_id_map.adoc b/docs/ref/util/nng_id_map.adoc
new file mode 100644
index 00000000..373219d0
--- /dev/null
+++ b/docs/ref/util/nng_id_map.adoc
@@ -0,0 +1,77 @@
+## nng_id_map
+
+Identifier based mapping table.
+
+### Synopsis
+
+```c
+#include <nng/nng.h>
+#include <nng/supplemental/util/idhash.h>
+
+typedef struct nng_id_map_s nng_id_map;
+
+#define NNG_MAP_RANDOM 1
+
+int   nng_id_map_alloc(nng_id_map **map_p, uint64_t lo, uint64_t hi, int flags);
+void  nng_id_map_free(nng_id_map *map);
+void *nng_id_get(nng_id_map *map, uint64_t id);
+int   nng_id_set(nng_id_map *map, uint64_t, void *value);
+int   nng_id_alloc(nng_id_map *map, uint64_t *id_p, void *value);
+int   nng_id_remove(nng_id_map *map, uint64_t id);
+```
+
+### Description
+
+These functions provide support for managing tables of data based on identifiers, ensuring that identifiers are allocated uniquely and within specified range limits.
+
+The table stores data pointers (which must not be `NULL`) at a logical numeric index.
+It does so efficiently, even if large gaps exist.
+It also provides a means to efficiently allocate a numeric identifier from a pool of unused identifiers.
+
+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.footnote:[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.]
+
+
+An initial table is allocated with `nng_id_map_alloc`, which takes the lowest legal identifier in _lo_, and the largest legal identifier in _hi_.
+The new table is returned in _map_p_, and should be used as the _map_ argument to the rest of these functions.
+
+If _lo_ and _hi_ are both zero, then a full range of 32-bit identifiers is assumed.footnote:[Consequently, if identifiers larger than or equal to 2^32^ are required, then both _lo_ and _hi_ must be specified with the exact values desired.]
+
+The _flags_ argument is a bit mask of flags for the table, can contain the following value:
+
+((`NNG_MAP_RANDOM`)):: The starting point for allocations is randomized, but subsequent allocations will then be monotonically increasing.
+This is useful to reduce the odds of different instances of an application using the same identifiers concurrently.
+
+The `nng_id_get` function returns the value previously stored with the given identifier.
+If no value is currently associated with the identifer, it returns `NULL`.
+
+The `nng_id_set` function sets the value with the associated identifier.
+This can be used to replace a previously allocated identifier.
+If the identifier was not previously allocated, then it is allocated as part of the call.
+This function does not necessarily honor the identifier range limits set for the map when it was allocated.
+
+The `nng_id_alloc` function allocates a new identifier from the range for the map, and associates it with the supplied _value_.
+
+The `nng_id_remove` function removes the identifier and its associated value from the table.
+
+NOTE: These functions are limited to storing at most 2^32^-1 identifiers, even though the identifers may themselves be larger than 2^32^.
+
+IMPORTANT: These functions are *not* thread-safe.
+Callers should use a xref:../thr/nng_mtx_lock.adoc[mutex] or similar approach when thread-safety is needed.
+
+### Return Values
+
+The `nng_id_map_alloc`, `nng_id_set`, `nng_id_alloc`, and `nng_id_remove` functions
+return 0 on success, or -1 on failure.
+
+The `nng_id_map_get` function returns the requested data pointer, or `NULL` if the identifier was not found.
+
+### Errors
+
+[horizontal]
+`NNG_ENOENT`:: The _id_ does not exist in the table.
+`NNG_ENOMEM`:: Insufficient memory is available, or the table is full.
+
+### See Also
+
+xref:../thr/index.adoc[Threads & Synchronization]
diff --git a/docs/ref/util/nng_random.adoc b/docs/ref/util/nng_random.adoc
new file mode 100644
index 00000000..f03a97e4
--- /dev/null
+++ b/docs/ref/util/nng_random.adoc
@@ -0,0 +1,22 @@
+## nng_random
+
+Get random number.
+
+### Synopsis
+
+```c
+#include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+uint32_t nng_random(void);
+```
+
+### Description
+
+The `nng_random` returns a random number.
+The value returned is suitable for use with cryptographic functions such as key generation.
+The value is obtained using platform specific cryptographically strong random number facilities when available.
+
+### Return Values
+
+Random 32-bit unsigned number.
diff --git a/docs/ref/util/nng_strdup.adoc b/docs/ref/util/nng_strdup.adoc
new file mode 100644
index 00000000..6c49b05c
--- /dev/null
+++ b/docs/ref/util/nng_strdup.adoc
@@ -0,0 +1,36 @@
+## nng_strdup
+
+Duplicate string.
+
+### Synopsis
+
+```c
+#include <nng/nng.h>
+
+char *nng_strdup(const char *src);
+```
+
+### Description
+
+The `nng_strdup` duplicates the string _src_ and returns it.
+
+This is logically equivalent to using xref:nng_alloc.adoc[`nng_alloc`] to allocate a region of memory of `strlen(s) + 1` bytes, and then using `strcpy` to copy the string into the destination before returning it.
+
+The returned string should be deallocated using xref:nng_strfree.adoc[`nng_strfree`], or using the xref:nng_free.adoc[`nng_free`] with the length of the returned string plus one (for the `NUL` terminating byte).
+
+IMPORTANT: Do not use the system `free`, {cpp} `delete` operator or similar functions to deallocate the string, since those may use a different memory arena!
+
+### Return Values
+
+This function returns the new string on success, and `NULL` on failure.
+
+### Errors
+
+No errors are returned, but a `NULL` return value should be
+treated the same as `NNG_ENOMEM`.
+
+### See Also
+
+xref:nng_alloc.adoc[nng_alloc],
+xref:nng_free.adoc[nng_free],
+xref:nng_strfree.adoc[nng_strfree]
\ No newline at end of file
diff --git a/docs/ref/util/nng_strfree.adoc b/docs/ref/util/nng_strfree.adoc
new file mode 100644
index 00000000..a74c90d9
--- /dev/null
+++ b/docs/ref/util/nng_strfree.adoc
@@ -0,0 +1,28 @@
+## nng_strfree
+
+Free memory.
+
+### Synopsis
+
+```c
+#include <nng/nng.h>
+
+void nng_strfree(char *str);
+```
+
+### Description
+
+The `nng_strfree` function deallocates the string _str_.
+This is equivalent to using xref:nng_free.adoc[`nng_free`] with the length of _str_ plus one (for the `NUL` terminating byte) as the size.
+
+IMPORTANT: This should only be used with strings that were allocated by xref:nng_strdup.adoc[`nng_strdup`] or xref:nng_alloc.adoc[`nng_alloc`].
+In all cases, the allocation size of the string must be the same as `strlen(str) + 1`.
+
+IMPORTANT: Consequently, if the a string created with xref:nng_strdup.adoc[`nng_strdup`] is modified to be shorter, then it is incorrect to call this function.
+(The xref:nng_free.adoc[`nng_free`] function can be used instead in that case, using the length of the original string plus one for the size.)
+
+### See Also
+
+xref:nng_alloc.adoc[nng_alloc],
+xref:nng_free.adoc[nng_free],
+xref:nng_strdup.adoc[nng_strdup]