This is the mail archive of the
archer@sourceware.org
mailing list for the Archer project.
document gdb.Frame
- From: Thiago Jung Bauermann <bauerman at br dot ibm dot com>
- To: archer ml <archer at sourceware dot org>
- Date: Mon, 29 Dec 2008 17:32:51 -0200
- Subject: document gdb.Frame
Hi,
I just committed this documentation of the Python bindings for
manipulating frames.
--
[]'s
Thiago Jung Bauermann
IBM Linux Technology Center
2008-12-24 Thiago Jung Bauermann <bauerman@br.ibm.com>
* gdb.texinfo (Basic Python): Document Frame-related functions.
(Frames in Python): New node.
(Python API): Update.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 13137ab..620d093 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -18049,6 +18049,7 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown.
* Functions In Python:: Writing new convenience functions.
* Objfiles in Python:: Object files.
* Breakpoints in Python:: Manipulating breakpoints using Python.
+* Frames In Python:: Acessing inferior stack frames from Python.
@end menu
@node Basic Python
@@ -18155,6 +18156,29 @@ Flush @value{GDBN}'s paginated standard output stream. Flushing
function.
@end defun
+@findex gdb.frames
+@defun frames
+Return a tuple of all frame objects.
+@end defun
+
+@findex gdb.newest_frame
+@defun newest_frame
+Return the newest frame object.
+@end defun
+
+@findex gdb.selected_frame
+@defun selected_frame
+Return the selected frame object.
+@end defun
+
+@findex gdb.frame_stop_reason_string
+@defun frame_stop_reason_string @var{reason}
+Return a string explaining the reason why @value{GDBN} stopped unwinding
+frames, as expressed by the given @var{reason} code (an integer, see the
+@code{unwind_stop_reason} method in
+@xref{Frames In Python,,Acessing inferior stack frames from Python}.)
+@end defun
+
@node Exception Handling
@subsubsection Exception Handling
@cindex python exceptions
@@ -19268,6 +19292,71 @@ separated by newlines. If there are no commands, this attribute is
@code{None}. This attribute is not writable.
@end defivar
+@node Frames in Python
+@subsubsection Acessing inferior stack frames from Python.
+
+@cindex frames in python
+@tindex gdb.Frame
+@tindex Frame
+When the debugged program stops, @value{GDBN} is able to analyse its call
+stack (see @xref{Frames,,Stack frames}). The @code{gdb.Frame} class
+represents a frame in the stack. You can get a tuple containing all the
+frames in the stack with the @code{gdb.frames} function, the newest
+frame with the @code{gdb.newest_frame} function, and the selected frame
+with the @code{gdb.selected_frame} function
+(see @xref{Selection,,Selecting a Frame}.) See
+@xref{Basic Python,,Basic Python}.
+
+A @code{gdb.Frame} object has the following methods:
+
+@table @code
+@defmethod Frame equals @code{frame}
+Compare frames.
+@end defmethod
+
+@defmethod Frame is_valid
+Returns true if the @code{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 @code{gdb.Frame} methods will throw
+an exception if it is invalid at the time the method call is made.
+@end defmethod
+
+@defmethod Frame name
+Returns the function name of the frame, or @code{None} if it can't be
+obtained.
+@end defmethod
+
+@defmethod Frame type
+Returns the type of the frame. The value can be one of
+@code{gdb.NORMAL_FRAME}, @code{gdb.DUMMY_FRAME}, @code{gdb.SIGTRAMP_FRAME}
+or @code{gdb.SENTINEL_FRAME}.
+@end defmethod
+
+@defmethod Frame pc
+Returns the frame's resume address.
+@end defmethod
+
+@defmethod Frame address_in_block
+Returns an address which falls within the frame's code block.
+@end defmethod
+
+@defmethod Frame older
+Return the frame immediately older (outer) to this frame.
+@end defmethod
+
+@defmethod Frame newer
+Return the frame immetidaely newer (inner) to this frame.
+@end defmethod
+
+@defmethod Frame find_sal
+Return the frame's symtab and line object (see @xref{Symtab_and_line,, Symtab and line}).
+@end defmethod
+
+@defmethod Frame read_var_value @var{symbol}
+Return the value of the variable corresponding to the given symbol in this frame.
+@end defmethod
+@end table
+
@node Interpreters
@chapter Command Interpreters
@cindex command interpreters