| stack.9 (174137) | stack.9 (174195) |
|---|---|
| 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.\" | 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 174137 2007-12-01 22:04:16Z rwatson $ | 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 | 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 |
| 39.Pp 40In kernel configuration files: | 39In the kernel configuration file: |
| 41.Cd "options DDB" | 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. | 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. |
| 66.Nm 67relies on the presence of 68.Xr DDB 4 , 69and all use of these functions must be made conditional on 70.Nm DDB 71being compiled in the kernel. | 66To use the KPI, at least one of 67.Cd "options DDB" 68and 69.Cd "options STACK" 70must be compiled into the kernel. |
| 72.Pp 73Each stack trace is described by a 74.Vt "struct stack" . 75Before a trace may be created or otherwise manipulated, storage for the trace 76must be allocated with 77.Fn stack_create , 78which may sleep. | 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. |
| 79Memory associated with a trace may be freed by calling | 78Memory associated with a trace is freed by calling |
| 80.Fn stack_destroy . 81.Pp 82A trace of the current kernel thread's call stack may be captured using 83.Fn stack_save . 84.Pp 85.Fn stack_print 86may be used to print a stack trace using the kernel | 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 |
| 87.Xr printf 9 . | 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. |
| 88.Pp 89.Fn stack_sbuf_print 90may be used to construct a human-readable string, including conversion (where 91possible) from a simple kernel instruction pointer to a named symbol and 92offset. 93The argument 94.Ar sb 95must be an initialized 96.Dv struct sbuf 97as described in 98.Xr sbuf 9 . 99This function may sleep if an auto-extending 100.Dv struct sbuf | 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 |
| 101is used, and because the kernel linker (used to look up symbol names) uses 102.Xr sx 9 103locks. 104.Pp | 109is used, or due to kernel linker locking. |
| 105In locking-sensitive environments, such as | 110In locking-sensitive environments, such as |
| 106.Xr DDB 4 , | 111.Xr ddb 4 , |
| 107the unsynchronized 108.Fn stack_sbuf_print_ddb | 112the unsynchronized 113.Fn stack_sbuf_print_ddb |
| 109variant may be invoked; this makes use of kernel linker data structures to 110look up symbol names without following locking protocols, so is appropriate 111for use in the debugger but not while the system is live. | 114variant may be invoked to avoid kernel linker locking; it should be used with 115a fixed-length sbuf. |
| 112.Pp 113The utility functions 114.Nm stack_zero , 115.Nm stack_copy , 116and 117.Nm stack_put 118may be used to manipulate stack data structures directly. 119.Sh SEE ALSO | 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 |
| 120.Xr DDB 4 , | 124.Xr ddb 4 , |
| 121.Xr printf 9 , 122.Xr sbuf 9 , 123.Xr sx 9 124.Sh AUTHORS 125.An -nosplit 126The 127.Xr stack 9 128function suite was created by 129.An Antoine Brodin . | 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 . |
| 130.Pp 131This manual page was written by 132.An Robert Watson . | 134.Xr stack 9 135was extended by 136.An Robert Watson 137for general-purpose use outside of 138.Xr ddb 4 . |