/share/man/man9/stack.9

  1.\"
  2.\" Copyright (c) 2007-2009 Robert N. M. Watson
  3.\" All rights reserved.
  4.\"
  5.\" Redistribution and use in source and binary forms, with or without
  6.\" modification, are permitted provided that the following conditions
  7.\" are met:
  8.\" 1. Redistributions of source code must retain the above copyright
  9.\"    notice(s), this list of conditions and the following disclaimer as
 10.\"    the first lines of this file unmodified other than the possible
 11.\"    addition of one or more copyright notices.
 12.\" 2. Redistributions in binary form must reproduce the above copyright
 13.\"    notice(s), this list of conditions and the following disclaimer in the
 14.\"    documentation and/or other materials provided with the distribution.
 15.\"
 16.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
 17.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 18.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 19.\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
 20.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 21.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 22.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 23.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 26.\" DAMAGE.
 27.\"
 28.\" $FreeBSD$
 29.\"
 30.Dd November 16, 2011
 31.Dt STACK 9
 32.Os
 33.Sh NAME
 34.Nm stack
 35.Nd kernel thread stack tracing routines
 36.Sh SYNOPSIS
 37.In sys/param.h
 38.In sys/stack.h
 39In the kernel configuration file:
 40.Cd "options DDB"
 41.Cd "options STACK"
 42.Ft struct stack *
 43.Fn stack_create "void"
 44.Ft void
 45.Fn stack_destroy "struct stack *st"
 46.Ft int
 47.Fn stack_put "struct stack *st" "vm_offset_t pc"
 48.Ft void
 49.Fn stack_copy "const struct stack *src" "struct stack dst"
 50.Ft void
 51.Fn stack_zero "struct stack *st"
 52.Ft void
 53.Fn stack_print "const struct stack *st"
 54.Ft void
 55.Fn stack_print_ddb "const struct stack *st"
 56.Ft void
 57.Fn stack_print_short "const struct stack *st"
 58.Ft void
 59.Fn stack_print_short_ddb "const struct stack *st"
 60.Ft void
 61.Fn stack_sbuf_print "struct sbuf sb*" "const struct stack *st"
 62.Ft void
 63.Fn stack_sbuf_print_ddb "struct sbuf sb*" "const struct stack *st"
 64.Ft void
 65.Fn stack_save "struct stack *st"
 66.Sh DESCRIPTION
 67The
 68.Nm
 69KPI allows querying of kernel stack trace information and the automated
 70generation of kernel stack trace strings for the purposes of debugging and
 71tracing.
 72To use the KPI, at least one of
 73.Cd "options DDB"
 74and
 75.Cd "options STACK"
 76must be compiled into the kernel.
 77.Pp
 78Each stack trace is described by a
 79.Vt "struct stack" .
 80Before a trace may be created or otherwise manipulated, storage for the trace
 81must be allocated with
 82.Fn stack_create ,
 83which may sleep.
 84Memory associated with a trace is freed by calling
 85.Fn stack_destroy .
 86.Pp
 87A trace of the current kernel thread's call stack may be captured using
 88.Fn stack_save .
 89.Pp
 90.Fn stack_print
 91and
 92.Fn stack_print_short
 93may be used to print a stack trace using the kernel
 94.Xr printf 9 ,
 95and may sleep as a result of acquiring
 96.Xr sx 9
 97locks in the kernel linker while looking up symbol names.
 98In locking-sensitive environments, the unsynchronized
 99.Fn stack_print_ddb
100and
101.Fn stack_print_short_ddb
102variants may be invoked.
103This function bypasses kernel linker locking, making it usable in
104.Xr ddb 4 ,
105but not in a live system where linker data structures may change.
106.Pp
107.Fn stack_sbuf_print
108may be used to construct a human-readable string, including conversion (where
109possible) from a simple kernel instruction pointer to a named symbol and
110offset.
111The argument
112.Ar sb
113must be an initialized
114.Dv struct sbuf
115as described in
116.Xr sbuf 9 .
117This function may sleep if an auto-extending
118.Dv struct sbuf
119is used, or due to kernel linker locking.
120In locking-sensitive environments, such as
121.Xr ddb 4 ,
122the unsynchronized
123.Fn stack_sbuf_print_ddb
124variant may be invoked to avoid kernel linker locking; it should be used with
125a fixed-length sbuf.
126.Pp
127The utility functions
128.Nm stack_zero ,
129.Nm stack_copy ,
130and
131.Nm stack_put
132may be used to manipulate stack data structures directly.
133.Sh SEE ALSO
134.Xr ddb 4 ,
135.Xr printf 9 ,
136.Xr sbuf 9 ,
137.Xr sx 9
138.Sh AUTHORS
139.An -nosplit
140The
141.Xr stack 9
142function suite was created by
143.An Antoine Brodin .
144.Xr stack 9
145was extended by
146.An Robert Watson
147for general-purpose use outside of
148.Xr ddb 4 .