<html lang="en">
<head>
<title>Selection - Debugging with GDB</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Debugging with GDB">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Stack.html#Stack" title="Stack">
<link rel="prev" href="Backtrace.html#Backtrace" title="Backtrace">
<link rel="next" href="Frame-Info.html#Frame-Info" title="Frame Info">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 1988-2019 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.''
-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="Selection"></a>
<p>
Next: <a rel="next" accesskey="n" href="Frame-Info.html#Frame-Info">Frame Info</a>,
Previous: <a rel="previous" accesskey="p" href="Backtrace.html#Backtrace">Backtrace</a>,
Up: <a rel="up" accesskey="u" href="Stack.html#Stack">Stack</a>
<hr>
</div>
<h3 class="section">8.3 Selecting a Frame</h3>
<p>Most commands for examining the stack and other data in your program work on
whichever stack frame is selected at the moment. Here are the commands for
selecting a stack frame; all of them finish by printing a brief description
of the stack frame just selected.
<a name="index-frame_0040r_007b_002c-selecting_007d-529"></a>
<a name="index-f-_0040r_007b_0028_0040code_007bframe_007d_0029_007d-530"></a>
<dl><dt><code>frame </code><span class="roman">[</span> <var>frame-selection-spec</var> <span class="roman">]</span><br><dt><code>f </code><span class="roman">[</span> <var>frame-selection-spec</var> <span class="roman">]</span><dd>The <samp><span class="command">frame</span></samp> command allows different stack frames to be
selected. The <var>frame-selection-spec</var> can be any of the following:
<a name="index-frame-level-531"></a>
<dl><dt><var>num</var><br><dt><code>level </code><var>num</var><dd>Select frame level <var>num</var>. Recall that frame zero is the innermost
(currently executing) frame, frame one is the frame that called the
innermost one, and so on. The highest level frame is usually the one
for <code>main</code>.
<p>As this is the most common method of navigating the frame stack, the
string <samp><span class="command">level</span></samp> can be omitted. For example, the following two
commands are equivalent:
<pre class="smallexample"> (gdb) frame 3
(gdb) frame level 3
</pre>
<p><a name="index-frame-address-532"></a><br><dt><code>address </code><var>stack-address</var><dd>Select the frame with stack address <var>stack-address</var>. The
<var>stack-address</var> for a frame can be seen in the output of
<samp><span class="command">info frame</span></samp>, for example:
<pre class="smallexample"> (gdb) info frame
Stack level 1, frame at 0x7fffffffda30:
rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5
tail call frame, caller of frame at 0x7fffffffda30
source language c++.
Arglist at unknown address.
Locals at unknown address, Previous frame's sp is 0x7fffffffda30
</pre>
<p>The <var>stack-address</var> for this frame is <code>0x7fffffffda30</code> as
indicated by the line:
<pre class="smallexample"> Stack level 1, frame at 0x7fffffffda30:
</pre>
<p><a name="index-frame-function-533"></a><br><dt><code>function </code><var>function-name</var><dd>Select the stack frame for function <var>function-name</var>. If there are
multiple stack frames for function <var>function-name</var> then the inner
most stack frame is selected.
<p><a name="index-frame-view-534"></a><br><dt><code>view </code><var>stack-address</var> <span class="roman">[</span> <var>pc-addr</var> <span class="roman">]</span><dd>View a frame that is not part of <span class="sc">gdb</span>'s backtrace. The frame
viewed has stack address <var>stack-addr</var>, and optionally, a program
counter address of <var>pc-addr</var>.
<p>This is useful mainly if the chaining of stack frames has been
damaged by a bug, making it impossible for <span class="sc">gdb</span> to assign
numbers properly to all frames. In addition, this can be useful
when your program has multiple stacks and switches between them.
<p>When viewing a frame outside the current backtrace using
<samp><span class="command">frame view</span></samp> then you can always return to the original
stack using one of the previous stack frame selection instructions,
for example <samp><span class="command">frame level 0</span></samp>.
</dl>
<p><a name="index-up-535"></a><br><dt><code>up </code><var>n</var><dd>Move <var>n</var> frames up the stack; <var>n</var> defaults to 1. For positive
numbers <var>n</var>, this advances toward the outermost frame, to higher
frame numbers, to frames that have existed longer.
<p><a name="index-down-536"></a><a name="index-do-_0040r_007b_0028_0040code_007bdown_007d_0029_007d-537"></a><br><dt><code>down </code><var>n</var><dd>Move <var>n</var> frames down the stack; <var>n</var> defaults to 1. For
positive numbers <var>n</var>, this advances toward the innermost frame, to
lower frame numbers, to frames that were created more recently.
You may abbreviate <code>down</code> as <code>do</code>.
</dl>
<p>All of these commands end by printing two lines of output describing the
frame. The first line shows the frame number, the function name, the
arguments, and the source file and line number of execution in that
frame. The second line shows the text of that source line.
<p>For example:
<pre class="smallexample"> (gdb) up
#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
at env.c:10
10 read_input_file (argv[i]);
</pre>
<p>After such a printout, the <code>list</code> command with no arguments
prints ten lines centered on the point of execution in the frame.
You can also edit the program at the point of execution with your favorite
editing program by typing <code>edit</code>.
See <a href="List.html#List">Printing Source Lines</a>,
for details.
<a name="index-select_002dframe-538"></a>
<dl><dt><code>select-frame </code><span class="roman">[</span> <var>frame-selection-spec</var> <span class="roman">]</span><dd>The <code>select-frame</code> command is a variant of <code>frame</code> that does
not display the new frame after selecting it. This command is
intended primarily for use in <span class="sc">gdb</span> command scripts, where the
output might be unnecessary and distracting. The
<var>frame-selection-spec</var> is as for the <samp><span class="command">frame</span></samp> command
described in <a href="Selection.html#Selection">Selecting a Frame</a>.
<p><a name="index-down_002dsilently-539"></a><a name="index-up_002dsilently-540"></a><br><dt><code>up-silently </code><var>n</var><dt><code>down-silently </code><var>n</var><dd>These two commands are variants of <code>up</code> and <code>down</code>,
respectively; they differ in that they do their work silently, without
causing display of the new frame. They are intended primarily for use
in <span class="sc">gdb</span> command scripts, where the output might be unnecessary and
distracting.
</dl>
</body></html>