From 405559254a43be1b9f847910a5abf560d992aa58 Mon Sep 17 00:00:00 2001
From: Joel Brobecker <brobecker@gnat.com>
Date: Fri, 11 Oct 2013 13:51:27 +0000
Subject: [PATCH] Document the -catch-assert and -catch-exception new GDB/MI
 commands.

This patch adds documentation for the new GDB/MI commands "-catch-assert"
and "-catch-exception", meant to provide the same functionality as
the "catch assert", "catch exception" and "catch exception unhandled"
CLI commands.

In the GDB Manual, there was already a section for catchpoint comments,
so that seemed like a natural place to document the new commands. But
commands related to a given concept seem to have traditionally been
organized alphabetically, and I didn't want future commands to break
down logical pairing of various commands. For instance, "-catch-load"
and "-catch-unload" are quite "distant" from each other, and it is easy
to imagine a new comment which would alphabetically fall in between,
causing them to be separated. So I introduced subsections to prevent
that from happening.

gdb/ChangeLog:

        * NEWS: Add entry documenting the new "-catch-assert" and
        "-catch-exception" GDB/MI commands.

gdb/doc/ChangeLog:

        * gdb.texinfo (Shared Library GDB/MI Catchpoint Commands):
        New subsection inside which the "-catch-load" and "-catch-unload"
        commands documentation is now placed.
        (Ada Exception GDB/MI Catchpoint Commands): New subsection
        documenting the "-catch-assert" and "-catch-exception" new
        GDB/MI commands.
---
 gdb/NEWS            |  3 ++
 gdb/doc/gdb.texinfo | 99 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 102 insertions(+)

diff --git a/gdb/NEWS b/gdb/NEWS
index 4e627b0e09a..10834df8391 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -149,6 +149,9 @@ show range-stepping
      command, stopping the program's execution at the start of its
      main subprogram.
 
+  ** The new commands -catch-assert and -catch-exceptions insert
+     catchpoints stopping the program when Ada exceptions are raised.
+
 * New system-wide configuration scripts
   A GDB installation now provides scripts suitable for use as system-wide
   configuration scripts for the following systems:
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 24773ea293e..44fb174fbf3 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -30328,6 +30328,14 @@ thread-groups=["i1"],times="1"@}]@}
 This section documents @sc{gdb/mi} commands for manipulating
 catchpoints.
 
+@menu
+* Shared Library GDB/MI Catchpoint Commands::
+* Ada Exception GDB/MI Catchpoint Commands::
+@end menu
+
+@node Shared Library GDB/MI Catchpoint Commands
+@subsection Shared Library @sc{gdb/mi} Catchpoints
+
 @subheading The @code{-catch-load} Command
 @findex -catch-load
 
@@ -30386,6 +30394,97 @@ what="load of library matching bar.so",catch-type="unload",times="0"@}
 (gdb)
 @end smallexample
 
+@node Ada Exception GDB/MI Catchpoint Commands
+@subsection Ada Exception @sc{gdb/mi} Catchpoints
+
+The following @sc{gdb/mi} commands can be used to create catchpoints
+that stop the execution when Ada exceptions are being raised.
+
+@subheading The @code{-catch-assert} Command
+@findex -catch-assert
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-assert [ -c @var{condition}] [ -d ] [ -t ]
+@end smallexample
+
+Add a catchpoint for failed Ada assertions.
+
+The possible optional parameters for this command are:
+
+@table @samp
+@item -c @var{condition}
+Make the catchpoint conditional on @var{condition}.
+@item -d
+Create a disabled catchpoint.
+@item -t
+Create a temporary catchpoint.
+@end table
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{catch assert}.
+
+@subsubheading Example
+
+@smallexample
+-catch-assert
+^done,bkptno="5",bkpt=@{number="5",type="breakpoint",disp="keep",
+enabled="y",addr="0x0000000000404888",what="failed Ada assertions",
+thread-groups=["i1"],times="0",
+original-location="__gnat_debug_raise_assert_failure"@}
+(gdb)
+@end smallexample
+
+@subheading The @code{-catch-exception} Command
+@findex -catch-exception
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-exception [ -c @var{condition}] [ -d ] [ -e @var{exception-name} ]
+    [ -t ] [ -u ]
+@end smallexample
+
+Add a catchpoint stopping when Ada exceptions are raised.
+By default, the command stops the program when any Ada exception
+gets raised.  But it is also possible, by using some of the
+optional parameters described below, to create more selective
+catchpoints.
+
+The possible optional parameters for this command are:
+
+@table @samp
+@item -c @var{condition}
+Make the catchpoint conditional on @var{condition}.
+@item -d
+Create a disabled catchpoint.
+@item -e @var{exception-name}
+Only stop when @var{exception-name} is raised.  This option cannot
+be used combined with @samp{-u}.
+@item -t
+Create a temporary catchpoint.
+@item -u
+Stop only when an unhandled exception gets raised.  This option
+cannot be used combined with @samp{-e}.
+@end table
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{catch exception}
+and @samp{catch exception unhandled}.
+
+@subsubheading Example
+
+@smallexample
+-catch-exception -e Program_Error
+^done,bkptno="4",bkpt=@{number="4",type="breakpoint",disp="keep",
+enabled="y",addr="0x0000000000404874",
+what="`Program_Error' Ada exception", thread-groups=["i1"],
+times="0",original-location="__gnat_debug_raise_exception"@}
+(gdb)
+@end smallexample
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 @node GDB/MI Program Context
-- 
2.30.2