2 _dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
3 _dnl__ This file is part of the source for the GDB manual.
5 @node Stack, Source, Stopping, Top
6 @chapter Examining the Stack
8 When your program has stopped, the first thing you need to know is where it
9 stopped and how it got there.
12 Each time your program performs a function call, the information about
13 where in the program the call was made from is saved in a block of data
14 called a @dfn{stack frame}. The frame also contains the arguments of the
15 call and the local variables of the function that was called. All the
16 stack frames are allocated in a region of memory called the @dfn{call
19 When your program stops, the _GDBN__ commands for examining the stack allow you
20 to see all of this information.
22 @cindex selected frame
23 One of the stack frames is @dfn{selected} by _GDBN__ and many _GDBN__ commands
24 refer implicitly to the selected frame. In particular, whenever you ask
25 _GDBN__ for the value of a variable in the program, the value is found in the
26 selected frame. There are special _GDBN__ commands to select whichever frame
27 you are interested in.
29 When the program stops, _GDBN__ automatically selects the currently executing
30 frame and describes it briefly as the @code{frame} command does
31 (@pxref{Frame Info, Info}).
34 * Frames:: Stack Frames
35 * Backtrace:: Backtraces
36 * Selection:: Selecting a Frame
37 * Frame Info:: Information on a Frame
40 @node Frames, Backtrace, Stack, Stack
45 The call stack is divided up into contiguous pieces called @dfn{stack
46 frames}, or @dfn{frames} for short; each frame is the data associated
47 with one call to one function. The frame contains the arguments given
48 to the function, the function's local variables, and the address at
49 which the function is executing.
52 @cindex outermost frame
53 @cindex innermost frame
54 When your program is started, the stack has only one frame, that of the
55 function @code{main}. This is called the @dfn{initial} frame or the
56 @dfn{outermost} frame. Each time a function is called, a new frame is
57 made. Each time a function returns, the frame for that function invocation
58 is eliminated. If a function is recursive, there can be many frames for
59 the same function. The frame for the function in which execution is
60 actually occurring is called the @dfn{innermost} frame. This is the most
61 recently created of all the stack frames that still exist.
64 Inside your program, stack frames are identified by their addresses. A
65 stack frame consists of many bytes, each of which has its own address; each
66 kind of computer has a convention for choosing one of those bytes whose
67 address serves as the address of the frame. Usually this address is kept
68 in a register called the @dfn{frame pointer register} while execution is
69 going on in that frame.
72 _GDBN__ assigns numbers to all existing stack frames, starting with
73 zero for the innermost frame, one for the frame that called it,
74 and so on upward. These numbers do not really exist in your program;
75 they are assigned by _GDBN__ to give you a way of designating stack
76 frames in _GDBN__ commands.
78 @cindex frameless execution
79 Some compilers allow functions to be compiled so that they operate
80 without stack frames. (For example, the @code{_GCC__} option
81 @samp{-fomit-frame-pointer} will generate functions without a frame.)
82 This is occasionally done with heavily used library functions to save
83 the frame setup time. _GDBN__ has limited facilities for dealing with
84 these function invocations. If the innermost function invocation has no
85 stack frame, _GDBN__ will nevertheless regard it as though it had a
86 separate frame, which is numbered zero as usual, allowing correct
87 tracing of the function call chain. However, _GDBN__ has no provision
88 for frameless functions elsewhere in the stack.
90 @node Backtrace, Selection, Frames, Stack
93 A backtrace is a summary of how the program got where it is. It shows one
94 line per frame, for many frames, starting with the currently executing
95 frame (frame zero), followed by its caller (frame one), and on up the
103 Print a backtrace of the entire stack: one line per frame for all
106 You can stop the backtrace at any time by typing the system interrupt
107 character, normally @kbd{Control-C}.
109 @item backtrace @var{n}
111 Similar, but print only the innermost @var{n} frames.
113 @item backtrace -@var{n}
115 Similar, but print only the outermost @var{n} frames.
121 The names @code{where} and @code{info stack} (abbreviated @code{info s})
122 are additional aliases for @code{backtrace}.
124 Each line in the backtrace shows the frame number and the function name.
125 The program counter value is also shown---unless you use @code{set
126 print address off}. The backtrace also shows the source file name and
127 line number, as well as the arguments to the function. The program
128 counter value is omitted if it is at the beginning of the code for that
131 Here is an example of a backtrace. It was made with the command
132 @samp{bt 3}, so it shows the innermost three frames.
136 #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) at builtin.c:993
137 #1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
138 #2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
140 (More stack frames follow...)
145 The display for frame zero doesn't begin with a program counter
146 value, indicating that the program has stopped at the beginning of the
147 code for line @code{993} of @code{builtin.c}.
149 @node Selection, Frame Info, Backtrace, Stack
150 @section Selecting a Frame
152 Most commands for examining the stack and other data in the program work on
153 whichever stack frame is selected at the moment. Here are the commands for
154 selecting a stack frame; all of them finish by printing a brief description
155 of the stack frame just selected.
162 Select frame number @var{n}. Recall that frame zero is the innermost
163 (currently executing) frame, frame one is the frame that called the
164 innermost one, and so on. The highest-numbered frame is @code{main}'s
167 @item frame @var{addr}
169 Select the frame at address @var{addr}. This is useful mainly if the
170 chaining of stack frames has been damaged by a bug, making it
171 impossible for _GDBN__ to assign numbers properly to all frames. In
172 addition, this can be useful when the program has multiple stacks and
173 switches between them.
176 On the SPARC architecture, @code{frame} needs two addresses to
177 select an arbitrary frame: a frame pointer and a stack pointer.
178 @c note to future updaters: this is conditioned on a flag
179 @c FRAME_SPECIFICATION_DYADIC in the tm-*.h files, currently only used
180 @c by SPARC, hence the specific attribution. Generalize or list all
181 @c possibilities if more supported machines start doing this.
186 Move @var{n} frames up the stack. For positive numbers @var{n}, this
187 advances toward the outermost frame, to higher frame numbers, to frames
188 that have existed longer. @var{n} defaults to one.
193 Move @var{n} frames down the stack. For positive numbers @var{n}, this
194 advances toward the innermost frame, to lower frame numbers, to frames
195 that were created more recently. @var{n} defaults to one. You may
196 abbreviate @code{down} as @code{do}.
199 All of these commands end by printing two lines of output describing the
200 frame. The first line shows the frame number, the function name, the
201 arguments, and the source file and line number of execution in that
202 frame. The second line shows the text of that source line. For
207 #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) at env.c:10
208 10 read_input_file (argv[i]);
211 After such a printout, the @code{list} command with no arguments will print
212 ten lines centered on the point of execution in the frame. @xref{List}.
215 @item up-silently @var{n}
216 @itemx down-silently @var{n}
217 @kindex down-silently
219 These two commands are variants of @code{up} and @code{down},
220 respectively; they differ in that they do their work silently, without
221 causing display of the new frame. They are intended primarily for use
222 in _GDBN__ command scripts, where the output might be unnecessary and
227 @node Frame Info, , Selection, Stack
228 @section Information About a Frame
230 There are several other commands to print information about the selected
236 When used without any argument, this command does not change which frame
237 is selected, but prints a brief description of the currently
238 selected stack frame. It can be abbreviated @code{f}. With an
239 argument, this command is used to select a stack frame (@pxref{Selection}).
245 This command prints a verbose description of the selected stack frame,
246 including the address of the frame, the addresses of the next frame down
247 (called by this frame) and the next frame up (caller of this frame),
248 the address of the frame's arguments, the program counter saved in it
249 (the address of execution in the caller frame), and which registers
250 were saved in the frame. The verbose description is useful when
251 something has gone wrong that has made the stack format fail to fit
252 the usual conventions.
254 @item info frame @var{addr}
255 @itemx info f @var{addr}
256 Print a verbose description of the frame at address @var{addr},
257 without selecting that frame. The selected frame remains unchanged by
262 Print the arguments of the selected frame, each on a separate line.
266 Print the local variables of the selected frame, each on a separate
267 line. These are all variables declared static or automatic within all
268 program blocks that execution in this frame is currently inside of.
272 @cindex catch exceptions
273 @cindex exception handlers
274 Print a list of all the exception handlers that are active in the
275 current stack frame at the current point of execution. To see other
276 exception handlers, visit the associated frame (using the @code{up},
277 @code{down}, or @code{frame} commands); then type @code{info catch}.
278 @xref{Exception Handling}.