public inbox for archer-commits@sourceware.org
help / color / mirror / Atom feed
* [SCM]  tromey/exception-improvements: document regexp argument to exception catchpoints
@ 2013-03-06 18:44 tromey
  0 siblings, 0 replies; only message in thread
From: tromey @ 2013-03-06 18:44 UTC (permalink / raw)
  To: archer-commits

The branch, tromey/exception-improvements has been updated
       via  f980c802ff82606a0d81944ce89feacea29ab3ab (commit)
       via  b1040ba23944095c04b57e39697ffb9fc6409633 (commit)
       via  32257d285544afbf433d7ce1b8a260bdd40afda0 (commit)
       via  456a5150de5cbd114a4acbf9ea3573d25fe5d94f (commit)
       via  47b77c05023d10833c0b293b37d7ec7f686a5930 (commit)
      from  14da3747d266a05e5dc4cb035a4bed27095f45b3 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email.

- Log -----------------------------------------------------------------
commit f980c802ff82606a0d81944ce89feacea29ab3ab
Author: Tom Tromey <tromey@redhat.com>
Date:   Wed Mar 6 11:44:41 2013 -0700

    document regexp argument to exception catchpoints

commit b1040ba23944095c04b57e39697ffb9fc6409633
Author: Tom Tromey <tromey@redhat.com>
Date:   Wed Mar 6 11:24:23 2013 -0700

    document $_exception

commit 32257d285544afbf433d7ce1b8a260bdd40afda0
Author: Tom Tromey <tromey@redhat.com>
Date:   Wed Mar 6 11:11:32 2013 -0700

    add NEWS entry for typeid

commit 456a5150de5cbd114a4acbf9ea3573d25fe5d94f
Author: Tom Tromey <tromey@redhat.com>
Date:   Wed Mar 6 10:17:39 2013 -0700

    reorganize catch throw section and add catch rethrow docs

commit 47b77c05023d10833c0b293b37d7ec7f686a5930
Author: Tom Tromey <tromey@redhat.com>
Date:   Wed Mar 6 09:59:07 2013 -0700

    remove obsolete text from the catchpoint node

-----------------------------------------------------------------------

Summary of changes:
 gdb/NEWS            |   11 +++++
 gdb/doc/gdb.texinfo |  114 ++++++++++++++++++++++++++------------------------
 2 files changed, 70 insertions(+), 55 deletions(-)

First 500 lines of diff:
diff --git a/gdb/NEWS b/gdb/NEWS
index 0877aa2..1a18de4 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -36,6 +36,14 @@ Lynx 178 PowerPC		powerpc-*-lynx*178
 
 * 'info proc' now works on some core files.
 
+* GDB now implements the the C++ 'typeid' operator.
+
+* The new convenience variable $_exception holds the exception being
+  thrown or caught at an exception-related catchpoint.
+
+* The exception-related catchpoints, like "catch throw", now accept a
+  regular expression which can be used to filter exceptions by type.
+
 * Python scripting
 
   ** Vectors can be created with gdb.Type.vector.
@@ -81,6 +89,9 @@ Lynx 178 PowerPC		powerpc-*-lynx*178
 
 * New commands (for set/show, see "New options" below)
 
+catch rethrow
+  Like "catch throw", but catches a re-thrown exception.
+
 catch signal 
   Catch signals.  This is similar to "handle", but allows commands and
   conditions to be attached.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 5f39d2e..29edfad 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -4052,13 +4052,63 @@ shared library.  Use the @code{catch} command to set a catchpoint.
 @kindex catch
 @item catch @var{event}
 Stop when @var{event} occurs.  @var{event} can be any of the following:
+
 @table @code
-@item throw
+@item throw @r{[}@var{regexp}@r{]}
+@itemx rethrow @r{[}@var{regexp}@r{]}
+@itemx catch @r{[}@var{regexp}@r{]}
 @cindex stop on C@t{++} exceptions
-The throwing of a C@t{++} exception.
+The throwing, re-throwing, or catching of a C@t{++} exception.
+
+If @var{regexp} is given, then only exceptions whose type matches the
+regular expression will be caught.
+
+@vindex $_exception@r{, convenience variable}
+The convenience variable @code{$_exception} is available at an
+exception-related catchpoint, on some systems.  This holds the
+exception being thrown.
+
+There are currently some limitations to C@t{++} exception handling in
+@value{GDBN}:
 
