Next: , 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.