doc/gdb/Backtrace.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software" and "Free Software Needs
Free Documentation", with the Front-Cover Texts being "A GNU Manual,"
and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: "You are free to copy and modify
this GNU Manual.  Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom." -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Debugging with GDB: Backtrace</title>

<meta name="description" content="Debugging with GDB: Backtrace">
<meta name="keywords" content="Debugging with GDB: Backtrace">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Stack.html#Stack" rel="up" title="Stack">
<link href="Selection.html#Selection" rel="next" title="Selection">
<link href="Frames.html#Frames" rel="previous" title="Frames">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Backtrace"></a>
<div class="header">
<p>
Next: <a href="Selection.html#Selection" accesskey="n" rel="next">Selection</a>, Previous: <a href="Frames.html#Frames" accesskey="p" rel="previous">Frames</a>, Up: <a href="Stack.html#Stack" accesskey="u" rel="up">Stack</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Backtraces"></a>
<h3 class="section">8.2 Backtraces</h3>

<a name="index-traceback"></a>
<a name="index-call-stack-traces"></a>
<p>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.
</p>
<a name="backtrace_002dcommand"></a><a name="index-backtrace"></a>
<a name="index-bt-_0028backtrace_0029"></a>
<p>To print a backtrace of the entire stack, use the <code>backtrace</code>
command, or its alias <code>bt</code>.  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 <kbd>Ctrl-c</kbd>.
</p>
<dl compact="compact">
<dt><code>backtrace [<var>option</var>]&hellip; [<var>qualifier</var>]&hellip; [<var>count</var>]</code></dt>
<dt><code>bt [<var>option</var>]&hellip; [<var>qualifier</var>]&hellip; [<var>count</var>]</code></dt>
<dd><p>Print the backtrace of the entire stack.
</p>
<p>The optional <var>count</var> can be one of the following:
</p>
<dl compact="compact">
<dt><code><var>n</var></code></dt>
<dt><code><var>n</var></code></dt>
<dd><p>Print only the innermost <var>n</var> frames, where <var>n</var> is a positive
number.
</p>
</dd>
<dt><code>-<var>n</var></code></dt>
<dt><code>-<var>n</var></code></dt>
<dd><p>Print only the outermost <var>n</var> frames, where <var>n</var> is a positive
number.
</p></dd>
</dl>

<p>Options:
</p>
<dl compact="compact">
<dt><code>-full</code></dt>
<dd><p>Print the values of the local variables also.  This can be combined
with the optional <var>count</var> to limit the number of frames shown.
</p>
</dd>
<dt><code>-no-filters</code></dt>
<dd><p>Do not run Python frame filters on this backtrace.  See <a href="Frame-Filter-API.html#Frame-Filter-API">Frame Filter API</a>, for more information.  Additionally use <a href="Frame-Filter-Management.html#disable-frame_002dfilter-all">disable frame-filter all</a> to turn off all frame filters.  This is only
relevant when <small>GDB</small> has been configured with <code>Python</code>
support.
</p>
</dd>
<dt><code>-hide</code></dt>
<dd><p>A Python frame filter might decide to &ldquo;elide&rdquo; 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 <code>-hide</code>
option causes elided frames to not be printed at all.
</p></dd>
</dl>

