Add a man page for stack(9).
MFC after: 1 week
This commit is contained in:
Robert Watson
parent
9be5e0002a
commit
12cef7aa96
@ -217,6 +217,7 @@ MAN= accept_filter.9 \
|
||||
sleepqueue.9 \
|
||||
socket.9 \
|
||||
spl.9 \
|
||||
stack.9 \
|
||||
store.9 \
|
||||
style.9 \
|
||||
suser.9 \
|
||||
@ -1066,6 +1067,13 @@ MLINKS+=spl.9 spl0.9 \
|
||||
spl.9 spltty.9 \
|
||||
spl.9 splvm.9 \
|
||||
spl.9 splx.9
|
||||
MLINKS+=stack.9 stack_copy.9 \
|
||||
stack.9 stack_create.9 \
|
||||
stack.9 stack_destroy.9 \
|
||||
stack.9 stack_put.9 \
|
||||
stack.9 stack_save.9 \
|
||||
stack.9 stack_sbuf_print.9 \
|
||||
stack.9 stack_zero.9
|
||||
MLINKS+=store.9 subyte.9 \
|
||||
store.9 suswintr.9 \
|
||||
store.9 susword.9 \
|
||||
|
||||
111
share/man/man9/stack.9
Normal file
111
share/man/man9/stack.9
Normal file
@ -0,0 +1,111 @@
|
||||
.\"
|
||||
.\" 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
|
||||
.Pp
|
||||
In kernel configuration files:
|
||||
.Cd "options DDB"
|
||||
.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_sbuf_print "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.
|
||||
.Nm
|
||||
relies on the presence of
|
||||
.Xr DDB 4 ,
|
||||
and all use of these functions must be made conditional on
|
||||
.Nm DDB
|
||||
being compiled in 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 may be freed by calling
|
||||
.Fn stack_destroy .
|
||||
.Pp
|
||||
A trace of the current kernel thread's call stack may be captured using
|
||||
.Fn stack_capture .
|
||||
.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.
|
||||
.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
|
||||
.Sh AUTHORS
|
||||
.An -nosplit
|
||||
The
|
||||
.Xr stack 9
|
||||
function suite was created by
|
||||
.An Antoine Brodin .
|
||||
.Pp
|
||||
This manual page was written by
|
||||
.An Robert Watson .
|
||||
Loading…
Reference in New Issue
Block a user