.TH BT 1 "September 21, 2005" .SH NAME bt \- Stack Traceback command .SH SYNOPSIS bt [ <stack-frame-address> ] .LP btp <pid> .LP btt <struct-task-address> .LP bta [ DRSTZUIMA ] .LP btc [<cpu>] .SH DESCRIPTION .hy 0 The .B bt command is used to print a stack traceback. It uses the current registers (see \fBrd\fP command) to determine the starting context and attempts to provide a complete stack traceback for the active thread. If \fIstack-frame-address\fP is supplied, it is assumed to point to the start of a valid stack frame and the stack will be traced back from that point (e.g. on i386 architecture, \fIstack-frame-address\fP should be the stack address of a saved \fB%eip\fP value from a \fBcall\fP instruction. on sparc64 architecture, it should be a pointer to a saved register window, as is found in the \fB%fp\fP register). .P If present, a kernel configuration option \fBCONFIG_FRAME_POINTER\fP should be enabled so that the compiler will utilize the frame pointer register properly to maintain a stack which can be correctly analyzed. Some architectures (e.g. sparc64) always use \fBCONFIG_FRAME_POINTER\fP, and so the option is not present. .P The \fBbt\fP command will attempt to analyze the stack without frame pointers if the \fBCONFIG_FRAME_POINTER\fP option is not enabled, but the analysis is difficult and may not produce accurate nor complete results. .P The \fBbtp\fP command will analyze the stack for the given process identification (see the \fBps\fP command). \fBbtp\fP sets the current process for any following register display or update commands. .P The \fBbtt\fP command will analyze the stack for the given task structure. It is exactly equivalent to \fBbtp\fR on the pid extracted from the task structure. \fBbtt\fP sets the current process for any following register display or update commands. .P The \fBbta\fP command lists the stack for all processes in the desired state. Without any parameters, \fBbta\fP gives a backtrace for all useful processes. If a parameter is specified, it is a single string consisting of the letters D, R, S, T, Z, U, I, M and A in any order. See the kdb \fBps\fR man page for more details. \fBbta\fP does not change the current process. .P The \fBbtc\fP command will analyze the stack for the current process on a specified cpu or, if no cpu number is supplied, for the current process on all cpus. It does not switch to the other cpus, instead it uses the task structures to identify and issue \fBbtt\fR against the current task on the desired cpus. \fBbtc\fP with no arguments does not change the current process. \fBbtc\fP with a cpu number sets the current process for any following register display or update commands. .P For each function, the stack trace prints at least two lines. The first line contains four or five fields\ :- .IP * 3 The pointer to the previous stack frame, blank if there is no valid frame pointer. .PD 0 .IP * 3 The current address within this frame. .IP * 3 The address converted to a function name (actually the first non-local label which is <= the address). .IP * 3 The offset of the address within the function. .IP * 3 Any parameters to the function. .PD 1 .PP On the next line there are five fields which are designed to make it easier to match the trace against the kernel code\ :- .IP * 3 The module name that contains the address, "kernel" if it is in the base kernel. .PD 0 .IP * 3 The section name that contains the address (not available on 2.6 kernels). .IP * 3 The start address of the section (not available on 2.6 kernels). .IP * 3 The start address of the function. .IP * 3 The end address of the function (the first non-local label which is > the address). .PD 1 .PP If arguments are being converted to symbols, any argument which converts to a kernel or module address is printed as\ :- .IP * 3 Argument address. .PD 0 .IP * 3 The module name that contains the address, "kernel" if it is in the base kernel. .IP * 3 The symbol name the argument maps to. .IP * 3 The offset of the argument from the symbol, suppressed if 0. .PD 1 .SH MATCHING TRACE TO KERNEL CODE The command "objdump\ -S" will disassemble an object and, if the code was compiled with debugging (gcc flag -g), objdump will interleave the C source lines with the generated object. .PP A complete objdump of the kernel or a module is too big, normally you only want specific functions. By default objdump will only print the .text section but Linux uses other section names for executable code. When objdump prints relocatable objects (modules) it uses an offset of 0 which is awkward to relate to the stack trace. The five fields which are printed for each function are designed to make it easier to match the stack trace against the kernel code using "objdump\ -S". .PP If the function is in the kernel then you need the section name, the start and end address of the function. The command is .PP .nf objdump -S -j <section_name> \\ --start-address=<start-address> \\ --stop-address=<end-address> \\ /usr/src/linux/vmlinux .fi .PP If the function is in a module then you need the section name, the start address of the section, the start and end address of the function, the module name. The command is .PP .nf objdump -S -j <section_name> \\ --adjust-vma=<section-start> \\ --start-address=<start-address> \\ --stop-address=<end-address> \\ /path/to/module/<module-name>.o .fi .PP Unfortunately the 2.6 kernel does not provide the information required to locate the start of the section, which makes it very difficult to perform a reliable objdump on a module. .PP All addresses to objdump must be preceded by '0x' if they are in hex, objdump does not assume hex. The stack trace values are printed with leading '0x' to make it easy to run objdump. .SH LIMITATIONS If the kernel is compiled without frame pointers, stack tracebacks may be incomplete. The \fBmds %esp\fP (i386) or \fBmds %fp\fP (sparc64) command may be useful in attemping to determine the actual stack traceback manually. .P A stack trace can be misleading if any code in a function exit has been executed, the stack is partially unwound at that stage. .P The \fBbt\fP command may print more arguments for a function than that function accepts; For sparc64, this will always happen as the debugger cannot determine the correct number. For i386, this happens when the C compiler doesn't immediately pop the arguments off the stack upon return from a called function. When this is this case, these extra stack words will be considered additional arguments by the \fBbt\fP command. .SH ENVIRONMENT The \fBBTARGS\fP environment variable governs the maximum number of arguments that are printed for any single function. On IA64 hardware, there is no difference between input and local registers, the first \fBBTARGS\fP registers are printed, up to the total limit of input plus local registers. Use a large value for \fBBTARGS\fP if you want to see the local registers on IA64. .PP If the \fBBTSP\fP environment variable is non-zero then each backtrace frame may print an extra line giving information about the stack pointers, this is architecture specific. .PP If the \fBBTSYMARG\fP environment variable is non-zero then any arguments that fall within the kernel are converted to symbols. .PP If the \fBNOSECT\fP environment variable is non-zero then the section information is suppressed. The default is NOSECT=1 so section data is suppressed; use set\ NOSECT=0 to see section information. .PP The \fBBTAPROMPT\fP environment variable controls the prompt after each process is listed by the \fBbta\fP command. If \fBBTAPROMPT\fP is not set or is non-zero then \fBbta\fP issues a prompt after each process is listed. If \fBBTAPROMPT\fP is set to zero then no prompt is issued and all processes are listed without human intervention. .PP \fBbt\fR with no parameters uses the \fBPS\fR environment variable, see the kdb \fBps\fR man page. .SH SMP CONSIDERATIONS None. .SH EXAMPLES .nf .na .ft CW Entering kdb (0xc3cb4000) due to Breakpoint @ 0xc011725d Instruction(i) breakpoint #0 at 0xc011725c qm_modules+0xd1: movl %ebp,%esp kdb> bt EBP EIP Function(args) 0xc3cb5f98 0xc011725d qm_modules+0xd1 (0x80721c0, 0x100, 0xbfff5000) kernel .text 0xc0100000 0xc011718c 0xc0117264 0xc3cb5fbc 0xc0117875 sys_query_module+0x1b1 (0x0, 0x1, 0x80721c0, 0x100, 0xbfff5000) kernel .text 0xc0100000 0xc01176c4 0xc01178e8 0xc01095f8 system_call+0x34 kernel .text 0xc0100000 0xc01095c4 0xc01095fc