<p>The <code>backtrace</code> command also supports a number of options that
allow overriding relevant global print settings as set by <code>set
backtrace</code> and <code>set print</code> subcommands:
</p>
<dl compact="compact">
<dt><code>-past-main [<code>on</code>|<code>off</code>]</code></dt>
<dd><p>Set whether backtraces should continue past <code>main</code>.  Related setting:
<a href="#set-backtrace-past_002dmain">set backtrace past-main</a>.
</p>
</dd>
<dt><code>-past-entry [<code>on</code>|<code>off</code>]</code></dt>
<dd><p>Set whether backtraces should continue past the entry point of a program.
Related setting: <a href="#set-backtrace-past_002dentry">set backtrace past-entry</a>.
</p>
</dd>
<dt><code>-entry-values <code>no</code>|<code>only</code>|<code>preferred</code>|<code>if-needed</code>|<code>both</code>|<code>compact</code>|<code>default</code></code></dt>
<dd><p>Set printing of function arguments at function entry.
Related setting: <a href="Print-Settings.html#set-print-entry_002dvalues">set print entry-values</a>.
</p>
</dd>
<dt><code>-frame-arguments <code>all</code>|<code>scalars</code>|<code>none</code></code></dt>
<dd><p>Set printing of non-scalar frame arguments.
Related setting: <a href="Print-Settings.html#set-print-frame_002darguments">set print frame-arguments</a>.
</p>
</dd>
<dt><code>-raw-frame-arguments [<code>on</code>|<code>off</code>]</code></dt>
<dd><p>Set whether to print frame arguments in raw form.
Related setting: <a href="Print-Settings.html#set-print-raw_002dframe_002darguments">set print raw-frame-arguments</a>.
</p>
</dd>
<dt><code>-frame-info <code>auto</code>|<code>source-line</code>|<code>location</code>|<code>source-and-location</code>|<code>location-and-address</code>|<code>short-location</code></code></dt>
<dd><p>Set printing of frame information.
Related setting: <a href="Print-Settings.html#set-print-frame_002dinfo">set print frame-info</a>.
</p></dd>
</dl>

<p>The optional <var>qualifier</var> is maintained for backward compatibility.
It can be one of the following:
</p>
<dl compact="compact">
<dt><code>full</code></dt>
<dd><p>Equivalent to the <code>-full</code> option.
</p>
</dd>
<dt><code>no-filters</code></dt>
<dd><p>Equivalent to the <code>-no-filters</code> option.
</p>
</dd>
<dt><code>hide</code></dt>
<dd><p>Equivalent to the <code>-hide</code> option.
</p></dd>
</dl>

</dd>
</dl>

<a name="index-where"></a>
<a name="index-info-stack"></a>
<p>The names <code>where</code> and <code>info stack</code> (abbreviated <code>info s</code>)
are additional aliases for <code>backtrace</code>.
</p>
<a name="index-multiple-threads_002c-backtrace"></a>
<p>In a multi-threaded program, <small>GDB</small> by default shows the
backtrace only for the current thread.  To display the backtrace for
several or all of the threads, use the command <code>thread apply</code>
(see <a href="Threads.html#Threads">thread apply</a>).  For example, if you type <kbd>thread
apply all backtrace</kbd>, <small>GDB</small> will display the backtrace for all
the threads; this is handy when you debug a core dump of a
multi-threaded program.
</p>
<p>Each line in the backtrace shows the frame number and the function name.
The program counter value is also shown&mdash;unless you use <code>set
print address off</code>.  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.
</p>
<p>Here is an example of a backtrace.  It was made with the command
&lsquo;<samp>bt 3</samp>&rsquo;, so it shows the innermost three frames.
</p>
<div class="smallexample">
<pre class="smallexample">#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...)
</pre></div>

<p>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 <code>993</code> of <code>builtin.c</code>.
</p>
<p>The value of parameter <code>data</code> in frame 1 has been replaced by
<code>&hellip;</code>.  By default, <small>GDB</small> prints the value of a parameter
only if it is a scalar (integer, pointer, enumeration, etc).  See command
<kbd>set print frame-arguments</kbd> in <a href="Print-Settings.html#Print-Settings">Print Settings</a> for more details
on how to configure the way function parameter values are printed.
The command <kbd>set print frame-info</kbd> (see <a href="Print-Settings.html#Print-Settings">Print Settings</a>) controls
what frame information is printed.
</p>
<a name="index-optimized-out_002c-in-backtrace"></a>
<a name="index-function-call-arguments_002c-optimized-out"></a>
<p>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&rsquo;t store those arguments
in the stack frame.  <small>GDB</small> has no way of displaying such
arguments in stack frames other than the innermost one.  Here&rsquo;s what
such a backtrace might look like:
</p>
<div class="smallexample">
<pre class="smallexample">#0  m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
    at builtin.c:993
#1  0x6e38 in expand_macro (sym=&lt;optimized out&gt;) at macro.c:242
#2  0x6840 in expand_token (obs=0x0, t=&lt;optimized out&gt;, td=0xf7fffb08)
    at macro.c:71
