| stack.9 (c2c014f24c10f90d85126ac5fbd4d8524de32b1c) | stack.9 (1c29da02798d968eb874b86221333a56393a94c3) |
|---|---|
| 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 --- 13 unchanged lines hidden (view full) --- 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.\" | 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 --- 13 unchanged lines hidden (view full) --- 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 October 6, 2017 | 30.Dd January 31, 2020 |
| 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 --- 21 unchanged lines hidden (view full) --- 60.Ft void 61.Fn stack_print_short_ddb "const struct stack *st" 62.Ft void 63.Fn stack_sbuf_print "struct sbuf sb*" "const struct stack *st" 64.Ft void 65.Fn stack_sbuf_print_ddb "struct sbuf sb*" "const struct stack *st" 66.Ft void 67.Fn stack_save "struct stack *st" | 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 --- 21 unchanged lines hidden (view full) --- 60.Ft void 61.Fn stack_print_short_ddb "const struct stack *st" 62.Ft void 63.Fn stack_sbuf_print "struct sbuf sb*" "const struct stack *st" 64.Ft void 65.Fn stack_sbuf_print_ddb "struct sbuf sb*" "const struct stack *st" 66.Ft void 67.Fn stack_save "struct stack *st" |
| 68.Ft void 69.Fn stack_save_td "struct stack *st" "struct thread *td" | |
| 70.Ft int | 68.Ft int |
| 71.Fn stack_save_td_running "struct stack *st" "struct thread *td" | 69.Fn stack_save_td "struct stack *st" "struct thread *td" |
| 72.Sh DESCRIPTION 73The 74.Nm 75KPI allows querying of kernel stack trace information and the automated 76generation of kernel stack trace strings for the purposes of debugging and 77tracing. 78To use the KPI, at least one of 79.Cd "options DDB" --- 8 unchanged lines hidden (view full) --- 88.Fn stack_create . 89The 90.Ar flags 91argument is passed to 92.Xr malloc 9 . 93Memory associated with a trace is freed by calling 94.Fn stack_destroy . 95.Pp | 70.Sh DESCRIPTION 71The 72.Nm 73KPI allows querying of kernel stack trace information and the automated 74generation of kernel stack trace strings for the purposes of debugging and 75tracing. 76To use the KPI, at least one of 77.Cd "options DDB" --- 8 unchanged lines hidden (view full) --- 86.Fn stack_create . 87The 88.Ar flags 89argument is passed to 90.Xr malloc 9 . 91Memory associated with a trace is freed by calling 92.Fn stack_destroy . 93.Pp |
| 96A trace of the current kernel thread's call stack may be captured using | 94A trace of the current thread's kernel call stack may be captured using |
| 97.Fn stack_save . 98.Fn stack_save_td | 95.Fn stack_save . 96.Fn stack_save_td |
| 99and 100.Fn stack_save_td_running 101can also be used to capture the stack of a caller-specified thread. 102Callers of these functions must own the thread lock of the specified thread. | 97can be used to capture the kernel stack of a caller-specified thread. 98Callers of these functions must own the thread lock of the specified thread, 99and the thread's stack must not be swapped out. |
| 103.Fn stack_save_td | 100.Fn stack_save_td |
| 104can capture the stack of a kernel thread that is not running or 105swapped out at the time of the call. 106.Fn stack_save_td_running 107can capture the stack of a running kernel thread. | 101can capture the kernel stack of a running thread, though note that this is 102not implemented on all platforms. 103If the thread is running, the caller must also hold the process lock for the 104target thread. |
| 108.Pp 109.Fn stack_print 110and 111.Fn stack_print_short 112may be used to print a stack trace using the kernel 113.Xr printf 9 , 114and may sleep as a result of acquiring 115.Xr sx 9 --- 36 unchanged lines hidden (view full) --- 152.Sh RETURN VALUES 153.Fn stack_put 154returns 0 on success. 155Otherwise the 156.Dv struct stack 157does not contain space to record additional frames, and a non-zero value is 158returned. 159.Pp | 105.Pp 106.Fn stack_print 107and 108.Fn stack_print_short 109may be used to print a stack trace using the kernel 110.Xr printf 9 , 111and may sleep as a result of acquiring 112.Xr sx 9 --- 36 unchanged lines hidden (view full) --- 149.Sh RETURN VALUES 150.Fn stack_put 151returns 0 on success. 152Otherwise the 153.Dv struct stack 154does not contain space to record additional frames, and a non-zero value is 155returned. 156.Pp |
| 160.Fn stack_save_td_running | 157.Fn stack_save_td |
| 161returns 0 when the stack capture was successful and a non-zero error number 162otherwise. 163In particular, | 158returns 0 when the stack capture was successful and a non-zero error number 159otherwise. 160In particular, |
| 164.Er EAGAIN | 161.Er EBUSY |
| 165is returned if the thread was running in user mode at the time that the 166capture was attempted, and 167.Er EOPNOTSUPP 168is returned if the operation is not implemented. 169.Sh SEE ALSO 170.Xr ddb 4 , 171.Xr printf 9 , 172.Xr sbuf 9 , --- 12 unchanged lines hidden --- | 162is returned if the thread was running in user mode at the time that the 163capture was attempted, and 164.Er EOPNOTSUPP 165is returned if the operation is not implemented. 166.Sh SEE ALSO 167.Xr ddb 4 , 168.Xr printf 9 , 169.Xr sbuf 9 , --- 12 unchanged lines hidden --- |