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/SUMMARY.md | 20 ++++++------ docs/reference/src/api/util/index.md | 9 ------ docs/reference/src/api/util/nng_alloc.md | 44 ------------------------- docs/reference/src/api/util/nng_clock.md | 44 ------------------------- docs/reference/src/api/util/nng_free.md | 35 -------------------- docs/reference/src/api/util/nng_msleep.md | 28 ---------------- docs/reference/src/api/util/nng_random.md | 26 --------------- docs/reference/src/api/util/nng_sleep_aio.md | 31 ------------------ docs/reference/src/api/util/nng_strdup.md | 46 -------------------------- docs/reference/src/api/util/nng_strerror.md | 33 ------------------- docs/reference/src/api/util/nng_strfree.md | 39 ---------------------- docs/reference/src/api/util/nng_version.md | 36 --------------------- docs/reference/src/refs.md | 26 +++++++++++++++ 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 ++++++++++++++++++++++ 24 files changed, 429 insertions(+), 381 deletions(-) delete mode 100644 docs/reference/src/api/util/index.md delete mode 100644 docs/reference/src/api/util/nng_alloc.md delete mode 100644 docs/reference/src/api/util/nng_clock.md delete mode 100644 docs/reference/src/api/util/nng_free.md delete mode 100644 docs/reference/src/api/util/nng_msleep.md delete mode 100644 docs/reference/src/api/util/nng_random.md delete mode 100644 docs/reference/src/api/util/nng_sleep_aio.md delete mode 100644 docs/reference/src/api/util/nng_strdup.md delete mode 100644 docs/reference/src/api/util/nng_strerror.md delete mode 100644 docs/reference/src/api/util/nng_strfree.md delete mode 100644 docs/reference/src/api/util/nng_version.md 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 diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md index bc24ac01..d6aaf9cb 100644 --- a/docs/reference/src/SUMMARY.md +++ b/docs/reference/src/SUMMARY.md @@ -99,16 +99,16 @@ - [Utility Functions](api/util/index.md) - - [nng_alloc](api/util/nng_alloc.md) - - [nng_clock](api/util/nng_clock.md) - - [nng_free](api/util/nng_free.md) - - [nng_msleep](api/util/nng_msleep.md) - - [nng_random](api/util/nng_random.md) - - [nng_sleep_aio](api/util/nng_sleep_aio.md) - - [nng_strdup](api/util/nng_strdup.md) - - [nng_strerror](api/util/nng_strerror.md) - - [nng_strfree](api/util/nng_strfree.md) - - [nng_version](api/util/nng_version.md) + - [nng_alloc](util/nng_alloc.md) + - [nng_clock](util/nng_clock.md) + - [nng_free](util/nng_free.md) + - [nng_msleep](util/nng_msleep.md) + - [nng_random](util/nng_random.md) + - [nng_sleep_aio](util/nng_sleep_aio.md) + - [nng_strdup](util/nng_strdup.md) + - [nng_strerror](util/nng_strerror.md) + - [nng_strfree](util/nng_strfree.md) + - [nng_version](util/nng_version.md) - [Threads and Synchronization](thr/index.md) diff --git a/docs/reference/src/api/util/index.md b/docs/reference/src/api/util/index.md deleted file mode 100644 index 2ca0bc0b..00000000 --- a/docs/reference/src/api/util/index.md +++ /dev/null @@ -1,9 +0,0 @@ -# General Purpose Functions - -# See Also - -[nng_alloc()](nng_alloc.md), -[nng_clock()](nng_clock.md), -[nng_free()](nng_free.md), -[nng_random()](nng_random.md), -[nng_version()](nng_version.md) diff --git a/docs/reference/src/api/util/nng_alloc.md b/docs/reference/src/api/util/nng_alloc.md deleted file mode 100644 index ffc46083..00000000 --- a/docs/reference/src/api/util/nng_alloc.md +++ /dev/null @@ -1,44 +0,0 @@ -# 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()`](../socket/nng_send.md) using -the flag `NNG_FLAG_ALLOC`. Alternatively, it can be freed when no -longer needed using [`nng_free()`](nng_free.md). - -> [!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.md), -[nng_send](../socket/nng_send.md) diff --git a/docs/reference/src/api/util/nng_clock.md b/docs/reference/src/api/util/nng_clock.md deleted file mode 100644 index 1bc4037d..00000000 --- a/docs/reference/src/api/util/nng_clock.md +++ /dev/null @@ -1,44 +0,0 @@ -# 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()`](../threads/nng_cv_until.md) -or [`nng_aio_set_expire()`](../aio/nng_aio_set_timeout.md). - -## RETURN VALUES - -Milliseconds since reference time. - -## SEE ALSO - -[nng_sleep_aio](nng_sleep_aio.md), -[nng_cv_until](../threads/nng_cv_until.md), -[nng_msleep](nng_msleep.md), -[nng_duration](nng_duration.md) diff --git a/docs/reference/src/api/util/nng_free.md b/docs/reference/src/api/util/nng_free.md deleted file mode 100644 index c25686b4..00000000 --- a/docs/reference/src/api/util/nng_free.md +++ /dev/null @@ -1,35 +0,0 @@ -# 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.md) 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.md), -[nng_recv](../socket/nng_recv.md) diff --git a/docs/reference/src/api/util/nng_msleep.md b/docs/reference/src/api/util/nng_msleep.md deleted file mode 100644 index 06dd16a6..00000000 --- a/docs/reference/src/api/util/nng_msleep.md +++ /dev/null @@ -1,28 +0,0 @@ -# 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.md), -[nng_clock](nng_clock.md) diff --git a/docs/reference/src/api/util/nng_random.md b/docs/reference/src/api/util/nng_random.md deleted file mode 100644 index 7cc73d2a..00000000 --- a/docs/reference/src/api/util/nng_random.md +++ /dev/null @@ -1,26 +0,0 @@ -# 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. diff --git a/docs/reference/src/api/util/nng_sleep_aio.md b/docs/reference/src/api/util/nng_sleep_aio.md deleted file mode 100644 index 799f512f..00000000 --- a/docs/reference/src/api/util/nng_sleep_aio.md +++ /dev/null @@ -1,31 +0,0 @@ -# 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.md), -[nng_msleep](nng_msleep.md), -[Asynchronous I/O](../aio/index.md) diff --git a/docs/reference/src/api/util/nng_strdup.md b/docs/reference/src/api/util/nng_strdup.md deleted file mode 100644 index b8d2fe42..00000000 --- a/docs/reference/src/api/util/nng_strdup.md +++ /dev/null @@ -1,46 +0,0 @@ -# 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.md) -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.md), or may be deallocated using the -[`nng_free()`](nng_free.md) 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.md), -[nng_free.md](nng_free.md), -[nng_strfree.md](nng_strfree.md) diff --git a/docs/reference/src/api/util/nng_strerror.md b/docs/reference/src/api/util/nng_strerror.md deleted file mode 100644 index 14041fad..00000000 --- a/docs/reference/src/api/util/nng_strerror.md +++ /dev/null @@ -1,33 +0,0 @@ -# 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. diff --git a/docs/reference/src/api/util/nng_strfree.md b/docs/reference/src/api/util/nng_strfree.md deleted file mode 100644 index cca7950d..00000000 --- a/docs/reference/src/api/util/nng_strfree.md +++ /dev/null @@ -1,39 +0,0 @@ -# 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.md) 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.md) 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.md) 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.md), -[nng_free](nng_free.md), -[nng_strdup](nng_strdup.md) diff --git a/docs/reference/src/api/util/nng_version.md b/docs/reference/src/api/util/nng_version.md deleted file mode 100644 index 53c49ee6..00000000 --- a/docs/reference/src/api/util/nng_version.md +++ /dev/null @@ -1,36 +0,0 @@ -# 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. diff --git a/docs/reference/src/refs.md b/docs/reference/src/refs.md index 2b4b0b65..e51ffe4e 100644 --- a/docs/reference/src/refs.md +++ b/docs/reference/src/refs.md @@ -64,6 +64,32 @@ [nng_msg_set_pipe]: ../msg/nng_msg_set_pipe.md [nng_msg_trim]: ../msg/nng_msg_trim.md + + +[nng_cv_alloc]: ../thr/nng_cv_alloc.md +[nng_cv_free]: ../thr/nng_cv_free.md +[nng_cv_until]: ../thr/nng_cv_until.md +[nng_cv_wait]: ../thr/nng_cv_wait.md +[nng_cv_wake]: ../thr/nng_cv_wake.md +[nng_cv_wake1]: ../thr/nng_cv_wake1.md +[nng_mtx_alloc]: ../thr/nng_mtx_alloc.md +[nng_mtx_free]: ../thr/nng_mtx_free.md +[nng_mtx_lock]: ../thr/nng_mtx_lock.md +[nng_mtx_unlock]: ../thr/nng_mtx_unlock.md + + + +[nng_alloc]: ../util/nng_alloc.md +[nng_clock]: ../util/nng_clock.md +[nng_free]: ../util/nng_free.md +[nng_msleep]: ../util/nng_msleep.md +[nng_random]: ../util/nng_random.md +[nng_sleep_aio]: ../util/nng_sleep_aio.md +[nng_strdup]: ../util/nng_strdup.md +[nng_strerror]: ../util/nng_strerror.md +[nng_strfree]: ../util/nng_strfree.md +[nng_version]: ../util/nng_version.md + [NNG_OPT_MAXTTL]: ../opts/nng_opt_max_ttl.md 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