Add a man page for stack(9).

MFC after:	1 week

1 files changed, 111 insertions, 0 deletions

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 .