(More stack frames follow...)
</pre></div>

<p>The values of arguments that were not saved in their stack frames are
shown as &lsquo;<samp>&lt;optimized out&gt;</samp>&rsquo;.
</p>
<p>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.
</p>
<a name="index-backtrace-beyond-main-function"></a>
<a name="index-program-entry-point"></a>
<a name="index-startup-code_002c-and-backtrace"></a>
<p>Most programs have a standard user entry point&mdash;a place where system
libraries and startup code transition into user code.  For C this is
<code>main</code><a name="DOCF9" href="#FOOT9"><sup>9</sup></a>.
When <small>GDB</small> finds the entry function in a backtrace
it will terminate the backtrace, to avoid tracing into highly
system-specific (and generally uninteresting) code.
</p>
<p>If you need to examine the startup code, or limit the number of levels
in a backtrace, you can change this behavior:
</p>
<dl compact="compact">
<dt><code>set backtrace past-main</code></dt>
<dt><code>set backtrace past-main on</code></dt>
<dd><a name="set-backtrace-past_002dmain"></a><a name="index-set-backtrace"></a>
<p>Backtraces will continue past the user entry point.
</p>
</dd>
<dt><code>set backtrace past-main off</code></dt>
<dd><p>Backtraces will stop when they encounter the user entry point.  This is the
default.
</p>
</dd>
<dt><code>show backtrace past-main</code></dt>
<dd><a name="index-show-backtrace"></a>
<p>Display the current user entry point backtrace policy.
</p>
</dd>
<dt><code>set backtrace past-entry</code></dt>
<dt><code>set backtrace past-entry on</code></dt>
<dd><a name="set-backtrace-past_002dentry"></a><p>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 <code>main</code> (or equivalent) is called.
</p>
</dd>
<dt><code>set backtrace past-entry off</code></dt>
<dd><p>Backtraces will stop when they encounter the internal entry point of an
application.  This is the default.
</p>
</dd>
<dt><code>show backtrace past-entry</code></dt>
<dd><p>Display the current internal entry point backtrace policy.
</p>
</dd>
<dt><code>set backtrace limit <var>n</var></code></dt>
<dt><code>set backtrace limit 0</code></dt>
<dt><code>set backtrace limit unlimited</code></dt>
<dd><a name="set-backtrace-limit"></a><a name="index-backtrace-limit"></a>
<p>Limit the backtrace to <var>n</var> levels.  A value of <code>unlimited</code>
or zero means unlimited levels.
</p>
</dd>
<dt><code>show backtrace limit</code></dt>
<dd><p>Display the current limit on backtrace levels.
</p></dd>
</dl>

<p>You can control how file names are displayed.
</p>
<dl compact="compact">
<dt><code>set filename-display</code></dt>
<dt><code>set filename-display relative</code></dt>
<dd><a name="index-filename_002ddisplay"></a>
<p>Display file names relative to the compilation directory.  This is the default.
</p>
</dd>
<dt><code>set filename-display basename</code></dt>
<dd><p>Display only basename of a filename.
</p>
</dd>
<dt><code>set filename-display absolute</code></dt>
<dd><p>Display an absolute filename.
</p>
</dd>
<dt><code>show filename-display</code></dt>
<dd><p>Show the current way to display filenames.
</p></dd>
</dl>

<div class="footnote">
<hr>
<h4 class="footnotes-heading">Footnotes</h4>

<h3><a name="FOOT9" href="#DOCF9">(9)</a></h3>
<p>Note that embedded programs (the so-called &ldquo;free-standing&rdquo;
environment) are not required to have a <code>main</code> function as the
entry point.  They could even have multiple entry points.</p>
</div>
<hr>
<div class="header">
<p>
Next: <a href="Selection.html#Selection" accesskey="n" rel="next">Selection</a>, Previous: <a href="Frames.html#Frames" accesskey="p" rel="previous">Frames</a>, Up: <a href="Stack.html#Stack" accesskey="u" rel="up">Stack</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>


</body>
</html>