/share/man/man9/stack.9

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 148 lines · 148 code · 0 blank · 0 comment · 0 complexity · cc493c56bbc26cedc4a7e660b70d6304 MD5 · raw file

  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 .