gdb: Backtrace
8.2 Backtraces
==============
A backtrace is a summary of how your program got where it is. It shows
one line per frame, for many frames, starting with the currently
executing frame (frame zero), followed by its caller (frame one), and on
up the stack.
To print a backtrace of the entire stack, use the 'backtrace'
command, or its alias 'bt'. This command will print one line per frame
for frames in the stack. By default, all stack frames are printed. You
can stop the backtrace at any time by typing the system interrupt
character, normally 'Ctrl-c'.
'backtrace [ARGS...]'
'bt [ARGS...]'
Print the backtrace of the entire stack. The optional ARGS can be
one of the following:
'N'
'N'
Print only the innermost N frames, where N is a positive
number.
'-N'
'-N'
Print only the outermost N frames, where N is a positive
number.
'full'
Print the values of the local variables also. This can be
combined with a number to limit the number of frames shown.
'no-filters'
Do not run Python frame filters on this backtrace. 
Frame Filter API, for more information. Additionally use
disable frame-filter all to turn off all frame
filters. This is only relevant when GDB has been configured
with 'Python' support.
'hide'
A Python frame filter might decide to "elide" some frames.
Normally such elided frames are still printed, but they are
indented relative to the filtered frames that cause them to be
elided. The 'hide' option causes elided frames to not be
printed at all.
The names 'where' and 'info stack' (abbreviated 'info s') are
additional aliases for 'backtrace'.
In a multi-threaded program, GDB by default shows the backtrace only
for the current thread. To display the backtrace for several or all of
the threads, use the command 'thread apply' (thread apply
Threads.). For example, if you type 'thread apply all backtrace', GDB
will display the backtrace for all the threads; this is handy when you
debug a core dump of a multi-threaded program.
Each line in the backtrace shows the frame number and the function
name. The program counter value is also shown--unless you use 'set
print address off'. The backtrace also shows the source file name and
line number, as well as the arguments to the function. The program
counter value is omitted if it is at the beginning of the code for that
line number.
Here is an example of a backtrace. It was made with the command 'bt
3', so it shows the innermost three frames.
#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
at builtin.c:993
#1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242
#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
at macro.c:71
(More stack frames follow...)
The display for frame zero does not begin with a program counter value,
indicating that your program has stopped at the beginning of the code
for line '993' of 'builtin.c'.
The value of parameter 'data' in frame 1 has been replaced by '...'. By
default, GDB prints the value of a parameter only if it is a scalar
(integer, pointer, enumeration, etc). See command 'set print
frame-arguments' in Print Settings for more details on how to
configure the way function parameter values are printed.
If your program was compiled with optimizations, some compilers will
optimize away arguments passed to functions if those arguments are never
used after the call. Such optimizations generate code that passes
arguments through registers, but doesn't store those arguments in the
stack frame. GDB has no way of displaying such arguments in stack
frames other than the innermost one. Here's what such a backtrace might
look like:
#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
at builtin.c:993
#1 0x6e38 in expand_macro (sym=<optimized out>) at macro.c:242
#2 0x6840 in expand_token (obs=0x0, t=<optimized out>, td=0xf7fffb08)
at macro.c:71
(More stack frames follow...)
The values of arguments that were not saved in their stack frames are
shown as '<optimized out>'.
If you need to display the values of such optimized-out arguments,
either deduce that from other variables whose values depend on the one
you are interested in, or recompile without optimizations.
Most programs have a standard user entry point--a place where system
libraries and startup code transition into user code. For C this is
'main'(1). When GDB finds the entry function in a backtrace it will
terminate the backtrace, to avoid tracing into highly system-specific
(and generally uninteresting) code.
If you need to examine the startup code, or limit the number of
levels in a backtrace, you can change this behavior:
'set backtrace past-main'
'set backtrace past-main on'
Backtraces will continue past the user entry point.
'set backtrace past-main off'
Backtraces will stop when they encounter the user entry point.
This is the default.
'show backtrace past-main'
Display the current user entry point backtrace policy.
'set backtrace past-entry'
'set backtrace past-entry on'
Backtraces will continue past the internal entry point of an
application. This entry point is encoded by the linker when the
application is built, and is likely before the user entry point
'main' (or equivalent) is called.
'set backtrace past-entry off'
Backtraces will stop when they encounter the internal entry point
of an application. This is the default.
'show backtrace past-entry'
Display the current internal entry point backtrace policy.
'set backtrace limit N'
'set backtrace limit 0'
'set backtrace limit unlimited'
Limit the backtrace to N levels. A value of 'unlimited' or zero
means unlimited levels.
'show backtrace limit'
Display the current limit on backtrace levels.
You can control how file names are displayed.
'set filename-display'
'set filename-display relative'
Display file names relative to the compilation directory. This is
the default.
'set filename-display basename'
Display only basename of a filename.
'set filename-display absolute'
Display an absolute filename.
'show filename-display'
Show the current way to display filenames.
---------- Footnotes ----------
(1) Note that embedded programs (the so-called "free-standing"
environment) are not required to have a 'main' function as the entry
point. They could even have multiple entry points.
Info Catalog
gdb: Frames
gdb: Stack
gdb: Selection