table of contents
other sections
STACK(9) | Kernel Developer's Manual | STACK(9) |
NAME¶
stack
—
kernel thread stack tracing routines
SYNOPSIS¶
#include
<sys/param.h>
#include
<sys/stack.h>
In the kernel
configuration file:
options DDB
options STACK
struct stack *
stack_create
(void);
void
stack_destroy
(struct
stack *st);
int
stack_put
(struct
stack *st,
vm_offset_t pc);
void
stack_copy
(const
struct stack *src,
struct stack
dst);
void
stack_zero
(struct
stack *st);
void
stack_print
(const
struct stack *st);
void
stack_print_ddb
(const
struct stack *st);
void
stack_print_short
(const
struct stack *st);
void
stack_print_short_ddb
(const
struct stack *st);
void
stack_sbuf_print
(struct
sbuf sb*, const
struct stack *st);
void
stack_sbuf_print_ddb
(struct
sbuf sb*, const
struct stack *st);
void
stack_save
(struct
stack *st);
DESCRIPTION¶
Thestack
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
options DDB
and
options STACK
must be compiled into the
kernel.
Each stack trace is described by a struct
stack. Before a trace may be created or otherwise manipulated, storage
for the trace must be allocated with
stack_create
(), which may sleep. Memory
associated with a trace is freed by calling
stack_destroy
().
A trace of the current kernel thread's call stack may be captured using
stack_save
().
stack_print
() and
stack_print_short
() may be used to print a
stack trace using the kernel printf(9), and may
sleep as a result of acquiring sx(9) locks in the
kernel linker while looking up symbol names. In locking-sensitive
environments, the unsynchronized
stack_print_ddb
() and
stack_print_short_ddb
() variants may be
invoked. This function bypasses kernel linker locking, making it usable in
ddb(4), but not in a live system where linker
data structures may change.
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
sb must be an initialized
struct sbuf
as described in
sbuf(9). This function may sleep if an
auto-extending struct sbuf
is used, or due
to kernel linker locking. In locking-sensitive environments, such as
ddb(4), the unsynchronized
stack_sbuf_print_ddb
() variant may be
invoked to avoid kernel linker locking; it should be used with a fixed-length
sbuf.
The utility functions stack_zero
,
stack_copy
, and
stack_put
may be used to manipulate stack
data structures directly.
SEE ALSO¶
ddb(4), printf(9), sbuf(9), sx(9)AUTHORS¶
The stack(9) function suite was created by Antoine Brodin. stack(9) was extended by Robert Watson for general-purpose use outside of ddb(4).November 16, 2011 | Debian |