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