[src/trunk]: src/share/man/man9 document kmem_strdupsize/kmem_strdupfree

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/5e9ba6a88eed
branches:  trunk
changeset: 357368:5e9ba6a88eed
user:      christos <christos%NetBSD.org@localhost>
date:      Tue Nov 07 18:36:27 2017 +0000

description:
document kmem_strdupsize/kmem_strdupfree

diffstat:

 share/man/man9/Makefile |   6 +++-
 share/man/man9/kmem.9   |  58 +++++++++++++++++++++++++++++++++++++++++-------
 2 files changed, 53 insertions(+), 11 deletions(-)

diffs (120 lines):

diff -r 6f8343d4e6cd -r 5e9ba6a88eed share/man/man9/Makefile
--- a/share/man/man9/Makefile   Tue Nov 07 18:35:57 2017 +0000
+++ b/share/man/man9/Makefile   Tue Nov 07 18:36:27 2017 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.416 2017/10/31 08:10:11 jdolecek Exp $
+#       $NetBSD: Makefile,v 1.417 2017/11/07 18:36:27 christos Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -448,7 +448,9 @@
        kmem.9 kmem_intr_alloc.9 \
        kmem.9 kmem_intr_free.9 \
        kmem.9 kmem_intr_zalloc.9 \
-       kmem.9 kmem_asprintf.9
+       kmem.9 kmem_asprintf.9 \
+       kmem.9 kmem_strdupsize.9 \
+       kmem.9 kmem_strfree.9
 MAN+=  kpreempt.9
 MLINKS+=kpreempt.9 kpreempt_disable.9 \
        kpreempt.9 kpreempt_disabled.9 \
diff -r 6f8343d4e6cd -r 5e9ba6a88eed share/man/man9/kmem.9
--- a/share/man/man9/kmem.9     Tue Nov 07 18:35:57 2017 +0000
+++ b/share/man/man9/kmem.9     Tue Nov 07 18:36:27 2017 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: kmem.9,v 1.22 2017/08/26 21:58:31 joerg Exp $
+.\"    $NetBSD: kmem.9,v 1.23 2017/11/07 18:36:27 christos Exp $
 .\"
 .\" Copyright (c)2006 YAMAMOTO Takashi,
 .\" All rights reserved.
@@ -25,7 +25,7 @@
 .\" SUCH DAMAGE.
 .\"
 .\" ------------------------------------------------------------
-.Dd February 28, 2016
+.Dd November 7, 2017
 .Dt KMEM 9
 .Os
 .\" ------------------------------------------------------------
@@ -59,6 +59,13 @@
 .Ft char *
 .Fn kmem_asprintf \
 "const char *fmt" "..."
+.\" ---
+.Ft char *
+.Fn kmem_strdupsize \
+"const char *str" "size_t *size" "km_flag_t kmflags"
+.Ft void
+.Fn kmem_strfree \
+"char *str"
 .\" ------------------------------------------------------------
 .Pp
 .Cd "options KMEM_SIZE"
@@ -163,6 +170,31 @@
 Normally,
 .Xr pool_cache 9
 should be used for memory allocation from interrupt context.
+.Pp
+The
+.Fn kmem_strdupsize
+function is a utility function that can be used to copy the string in the
+.Fa str
+argument to a new buffer allocated using
+.Fn kmem_alloc
+and optionally return the size of the allocation (the length of the string
+plus the trailing
+.Dv NUL )
+in the
+.Fa size
+argument if that is not
+.Dv NULL .
+.Pp
+The
+.Fn kmem_strfree
+function can be used to free a
+.Dv NUL
+terminated string computing the length of the string using
+.Xr strlen 3
+and adding one for the
+.Dv NUL
+and then using
+.Fn kmem_free .
 .\" ------------------------------------------------------------
 .Sh NOTES
 Making
@@ -313,7 +345,11 @@
 .Dv DEBUG .
 .Sh RETURN VALUES
 On success,
-.Fn kmem_alloc
+.Fn kmem_alloc ,
+.Fn kmem_asprintf ,
+.Fn kmem_intr_alloc ,
+.Fn kmem_intr_zalloc ,
+.Fn kmem_strdupsize ,
 and
 .Fn kmem_zalloc
 return a pointer to allocated memory.
@@ -335,12 +371,16 @@
 .Xr uvm_km 9
 .\" ------------------------------------------------------------
 .Sh CAVEATS
-Neither
-.Fn kmem_alloc
-nor
-.Fn kmem_free
-can be used from interrupt context, from a soft interrupt, or from
-a callout.
+The
+.Fn kmem_alloc ,
+.Fn kmem_asprintf ,
+.Fn kmem_free ,
+.Fn kmem_strdupsize ,
+.Fn kmem_strfree ,
+and
+.Fn kmem_zalloc
+functions cannot be used from interrupt context, from a soft interrupt,
+or from a callout.
 Use
 .Xr pool_cache 9
 in these situations.