From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 8463 invoked by alias); 15 Feb 2010 23:39:31 -0000 Received: (qmail 8454 invoked by uid 22791); 15 Feb 2010 23:39:29 -0000 X-SWARE-Spam-Status: No, hits=-5.7 required=5.0 tests=AWL,BAYES_00,KAM_STOCKGEN,RCVD_IN_DNSWL_HI,SPF_HELO_PASS,SPF_PASS X-Spam-Check-By: sourceware.org Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Mon, 15 Feb 2010 23:39:22 +0000 Received: from int-mx05.intmail.prod.int.phx2.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.18]) by mx1.redhat.com (8.13.8/8.13.8) with ESMTP id o1FNdKKx010342 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 15 Feb 2010 18:39:20 -0500 Received: from localhost.localdomain (ovpn01.gateway.prod.ext.phx2.redhat.com [10.5.9.1]) by int-mx05.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id o1FNdIwl000987; Mon, 15 Feb 2010 18:39:19 -0500 Message-ID: <4B79DB26.30903@redhat.com> Date: Mon, 15 Feb 2010 23:39:00 -0000 From: Phil Muldoon User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.1.7) Gecko/20100120 Fedora/3.0.1-1.fc12 Lightning/1.0b2pre Thunderbird/3.0.1 MIME-Version: 1.0 To: Eli Zaretskii CC: tromey@redhat.com, gdb-patches@sourceware.org Subject: Re: [patch][python] Add symbol, symbol table and frame block support to GDB API References: <4B66DA35.7080701@redhat.com> <4B796506.7010909@redhat.com> <83mxzaxrtp.fsf@gnu.org> In-Reply-To: <83mxzaxrtp.fsf@gnu.org> Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2010-02/txt/msg00377.txt.bz2 On 02/15/2010 06:43 PM, Eli Zaretskii wrote: >> What do you think? > > I like it. But I want more ;-) > >> +@defmethod Frame find_sal >> +Return the frame's symtab and line object. >> +@xref{Symbol Tables In Python}. >> +@end defmethod > > Sometimes "Returns", sometimes "Return". I think the latter is > better, and we also use it more. In any case, we should use one or > the other consistently. Ok fixed in the patch and in a few other places the patch touches. >> +Please see @ref{Frames In Python} for a more in-depth discussion on >> +frames. Furthermore, see @ref{Stack, ,Examining the Stack} for more >> +detailed technical information on @value{GDBN}'s book-keeping of the >> +stack. Ok. I'm not sure if your previous Ok carries forward here. I've attached an updated copy of the doc patch just to be sure. Cheers, Phil -- diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 0e3e093..81a71af 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -19547,7 +19547,10 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown. * Commands In Python:: Implementing new commands in Python. * Functions In Python:: Writing new convenience functions. * Objfiles In Python:: Object files. -* Frames In Python:: Acessing inferior stack frames from Python. +* Frames In Python:: Accessing inferior stack frames from Python. +* Blocks In Python:: Accessing frame blocks from Python. +* Symbols In Python:: Python representation of symbols. +* Symbol Tables In Python:: Python representation of symbol tables. * Lazy Strings In Python:: Python representation of lazy strings. @end menu @@ -20707,7 +20710,7 @@ information. @end defivar @node Frames In Python -@subsubsection Acessing inferior stack frames from Python. +@subsubsection Accessing inferior stack frames from Python. @cindex frames in python When the debugged program stops, @value{GDBN} is able to analyze its call @@ -20733,7 +20736,7 @@ Return the selected frame object. (@pxref{Selection,,Selecting a Frame}). @end defun @defun frame_stop_reason_string reason -Return a string explaining the reason why @value{GDBN} stopped unwinding +Returns 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 further down in this section). @end defun @@ -20760,7 +20763,7 @@ or @code{gdb.SENTINEL_FRAME}. @end defmethod @defmethod Frame unwind_stop_reason -Return an integer representing the reason why it's not possible to find +Returns an integer representing the reason why it's not possible to find more frames toward the outermost frame. Use @code{gdb.frame_stop_reason_string} to convert the value returned by this function to a string. @@ -20770,18 +20773,325 @@ function to a string. Returns the frame's resume address. @end defmethod +@defmethod Frame block +Returns the frame's code block. @xref{Blocks In Python}. +@end defmethod + +@defmethod Frame function +Returns the symbol for the function corresponding to this frame. +@xref{Symbols In Python}. +@end defmethod + @defmethod Frame older -Return the frame that called this frame. +Returns the frame that called this frame. @end defmethod @defmethod Frame newer -Return the frame called by this frame. +Returns the frame called by this frame. +@end defmethod + +@defmethod Frame find_sal +Returns the frame's symtab and line object. +@xref{Symbol Tables In Python}. @end defmethod @defmethod Frame read_var variable -Return the value of the given variable in this frame. @var{variable} must +Returns the value of the given variable in this frame. @var{variable} must be a string. @end defmethod + +@defmethod Frame select +Set this frame to be the selected frame. @xref{Stack, ,Examining the +Stack}. +@end defmethod +@end table + +@node Blocks In Python +@subsubsection Accessing frame blocks from Python. + +@cindex blocks in python +@tindex gdb.Block + +Within each frame, @value{GDBN} maintains information on each block +stored in that frame. These blocks are organized hierarchically, and +are represented individually in Python as a @code{gdb.Block}. +Please see @ref{Frames In Python}, for a more in-depth discussion on +frames. Furthermore, see @ref{Stack, ,Examining the Stack}, for more +detailed technical information on @value{GDBN}'s book-keeping of the +stack. + +The following block-related functions are available in the @code{gdb} +module: + +@findex gdb.block_for_pc +@defun block_for_pc pc +Returns the @code{gdb.Block} containing the given @var{pc} value. If the +block cannot be found for the @var{pc} value specified, the function +will return @code{None}. +@end defun + +A @code{gdb.Block} object has the following attributes: + +@table @code +@defivar Block start +The start address of the block. This attribute is not writable. +@end defivar + +@defivar Block end +The end address of the block. This attribute is not writable. +@end defivar + +@defivar Block function +The name of the block represented as a @code{gdb.Symbol}. If the +block is not named, then this attribute holds @code{None}. This +attribute is not writable. +@end defivar + +@defivar Block superblock +The block containing this block. If this parent block does not exist, +this attribute holds @code{None}. This attribute is not writable. +@end defivar +@end table + +@node Symbols In Python +@subsubsection Python representation of Symbols. + +@cindex symbols in python +@tindex gdb.Symbol + +@value{GDBN} represents every variable, function and type as an +entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}. +Similarly, Python represents these symbols in @value{GDBN} with the +@code{gdb.Symbol} object. + +The following symbol-related functions are available in the @code{gdb} +module: + +@findex gdb.lookup_symbol +@defun lookup_symbol name [block] [domain] +This function searches for a symbol by name. The search scope can be +restricted to the parameters defined in the optional domain and block +arguments. + +@var{name} is the name of the symbol. It must be a string. The +optional @var{block} argument restricts the search to symbols visible +in that @var{block}. The @var{block} argument must be a +@code{gdb.Block} object. The optional @var{domain} argument restricts +the search to the domain type. The @var{domain} argument must be a +domain constant defined in the @code{gdb} module and described later +in this chapter. +@end defun + +A @code{gdb.Symbol} object has the following attributes: + +@table @code +@defivar Symbol symtab +The symbol table in which the symbol appears. This attribute is +represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In +Python}. This attribute is not writable. +@end defivar + +@defivar Symbol name +The name of the symbol as a string. This attribute is not writable. +@end defivar + +@defivar Symbol linkage_name +The name of the symbol, as used by the linker (i.e., may be mangled). +This attribute is not writable. +@end defivar + +@defivar Symbol print_name +The name of the symbol in a form suitable for output. This is either +@code{name} or @code{linkage_name}, depending on whether the user +asked @value{GDBN} to display demangled or mangled names. +@end defivar + +@defivar Symbol addr_class +The address class of the symbol. This classifies how to find the value +of a symbol. Each address class is a constant defined in the +@code{gdb} module and described later in this chapter. +@end defivar + +@defivar Symbol is_argument +@code{True} if the symbol is an argument of a function. +@end defivar + +@defivar Symbol is_constant +@code{True} if the symbol is a constant. +@end defivar + +@defivar Symbol is_function +@code{True} if the symbol is a function or a method. +@end defivar + +@defivar Symbol is_variable +@code{True} if the symbol is a variable. +@end defivar +@end table + +The available domain categories in @code{gdb.Symbol} are represented +as constants in the @code{gdb} module: + +@table @code +@findex SYMBOL_UNDEF_DOMAIN +@findex gdb.SYMBOL_UNDEF_DOMAIN +@item SYMBOL_UNDEF_DOMAIN +This is used when a domain has not been discovered or none of the +following domains apply. This usually indicates an error either +in the symbol information or in @value{GDBN}'s handling of symbols. +@findex SYMBOL_VAR_DOMAIN +@findex gdb.SYMBOL_VAR_DOMAIN +@item SYMBOL_VAR_DOMAIN +This domain contains variables, function names, typedef names and enum +type values. +@findex SYMBOL_STRUCT_DOMAIN +@findex gdb.SYMBOL_STRUCT_DOMAIN +@item SYMBOL_STRUCT_DOMAIN +This domain holds struct, union and enum type names. +@findex SYMBOL_LABEL_DOMAIN +@findex gdb.SYMBOL_LABEL_DOMAIN +@item SYMBOL_LABEL_DOMAIN +This domain contains names of labels (for gotos). +@findex SYMBOL_VARIABLES_DOMAIN +@findex gdb.SYMBOL_VARIABLES_DOMAIN +@item SYMBOL_VARIABLES_DOMAIN +This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it +contains everything minus functions and types. +@findex SYMBOL_FUNCTIONS_DOMAIN +@findex gdb.SYMBOL_FUNCTIONS_DOMAIN +@item SYMBOL_FUNCTION_DOMAIN +This domain contains all functions. +@findex SYMBOL_TYPES_DOMAIN +@findex gdb.SYMBOL_TYPES_DOMAIN +@item SYMBOL_TYPES_DOMAIN +This domain contains all types. +@end table + +The available address class categories in @code{gdb.Symbol} are represented +as constants in the @code{gdb} module: + +@table @code +@findex SYMBOL_LOC_UNDEF +@findex gdb.SYMBOL_LOC_UNDEF +@item SYMBOL_LOC_UNDEF +If this is returned by address class, it indicates an error either in +the symbol information or in @value{GDBN}'s handling of symbols. +@findex SYMBOL_LOC_CONST +@findex gdb.SYMBOL_LOC_CONST +@item SYMBOL_LOC_CONST +Value is constant int. +@findex SYMBOL_LOC_STATIC +@findex gdb.SYMBOL_LOC_STATIC +@item SYMBOL_LOC_STATIC +Value is at a fixed address. +@findex SYMBOL_LOC_REGISTER +@findex gdb.SYMBOL_LOC_REGISTER +@item SYMBOL_LOC_REGISTER +Value is in a register. +@findex SYMBOL_LOC_ARG +@findex gdb.SYMBOL_LOC_ARG +@item SYMBOL_LOC_ARG +Value is an argument. This value is at the offset stored within the +symbol inside the frame's argument list. +@findex SYMBOL_LOC_REF_ARG +@findex gdb.SYMBOL_LOC_REF_ARG +@item SYMBOL_LOC_REF_ARG +Value address is stored in the frame's argument list. Just like +@code{LOC_ARG} except that the value's address is stored at the +offset, not the value itself. +@findex SYMBOL_LOC_REGPARM_ADDR +@findex gdb.SYMBOL_LOC_REGPARM_ADDR +@item SYMBOL_LOC_REGPARM_ADDR +Value is a specified register. Just like @code{LOC_REGISTER} except +the register holds the address of the argument instead of the argument +itself. +@findex SYMBOL_LOC_LOCAL +@findex gdb.SYMBOL_LOC_LOCAL +@item SYMBOL_LOC_LOCAL +Value is a local variable. +@findex SYMBOL_LOC_TYPEDEF +@findex gdb.SYMBOL_LOC_TYPEDEF +@item SYMBOL_LOC_TYPEDEF +Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all +have this class. +@findex SYMBOL_LOC_BLOCK +@findex gdb.SYMBOL_LOC_BLOCK +@item SYMBOL_LOC_BLOCK +Value is a block. +@findex SYMBOL_LOC_CONST_BYTES +@findex gdb.SYMBOL_LOC_CONST_BYTES +@item SYMBOL_LOC_CONST_BYTES +Value is a byte-sequence. +@findex SYMBOL_LOC_UNRESOLVED +@findex gdb.SYMBOL_LOC_UNRESOLVED +@item SYMBOL_LOC_UNRESOLVED +Value is at a fixed address, but the address of the variable has to be +determined from the minimal symbol table whenever the variable is +referenced. +@findex SYMBOL_LOC_OPTIMIZED_OUT +@findex gdb.SYMBOL_LOC_OPTIMIZED_OUT +@item SYMBOL_LOC_OPTIMIZED_OUT +The value does not actually exist in the program. +@findex SYMBOL_LOC_COMPUTED +@findex gdb.SYMBOL_LOC_COMPUTED +@item SYMBOL_LOC_COMPUTED +The value's address is a computed location. +@end table + +@node Symbol Tables In Python +@subsubsection Symbol table representation in Python. + +@cindex symbol tables in python +@tindex gdb.Symtab +@tindex gdb.Symtab_and_line + +Access to symbol table data maintained by @value{GDBN} on the inferior +is exposed to Python via two objects: @code{gdb.Symtab_and_line} and +@code{gdb.Symtab}. Symbol table and line data for a frame is returned +from the @code{find_sal} method in @code{gdb.Frame} object. +@xref{Frames In Python}. + +For more information on @value{GDBN}'s symbol table management, see +@ref{Symbols, ,Examining the Symbol Table} for more information. + +A @code{gdb.Symtab_and_line} object has the following attributes: + +@table @code +@defivar Symtab_and_line symtab +The symbol table object (@code{gdb.Symtab}) for this frame. +This attribute is not writable. +@end defivar + +@defivar Symtab_and_line pc +Indicates the current program counter address. This attribute is not +writable. +@end defivar + +@defivar Symtab_and_line line +Indicates the current line number for this object. This +attribute is not writable. +@end defivar +@end table + +A @code{gdb.Symtab} object has the following attributes: + +@table @code +@defivar Symtab filename +The symbol table's source filename. This attribute is not writable. +@end defivar + +@defivar Symtab objfile +The symbol table's backing object file. @xref{Objfiles In Python}. +This attribute is not writable. +@end defivar +@end table + +The following methods are provided: + +@table @code +@defmethod Symtab fullname +Returns the symbol table's source absolute file name. +@end defmethod @end table @node Lazy Strings In Python