From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 16664 invoked by alias); 7 Nov 2013 16:37:22 -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 16539 invoked by uid 89); 7 Nov 2013 16:37:21 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=0.6 required=5.0 tests=AWL,BAYES_50,RDNS_NONE,SPAM_SUBJECT,SPF_HELO_PASS,SPF_PASS autolearn=no version=3.3.2 X-HELO: mx1.redhat.com Received: from Unknown (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Thu, 07 Nov 2013 16:37:19 +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 rA7GbB5A014564 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Thu, 7 Nov 2013 11:37:12 -0500 Received: from localhost.localdomain (ovpn-112-33.ams2.redhat.com [10.36.112.33]) by int-mx01.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id rA7GbAsP006283; Thu, 7 Nov 2013 11:37:10 -0500 Message-ID: <527BC1B5.4070200@redhat.com> Date: Thu, 07 Nov 2013 17:07:00 -0000 From: Phil Muldoon MIME-Version: 1.0 To: Tom Tromey CC: gdb-patches@sourceware.org Subject: Re: [patch][python] 3/3 Python representation of GDB line tables (Documentation) References: <5253F594.1060809@redhat.com> <87fvrrd7nz.fsf@fleche.redhat.com> In-Reply-To: <87fvrrd7nz.fsf@fleche.redhat.com> Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit X-IsSubscribed: yes X-SW-Source: 2013-11/txt/msg00195.txt.bz2 On 23/10/13 22:00, Tom Tromey wrote: >>>>>> "Phil" == Phil Muldoon writes: > > Phil> This patch in the series contains the documentation for Python > Phil> linetables. > > Thanks! > > Phil> +Python code can request and inspect line table information from a > Phil> +symbol table that is loaded in @value{GDBN}. To acquire the line > Phil> +table information for a particular symbol table, use the > Phil> +@code{linetable} function (@pxref{Symbol Tables In Python}). > > I think that this should mention what a line table is. Something along > the lines of how the line table maps between source lines and addresses. I added a brief explanation to that paragraph. If we need more, we will have to think about including a separate section. Cheers Phil -- diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 44fb174..eb6dfc0 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -23431,6 +23431,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. @@ -26964,6 +26965,89 @@ 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}. A line table is a +mapping of source lines to their executable locations in memory. 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