feat: Added FreeBSD man pages

1 files changed, 184 insertions, 0 deletions

diff --git a/static/freebsd/man9/stack.9 b/static/freebsd/man9/stack.9
new file mode 100644
index 00000000..c912cd30
--- /dev/null
+++ b/static/freebsd/man9/stack.9
@@ -0,0 +1,184 @@
+.\"
+.\" Copyright (c) 2007-2009 Robert N. M. Watson
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice(s), this list of conditions and the following disclaimer as
+.\"    the first lines of this file unmodified other than the possible
+.\"    addition of one or more copyright notices.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice(s), this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
+.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+.\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
+.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+.\" DAMAGE.
+.\"
+.Dd March 6, 2022
+.Dt STACK 9
+.Os
+.Sh NAME
+.Nm stack
+.Nd kernel thread stack tracing routines
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/stack.h
+.Pp
+In the kernel configuration file:
+.Cd "options DDB"
+.Cd "options STACK"
+.Pp
+.Ft struct stack *
+.Fn stack_create "int flags"
+.Ft void
+.Fn stack_destroy "struct stack *st"
+.Ft int
+.Fn stack_put "struct stack *st" "vm_offset_t pc"
+.Ft void
+.Fn stack_copy "const struct stack *src" "struct stack *dst"
+.Ft void
+.Fn stack_zero "struct stack *st"
+.Ft void
+.Fn stack_print "const struct stack *st"
+.Ft void
+.Fn stack_print_ddb "const struct stack *st"
+.Ft void
+.Fn stack_print_short "const struct stack *st"
+.Ft void
+.Fn stack_print_short_ddb "const struct stack *st"
+.Ft void
+.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"
+.Ft void
+.Fn stack_save "struct stack *st"
+.Ft int
+.Fn stack_save_td "struct stack *st" "struct thread *td"
+.Sh DESCRIPTION
+The
+.Nm
+KPI allows querying of kernel stack trace information and the automated
+generation of kernel stack trace strings for the purposes of debugging and
+tracing.
+To use the KPI, at least one of
+.Cd "options DDB"
+and
+.Cd "options STACK"
+must be compiled into the kernel.
+.Pp
+Each stack trace is described by a
+.Vt "struct stack" .
+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 .
+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
+.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
+not implemented on all platforms.
+If the thread is running, the caller must also hold the process lock for the
+target thread.
+.Pp
+.Fn stack_print
+and
+.Fn stack_print_short
+may be used to print a stack trace using the kernel
+.Xr printf 9 ,
+and may sleep as a result of acquiring
+.Xr sx 9
+locks in the kernel linker while looking up symbol names.
+In locking-sensitive environments, the unsynchronized
+.Fn stack_print_ddb
+and
+.Fn stack_print_short_ddb
+variants may be invoked.
+This function bypasses kernel linker locking, making it usable in
+.Xr ddb 4 ,
+but not in a live system where linker data structures may change.
+.Pp
+.Fn stack_sbuf_print
+may be used to construct a human-readable string, including conversion (where
+possible) from a simple kernel instruction pointer to a named symbol and
+offset.
+The argument
+.Ar sb
+must be an initialized
+.Dv struct sbuf
+as described in
+.Xr sbuf 9 .
+This function may sleep if an auto-extending
+.Dv struct sbuf
+is used, or due to kernel linker locking.
+In locking-sensitive environments, such as
+.Xr ddb 4 ,
+the unsynchronized
+.Fn stack_sbuf_print_ddb
+variant may be invoked to avoid kernel linker locking; it should be used with
+a fixed-length sbuf.
+.Pp
+The utility functions
+.Nm stack_zero ,
+.Nm stack_copy ,
+and
+.Nm stack_put
+may be used to manipulate stack data structures directly.
+.Sh RETURN VALUES
+.Fn stack_put
+returns 0 on success.
+Otherwise the
+.Dv struct stack
+does not contain space to record additional frames, and a non-zero value is
+returned.
+.Pp
+.Fn stack_save_td
+returns 0 when the stack capture was successful and a non-zero error number
+otherwise.
+In particular,
+.Er EBUSY
+is returned if the thread was running in user mode at the time that the
+capture was attempted, and
+.Er EOPNOTSUPP
+is returned if the operation is not implemented.
+.Sh SEE ALSO
+.Xr ddb 4 ,
+.Xr printf 9 ,
+.Xr sbuf 9 ,
+.Xr sx 9
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+function suite was created by
+.An Antoine Brodin .
+.Nm
+was extended by
+.An Robert Watson
+for general-purpose use outside of
+.Xr ddb 4 .