aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRobert Watson <rwatson@FreeBSD.org>2007-11-27 11:02:41 +0000
committerRobert Watson <rwatson@FreeBSD.org>2007-11-27 11:02:41 +0000
commit12cef7aa96f202f70d5ad98aa2c814fc86159e63 (patch)
tree932c17f91b2a13ad917004c8efb4c759298e8ab5
parent9be5e0002ae75ce76354466711948bb67c8e1126 (diff)
downloadsrc-12cef7aa96f202f70d5ad98aa2c814fc86159e63.tar.gz
src-12cef7aa96f202f70d5ad98aa2c814fc86159e63.zip
Add a man page for stack(9).
MFC after: 1 week
Notes
Notes: svn path=/head/; revision=173979
-rw-r--r--share/man/man9/Makefile8
-rw-r--r--share/man/man9/stack.9111
2 files changed, 119 insertions, 0 deletions
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index a1f3504e56d7..ffd3bd89f0cc 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -217,6 +217,7 @@ MAN= accept_filter.9 \
sleepqueue.9 \
socket.9 \
spl.9 \
+ stack.9 \
store.9 \
style.9 \
suser.9 \
@@ -1066,6 +1067,13 @@ MLINKS+=spl.9 spl0.9 \
spl.9 spltty.9 \
spl.9 splvm.9 \
spl.9 splx.9
+MLINKS+=stack.9 stack_copy.9 \
+ stack.9 stack_create.9 \
+ stack.9 stack_destroy.9 \
+ stack.9 stack_put.9 \
+ stack.9 stack_save.9 \
+ stack.9 stack_sbuf_print.9 \
+ stack.9 stack_zero.9
MLINKS+=store.9 subyte.9 \
store.9 suswintr.9 \
store.9 susword.9 \
diff --git a/share/man/man9/stack.9 b/share/man/man9/stack.9
new file mode 100644
index 000000000000..7f385d394e78
--- /dev/null
+++ b/share/man/man9/stack.9
@@ -0,0 +1,111 @@
+.\"
+.\" Copyright (c) 2007 Robert N. M. Watson
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice(s), this list of conditions and the following disclaimer as
+.\" the first lines of this file unmodified other than the possible
+.\" addition of one or more copyright notices.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice(s), this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
+.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
+.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+.\" DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd February 27, 2007
+.Dt STACK 9
+.Os
+.Sh NAME
+.Nm stack
+.Nd kernel thread stack tracing routines
+.Sh SYNOPSIS
+.In sys/param.h>
+.In sys/stack.h
+.Pp
+In kernel configuration files:
+.Cd "options DDB"
+.Ft struct stack *
+.Fn stack_create "void"
+.Ft void
+.Fn stack_destroy "struct stack *st"
+.Ft int
+.Fn stack_put "struct stack *st" "vm_offset_t pc"
+.Ft void
+.Fn stack_copy "struct stack *src" "struct stack dst"
+.Ft void
+.Fn stack_zero "struct stack *st"
+.Ft void
+.Fn stack_sbuf_print "struct sbuf sb*" "struct stack *st"
+.Ft void
+.Fn stack_save "struct stack *st"
+.Sh DESCRIPTION
+The
+.Nm
+KPI allows querying of kernel stack trace information and the automated
+generation of kernel stack trace strings for the purposes of debugging and
+tracing.
+.Nm
+relies on the presence of
+.Xr DDB 4 ,
+and all use of these functions must be made conditional on
+.Nm DDB
+being compiled in the kernel.
+.Pp
+Each stack trace is described by a
+.Vt "struct stack" .
+Before a trace may be created or otherwise manipulated, storage for the trace
+must be allocated with
+.Fn stack_create ,
+which may sleep.
+Memory associated with a trace may be freed by calling
+.Fn stack_destroy .
+.Pp
+A trace of the current kernel thread's call stack may be captured using
+.Fn stack_capture .
+.Pp
+.Fn stack_sbuf_print
+may be used to construct a human-readable string, including conversion (where
+possible) from a simple kernel instruction pointer to a named symbol and
+offset.
+The argument
+.Ar sb
+must be an initialized
+.Dv struct sbuf
+as described in
+.Xr sbuf 9 .
+This function may sleep if an auto-extending
+.Dv struct sbuf
+is used.
+.Pp
+The utility functions
+.Nm stack_zero ,
+.Nm stack_copy ,
+and
+.Nm stack_put
+may be used to manipulate stack data structures directly.
+.Sh SEE ALSO
+.Xr DDB 4
+.Sh AUTHORS
+.An -nosplit
+The
+.Xr stack 9
+function suite was created by
+.An Antoine Brodin .
+.Pp
+This manual page was written by
+.An Robert Watson .