diff options
Diffstat (limited to 'share/man/man9/stack.9')
| -rw-r--r-- | share/man/man9/stack.9 | 140 |
1 files changed, 140 insertions, 0 deletions
diff --git a/share/man/man9/stack.9 b/share/man/man9/stack.9 new file mode 100644 index 000000000000..8d03dd7bc069 --- /dev/null +++ b/share/man/man9/stack.9 @@ -0,0 +1,140 @@ +.\" +.\" Copyright (c) 2007 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. +.\" +.\" $FreeBSD$ +.\" +.Dd February 27, 2007 +.Dt STACK 9 +.Os +.Sh NAME +.Nm stack +.Nd kernel thread stack tracing routines +.Sh SYNOPSIS +.In sys/param.h> +.In sys/stack.h +In the kernel configuration file: +.Cd "options DDB" +.Cd "options STACK" +.Ft struct stack * +.Fn stack_create "void" +.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 "struct stack *src" "struct stack dst" +.Ft void +.Fn stack_zero "struct stack *st" +.Ft void +.Fn stack_print "struct stack *st" +.Ft void +.Fn stack_print_ddb "struct stack *st" +.Ft void +.Fn stack_sbuf_print "struct sbuf sb*" "struct stack *st" +.Ft void +.Fn stack_sbuf_print_ddb "struct sbuf sb*" "struct stack *st" +.Ft void +.Fn stack_save "struct stack *st" +.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" . +Before a trace may be created or otherwise manipulated, storage for the trace +must be allocated with +.Fn stack_create , +which may sleep. +Memory associated with a trace is freed by calling +.Fn stack_destroy . +.Pp +A trace of the current kernel thread's call stack may be captured using +.Fn stack_save . +.Pp +.Fn stack_print +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 +variant 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 SEE ALSO +.Xr ddb 4 , +.Xr printf 9 , +.Xr sbuf 9 , +.Xr sx 9 +.Sh AUTHORS +.An -nosplit +The +.Xr stack 9 +function suite was created by +.An Antoine Brodin . +.Xr stack 9 +was extended by +.An Robert Watson +for general-purpose use outside of +.Xr ddb 4 . |