[RFA/doco] Document "set/show multiple-symbols" command
Joel Brobecker
brobecker@adacore.com
Wed Apr 2 21:02:00 GMT 2008
Hi Eli,
Here is a new throw at documenting this new option. I think I incorporated
all your comments, and I'm relatively satisfied with the current version.
Let me know what you think!
2008-04-02 Joel Brobecker <brobecker@adacore.com>
* gdb.texinfo (Breakpoint Menus): Delete. Contents moved inside
new node "Ambiguous Expressions". Replace references to this
node by references to "Ambiguous Expressions" throughout.
(Ambiguous Expressions): New node.
Tested on my x86-linux laptop by rebuilding the HTML documentation.
--
Joel
-------------- next part --------------
Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.478
diff -u -p -r1.478 gdb.texinfo
--- gdb.texinfo 26 Mar 2008 18:37:47 -0000 1.478
+++ gdb.texinfo 2 Apr 2008 18:45:34 -0000
@@ -2877,7 +2877,6 @@ all breakpoints in that range are operat
* Disabling:: Disabling breakpoints
* Conditions:: Break conditions
* Break Commands:: Breakpoint command lists
-* Breakpoint Menus:: Breakpoint menus
* Error in Breakpoints:: ``Cannot insert breakpoints''
* Breakpoint-related Warnings:: ``Breakpoint address adjusted...''
@end menu
@@ -2910,7 +2909,8 @@ before it executes any of the code in th
When using source languages that permit overloading of symbols, such as
C@t{++}, a function name may refer to more than one possible place to break.
-@xref{Breakpoint Menus,,Breakpoint Menus}, for a discussion of that situation.
+@xref{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of
+that situation.
@item break
When called without any arguments, @code{break} sets a breakpoint at
@@ -3857,53 +3857,6 @@ cont
end
@end smallexample
-@node Breakpoint Menus
-@subsection Breakpoint Menus
-@cindex overloading
-@cindex symbol overloading
-
-Some programming languages (notably C@t{++} and Objective-C) permit a
-single function name
-to be defined several times, for application in different contexts.
-This is called @dfn{overloading}. When a function name is overloaded,
-@samp{break @var{function}} is not enough to tell @value{GDBN} where you want
-a breakpoint. You can use explicit signature of the function, as in
-@samp{break @var{function}(@var{types})}, to specify which
-particular version of the function you want. Otherwise, @value{GDBN} offers
-you a menu of numbered choices for different possible breakpoints, and
-waits for your selection with the prompt @samp{>}. The first two
-options are always @samp{[0] cancel} and @samp{[1] all}. Typing @kbd{1}
-sets a breakpoint at each definition of @var{function}, and typing
-@kbd{0} aborts the @code{break} command without setting any new
-breakpoints.
-
-For example, the following session excerpt shows an attempt to set a
-breakpoint at the overloaded symbol @code{String::after}.
-We choose three particular definitions of that function name:
-
-@c FIXME! This is likely to change to show arg type lists, at least
-@smallexample
-@group
-(@value{GDBP}) b String::after
-[0] cancel
-[1] all
-[2] file:String.cc; line number:867
-[3] file:String.cc; line number:860
-[4] file:String.cc; line number:875
-[5] file:String.cc; line number:853
-[6] file:String.cc; line number:846
-[7] file:String.cc; line number:735
-> 2 4 6
-Breakpoint 1 at 0xb26c: file String.cc, line 867.
-Breakpoint 2 at 0xb344: file String.cc, line 875.
-Breakpoint 3 at 0xafcc: file String.cc, line 846.
-Multiple breakpoints were set.
-Use the "delete" command to delete unwanted
- breakpoints.
-(@value{GDBP})
-@end group
-@end smallexample
-
@c @ifclear BARETARGET
@node Error in Breakpoints
@subsection ``Cannot insert breakpoints''
@@ -5562,6 +5515,7 @@ Table}.
@menu
* Expressions:: Expressions
+* Ambiguous Expressions:: Ambiguous Expressions
* Variables:: Program variables
* Arrays:: Artificial arrays
* Output Formats:: Output formats
@@ -5640,6 +5594,89 @@ a cast). This construct is allowed rega
normally supposed to reside at @var{addr}.
@end table
+@node Ambiguous Expressions
+@section Ambiguous Expressions
+@cindex Ambiguous Expressions
+
+Expressions can sometimes contain some ambiguous elements. For instance,
+some programming languages (notably Ada, C@t{++} and Objective-C) permit
+a single function name to be defined several times, for application in
+different contexts. This is called @dfn{overloading}. Another example
+involving Ada is generics. A @dfn{generic package} is similar to C@t{++}
+templates and is typically instantiated several times, resulting in
+the same function name being defined in different contexts.
+
+In some cases and depending on the language, it is possible to adjust
+the expression to remove the ambiguity. For instance in C@t{++}, you
+can specify the signature of the function you want to break on, as in
+@samp{break @var{function}(@var{types})}. In Ada, using the fully
+qualified name of your function often makes the expression unambiguous
+as well.
+
+When an ambiguity that needs to be resolved is detected, the debugger
+has the capability to display a menu of numbered choices for each
+possibility, and then waits for the selection with the prompt @samp{>}.
+The first option is always @samp{[0] cancel}, and typing @kbd{0 @key{RET}}
+aborts the current command. If the command in which the expression was
+used allows more than one choice to be selected, the next option in the
+menu is @samp{[1] all}, and typing @kbd{1 @key{RET}} selects all possible
+choices.
+
+For example, the following session excerpt shows an attempt to set a
+breakpoint at the overloaded symbol @code{String::after}.
+We choose three particular definitions of that function name:
+
+@c FIXME! This is likely to change to show arg type lists, at least
+@smallexample
+@group
+(@value{GDBP}) b String::after
+[0] cancel
+[1] all
+[2] file:String.cc; line number:867
+[3] file:String.cc; line number:860
+[4] file:String.cc; line number:875
+[5] file:String.cc; line number:853
+[6] file:String.cc; line number:846
+[7] file:String.cc; line number:735
+> 2 4 6
+Breakpoint 1 at 0xb26c: file String.cc, line 867.
+Breakpoint 2 at 0xb344: file String.cc, line 875.
+Breakpoint 3 at 0xafcc: file String.cc, line 846.
+Multiple breakpoints were set.
+Use the "delete" command to delete unwanted
+ breakpoints.
+(@value{GDBP})
+@end group
+@end smallexample
+
+@table @code
+@kindex set multiple-symbols
+@item set multiple-symbols @var{mode}
+@cindex multiple-symbols menu
+
+This option allows you to adjust the debugger behavior when an expression
+is ambiguous.
+
+By default, @var{mode} is set to @code{all}. If the command with which
+the expression is used allows more than one choice, then @value{GDBN}
+automatically selects all possible choices. For instance, inserting
+a breakpoint on a function using an ambiguous name results in a breakpoint
+inserted on each possible match. However, if a unique choice must be made,
+then @value{GDBN} uses the menu to help you disambiguate the expression.
+For instance, printing the address of an overloaded function will result
+in the use of the menu.
+
+When @var{mode} is set to @code{ask}, the debugger always uses the menu
+when an ambiguity is detected.
+
+Finally, when @var{mode} is set to @code{cancel}, the debugger reports
+an error due to the ambiguity and the command is aborted.
+
+@kindex show multiple-symbols
+@item show multiple-symbols
+Show the current value of the @code{multiple-symbols} setting.
+@end table
+
@node Variables
@section Program Variables
@@ -9621,8 +9658,9 @@ designed specifically for use with C@t{+
@cindex break in overloaded functions
@item @r{breakpoint menus}
When you want a breakpoint in a function whose name is overloaded,
-@value{GDBN} breakpoint menus help you specify which function definition
-you want. @xref{Breakpoint Menus,,Breakpoint Menus}.
+@value{GDBN} has the capability to display a breakpoint menu to help you
+specify which function definition you want.
+@xref{Ambiguous Expressions,,Ambiguous Expressions}.
@cindex overloading in C@t{++}
@item rbreak @var{regex}
More information about the Gdb-patches
mailing list