Go to the previous, next section.

Examining the Stack

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, the information about where in your program the call was made from is saved in a block of data called a 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 call stack.

When your program stops, the _GDBN__ commands for examining the stack allow you to see all of this information.

One of the stack frames is 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 your program, the value is found in the selected frame. There are special _GDBN__ commands to select whichever frame you are interested in.

When your program stops, _GDBN__ automatically selects the currently executing frame and describes it briefly as the frame command does (see section Information About a Frame).

Stack Frames

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 of those bytes 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.

_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.

Some compilers allow functions to be compiled so that they operate without stack frames. (For example, the _GCC__ option `-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.

Backtraces

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

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 C-c.

backtrace n

bt n

Similar, but print only the innermost n frames.

backtrace -n

bt -n

Similar, but print only the outermost n frames.

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.

Selecting a Frame

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

Select frame number 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 main's frame.

frame addr

f addr

Select the frame at address 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 your program has multiple stacks and switches between them.

_if__(_SPARC__) On the SPARC architecture, frame needs two addresses to select an arbitrary frame: a frame pointer and a stack pointer. _fi__(_SPARC__)

up n

Move n frames up the stack. For positive numbers n, this advances toward the outermost frame, to higher frame numbers, to frames that have existed longer. n defaults to one.

down n

Move n frames down the stack. For positive numbers n, this advances toward the innermost frame, to lower frame numbers, to frames that were created more recently. n defaults to one. You may abbreviate 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:

(_GDBP__) 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 will print ten lines centered on the point of execution in the frame. See section Printing Source Lines.

up-silently n

down-silently n

These two commands are variants of 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 _GDBN__ command scripts, where the output might be unnecessary and distracting.

Information About a Frame

There are several other commands to print information about the selected stack frame.

frame

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 f. With an argument, this command is used to select a stack frame (see section Selecting a Frame).

info frame

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 language that the source code corresponding to this frame was written in, 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.

info frame addr

info f addr

Print a verbose description of the frame at address addr, without selecting that frame. The selected frame remains unchanged by this command.

info args

Print the arguments of the selected frame, each on a separate line.

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.

info catch

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 up, down, or frame commands); then type info catch. See section Breakpoints and Exceptions.

Go to the previous, next section.