Chapter 6. Examining the Stack

Table of Contents
6.1. Stack Frames
6.2. Backtraces
6.3. Selecting a Frame
6.4. Information about a Frame

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 debugger commands for examining the stack allow you to see all of this information.

One of the stack frames is selected by the debugger and many the debugger commands refer implicitly to the selected frame. In particular, whenever you ask the debugger for the value of a variable in your program, the value is found in the selected frame. There are special the debugger commands to select whichever frame you are interested in. See Section 6.3.

When your program stops, the debugger automatically selects the currently executing frame and describes it briefly, similar to the frame command (see Section 6.4).

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

The debugger 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 the debugger to give you a way of designating stack frames in the debugger commands.

frame args

The 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 of the stack frame number. Without an argument, frame prints the current stack frame.

select-frame

The select-frame command allows you to move from one stack frame to another without printing the frame. This is the silent version of frame.