1.\" 2.\" Copyright (c) 2007 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 February 27, 2007 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 39.Pp 40In kernel configuration files: 41.Cd "options DDB" 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 "struct stack *src" "struct stack dst" 50.Ft void 51.Fn stack_zero "struct stack *st" 52.Ft void 53.Fn stack_sbuf_print "struct sbuf sb*" "struct stack *st" 54.Ft void 55.Fn stack_save "struct stack *st" 56.Sh DESCRIPTION 57The 58.Nm 59KPI allows querying of kernel stack trace information and the automated 60generation of kernel stack trace strings for the purposes of debugging and 61tracing. 62.Nm 63relies on the presence of 64.Xr DDB 4 , 65and all use of these functions must be made conditional on 66.Nm DDB 67being compiled in the kernel. 68.Pp 69Each stack trace is described by a 70.Vt "struct stack" . 71Before a trace may be created or otherwise manipulated, storage for the trace 72must be allocated with 73.Fn stack_create , 74which may sleep. 75Memory associated with a trace may be freed by calling 76.Fn stack_destroy . 77.Pp 78A trace of the current kernel thread's call stack may be captured using 79.Fn stack_save . 80.Pp 81.Fn stack_sbuf_print 82may be used to construct a human-readable string, including conversion (where 83possible) from a simple kernel instruction pointer to a named symbol and 84offset. 85The argument 86.Ar sb 87must be an initialized 88.Dv struct sbuf 89as described in 90.Xr sbuf 9 . 91This function may sleep if an auto-extending 92.Dv struct sbuf 93is used. 94.Pp 95The utility functions 96.Nm stack_zero , 97.Nm stack_copy , 98and 99.Nm stack_put 100may be used to manipulate stack data structures directly. 101.Sh SEE ALSO 102.Xr DDB 4 103.Sh AUTHORS 104.An -nosplit 105The 106.Xr stack 9 107function suite was created by 108.An Antoine Brodin . 109.Pp 110This manual page was written by 111.An Robert Watson . 112