From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 13408 invoked by alias); 8 Oct 2013 12:07:52 -0000 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 Received: (qmail 13395 invoked by uid 89); 8 Oct 2013 12:07:51 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-4.2 required=5.0 tests=AWL,BAYES_00,RP_MATCHES_RCVD,SPF_HELO_PASS,SPF_PASS autolearn=ham version=3.3.2 X-HELO: mx1.redhat.com Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Tue, 08 Oct 2013 12:07:51 +0000 Received: from int-mx01.intmail.prod.int.phx2.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id r98C7nU2028406 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Tue, 8 Oct 2013 08:07:49 -0400 Received: from localhost.localdomain (ovpn-112-21.ams2.redhat.com [10.36.112.21]) by int-mx01.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id r98C7mPd012501 for ; Tue, 8 Oct 2013 08:07:49 -0400 Message-ID: <5253F594.1060809@redhat.com> Date: Tue, 08 Oct 2013 12:07:00 -0000 From: Phil Muldoon MIME-Version: 1.0 To: gdb-patches@sourceware.org Subject: [patch][python] 3/3 Python representation of GDB line tables (Documentation) Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit X-IsSubscribed: yes X-SW-Source: 2013-10/txt/msg00218.txt.bz2 This patch in the series contains the documentation for Python linetables. Cheers, Phil 2013-10-08 Phil Muldoon * gdb.texinfo (Symbol Tables In Python): Add linetable method entry. (Line Tables In Python): New node. --- diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 07d5068..a50dd96 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -23334,6 +23334,7 @@ optional arguments while skipping others. Example: * Blocks In Python:: Accessing blocks from Python. * Symbols In Python:: Python representation of symbols. * Symbol Tables In Python:: Python representation of symbol tables. +* Line Tables In Python:: Python representation of line tables. * Breakpoints In Python:: Manipulating breakpoints using Python. * Finish Breakpoints in Python:: Setting Breakpoints on function return using Python. @@ -26867,6 +26868,88 @@ Return the static block of the underlying symbol table. @xref{Blocks In Python}. @end defun +@defun Symtab.linetable () +Return the line table associated with the symbol table. +@xref{Line Tables In Python}. +@end defun + +@node Line Tables In Python +@subsubsection Manipulating line tables using Python + +@cindex line tables in python +@tindex gdb.LineTable + +Python code can request and inspect line table information from a +symbol table that is loaded in @value{GDBN}. To acquire the line +table information for a particular symbol table, use the +@code{linetable} function (@pxref{Symbol Tables In Python}). + +A @code{gdb.LineTable} is iterable. The iterator returns +@code{LineTableEntry} objects that correspond to the source line and +address for each line table entry. @code{LineTableEntry} objects have +the following attributes: + +@defvar LineTableEntry.line +The source line number for this line table entry. This number +corresponds to the actual line of source. This attribute is not +writable. +@end defvar + +@defvar LineTableEntry.pc +The address that is associated with the line table entry where the +executable code for that source line resides in memory. This +attribute is not writable. +@end defvar + +As there can be multiple addresses for a single source line, you may +receive multiple @code{LineTableEntry} objects with matching +@code{line} attributes, but with different @code{pc} attributes. The +iterator is sorted in ascending @code{pc} order. Here is a small +example illustrating iterating over a line table. + +@smallexample +symtab = gdb.selected_frame().find_sal().symtab +linetable = symtab.linetable() +for line in linetable: + print "Line: "+str(line.line)+" Address: "+hex(line.pc) +@end smallexample + +This will have the following output: + +@smallexample +Line: 33 Address: 0x4005c8L +Line: 37 Address: 0x4005caL +Line: 39 Address: 0x4005d2L +Line: 40 Address: 0x4005f8L +Line: 42 Address: 0x4005ffL +Line: 44 Address: 0x400608L +Line: 42 Address: 0x40060cL +Line: 45 Address: 0x400615L +@end smallexample + +In addition to being able to iterate over a @code{LineTable}, it also +has the following direct access methods: + +@defun LineTable.line (line) +Return a Python @code{Tuple} of @code{LineTableEntry} objects for any +entries in the line table for the given @var{line}. @var{line} refers +to the source code line. If there are no entries for that source code +@var{line}, the Python @code{None} is returned. +@end defun + +@defun LineTable.has_pcs (line) +Return a Python @code{Boolean} indicating whether there is an entry in +the line table for this source line. Return @code{True} if an entry +is found, or @code{False} if not. +@end defun + +@defun LineTable.source_lines () +Return a Python @code{Frozenset} of the source line numbers in the +symbol table. Only lines with executable code locations are returned. +The contents of the @code{Frozenset} will just be the source line +entries represented as Python @code{Long} values. +@end defun + @node Breakpoints In Python @subsubsection Manipulating breakpoints using Python -- 1.8.1.4