-@item catch
-The catching of a C@t{++} exception.
+@itemize @bullet
+@item
+The support for these commands is system-dependent.  Currently, only
+systems using the @samp{gnu-v3} C@t{++} ABI (@pxref{ABI}) are
+supported.
+
+@item
+The regular expression feature and the @code{$_exception} convenience
+variable rely on the presence of some SDT probes in @code{libstdc++}.
+If these probes are not present, then these features cannot be used.
+
+@item
+The @code{$_exception} convenience variable is only valid at the
+instruction at which an exception-related catchpoint is set.
+
+@item
+When an exception-related catchpoint is hit, @value{GDBN} stops at a
+location in the system library which implements runtime exception
+support for C@t{++}, usually @code{libstdc++}.  You can use @code{up}
+(@pxref{Selection}) to get to your code.
+
+@item
+If you call a function interactively, @value{GDBN} normally returns
+control to you when the function has finished executing.  If the call
+raises an exception, however, the call may bypass the mechanism that
+returns control to you and cause your program either to abort or to
+simply continue running until it hits a breakpoint, catches a signal
+that @value{GDBN} is listening for, or exits.  This is the case even if
+you set a catchpoint for the exception; catchpoints on exceptions are
+disabled within interactive calls.  @xref{Calling}, for information on
+controlling this with @code{set unwind-on-terminating-exception}.
+
+@item
+You cannot raise an exception interactively.
+
+@item
+You cannot install an exception handler interactively.
+@end itemize
 
 @item exception
 @cindex Ada exception catching
@@ -4268,57 +4318,6 @@ automatically deleted after the first time the event is caught.
 
 Use the @code{info break} command to list the current catchpoints.
 
-There are currently some limitations to C@t{++} exception handling
-(@code{catch throw} and @code{catch catch}) in @value{GDBN}:
-
-@itemize @bullet
-@item
-If you call a function interactively, @value{GDBN} normally returns
-control to you when the function has finished executing.  If the call
-raises an exception, however, the call may bypass the mechanism that
-returns control to you and cause your program either to abort or to
-simply continue running until it hits a breakpoint, catches a signal
-that @value{GDBN} is listening for, or exits.  This is the case even if
-you set a catchpoint for the exception; catchpoints on exceptions are
-disabled within interactive calls.
-
-@item
-You cannot raise an exception interactively.
-
-@item
-You cannot install an exception handler interactively.
-@end itemize
-
-@cindex raise exceptions
-Sometimes @code{catch} is not the best way to debug exception handling:
-if you need to know exactly where an exception is raised, it is better to
-stop @emph{before} the exception handler is called, since that way you
-can see the stack before any unwinding takes place.  If you set a
-breakpoint in an exception handler instead, it may not be easy to find
-out where the exception was raised.
-
-To stop just before an exception handler is called, you need some
-knowledge of the implementation.  In the case of @sc{gnu} C@t{++}, exceptions are
-raised by calling a library function named @code{__raise_exception}
-which has the following ANSI C interface:
-
-@smallexample
-    /* @var{addr} is where the exception identifier is stored.
-       @var{id} is the exception identifier.  */
-    void __raise_exception (void **addr, void *id);
-@end smallexample
-
-@noindent
-To make the debugger catch all exceptions before any stack
-unwinding takes place, set a breakpoint on @code{__raise_exception}
-(@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Exceptions}).
-
-With a conditional breakpoint (@pxref{Conditions, ,Break Conditions})
-that depends on the value of @var{id}, you can stop your program when
-a specific exception is raised.  You can use multiple conditional
-breakpoints to stop your program when any of a number of exceptions are
-raised.
-
 
 @node Delete Breaks
 @subsection Deleting Breakpoints
@@ -9349,6 +9348,10 @@ to match the format in which the data was printed.
 The variable @code{$_exitcode} is automatically set to the exit code when
 the program being debugged terminates.
 
+@item $_exception
+The variable @code{$_exception} is set to the exception object being
+thrown at an exception-related catchpoint.  @xref{Set Catchpoints}.
+
 @item $_probe_argc
 @itemx $_probe_arg0@dots{}$_probe_arg11
 Arguments to a static probe.  @xref{Static Probe Points}.
@@ -13313,6 +13316,7 @@ classes.
 
 @cindex C@t{++} exception handling
 @item catch throw
+@itemx catch rethrow
 @itemx catch catch
 Debug C@t{++} exception handling using these commands.  @xref{Set
 Catchpoints, , Setting Catchpoints}.


hooks/post-receive
--
Repository for Project Archer.


^ permalink raw reply	[flat|nested] only message in thread

only message in thread, other threads:[~2013-03-06 18:44 UTC | newest]

Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2013-03-06 18:44 [SCM] tromey/exception-improvements: document regexp argument to exception catchpoints 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).