Next: Blocks In Python, Previous: Objfiles In Python, Up: Python API [Contents][Index]
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 gdb.error
exception (see Exception Handling).
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:
Return the selected frame object. (see Selecting a Frame).
Return the newest frame object for the selected thread.
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).
GDB internally keeps a cache of the frames that have been unwound. This function invalidates this cache.
This function should not generally be called by ordinary Python code. It is documented for the sake of completeness.
A gdb.Frame object has the following methods:
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.
Returns the function name of the frame, or None if it can’t be
obtained.
Returns the gdb.Architecture object corresponding to the frame’s
architecture. See Architectures In Python.
Returns the type of the frame. The value can be one of:
gdb.NORMAL_FRAMEAn ordinary stack frame.
gdb.DUMMY_FRAMEA fake stack frame that was created by GDB when performing an inferior function call.
gdb.INLINE_FRAMEA frame representing an inlined function. The function was inlined
into a gdb.NORMAL_FRAME that is older than this one.
gdb.TAILCALL_FRAMEA frame representing a tail call. See Tail Call Frames.
gdb.SIGTRAMP_FRAMEA signal trampoline frame. This is the frame created by the OS when it calls into a signal handler.
gdb.ARCH_FRAMEA fake stack frame representing a cross-architecture call.
gdb.SENTINEL_FRAMEThis is like gdb.NORMAL_FRAME, but it is only used for the
newest frame.
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. The value can be one of:
gdb.FRAME_UNWIND_NO_REASONNo particular reason (older frames should be available).
gdb.FRAME_UNWIND_NULL_IDThe previous frame’s analyzer returns an invalid result. This is no longer used by GDB, and is kept only for backward compatibility.
gdb.FRAME_UNWIND_OUTERMOSTThis frame is the outermost.
gdb.FRAME_UNWIND_UNAVAILABLECannot unwind further, because that would require knowing the values of registers or memory that have not been collected.
gdb.FRAME_UNWIND_INNER_IDThis frame ID looks like it ought to belong to a NEXT frame, but we got it for a PREV frame. Normally, this is a sign of unwinder failure. It could also indicate stack corruption.
gdb.FRAME_UNWIND_SAME_IDThis frame has the same ID as the previous one. That means that unwinding further would almost certainly give us another frame with exactly the same ID, so break the chain. Normally, this is a sign of unwinder failure. It could also indicate stack corruption.
gdb.FRAME_UNWIND_NO_SAVED_PCThe frame unwinder did not find any saved PC, but we needed one to unwind further.
gdb.FRAME_UNWIND_MEMORY_ERRORThe frame unwinder caused an error while trying to access memory.
gdb.FRAME_UNWIND_FIRST_ERRORAny stop reason greater or equal to this value indicates some kind of error. This special value facilitates writing code that tests for errors in unwinding in a way that will work correctly even if the list of the other values is modified in future GDB versions. Using it, you could write:
reason = gdb.selected_frame().unwind_stop_reason ()
reason_str = gdb.frame_stop_reason_string (reason)
if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
print ("An error occurred: %s" % reason_str)
Returns the frame’s resume address.
Return the frame’s code block. See Blocks In Python. If the frame does not have a block – for example, if there is no debugging information for the code in question – then this will throw an exception.
Return the symbol for the function corresponding to this frame. See Symbols In Python.
Return the frame that called this frame. If this is the oldest frame,
return None.
Return the frame called by this frame. If this is the newest frame,
return None.
Return the frame’s symtab and line object. See Symbol Tables In Python.
Return the value of register in this frame. Returns a
Gdb.Value object. Throws an exception if register does
not exist. The register argument must be one of the following:
'sp' or
'rax').
gdb.RegisterDescriptor object (see Registers In Python).
Using a string to access registers will be slightly slower than the
other two methods as GDB must look up the mapping between
name and internal register number. If performance is critical
consider looking up and caching a gdb.RegisterDescriptor
object.
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). The variable
argument must be a string or a gdb.Symbol object; block must be a
gdb.Block object.
Set this frame to be the selected frame. See Examining the Stack.
In some languages (e.g., Ada, but also a GNU C extension), a nested function can access the variables in the outer scope. This is done via a “static link”, which is a reference from the nested frame to the appropriate outer frame.
This method returns this frame’s static link frame, if one exists. If
there is no static link, this method returns None.
Return an integer, the stack frame level for this frame. See Stack Frames.
Return a string, the source language for this frame.
Next: Blocks In Python, Previous: Objfiles In Python, Up: Python API [Contents][Index]