First cut.

[deliverable/binutils-gdb.git] / gdb / doc / gdb.stack-m4

_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