[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When your program has stopped, the first thing you need to know is where it stopped and how it got there.
Each time your program performs a function call, information about the call is generated. That information includes the location of the call in your program, the arguments of the call, and the local variables of the function being called. The information is saved in a block of data called a stack frame. The stack frames are allocated in a region of memory called the call stack.
When your program stops, the GDB commands for examining the stack allow you to see all of this information.
One of the stack frames is selected by GDB and many GDB commands refer implicitly to the selected frame. In particular, whenever you ask GDB for the value of a variable in your program, the value is found in the selected frame. There are special GDB commands to select whichever frame you are interested in. See section Selecting a frame.
When your program stops, GDB automatically selects the
currently executing frame and describes it briefly, similar to the
frame
command (see section Information about a frame).
6.1 Stack frames 6.2 Backtraces 6.3 Selecting a frame 6.4 Information about a frame Information on a frame
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The call stack is divided up into contiguous pieces called stack frames, or 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.
When your program is started, the stack has only one frame, that of the
function main
. This is called the initial frame or the
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 innermost frame. This is the most
recently created of all the stack frames that still exist.
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 byte whose address serves as the address of the frame. Usually this address is kept in a register called the frame pointer register while execution is going on in that frame.
GDB 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 GDB to give you a way of designating stack frames in GDB commands.
Some compilers provide a way to compile functions so that they operate without stack frames. (For example, the gcc option
`-fomit-frame-pointer' |
frame args
frame
command allows you to move from one stack frame to another,
and to print the stack frame you select. args may be either the
address of the frame or the stack frame number. Without an argument,
frame
prints the current stack frame.
select-frame
select-frame
command allows you to move from one stack frame
to another without printing the frame. This is the silent version of
frame
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A backtrace is a summary of how your 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.
backtrace
bt
You can stop the backtrace at any time by typing the system interrupt character, normally C-c.
backtrace n
bt n
backtrace -n
bt -n
The names where
and info stack
(abbreviated info s
)
are additional aliases for backtrace
.
Each line in the backtrace shows the frame number and the function name.
The program counter value is also shown--unless you use 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 `bt 3', so it shows the innermost three frames.
#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...) |
The display for frame zero does not begin with a program counter
value, indicating that your program has stopped at the beginning of the
code for line 993
of builtin.c
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
frame n
f n
main
.
frame addr
f addr
On the SPARC architecture, frame
needs two addresses to
select an arbitrary frame: a frame pointer and a stack pointer.
On the MIPS and Alpha architecture, it needs two addresses: a stack pointer and a program counter.
On the 29k architecture, it needs three addresses: a register stack pointer, a program counter, and a memory stack pointer.
up n
down n
down
as do
.
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:
(gdb) up #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) at env.c:10 10 read_input_file (argv[i]); |
After such a printout, the list
command with no arguments
prints ten lines centered on the point of execution in the frame.
See section Printing source lines.
up-silently n
down-silently n
up
and 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 GDB command scripts, where the output might be unnecessary and
distracting.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There are several other commands to print information about the selected stack frame.
frame
f
f
. With an
argument, this command is used to select a stack frame.
See section Selecting a frame.
info frame
info f
The verbose description is useful when something has gone wrong that has made the stack format fail to fit the usual conventions.
info frame addr
info f addr
frame
command.
See section Selecting a frame.
info args
info locals
info catch
up
,
down
, or frame
commands); then type info catch
.
See section Setting catchpoints.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Please send FSF & GNU inquiries & questions to [email protected]. There are also other ways to contact the FSF.
These pages are maintained by the GDB developers.
Copyright Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA.
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.
This document was generated by GDB Administrator on March, 29 2002 using texi2html