diff options
author | Pedro Alves <palves@redhat.com> | 2017-06-21 20:12:41 +0100 |
---|---|---|
committer | Pedro Alves <palves@redhat.com> | 2017-10-19 18:30:30 +0100 |
commit | 0934a353a3b57771475693216cb47eab470ed71f (patch) | |
tree | 2c6dcfe4dd68858cb74d9ea3538fe5581dd506da | |
parent | 26f85f364db04b69855eabcfc61d85d81e2964e2 (diff) | |
download | binutils-gdb-users/palves/cxx-breakpoint-improvements.tar.gz |
Document breakpoints / linespec & co improvements (manual + NEWS)users/palves/cxx-breakpoint-improvements
gdb/doc/ChangeLog:
yyyy-mm-dd Pedro Alves <palves@redhat.com>
* NEWS: Mention breakpoints, linespecs and explicit locations, and
completion improvements.
gdb/doc/ChangeLog:
yyyy-mm-dd Pedro Alves <palves@redhat.com>
* gdb.texinfo (Completion): Update need-quoting examples. Remove
false claim that GDB inserts quoting automatically.
(Linespec Locations): Document how "function" is
interpreted in C++.
(Explicit Locations): Document how "-function" is interpreted in
C++. Document -qualified.
(Debugging C Plus Plus): Document setting breakpoints in functions
with ABI tags.
-rw-r--r-- | gdb/NEWS | 71 | ||||
-rw-r--r-- | gdb/doc/gdb.texinfo | 133 |
2 files changed, 181 insertions, 23 deletions
@@ -123,6 +123,77 @@ starti (gdb) p (float) var $3 = 3.14 +* Completion improvements + + ** GDB can now complete function parameters in linespecs and + explicit locations without quoting. When setting breakpoints, + quoting around functions names to help with TAB-completion is + generally no longer necessary. For example, this now completes + correctly: + + (gdb) b function(in[TAB] + (gdb) b function(int) + + Related, GDB is no longer confused with completing functions in + C++ anonymous namespaces: + + (gdb) b (anon[TAB] + (gdb) b (anonymous namespace)::[TAB][TAB] + (anonymous namespace)::a_function() + (anonymous namespace)::b_function() + + ** GDB now has much improved linespec and explicit locations TAB + completion support, that better understands what you're + completing and offers better suggestions. For example, GDB no + longer offers data symbols as possible completions when you're + setting a breakpoint. + + ** GDB now TAB-completes label symbol names. + + ** The "complete" command now mimics TAB completion accurately. + +* Breakpoints on C++ functions now ignore leading namespaces/classes + + By default, breakpoints on functions/methods are now interpreted as + specifying all functions with the given name ignoring missing + leading specifiers (namespaces and classes). + + For example, assuming a C++ program with symbols named: + + A::B::func + B::func + + both commands "break func" and "break B::func" set a breakpoint on + both symbols. The explicit location option "-function" was changed + accordingly. + + To override this, you can specify an explicitly fully qualified + name, usign the new explicit location option "-qualified". For + example, using the same C++ program, the "break -qualified B::func" + command sets a breakpoint on "B::func", only. + +* Breakpoints on functions marked with C++ ABI tags + + GDB can now set breakpoints on functions marked with C++ ABI tags + (e.g., [abi:cxx11]). See here for a description of ABI tags: + https://developers.redhat.com/blog/2015/02/05/gcc5-and-the-c11-abi/ + + Functions with a C++11 abi tag are demangled/displayed like this: + + function[abi:cxx11](int) + ^^^^^^^^^^^ + + You can now set a breakpoint on such functions simply as if they had + no tag, like: + + (gdb) b function(int) + + Or if you need to disambiguate between tags, like: + + (gdb) b function[abi:other_tag](int) + + Tab completion was adjusted accordingly as well. + * New native configurations FreeBSD/aarch64 aarch64*-*-freebsd* diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index bfeb7a9a35d..16c9f0fd672 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -1638,39 +1638,56 @@ its notion of a word. To permit word completion to work in this situation, you may enclose words in @code{'} (single quote marks) in @value{GDBN} commands. -The most likely situation where you might need this is in typing the -name of a C@t{++} function. This is because C@t{++} allows function -overloading (multiple definitions of the same function, distinguished -by argument type). For example, when you want to set a breakpoint you -may need to distinguish whether you mean the version of @code{name} -that takes an @code{int} parameter, @code{name(int)}, or the version -that takes a @code{float} parameter, @code{name(float)}. To use the -word-completion facilities in this situation, type a single quote +A likely situation where you might need this is in typing an +expression that involves a C@t{++} symbol name with template +parameters. This is because when completing expressions, GDB treats +the @samp{<} character as word delimiter, assuming that it's the +less-than comparison operator (@pxref{C Operators, , C and C@t{++} +Operators}). + +For example, when you want to call a C@t{++} template function +interactively using the @code{print} or @code{call} commands, you may +need to distinguish whether you mean the version of @code{name} that +was specialized for @code{int}, @code{name<int>()}, or the version +that was specialized for @code{float}, @code{name<float>()}. To use +the word-completion facilities in this situation, type a single quote @code{'} at the beginning of the function name. This alerts @value{GDBN} that it may need to consider more information than usual when you press @key{TAB} or @kbd{M-?} to request word completion: @smallexample -(@value{GDBP}) b 'bubble( @kbd{M-?} -bubble(double,double) bubble(int,int) -(@value{GDBP}) b 'bubble( +(@value{GDBP}) p 'func< @kbd{M-?} +func<int>() func<float>() +(@value{GDBP}) p 'func< @end smallexample -In some cases, @value{GDBN} can tell that completing a name requires using -quotes. When this happens, @value{GDBN} inserts the quote for you (while -completing as much as it can) if you do not type the quote in the first -place: +When setting breakpoints however (@pxref{Specify Location}), you don't +usually need to type a quote before the function name, because +@value{GDBN} understands that you want to set a breakpoint on a +function: @smallexample -(@value{GDBP}) b bub @key{TAB} -@exdent @value{GDBN} alters your input line to the following, and rings a bell: -(@value{GDBP}) b 'bubble( +(@value{GDBP}) b func< @kbd{M-?} +func<int>() func<float>() +(@value{GDBP}) b func< @end smallexample -@noindent -In general, @value{GDBN} can tell that a quote is needed (and inserts it) if -you have not yet started typing the argument list when you ask for -completion on an overloaded symbol. +This is true even in the case of typing the name of C@t{++} overloaded +functions (multiple definitions of the same function, distinguished by +argument type). For example, when you want to set a breakpoint you +don't need to distinguish whether you mean the version of @code{name} +that takes an @code{int} parameter, @code{name(int)}, or the version +that takes a @code{float} parameter, @code{name(float)}. + +@smallexample +(@value{GDBP}) b bubble( @kbd{M-?} +bubble(int) bubble(double) +(@value{GDBP}) b bubble(dou @kbd{M-?} +bubble(double) +@end smallexample + +See @ref{quoting names} for a description of other scenarios that +require quoting. For more information about overloaded functions, see @ref{C Plus Plus Expressions, ,C@t{++} Expressions}. You can use the command @code{set @@ -7899,6 +7916,16 @@ name of @file{/build/trunk/gcc/expr.c}, but not Specifies the line that begins the body of the function @var{function}. For example, in C, this is the line with the open brace. +For C@t{++}, @var{function} is interpreted as specifying all functions +named @var{function} ignoring missing leading specifiers (namespaces +and classes). + +For example, assuming a program with symbols named @code{A::B::func} +and @code{B::func}, both commands @w{@kbd{break func}} and +@w{@kbd{break B::func}} set a breakpoint on both symbols. To +override this, you can use the explicit location option +@code{-qualified}. @xref{Explicit Locations}. + @item @var{function}:@var{label} Specifies the line where @var{label} appears in @var{function}. @@ -7963,6 +7990,22 @@ on function locations unmodified by other options (such as @code{-label} or @code{-line}) refer to the line that begins the body of the function. In C, for example, this is the line with the open brace. +For C@t{++}, @var{function} is interpreted as specifying all functions +named @var{function} ignoring missing leading specifiers (namespaces +and classes). + +For example, assuming a program with symbols named @code{A::B::func} +and @code{B::func}, both commands @w{@kbd{break -function func}} and +@w{@kdb{break -function B::func}} set a breakpoint on both symbols. + +@item -qualified @var{function} +Like @code{-function}, but the value specifies a fully qualified name +of a function. + +For example, assuming a C@t{++} program with symbols named +@code{A::B::func} and @code{B::func}, the @w{@kbd{break -qualified +B::func}} command sets a breakpoint on @code{B::func}, only. + @item -label @var{label} The value specifies the name of a label. When the function name is not specified, the label is searched in the function of the currently @@ -7976,7 +8019,7 @@ relative to the current line. @end table Explicit location options may be abbreviated by omitting any non-unique -trailing characters from the option name, e.g., @code{break -s main.c -li 3}. +trailing characters from the option name, e.g., @w{@kdb{break -s main.c -li 3}}. @node Address Locations @subsection Address Locations @@ -15062,6 +15105,49 @@ the same notation that is used to declare such symbols in C@t{++}: type also use the @value{GDBN} command-line word completion facilities to list the available choices, or to finish the type list for you. @xref{Completion,, Command Completion}, for details on how to do this. + +@item @r{Breakpoints in functions with ABI tags} + +The GNU C@t{++} compiler introduced the notion of ABI ``tags'', which +correspond to changes in the ABI of a type, function, or variable that +would not otherwise be reflected in a mangled name. See +@url{https://developers.redhat.com/blog/2015/02/05/gcc5-and-the-c11-abi/} +for more detail. + +The ABI tags are visible in C@t{++} demangled names. For example, a +function that returns a std::string: + +@smallexample +std::string function(int); +@end smallexample + +@noindent +when compiled for the C++11 ABI is marked with the @code{cxx11} ABI +tag, and @value{GDBN} displays the symbol like this: + +@smallexample +function[abi:cxx11](int) +@end smallexample + +You can set a breakpoint on such functions simply as if they had no +tag. For example: + +@smallexample +(gdb) b function(int) +Breakpoint 2 at 0x40060d: file main.cc, line 10. +(gdb) info breakpoints +Num Type Disp Enb Address What +1 breakpoint keep y 0x0040060d in function[abi:cxx11](int) + at main.cc:10 +@end smallexample + +On the rare occasion you need to disambiguate between different ABI +tags, you can do so by simply including the ABI tag in the function +name, like: + +@smallexample +(@value{GDBP}) b ambiguous[abi:other_tag](int) +@end smallexample @end table @node Decimal Floating Point @@ -16888,6 +16974,7 @@ file-management commands (@pxref{Files, ,Commands to Specify Files}). @cindex symbol names @cindex names of symbols @cindex quoting names +@anchor{quoting names} Occasionally, you may need to refer to symbols that contain unusual characters, which @value{GDBN} ordinarily treats as word delimiters. The most frequent case is in referring to static variables in other |