From a65bee6705ac73bb334ee052bcf1e85bcc9efceb Mon Sep 17 00:00:00 2001
From: Eric van Gyzen <vangyzen@FreeBSD.org>
Date: Sun, 6 Mar 2022 19:12:28 -0600
Subject: [PATCH] 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