diff options
Diffstat (limited to 'gdb/doc')
| -rw-r--r-- | gdb/doc/ChangeLog | 6 | ||||
| -rw-r--r-- | gdb/doc/gdb.texinfo | 53 |
2 files changed, 59 insertions, 0 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 0632d09..0ede40b 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,9 @@ +2011-12-23 Kevin Pouget <kevin.pouget@st.com> + + Introduce gdb.FinishBreakpoint in Python. + * gdb.texinfo (Finish Breakpoints in Python): New subsection. + (Python API): Add menu entry for Finish Breakpoints. + 2011-12-19 Jan Kratochvil <jan.kratochvil@redhat.com> * gdbint.texinfo (Testsuite): Describe KFAIL and XFAIL in Writing diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 4a7ae6e..3cd3b67 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -21525,6 +21525,8 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown. * Symbol Tables In Python:: Python representation of symbol tables. * Lazy Strings In Python:: Python representation of lazy strings. * Breakpoints In Python:: Manipulating breakpoints using Python. +* Finish Breakpoints in Python:: Setting Breakpoints on function return + using Python. @end menu @node Basic Python @@ -24359,6 +24361,57 @@ commands, separated by newlines. If there are no commands, this attribute is @code{None}. This attribute is not writable. @end defvar +@node Finish Breakpoints in Python +@subsubsection Finish Breakpoints + +@cindex python finish breakpoints +@tindex gdb.FinishBreakpoint + +A finish breakpoint is a temporary breakpoint set at the return address of +a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint} +extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled +and deleted when the execution will run out of the breakpoint scope (i.e.@: +@code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered). +Finish breakpoints are thread specific and must be create with the right +thread selected. + +@defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]}) +Create a finish breakpoint at the return address of the @code{gdb.Frame} +object @var{frame}. If @var{frame} is not provided, this defaults to the +newest frame. The optional @var{internal} argument allows the breakpoint to +become invisible to the user. @xref{Breakpoints In Python}, for further +details about this argument. +@end defun + +@defun FinishBreakpoint.out_of_scope (self) +In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN} +@code{return} command, @dots{}), a function may not properly terminate, and +thus never hit the finish breakpoint. When @value{GDBN} notices such a +situation, the @code{out_of_scope} callback will be triggered. + +You may want to sub-class @code{gdb.FinishBreakpoint} and override this +method: + +@smallexample +class MyFinishBreakpoint (gdb.FinishBreakpoint) + def stop (self): + print "normal finish" + return True + + def out_of_scope (): + print "abnormal finish" +@end smallexample +@end defun + +@defvar FinishBreakpoint.return_value +When @value{GDBN} is stopped at a finish breakpoint and the frame +used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this +attribute will contain a @code{gdb.Value} object corresponding to the return +value of the function. The value will be @code{None} if the function return +type is @code{void} or if the return value was not computable. This attribute +is not writable. +@end defvar + @node Lazy Strings In Python @subsubsection Python representation of lazy strings. |