Next: Blocks In Python, Previous: Objfiles In Python, Up: Python API

##### 23.2.2.15 Accessing inferior stack frames from Python.

When the debugged program stops, gdb is able to analyze its call stack (see Stack frames). The `gdb.Frame` class represents a frame in the stack. A `gdb.Frame` object is only valid while its corresponding frame exists in the inferior's stack. If you try to use an invalid frame object, gdb will throw a `RuntimeError` exception.

Two `gdb.Frame` objects can be compared for equality with the `==` operator, like:

         (gdb) python print gdb.newest_frame() == gdb.selected_frame ()
         True

The following frame-related functions are available in the `gdb` module:

— Function: selected_frame

> Return the selected frame object. (see Selecting a Frame).

— Function: frame_stop_reason_string reason

> Return a string explaining the reason why gdb stopped unwinding frames, as expressed by the given reason code (an integer, see the `unwind_stop_reason` method further down in this section).

A `gdb.Frame` object has the following methods:

— Method on Frame: is_valid

> Returns true if the `gdb.Frame` object is valid, false if not. A frame object can become invalid if the frame it refers to doesn't exist anymore in the inferior. All `gdb.Frame` methods will throw an exception if it is invalid at the time the method is called.

— Method on Frame: name

> Returns the function name of the frame, or `None` if it can't be obtained.

— Method on Frame: type

> Returns the type of the frame. The value can be one of `gdb.NORMAL_FRAME`, `gdb.DUMMY_FRAME`, `gdb.SIGTRAMP_FRAME` or `gdb.SENTINEL_FRAME`.

— Method on Frame: unwind_stop_reason

> Return an integer representing the reason why it's not possible to find more frames toward the outermost frame. Use `gdb.frame_stop_reason_string` to convert the value returned by this function to a string.

— Method on Frame: pc

> Returns the frame's resume address.

— Method on Frame: block

> Return the frame's code block. See Blocks In Python.

— Method on Frame: function

> Return the symbol for the function corresponding to this frame. See Symbols In Python.

— Method on Frame: older

> Return the frame that called this frame.

— Method on Frame: newer

> Return the frame called by this frame.

— Method on Frame: find_sal

> Return the frame's symtab and line object. See Symbol Tables In Python.

— Method on Frame: read_var variable [block]

> Return the value of variable in this frame. If the optional argument block is provided, search for the variable from that block; otherwise start at the frame's current block (which is determined by the frame's current program counter). variable must be a string or a `gdb.Symbol` object. block must be a `gdb.Block` object.

— Method on Frame: select

> Set this frame to be the selected frame. See Examining the Stack.