share/man/man9/stack.9

   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 In 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 "struct stack *src" "struct stack dst"
  50 .Ft void
  51 .Fn stack_zero "struct stack *st"
  52 .Ft void
  53 .Fn stack_print "struct stack *st"
  54 .Ft void
  55 .Fn stack_sbuf_print "struct sbuf sb*" "struct stack *st"
  56 .Ft void
  57 .Fn stack_sbuf_print_ddb "struct sbuf sb*" "struct stack *st"
  58 .Ft void
  59 .Fn stack_save "struct stack *st"
  60 .Sh DESCRIPTION
  61 The
  62 .Nm
  63 KPI allows querying of kernel stack trace information and the automated
  64 generation of kernel stack trace strings for the purposes of debugging and
  65 tracing.
  66 To use the KPI, at least one of
  67 .Cd "options DDB"
  68 and
  69 .Cd "options STACK"
  70 must be compiled into the kernel.
  71 .Pp
  72 Each stack trace is described by a
  73 .Vt "struct stack" .
  74 Before a trace may be created or otherwise manipulated, storage for the trace
  75 must be allocated with
  76 .Fn stack_create ,
  77 which may sleep.
  78 Memory associated with a trace is freed by calling
  79 .Fn stack_destroy .
  80 .Pp
  81 A trace of the current kernel thread's call stack may be captured using
  82 .Fn stack_save .
  83 .Pp
  84 .Fn stack_print
  85 may be used to print a stack trace using the kernel
  86 .Xr printf 9 ,
  87 and may sleep as a result of acquiring
  88 .Xr sx 9
  89 locks in the kernel linker while looking up symbol names.
  90 In locking-sensitive environments, the unsynchronized
  91 .Fn stack_print_ddb
  92 variant may be invoked.
  93 This function bypasses kernel linker locking, making it usable in
  94 .Xr ddb 4 ,
  95 but not in a live system where linker data structures may change.
  96 .Pp
  97 .Fn stack_sbuf_print
  98 may be used to construct a human-readable string, including conversion (where
  99 possible) from a simple kernel instruction pointer to a named symbol and
 100 offset.
 101 The argument
 102 .Ar sb
 103 must be an initialized
 104 .Dv struct sbuf
 105 as described in
 106 .Xr sbuf 9 .
 107 This function may sleep if an auto-extending
 108 .Dv struct sbuf
 109 is used, or due to kernel linker locking.
 110 In locking-sensitive environments, such as
 111 .Xr ddb 4 ,
 112 the unsynchronized
 113 .Fn stack_sbuf_print_ddb
 114 variant may be invoked to avoid kernel linker locking; it should be used with
 115 a fixed-length sbuf.
 116 .Pp
 117 The utility functions
 118 .Nm stack_zero ,
 119 .Nm stack_copy ,
 120 and
 121 .Nm stack_put
 122 may be used to manipulate stack data structures directly.
 123 .Sh SEE ALSO
 124 .Xr ddb 4 ,
 125 .Xr printf 9 ,
 126 .Xr sbuf 9 ,
 127 .Xr sx 9
 128 .Sh AUTHORS
 129 .An -nosplit
 130 The
 131 .Xr stack 9
 132 function suite was created by
 133 .An Antoine Brodin .
 134 .Xr stack 9
 135 was extended by
 136 .An Robert Watson
 137 for general-purpose use outside of
 138 .Xr ddb 4 .