util funcs reorg

11 files changed, 393 insertions, 0 deletions

diff --git a/docs/reference/src/util/index.md b/docs/reference/src/util/index.md
new file mode 100644
index 00000000..0d7db007
--- /dev/null
+++ b/docs/reference/src/util/index.md
@@ -0,0 +1,11 @@
+# General Purpose Functions
+
+# See Also
+
+[nng_alloc()][nng_alloc],
+[nng_clock()][nng_clock],
+[nng_free()][nng_free],
+[nng_random()][nng_random],
+[nng_version()][nng_version]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/util/nng_alloc.md b/docs/reference/src/util/nng_alloc.md
new file mode 100644
index 00000000..6f992798
--- /dev/null
+++ b/docs/reference/src/util/nng_alloc.md
@@ -0,0 +1,46 @@
+# nng_alloc
+
+## NAME
+
+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 [`nng_send()`][nng_send] using
+the flag `NNG_FLAG_ALLOC`. Alternatively, it can be freed when no
+longer needed using [`nng_free()`][nng_free].
+
+> [!IMPORTANT]
+> Do not use the system `free()` function (or the C++ `delete` operator) to release this memory.
+> On some configurations this may work, but on others it will lead to a crash or
+> other unpredictable behavior.
+
+## RETURN VALUES
+
+This function returns a pointer to the allocated memory on success,
+and `NULL` otherwise.
+
+## ERRORS
+
+No errors are returned, but if memory cannot be allocated then `NULL`
+is returned.
+
+## SEE ALSO
+
+[nng_free][nng_free],
+[nng_send][nng_send]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/util/nng_clock.md b/docs/reference/src/util/nng_clock.md
new file mode 100644
index 00000000..d2b69fb9
--- /dev/null
+++ b/docs/reference/src/util/nng_clock.md
@@ -0,0 +1,46 @@
+# nng_clock
+
+## NAME
+
+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()` function 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.
+
+This function is intended to help with setting appropriate
+timeouts using [`nng_cv_until()`][nng_cv_until]
+or [`nng_aio_set_expire()`][nng_aio_set_timeout].
+
+## RETURN VALUES
+
+Milliseconds since reference time.
+
+## SEE ALSO
+
+[nng_sleep_aio][nng_sleep_aio],
+[nng_cv_until][nng_cv_until],
+[nng_msleep][nng_msleep],
+[nng_duration][duration]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/util/nng_free.md b/docs/reference/src/util/nng_free.md
new file mode 100644
index 00000000..e93e91e6
--- /dev/null
+++ b/docs/reference/src/util/nng_free.md
@@ -0,0 +1,37 @@
+# nng_free
+
+## NAME
+
+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 [`nng_alloc()`][nng_alloc] or
+[`nng_recv()`](../socket/nng_recv.md) 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 C++ `new` operator.
+> Doing so may result in unpredictable
+> behavior, including corruption of application memory.
+
+## SEE ALSO
+
+[nng_alloc][nng_alloc],
+[nng_recv](../socket/nng_recv.md)
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/util/nng_msleep.md b/docs/reference/src/util/nng_msleep.md
new file mode 100644
index 00000000..add422fa
--- /dev/null
+++ b/docs/reference/src/util/nng_msleep.md
@@ -0,0 +1,30 @@
+# nng_msleep
+
+## NAME
+
+nng_msleep --- sleep milliseconds
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+void nng_msleep(nng_duration msec);
+```
+
+## DESCRIPTION
+
+The `nng_msleep()` blocks the caller for at least _msec_ milliseconds.
+
+> [!NOTE]
+> This function may block for longer than requested.
+> The actual wait time is determined by the capabilities of the
+> underlying system.
+
+## SEE ALSO
+
+[nng_sleep_aio][nng_sleep_aio],
+[nng_clock][nng_clock]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/util/nng_random.md b/docs/reference/src/util/nng_random.md
new file mode 100644
index 00000000..e4f6f52a
--- /dev/null
+++ b/docs/reference/src/util/nng_random.md
@@ -0,0 +1,28 @@
+# nng_random
+
+## NAME
+
+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
+
+Returns a random 32-bit value.
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/util/nng_sleep_aio.md b/docs/reference/src/util/nng_sleep_aio.md
new file mode 100644
index 00000000..7092fa3a
--- /dev/null
+++ b/docs/reference/src/util/nng_sleep_aio.md
@@ -0,0 +1,33 @@
+# nng_sleep_aio
+
+## NAME
+
+nng_sleep_aio - sleep asynchronously
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+void nng_sleep_aio(nng_duration msec, nng_aio *aio);
+```
+
+## DESCRIPTION
+
+The `nng_sleep_aio()` function provides an asynchronous delay mechanism,
+causing the callback for _aio_ to be executed after _msec_ milliseconds.
+If the sleep finishes completely, the result will always be zero.
+
+> [!NOTE]
+> If a timeout is set on _aio_ using
+> [`nng_aio_set_timeout()`](../aio/nng_aio_set_timeout.md), and it is shorter
+> than _msec_,
+> then the sleep will wake up early, with a result code of `NNG_ETIMEDOUT`.
+
+## SEE ALSO
+
+[nng_clock][nng_clock],
+[nng_msleep][nng_msleep],
+[Asynchronous I/O](../aio/index.md)
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/util/nng_strdup.md b/docs/reference/src/util/nng_strdup.md
new file mode 100644
index 00000000..363af304
--- /dev/null
+++ b/docs/reference/src/util/nng_strdup.md
@@ -0,0 +1,48 @@
+# nng_strdup
+
+## NAME
+
+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 [`nng_alloc()`][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
+[`nng_strfree()`][nng_strfree], or may be deallocated using the
+[`nng_free()`][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
+
+[nng_alloc.md][nng_alloc],
+[nng_free.md][nng_free],
+[nng_strfree.md][nng_strfree]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/util/nng_strerror.md b/docs/reference/src/util/nng_strerror.md
new file mode 100644
index 00000000..4772d705
--- /dev/null
+++ b/docs/reference/src/util/nng_strerror.md
@@ -0,0 +1,35 @@
+# nng_strerror
+
+## NAME
+
+nng_strerror --- return an error description
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+const char * nng_strerror(int err);
+```
+
+## DESCRIPTION
+
+The `nng_strerror()` returns the human-readable description of the
+given error in `err`.
+
+The returned error message is provided in US English, but in the
+future locale-specific strings may be presented instead.
+
+> [!NOTE]
+> The specific strings associated with specific error messages are
+> subject to change.
+> Therefore applications must not depend on the message,
+> but may use them verbatim when supplying information to end-users, such
+> as in diagnostic messages or log entries.
+
+## RETURN VALUES
+
+This function returns the human-readable error message, terminated
+by a `NUL` byte.
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/util/nng_strfree.md b/docs/reference/src/util/nng_strfree.md
new file mode 100644
index 00000000..3cebb7f6
--- /dev/null
+++ b/docs/reference/src/util/nng_strfree.md
@@ -0,0 +1,41 @@
+# nng_strfree
+
+## NAME
+
+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 [`nng_free()`][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 [`nng_strdup()`][nng_strdup] or [`nng_alloc()`](nng_alloc.md).
+> 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
+> [`nng_strdup()`][nng_strfree] is modified to be shorter, then
+> it is incorrect to call this function.
+> (The [`nng_free()`](nng_Free.md) function can be used instead in that
+> case, using the length of the original string plus one for the size.)
+
+## SEE ALSO
+
+[nng_alloc][nng_alloc],
+[nng_free][nng_free],
+[nng_strdup][nng_strdup]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/util/nng_version.md b/docs/reference/src/util/nng_version.md
new file mode 100644
index 00000000..cd6666e3
--- /dev/null
+++ b/docs/reference/src/util/nng_version.md
@@ -0,0 +1,38 @@
+# nng_version
+
+## NAME
+
+nng_version --- report library version
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+const char * nng_version(void);
+```
+
+## DESCRIPTION
+
+The `nng_version()` function returns a human readable {{i:version number}}
+for _NNG_.
+
+Additionally, compile time version information is available
+via some predefined macros:
+
+- {{i:`NNG_MAJOR_VERSION`}}: Major version number.
+- {{i:`NNG_MINOR_VERSION`}}: Minor version number.
+- {{i:`NNG_PATCH_VERSION`}}: Patch version number.
+
+_NNG_ is developed and released using
+[Semantic Versioning 2.0](http://www.semver.org), and
+the version numbers reported refer to both the API and the library itself.
+(The {{i:ABI}} -- {{i:application binary interface}} -- between the
+library and the application is controlled in a similar, but different
+manner depending upon the link options and how the library is built.)
+
+## RETURN VALUES
+
+`NUL`-terminated string containing the library version number.
+
+{{#include ../refs.md}}