git: a65bee6705ac - main - stack(9): dynamic allocation is not necessary

The branch main has been updated by vangyzen:

URL: https://cgit.FreeBSD.org/src/commit/?id=a65bee6705ac73bb334ee052bcf1e85bcc9efceb

commit a65bee6705ac73bb334ee052bcf1e85bcc9efceb
Author:     Eric van Gyzen <vangyzen@FreeBSD.org>
AuthorDate: 2022-03-07 01:12:28 +0000
Commit:     Eric van Gyzen <vangyzen@FreeBSD.org>
CommitDate: 2022-03-26 01:10:38 +0000

    stack(9): dynamic allocation is not necessary
    
    The man page said dynamic allocation was required, but struct stack
    can be allocated in any way, including on the stack.  Make this clear,
    and explain how to initialize the struct.
    
    While I'm here, stack_save does not require any lock.
    
    Reviewed by:    markj, Pau Amma <pauamma_gundo.com>
    MFC after:      1 week
    Sponsored by:   Dell EMC Isilon
    Differential Revision:  https://reviews.freebsd.org/D34461
---
 share/man/man9/stack.9 | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/share/man/man9/stack.9 b/share/man/man9/stack.9
index 6ac24ffe9500..9ac64ff333a8 100644
--- a/share/man/man9/stack.9
+++ b/share/man/man9/stack.9
@@ -27,7 +27,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd January 31, 2020
+.Dd March 6, 2022
 .Dt STACK 9
 .Os
 .Sh NAME
@@ -48,7 +48,7 @@ In the kernel configuration file:
 .Ft int
 .Fn stack_put "struct stack *st" "vm_offset_t pc"
 .Ft void
-.Fn stack_copy "const struct stack *src" "struct stack dst"
+.Fn stack_copy "const struct stack *src" "struct stack *dst"
 .Ft void
 .Fn stack_zero "struct stack *st"
 .Ft void
@@ -60,9 +60,9 @@ In the kernel configuration file:
 .Ft void
 .Fn stack_print_short_ddb "const struct stack *st"
 .Ft void
-.Fn stack_sbuf_print "struct sbuf sb*" "const struct stack *st"
+.Fn stack_sbuf_print "struct sbuf *sb" "const struct stack *st"
 .Ft void
-.Fn stack_sbuf_print_ddb "struct sbuf sb*" "const struct stack *st"
+.Fn stack_sbuf_print_ddb "struct sbuf *sb" "const struct stack *st"
 .Ft void
 .Fn stack_save "struct stack *st"
 .Ft int
@@ -81,21 +81,26 @@ must be compiled into the kernel.
 .Pp
 Each stack trace is described by a
 .Vt "struct stack" .
-Before a trace may be created or otherwise manipulated, storage for the trace
-must be allocated with
+It can be declared in the usual ways, including on the stack, and optionally
+initialized with
+.Fn stack_zero ,
+though this is not necessary before saving a trace.
+It can also be dynamically allocated with
 .Fn stack_create .
 The
 .Ar flags
 argument is passed to
 .Xr malloc 9 .
-Memory associated with a trace is freed by calling
+This dynamic allocation must be freed with
 .Fn stack_destroy .
 .Pp
 A trace of the current thread's kernel call stack may be captured using
 .Fn stack_save .
 .Fn stack_save_td
 can be used to capture the kernel stack of a caller-specified thread.
-Callers of these functions must own the thread lock of the specified thread,
+Callers of
+.Fn stack_save_td
+must own the thread lock of the specified thread,
 and the thread's stack must not be swapped out.
 .Fn stack_save_td
 can capture the kernel stack of a running thread, though note that this is