* [patch][python] 3/3 Python representation of GDB line tables (Documentation)
@ 2013-10-08 12:07 Phil Muldoon
2013-10-23 21:00 ` Tom Tromey
0 siblings, 1 reply; 4+ messages in thread
From: Phil Muldoon @ 2013-10-08 12:07 UTC (permalink / raw)
To: gdb-patches
This patch in the series contains the documentation for Python
linetables.
Cheers,
Phil
2013-10-08 Phil Muldoon <pmuldoon@redhat.com>
* 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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [patch][python] 3/3 Python representation of GDB line tables (Documentation)
2013-10-08 12:07 [patch][python] 3/3 Python representation of GDB line tables (Documentation) Phil Muldoon
@ 2013-10-23 21:00 ` Tom Tromey
2013-11-07 17:07 ` Phil Muldoon
0 siblings, 1 reply; 4+ messages in thread
From: Tom Tromey @ 2013-10-23 21:00 UTC (permalink / raw)
To: Phil Muldoon; +Cc: gdb-patches
>>>>> "Phil" == Phil Muldoon <pmuldoon@redhat.com> 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.
Tom
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [patch][python] 3/3 Python representation of GDB line tables (Documentation)
2013-10-23 21:00 ` Tom Tromey
@ 2013-11-07 17:07 ` Phil Muldoon
2013-11-07 17:32 ` Tom Tromey
0 siblings, 1 reply; 4+ messages in thread
From: Phil Muldoon @ 2013-11-07 17:07 UTC (permalink / raw)
To: Tom Tromey; +Cc: gdb-patches
On 23/10/13 22:00, Tom Tromey wrote:
>>>>>> "Phil" == Phil Muldoon <pmuldoon@redhat.com> 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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [patch][python] 3/3 Python representation of GDB line tables (Documentation)
2013-11-07 17:07 ` Phil Muldoon
@ 2013-11-07 17:32 ` Tom Tromey
0 siblings, 0 replies; 4+ messages in thread
From: Tom Tromey @ 2013-11-07 17:32 UTC (permalink / raw)
To: Phil Muldoon; +Cc: gdb-patches
>>>>> "Phil" == Phil Muldoon <pmuldoon@redhat.com> writes:
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.
Phil> I added a brief explanation to that paragraph. If we need more, we
Phil> will have to think about including a separate section.
It looks good to me.
Thanks, Phil.
Tom
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2013-11-07 17:08 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2013-10-08 12:07 [patch][python] 3/3 Python representation of GDB line tables (Documentation) Phil Muldoon
2013-10-23 21:00 ` Tom Tromey
2013-11-07 17:07 ` Phil Muldoon
2013-11-07 17:32 ` Tom Tromey
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).