diff options
Diffstat (limited to 'share/doc/gdb/Backtrace.html')
| -rw-r--r-- | share/doc/gdb/Backtrace.html | 357 |
1 files changed, 357 insertions, 0 deletions
diff --git a/share/doc/gdb/Backtrace.html b/share/doc/gdb/Backtrace.html new file mode 100644 index 0000000..5e737cd --- /dev/null +++ b/share/doc/gdb/Backtrace.html @@ -0,0 +1,357 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1988-2023 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> [<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>]… [<var>qualifier</var>]… [<var>count</var>]</code></dt> +<dt><code>bt [<var>option</var>]… [<var>qualifier</var>]… [<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 “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 <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—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 +‘<samp>bt 3</samp>’, 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>…</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’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’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=<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...) +</pre></div> + +<p>The values of arguments that were not saved in their stack frames are +shown as ‘<samp><optimized out></samp>’. +</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—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 “free-standing” +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> [<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> |