From patchwork Wed Jun 21 19:14:04 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pedro Alves X-Patchwork-Id: 21182 Received: (qmail 53429 invoked by alias); 21 Jun 2017 19:14:15 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Delivered-To: mailing list gdb-patches@sourceware.org Received: (qmail 53353 invoked by uid 89); 21 Jun 2017 19:14:10 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-25.9 required=5.0 tests=BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, KAM_LAZY_DOMAIN_SECURITY, SPF_HELO_PASS, T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 spammy= X-HELO: mx1.redhat.com Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Wed, 21 Jun 2017 19:14:07 +0000 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 73146303154; Wed, 21 Jun 2017 19:14:06 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com 73146303154 Authentication-Results: ext-mx05.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx05.extmail.prod.ext.phx2.redhat.com; spf=pass smtp.mailfrom=palves@redhat.com DKIM-Filter: OpenDKIM Filter v2.11.0 mx1.redhat.com 73146303154 Received: from [127.0.0.1] (ovpn04.gateway.prod.ext.ams2.redhat.com [10.39.146.4]) by smtp.corp.redhat.com (Postfix) with ESMTP id 8383860601; Wed, 21 Jun 2017 19:14:05 +0000 (UTC) Subject: Re: [PATCH 40/40] Document breakpoints / linespec & co improvements (manual + NEWS) To: Eli Zaretskii References: <1496406158-12663-1-git-send-email-palves@redhat.com> <1496406158-12663-41-git-send-email-palves@redhat.com> <83a85qczmo.fsf@gnu.org> <77ada869-54e0-6fbd-3edd-9a0000cd1aaf@redhat.com> Cc: gdb-patches@sourceware.org From: Pedro Alves Message-ID: Date: Wed, 21 Jun 2017 20:14:04 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.4.0 MIME-Version: 1.0 In-Reply-To: <77ada869-54e0-6fbd-3edd-9a0000cd1aaf@redhat.com> On 06/21/2017 04:50 PM, Pedro Alves wrote: > The only thing I didn't address was the @code vs @kbd point. > See the other email. > > Otherwise, how does this version look? And here's the version addresses that too. From 35a8155edc16951cbfe173d0c6dbd34c39f85be4 Mon Sep 17 00:00:00 2001 From: Pedro Alves Date: Wed, 21 Jun 2017 20:12:41 +0100 Subject: [PATCH] Document breakpoints / linespec & co improvements (manual + NEWS) gdb/doc/ChangeLog: yyyy-mm-dd Pedro Alves * NEWS: Mention breakpoints, linespecs and explicit locations, and completion improvements. gdb/doc/ChangeLog: yyyy-mm-dd Pedro Alves * 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. --- gdb/doc/gdb.texinfo | 133 +++++++++++++++++++++++++++++++++++++++++++--------- gdb/NEWS | 71 ++++++++++++++++++++++++++++ 2 files changed, 181 insertions(+), 23 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 9fb70f6..1db8690 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()}, or the version +that was specialized for @code{float}, @code{name()}. 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() func() +(@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() func() +(@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 @@ -7845,6 +7862,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}. @@ -7909,6 +7936,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 @@ -7922,7 +7965,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 @@ -14992,6 +15035,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 @@ -16818,6 +16904,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 diff --git a/gdb/NEWS b/gdb/NEWS index 112aa2f..eebe89a 100644 --- a/gdb/NEWS +++ b/gdb/NEWS @@ -3,6 +3,77 @@ *** Changes since GDB 8.0 +* 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 complete + 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. + *** Changes in GDB 8.0 * GDB now supports access to the PKU register on GNU/Linux. The register is