From b779b71b00c5f5f8cb9f0ee7d8feeadf9e2dca48 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 30 Mar 2024 16:12:02 -0700 Subject: util funcs reorg --- docs/reference/src/util/index.md | 11 ++++++++ docs/reference/src/util/nng_alloc.md | 46 ++++++++++++++++++++++++++++++ docs/reference/src/util/nng_clock.md | 46 ++++++++++++++++++++++++++++++ docs/reference/src/util/nng_free.md | 37 ++++++++++++++++++++++++ docs/reference/src/util/nng_msleep.md | 30 ++++++++++++++++++++ docs/reference/src/util/nng_random.md | 28 +++++++++++++++++++ docs/reference/src/util/nng_sleep_aio.md | 33 ++++++++++++++++++++++ docs/reference/src/util/nng_strdup.md | 48 ++++++++++++++++++++++++++++++++ docs/reference/src/util/nng_strerror.md | 35 +++++++++++++++++++++++ docs/reference/src/util/nng_strfree.md | 41 +++++++++++++++++++++++++++ docs/reference/src/util/nng_version.md | 38 +++++++++++++++++++++++++ 11 files changed, 393 insertions(+) create mode 100644 docs/reference/src/util/index.md create mode 100644 docs/reference/src/util/nng_alloc.md create mode 100644 docs/reference/src/util/nng_clock.md create mode 100644 docs/reference/src/util/nng_free.md create mode 100644 docs/reference/src/util/nng_msleep.md create mode 100644 docs/reference/src/util/nng_random.md create mode 100644 docs/reference/src/util/nng_sleep_aio.md create mode 100644 docs/reference/src/util/nng_strdup.md create mode 100644 docs/reference/src/util/nng_strerror.md create mode 100644 docs/reference/src/util/nng_strfree.md create mode 100644 docs/reference/src/util/nng_version.md (limited to 'docs/reference/src/util') 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 + +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 +#include + +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 + +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 +#include + +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 +#include + +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 + +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 + +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 + +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 + +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 + +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}} -- cgit v1.2.3-70-g09d2