*** empty log message ***
This commit is contained in:
Roland Pesch
parent
5ad1d83042
commit
9bcc06ef16
25 changed files with 6393 additions and 6289 deletions
279
gdb/doc/gdb.stack-m4
Executable file
279
gdb/doc/gdb.stack-m4
Executable file
|
|
@ -0,0 +1,279 @@
|
|||
_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.
|
||||
_dnl__ $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
|
||||
Loading…
Add table
Add a link
Reference in a new issue