280 lines
10 KiB
Plaintext
Executable File
280 lines
10 KiB
Plaintext
Executable File
_dnl__ -*- Texinfo -*-
|
|
_dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
|
|
_dnl__ This file is part of the source for the GDB manual.
|
|
@c M4 FRAGMENT: $Id$
|
|
@node Stack, Source, Stopping, Top
|
|
@chapter Examining the Stack
|
|
|
|
When your program has stopped, the first thing you need to know is where it
|
|
stopped and how it got there.
|
|
|
|
@cindex call stack
|
|
Each time your program performs a function call, the information about
|
|
where in the program the call was made from is saved in a block of data
|
|
called a @dfn{stack frame}. The frame also contains the arguments of the
|
|
call and the local variables of the function that was called. All the
|
|
stack frames are allocated in a region of memory called the @dfn{call
|
|
stack}.
|
|
|
|
When your program stops, the _GDBN__ commands for examining the stack allow you
|
|
to see all of this information.
|
|
|
|
@cindex selected frame
|
|
One of the stack frames is @dfn{selected} by _GDBN__ and many _GDBN__ commands
|
|
refer implicitly to the selected frame. In particular, whenever you ask
|
|
_GDBN__ for the value of a variable in the program, the value is found in the
|
|
selected frame. There are special _GDBN__ commands to select whichever frame
|
|
you are interested in.
|
|
|
|
When the program stops, _GDBN__ automatically selects the currently executing
|
|
frame and describes it briefly as the @code{frame} command does
|
|
(@pxref{Frame Info, Info}).
|
|
|
|
@menu
|
|
* Frames:: Stack Frames
|
|
* Backtrace:: Backtraces
|
|
* Selection:: Selecting a Frame
|
|
* Frame Info:: Information on a Frame
|
|
@end menu
|
|
|
|
@node Frames, Backtrace, Stack, Stack
|
|
@section Stack Frames
|
|
|
|
@cindex frame
|
|
@cindex stack frame
|
|
The call stack is divided up into contiguous pieces called @dfn{stack
|
|
frames}, or @dfn{frames} for short; each frame is the data associated
|
|
with one call to one function. The frame contains the arguments given
|
|
to the function, the function's local variables, and the address at
|
|
which the function is executing.
|
|
|
|
@cindex initial frame
|
|
@cindex outermost frame
|
|
@cindex innermost frame
|
|
When your program is started, the stack has only one frame, that of the
|
|
function @code{main}. This is called the @dfn{initial} frame or the
|
|
@dfn{outermost} frame. Each time a function is called, a new frame is
|
|
made. Each time a function returns, the frame for that function invocation
|
|
is eliminated. If a function is recursive, there can be many frames for
|
|
the same function. The frame for the function in which execution is
|
|
actually occurring is called the @dfn{innermost} frame. This is the most
|
|
recently created of all the stack frames that still exist.
|
|
|
|
@cindex frame pointer
|
|
Inside your program, stack frames are identified by their addresses. A
|
|
stack frame consists of many bytes, each of which has its own address; each
|
|
kind of computer has a convention for choosing one of those bytes whose
|
|
address serves as the address of the frame. Usually this address is kept
|
|
in a register called the @dfn{frame pointer register} while execution is
|
|
going on in that frame.
|
|
|
|
@cindex frame number
|
|
_GDBN__ assigns numbers to all existing stack frames, starting with
|
|
zero for the innermost frame, one for the frame that called it,
|
|
and so on upward. These numbers do not really exist in your program;
|
|
they are assigned by _GDBN__ to give you a way of designating stack
|
|
frames in _GDBN__ commands.
|
|
|
|
@cindex frameless execution
|
|
Some compilers allow functions to be compiled so that they operate
|
|
without stack frames. (For example, the @code{_GCC__} option
|
|
@samp{-fomit-frame-pointer} will generate functions without a frame.)
|
|
This is occasionally done with heavily used library functions to save
|
|
the frame setup time. _GDBN__ has limited facilities for dealing with
|
|
these function invocations. If the innermost function invocation has no
|
|
stack frame, _GDBN__ will nevertheless regard it as though it had a
|
|
separate frame, which is numbered zero as usual, allowing correct
|
|
tracing of the function call chain. However, _GDBN__ has no provision
|
|
for frameless functions elsewhere in the stack.
|
|
|
|
@node Backtrace, Selection, Frames, Stack
|
|
@section Backtraces
|
|
|
|
A backtrace is a summary of how the 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.
|
|
|
|
@table @code
|
|
@item backtrace
|
|
@itemx bt
|
|
@kindex backtrace
|
|
@kindex bt
|
|
Print a backtrace of the entire stack: one line per frame for all
|
|
frames in the stack.
|
|
|
|
You can stop the backtrace at any time by typing the system interrupt
|
|
character, normally @kbd{Control-C}.
|
|
|
|
@item backtrace @var{n}
|
|
@itemx bt @var{n}
|
|
Similar, but print only the innermost @var{n} frames.
|
|
|
|
@item backtrace -@var{n}
|
|
@itemx bt -@var{n}
|
|
Similar, but print only the outermost @var{n} frames.
|
|
@end table
|
|
|
|
@kindex where
|
|
@kindex info stack
|
|
@kindex info s
|
|
The names @code{where} and @code{info stack} (abbreviated @code{info s})
|
|
are additional aliases for @code{backtrace}.
|
|
|
|
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}. 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
|
|
@samp{bt 3}, so it shows the innermost three frames.
|
|
|
|
@smallexample
|
|
@group
|
|
#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) at builtin.c:993
|
|
#1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
|
|
#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
|
|
at macro.c:71
|
|
(More stack frames follow...)
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The display for frame zero doesn't begin with a program counter
|
|
value, indicating that the program has stopped at the beginning of the
|
|
code for line @code{993} of @code{builtin.c}.
|
|
|
|
@node Selection, Frame Info, Backtrace, Stack
|
|
@section Selecting a Frame
|
|
|
|
Most commands for examining the stack and other data in the 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.
|
|
|
|
@table @code
|
|
@item frame @var{n}
|
|
@itemx f @var{n}
|
|
@kindex frame
|
|
@kindex f
|
|
Select frame number @var{n}. 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-numbered frame is @code{main}'s
|
|
frame.
|
|
|
|
@item frame @var{addr}
|
|
@itemx f @var{addr}
|
|
Select the frame at address @var{addr}. This is useful mainly if the
|
|
chaining of stack frames has been damaged by a bug, making it
|
|
impossible for _GDBN__ to assign numbers properly to all frames. In
|
|
addition, this can be useful when the program has multiple stacks and
|
|
switches between them.
|
|
|
|
_if_(_SPARC__)
|
|
On the SPARC architecture, @code{frame} needs two addresses to
|
|
select an arbitrary frame: a frame pointer and a stack pointer.
|
|
@c note to future updaters: this is conditioned on a flag
|
|
@c FRAME_SPECIFICATION_DYADIC in the tm-*.h files, currently only used
|
|
@c by SPARC, hence the specific attribution. Generalize or list all
|
|
@c possibilities if more supported machines start doing this.
|
|
_fi_(_SPARC__)
|
|
|
|
@item up @var{n}
|
|
@kindex up
|
|
Move @var{n} frames up the stack. For positive numbers @var{n}, this
|
|
advances toward the outermost frame, to higher frame numbers, to frames
|
|
that have existed longer. @var{n} defaults to one.
|
|
|
|
@item down @var{n}
|
|
@kindex down
|
|
@kindex do
|
|
Move @var{n} frames down the stack. For positive numbers @var{n}, this
|
|
advances toward the innermost frame, to lower frame numbers, to frames
|
|
that were created more recently. @var{n} defaults to one. You may
|
|
abbreviate @code{down} as @code{do}.
|
|
@end table
|
|
|
|
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. For
|
|
example:
|
|
|
|
@smallexample
|
|
(_GDBP__) up
|
|
#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) at env.c:10
|
|
10 read_input_file (argv[i]);
|
|
@end smallexample
|
|
|
|
After such a printout, the @code{list} command with no arguments will print
|
|
ten lines centered on the point of execution in the frame. @xref{List}.
|
|
|
|
@table @code
|
|
@item up-silently @var{n}
|
|
@itemx down-silently @var{n}
|
|
@kindex down-silently
|
|
@kindex up-silently
|
|
These two commands are variants of @code{up} and @code{down},
|
|
respectively; they differ in that they do their work silently, without
|
|
causing display of the new frame. They are intended primarily for use
|
|
in _GDBN__ command scripts, where the output might be unnecessary and
|
|
distracting.
|
|
|
|
@end table
|
|
|
|
@node Frame Info, , Selection, Stack
|
|
@section Information About a Frame
|
|
|
|
There are several other commands to print information about the selected
|
|
stack frame.
|
|
|
|
@table @code
|
|
@item frame
|
|
@itemx f
|
|
When used without any argument, this command does not change which frame
|
|
is selected, but prints a brief description of the currently
|
|
selected stack frame. It can be abbreviated @code{f}. With an
|
|
argument, this command is used to select a stack frame (@pxref{Selection}).
|
|
|
|
@item info frame
|
|
@kindex info frame
|
|
@itemx info f
|
|
@kindex info f
|
|
This command prints a verbose description of the selected stack frame,
|
|
including the address of the frame, the addresses of the next frame down
|
|
(called by this frame) and the next frame up (caller of this frame),
|
|
the address of the frame's arguments, the program counter saved in it
|
|
(the address of execution in the caller frame), and which registers
|
|
were saved in the frame. The verbose description is useful when
|
|
something has gone wrong that has made the stack format fail to fit
|
|
the usual conventions.
|
|
|
|
@item info frame @var{addr}
|
|
@itemx info f @var{addr}
|
|
Print a verbose description of the frame at address @var{addr},
|
|
without selecting that frame. The selected frame remains unchanged by
|
|
this command.
|
|
|
|
@item info args
|
|
@kindex info args
|
|
Print the arguments of the selected frame, each on a separate line.
|
|
|
|
@item info locals
|
|
@kindex info locals
|
|
Print the local variables of the selected frame, each on a separate
|
|
line. These are all variables declared static or automatic within all
|
|
program blocks that execution in this frame is currently inside of.
|
|
|
|
@item info catch
|
|
@kindex info catch
|
|
@cindex catch exceptions
|
|
@cindex exception handlers
|
|
Print a list of all the exception handlers that are active in the
|
|
current stack frame at the current point of execution. To see other
|
|
exception handlers, visit the associated frame (using the @code{up},
|
|
@code{down}, or @code{frame} commands); then type @code{info catch}.
|
|
@xref{Exception Handling}.
|
|
@end table
|