diff options
author | rwatson <rwatson@FreeBSD.org> | 2007-12-02 20:40:35 +0000 |
---|---|---|
committer | rwatson <rwatson@FreeBSD.org> | 2007-12-02 20:40:35 +0000 |
commit | 99285f7544399971d1bcb6e3c18e7010905925e5 (patch) | |
tree | 25f0781d4e40520309936f686c0accc99753b656 /share/man/man9/stack.9 | |
parent | e6e32be1d57fbe0f67adfd9c0cb818a1660dca5a (diff) | |
download | FreeBSD-src-99285f7544399971d1bcb6e3c18e7010905925e5.zip FreeBSD-src-99285f7544399971d1bcb6e3c18e7010905925e5.tar.gz |
Break out stack(9) from ddb(4):
- Introduce per-architecture stack_machdep.c to hold stack_save(9).
- Introduce per-architecture machine/stack.h to capture any common
definitions required between db_trace.c and stack_machdep.c.
- Add new kernel option "options STACK"; we will build in stack(9) if it is
defined, or also if "options DDB" is defined to provide compatibility
with existing users of stack(9).
Add new stack_save_td(9) function, which allows the capture of a stacktrace
of another thread rather than the current thread, which the existing
stack_save(9) was limited to. It requires that the thread be neither
swapped out nor running, which is the responsibility of the consumer to
enforce.
Update stack(9) man page.
Build tested: amd64, arm, i386, ia64, powerpc, sparc64, sun4v
Runtime tested: amd64 (rwatson), arm (cognet), i386 (rwatson)
Diffstat (limited to 'share/man/man9/stack.9')
-rw-r--r-- | share/man/man9/stack.9 | 50 |
1 files changed, 28 insertions, 22 deletions
diff --git a/share/man/man9/stack.9 b/share/man/man9/stack.9 index 17cf509..d71af96 100644 --- a/share/man/man9/stack.9 +++ b/share/man/man9/stack.9 @@ -36,9 +36,9 @@ .Sh SYNOPSIS .In sys/param.h> .In sys/stack.h -.Pp -In kernel configuration files: +In the kernel configuration file: .Cd "options DDB" +.Cd "options STACK" .Ft struct stack * .Fn stack_create "void" .Ft void @@ -63,12 +63,11 @@ The 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. +To use the KPI, at least one of +.Cd "options DDB" +and +.Cd "options STACK" +must be compiled into the kernel. .Pp Each stack trace is described by a .Vt "struct stack" . @@ -76,7 +75,7 @@ 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 +Memory associated with a trace is freed by calling .Fn stack_destroy . .Pp A trace of the current kernel thread's call stack may be captured using @@ -84,7 +83,16 @@ A trace of the current kernel thread's call stack may be captured using .Pp .Fn stack_print may be used to print a stack trace using the kernel -.Xr printf 9 . +.Xr printf 9 , +and may sleep as a result of acquiring +.Xr sx 9 +locks in the kernel linker while looking up symbol names. +In locking-sensitive environments, the unsynchronized +.Fn stack_print_ddb +variant may be invoked. +This function bypasses kernel linker locking, making it usable in +.Xr ddb 4 , +but not in a live system where linker data structures may change. .Pp .Fn stack_sbuf_print may be used to construct a human-readable string, including conversion (where @@ -98,17 +106,13 @@ as described in .Xr sbuf 9 . This function may sleep if an auto-extending .Dv struct sbuf -is used, and because the kernel linker (used to look up symbol names) uses -.Xr sx 9 -locks. -.Pp +is used, or due to kernel linker locking. In locking-sensitive environments, such as -.Xr DDB 4 , +.Xr ddb 4 , the unsynchronized .Fn stack_sbuf_print_ddb -variant may be invoked; this makes use of kernel linker data structures to -look up symbol names without following locking protocols, so is appropriate -for use in the debugger but not while the system is live. +variant may be invoked to avoid kernel linker locking; it should be used with +a fixed-length sbuf. .Pp The utility functions .Nm stack_zero , @@ -117,7 +121,7 @@ and .Nm stack_put may be used to manipulate stack data structures directly. .Sh SEE ALSO -.Xr DDB 4 , +.Xr ddb 4 , .Xr printf 9 , .Xr sbuf 9 , .Xr sx 9 @@ -127,6 +131,8 @@ The .Xr stack 9 function suite was created by .An Antoine Brodin . -.Pp -This manual page was written by -.An Robert Watson . +.Xr stack 9 +was extended by +.An Robert Watson +for general-purpose use outside of +.Xr ddb 4 . |