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(int
flags);
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);
void
stack_save_td(struct
stack *st, struct thread
*td);
int
stack_save_td_running(struct
stack *st, struct thread
*td);
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().
The flags argument is passed to
malloc(9). 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_save_td()
and
stack_save_td_running()
can also be used to capture the stack of a caller-specified thread. Callers
of these functions must own the thread lock of the specified thread.
stack_save_td() can capture the stack of a kernel
thread that is not running or swapped out at the time of the call.
stack_save_td_running() can capture the stack of a
running kernel thread.
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.
RETURN VALUES
stack_put() returns 0 on success.
Otherwise the struct stack does not contain space to
record additional frames, and a non-zero value is returned.
stack_save_td_running() returns 0 when the
stack capture was successful and a non-zero error number otherwise. In
particular, EAGAIN is returned if the thread was
running in user mode at the time that the capture was attempted, and
EOPNOTSUPP is returned if the operation is not
implemented.
SEE ALSO
AUTHORS
The stack function suite was created by
Antoine Brodin. stack was
extended by Robert Watson for general-purpose use
outside of ddb(4).