1.\"
2.\" Copyright (c) 2007 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
--- 11 unchanged lines hidden (view full) ---
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: head/share/man/man9/stack.9 174195 2007-12-02 20:40:35Z rwatson $
29.\"
30.Dd February 27, 2007
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
39In 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 "struct stack *src" "struct stack dst"
--- 8 unchanged lines hidden (view full) ---
58.Ft void
59.Fn stack_save "struct stack *st"
60.Sh DESCRIPTION
61The
62.Nm
63KPI allows querying of kernel stack trace information and the automated
64generation of kernel stack trace strings for the purposes of debugging and
65tracing.
66To use the KPI, at least one of
67.Cd "options DDB"
68and
69.Cd "options STACK"
70must be compiled into the kernel.
71.Pp
72Each stack trace is described by a
73.Vt "struct stack" .
74Before a trace may be created or otherwise manipulated, storage for the trace
75must be allocated with
76.Fn stack_create ,
77which may sleep.
78Memory associated with a trace is freed by calling
79.Fn stack_destroy .
80.Pp
81A trace of the current kernel thread's call stack may be captured using
82.Fn stack_save .
83.Pp
84.Fn stack_print
85may be used to print a stack trace using the kernel
86.Xr printf 9 ,
87and may sleep as a result of acquiring
88.Xr sx 9
89locks in the kernel linker while looking up symbol names.
90In locking-sensitive environments, the unsynchronized
91.Fn stack_print_ddb
92variant may be invoked.
93This function bypasses kernel linker locking, making it usable in
94.Xr ddb 4 ,
95but not in a live system where linker data structures may change.
96.Pp
97.Fn stack_sbuf_print
98may be used to construct a human-readable string, including conversion (where
99possible) from a simple kernel instruction pointer to a named symbol and
100offset.
101The argument
102.Ar sb
103must be an initialized
104.Dv struct sbuf
105as described in
106.Xr sbuf 9 .
107This function may sleep if an auto-extending
108.Dv struct sbuf
109is used, or due to kernel linker locking.
110In locking-sensitive environments, such as
111.Xr ddb 4 ,
112the unsynchronized
113.Fn stack_sbuf_print_ddb
114variant may be invoked to avoid kernel linker locking; it should be used with
115a fixed-length sbuf.
116.Pp
117The utility functions
118.Nm stack_zero ,
119.Nm stack_copy ,
120and
121.Nm stack_put
122may be used to manipulate stack data structures directly.
123.Sh SEE ALSO
124.Xr ddb 4 ,
125.Xr printf 9 ,
126.Xr sbuf 9 ,
127.Xr sx 9
128.Sh AUTHORS
129.An -nosplit
130The
131.Xr stack 9
132function suite was created by
133.An Antoine Brodin .
134.Xr stack 9
135was extended by
136.An Robert Watson
137for general-purpose use outside of
138.Xr ddb 4 .
2.\" Copyright (c) 2007 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
--- 11 unchanged lines hidden (view full) ---
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: head/share/man/man9/stack.9 174195 2007-12-02 20:40:35Z rwatson $
29.\"
30.Dd February 27, 2007
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
39In 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 "struct stack *src" "struct stack dst"
--- 8 unchanged lines hidden (view full) ---
58.Ft void
59.Fn stack_save "struct stack *st"
60.Sh DESCRIPTION
61The
62.Nm
63KPI allows querying of kernel stack trace information and the automated
64generation of kernel stack trace strings for the purposes of debugging and
65tracing.
66To use the KPI, at least one of
67.Cd "options DDB"
68and
69.Cd "options STACK"
70must be compiled into the kernel.
71.Pp
72Each stack trace is described by a
73.Vt "struct stack" .
74Before a trace may be created or otherwise manipulated, storage for the trace
75must be allocated with
76.Fn stack_create ,
77which may sleep.
78Memory associated with a trace is freed by calling
79.Fn stack_destroy .
80.Pp
81A trace of the current kernel thread's call stack may be captured using
82.Fn stack_save .
83.Pp
84.Fn stack_print
85may be used to print a stack trace using the kernel
86.Xr printf 9 ,
87and may sleep as a result of acquiring
88.Xr sx 9
89locks in the kernel linker while looking up symbol names.
90In locking-sensitive environments, the unsynchronized
91.Fn stack_print_ddb
92variant may be invoked.
93This function bypasses kernel linker locking, making it usable in
94.Xr ddb 4 ,
95but not in a live system where linker data structures may change.
96.Pp
97.Fn stack_sbuf_print
98may be used to construct a human-readable string, including conversion (where
99possible) from a simple kernel instruction pointer to a named symbol and
100offset.
101The argument
102.Ar sb
103must be an initialized
104.Dv struct sbuf
105as described in
106.Xr sbuf 9 .
107This function may sleep if an auto-extending
108.Dv struct sbuf
109is used, or due to kernel linker locking.
110In locking-sensitive environments, such as
111.Xr ddb 4 ,
112the unsynchronized
113.Fn stack_sbuf_print_ddb
114variant may be invoked to avoid kernel linker locking; it should be used with
115a fixed-length sbuf.
116.Pp
117The utility functions
118.Nm stack_zero ,
119.Nm stack_copy ,
120and
121.Nm stack_put
122may be used to manipulate stack data structures directly.
123.Sh SEE ALSO
124.Xr ddb 4 ,
125.Xr printf 9 ,
126.Xr sbuf 9 ,
127.Xr sx 9
128.Sh AUTHORS
129.An -nosplit
130The
131.Xr stack 9
132function suite was created by
133.An Antoine Brodin .
134.Xr stack 9
135was extended by
136.An Robert Watson
137for general-purpose use outside of
138.Xr ddb 4 .