Converted nng_strdup and nng_strfree to mdbook.

nanomsg · Oct 7, 2024 · 7dd81b3 · 7dd81b3
1 parent c6a0c72
commit 7dd81b3
Show file tree

Hide file tree

Showing 6 changed files with 64 additions and 119 deletions.
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
@@ -26,19 +26,22 @@ intended to solve common communication problems in distributed applications.
 
 It provides a C language API.
 
+<!--
 === Common Functions
 
 The following common functions exist in _libnng_.
 
 |===
-//|xref:nng_alloc.3.adoc[nng_alloc()]|allocate memory
-//|xref:nng_free.3.adoc[nng_free()]|free memory
-|xref:nng_strdup.3.adoc[nng_strdup()]|duplicate string
-//|xref:nng_strerror.3.adoc[nng_strerror()]|return an error description
-|xref:nng_strfree.3.adoc[nng_strfree()]|free string
+// |xref:nng_alloc.3.adoc[nng_alloc()]|allocate memory
+// |xref:nng_free.3.adoc[nng_free()]|free memory
+// |xref:nng_strdup.3.adoc[nng_strdup()]|duplicate string
+// |xref:nng_strerror.3.adoc[nng_strerror()]|return an error description
+// |xref:nng_strfree.3.adoc[nng_strfree()]|free string
 // |xref:nng_version.3.adoc[nng_version()]|report library version
 |===
 
+-->
+
 === Socket Functions
 
 The following functions operate on sockets.

diff --git a/docs/man/nng_strdup.3.adoc b/docs/man/nng_strdup.3.adoc
diff --git a/docs/man/nng_strfree.3.adoc b/docs/man/nng_strfree.3.adoc
diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md
@@ -13,6 +13,7 @@
     - [nng_id_map](./api/util/nng_id_map.md)
     - [nng_msleep](./api/util/nng_msleep.md)
     - [nng_random](./api/util/nng_random.md)
+    - [nng_strdup](./api/util/nng_strdup.md)
     - [nng_strerror](./api/util/nng_strerror.md)
     - [nng_version](./api/util/nng_version.md)
 

diff --git a/docs/ref/api/util/index.md b/docs/ref/api/util/index.md
@@ -10,5 +10,6 @@ of other uses.
 - [nng_id_map](nng_id_map.md)
 - [nng_msleep](nng_msleep.md)
 - [nng_random](nng_random.md)
+- [nng_strdup](nng_strdup.md)
 - [nng_strerror](nng_strerror.md)
 - [nng_version](nng_version.md)
diff --git a/docs/ref/api/util/nng_strdup.md b/docs/ref/api/util/nng_strdup.md
@@ -0,0 +1,54 @@
+# nng_strdup
+
+## NAME
+
+nng_strdup --- duplicate string
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+char *nng_strdup(const char *src);
+void nng_strfree(char *str);
+```
+
+## DESCRIPTION
+
+The {{i:`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
+{{i:`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!
+
+> [!IMPORTANT]
+> If a string created with
+> `nng_strdup` is modified to be shorter, then it is incorrect to free it with `nng_strfree`.
+> (The [`nng_free`][nng_free] function can be used instead in that
+> case, using the length of the original string plus one to account for the `NUL` byte, for the size.)
+
+## RETURN VALUES
+
+The `nng_strdup` function returns the new string on success, and `NULL` on failure.
+
+## ERRORS
+
+No errors are returned from `nng_strdup`, but a `NULL` return value should be
+treated the same as `NNG_ENOMEM`.
+
+## SEE ALSO
+
+[nng_alloc][nng_alloc]
+
+[nng_alloc]: ../util/nng_alloc.md
+[nng_free]: ../util/nng_alloc.md