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 . 149