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 October 6, 2017
  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
  40 In the kernel configuration file:
  41 .Cd "options DDB"
  42 .Cd "options STACK"
  43 .Pp
  44 .Ft struct stack *
  45 .Fn stack_create "int flags"
  46 .Ft void
  47 .Fn stack_destroy "struct stack *st"
  48 .Ft int
  49 .Fn stack_put "struct stack *st" "vm_offset_t pc"
  50 .Ft void
  51 .Fn stack_copy "const struct stack *src" "struct stack dst"
  52 .Ft void
  53 .Fn stack_zero "struct stack *st"
  54 .Ft void
  55 .Fn stack_print "const struct stack *st"
  56 .Ft void
  57 .Fn stack_print_ddb "const struct stack *st"
  58 .Ft void
  59 .Fn stack_print_short "const struct stack *st"
  60 .Ft void
  61 .Fn stack_print_short_ddb "const struct stack *st"
  62 .Ft void
  63 .Fn stack_sbuf_print "struct sbuf sb*" "const struct stack *st"
  64 .Ft void
  65 .Fn stack_sbuf_print_ddb "struct sbuf sb*" "const struct stack *st"
  66 .Ft void
  67 .Fn stack_save "struct stack *st"
  68 .Ft void
  69 .Fn stack_save_td "struct stack *st" "struct thread *td"
  70 .Ft int
  71 .Fn stack_save_td_running "struct stack *st" "struct thread *td"
  72 .Sh DESCRIPTION
  73 The
  74 .Nm
  75 KPI allows querying of kernel stack trace information and the automated
  76 generation of kernel stack trace strings for the purposes of debugging and
  77 tracing.
  78 To use the KPI, at least one of
  79 .Cd "options DDB"
  80 and
  81 .Cd "options STACK"
  82 must be compiled into the kernel.
  83 .Pp
  84 Each stack trace is described by a
  85 .Vt "struct stack" .
  86 Before a trace may be created or otherwise manipulated, storage for the trace
  87 must be allocated with
  88 .Fn stack_create .
  89 The
  90 .Ar flags
  91 argument is passed to
  92 .Xr malloc 9 .
  93 Memory associated with a trace is freed by calling
  94 .Fn stack_destroy .
  95 .Pp
  96 A trace of the current kernel thread's call stack may be captured using
  97 .Fn stack_save .
  98 .Fn stack_save_td
  99 and
 100 .Fn stack_save_td_running
 101 can also be used to capture the stack of a caller-specified thread.
 102 Callers of these functions must own the thread lock of the specified thread.
 103 .Fn stack_save_td
 104 can capture the stack of a kernel thread that is not running or
 105 swapped out at the time of the call.
 106 .Fn stack_save_td_running
 107 can capture the stack of a running kernel thread.
 108 .Pp
 109 .Fn stack_print
 110 and
 111 .Fn stack_print_short
 112 may be used to print a stack trace using the kernel
 113 .Xr printf 9 ,
 114 and may sleep as a result of acquiring
 115 .Xr sx 9
 116 locks in the kernel linker while looking up symbol names.
 117 In locking-sensitive environments, the unsynchronized
 118 .Fn stack_print_ddb
 119 and
 120 .Fn stack_print_short_ddb
 121 variants may be invoked.
 122 This function bypasses kernel linker locking, making it usable in
 123 .Xr ddb 4 ,
 124 but not in a live system where linker data structures may change.
 125 .Pp
 126 .Fn stack_sbuf_print
 127 may be used to construct a human-readable string, including conversion (where
 128 possible) from a simple kernel instruction pointer to a named symbol and
 129 offset.
 130 The argument
 131 .Ar sb
 132 must be an initialized
 133 .Dv struct sbuf
 134 as described in
 135 .Xr sbuf 9 .
 136 This function may sleep if an auto-extending
 137 .Dv struct sbuf
 138 is used, or due to kernel linker locking.
 139 In locking-sensitive environments, such as
 140 .Xr ddb 4 ,
 141 the unsynchronized
 142 .Fn stack_sbuf_print_ddb
 143 variant may be invoked to avoid kernel linker locking; it should be used with
 144 a fixed-length sbuf.
 145 .Pp
 146 The utility functions
 147 .Nm stack_zero ,
 148 .Nm stack_copy ,
 149 and
 150 .Nm stack_put
 151 may be used to manipulate stack data structures directly.
 152 .Sh RETURN VALUES
 153 .Fn stack_put
 154 returns 0 on success.
 155 Otherwise the
 156 .Dv struct stack
 157 does not contain space to record additional frames, and a non-zero value is
 158 returned.
 159 .Pp
 160 .Fn stack_save_td_running
 161 returns 0 when the stack capture was successful and a non-zero error number
 162 otherwise.
 163 In particular,
 164 .Er EAGAIN
 165 is returned if the thread was running in user mode at the time that the
 166 capture was attempted, and
 167 .Er EOPNOTSUPP
 168 is returned if the operation is not implemented.
 169 .Sh SEE ALSO
 170 .Xr ddb 4 ,
 171 .Xr printf 9 ,
 172 .Xr sbuf 9 ,
 173 .Xr sx 9
 174 .Sh AUTHORS
 175 .An -nosplit
 176 The
 177 .Nm
 178 function suite was created by
 179 .An Antoine Brodin .
 180 .Nm
 181 was extended by
 182 .An Robert Watson
 183 for general-purpose use outside of
 184 .Xr ddb 4 .