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.
This commit is contained in:
Joel Brobecker 2013-10-11 13:51:27 +00:00
parent 2a3be96627
commit 405559254a
2 changed files with 102 additions and 0 deletions

View File

@ -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:

View File

@ -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