From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 86694 invoked by alias); 21 Jun 2017 15:50:32 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 86683 invoked by uid 89); 21 Jun 2017 15:50:30 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-26.9 required=5.0 tests=BAYES_00,GIT_PATCH_0,GIT_PATCH_1,GIT_PATCH_2,GIT_PATCH_3,SPF_HELO_PASS,T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 spammy=Plus, enclose, Tab, Ct 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 15:50:27 +0000 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 2CA1F2DE3D; Wed, 21 Jun 2017 15:50:26 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com 2CA1F2DE3D Authentication-Results: ext-mx09.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx09.extmail.prod.ext.phx2.redhat.com; spf=pass smtp.mailfrom=palves@redhat.com DKIM-Filter: OpenDKIM Filter v2.11.0 mx1.redhat.com 2CA1F2DE3D 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 2C6E6171A1; Wed, 21 Jun 2017 15:50:24 +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> Cc: gdb-patches@sourceware.org From: Pedro Alves Message-ID: <77ada869-54e0-6fbd-3edd-9a0000cd1aaf@redhat.com> Date: Wed, 21 Jun 2017 15:50:00 -0000 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: Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 7bit X-SW-Source: 2017-06/txt/msg00594.txt.bz2 On 06/02/2017 02:33 PM, Pedro Alves wrote: > On 06/02/2017 02:01 PM, Eli Zaretskii wrote: >>> From: Pedro Alves >>> Date: Fri, 2 Jun 2017 13:22:38 +0100 >>> >>> +For example, assuming a program with symbols named @code{A::B::func} >>> +and @code{B::func}, both commands @code{break -function func} and >>> +@code{break -function B::func} set a breakpoint on both symbols. >> >> The 2 commands are long and include whitespace, so I'd suggest >> enclosing each one in @w{..}, to avoid a line break in the middle of a >> command. >> >> Also, I think @kbd is more appropriate here than @code, since you mean >> commands the user will type, not just command names. >> >> I'm surprised you didn't change anything where the manual discusses >> quoting of names and symbols. For example, the node "Completion" >> explicitly describes a use case with overloaded functions in C++; the >> node "Symbols" describes a case with "::" that requires quoting. >> There's another example in "Machine Code", and also in "Ambiguous >> Expression", and in "Variables". Maybe you already reviewed all of >> those and concluded no changes were necessary, but I just thought I'd >> mention them. > > Thanks, I just didn't think of looking for quoting bits in the > manual, for some reason. I'll take a closer look. I've now reviewed these, and it looks to be like only the "Completion" node needs adjustment. I replaced the example there with another example that came to mind when I tried to think of when I use quoting. I'm not sure it's "the most frequent" case, so I softened the "the" to "a". I also found there an ancient paragraph saying that GDB inserts quoting automatically, which is plain false (and I don't recall ever running a version of GDB that did that). I also added a cross reference to elsewhere in the manual where we discuss the need for quoting of symbol names. > >> >>> + ** GDB now has a much improved linespec and explicit locations TAB >>> + completion support, that better understands what you're >>> + completing and offers better suggestions. >> >> Is this a general improvement, or is it limited to C++ symbols? If >> the latter, suggest to mention that. > > You're right. It's more general than C++. I've reordered the sections and split appart the C++-related subsections to their own sections, to hopefully make things a bit clearer. I've also adjusted the wording in a couple cases, and extended some cases with examples. > >> >>> + ** GDB can now complete function parameters in linespecs and >>> + explicit locations, even without quoting. When setting >>> + breakpoints, quoting around functions names to help with >>> + TAB-completion is generally no longer necessary. >> >> Likewise. >> >>> + ** GDB can now set breakpoints functions marked with [abi:cxx11] >>> + tags. >> >> "on functions", I think. Fixed. >> >> And btw, what are those tags? > > This is the best document that I know describing them: > > https://developers.redhat.com/blog/2015/02/05/gcc5-and-the-c11-abi/ > > Functions that ended up requiring an abi tag are demangled like this: > > string_printf[abi:cxx11](char const*, ...) > ^^^^^^^^^^^ > > That's an actual function in GDB. It ended requiring an ABI tag > because it returns std::string. See intro of patch 39 for more. > >> I don't think I see them documented in the manual; did I miss something? > > Hmm, I guess we could add something, indeed. I've added something now. The "Debugging C Plus Plus" node has a section talking about setting breakpoints on overloaded functions which looked like the right place for this. The only thing I didn't address was the @code vs @kbd point. See the other email. Otherwise, how does this version look? >From 746f2009e4d27da6d43844c36cc4b04ce71fe1d5 Mon Sep 17 00:00:00 2001 From: Pedro Alves Date: Wed, 21 Jun 2017 16:04:40 +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 | 131 +++++++++++++++++++++++++++++++++++++++++++--------- gdb/NEWS | 71 ++++++++++++++++++++++++++++ 2 files changed, 180 insertions(+), 22 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 9fb70f6..eff1f55 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{@code{break func}} and +@w{@code{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 @code{break -function func} and +@code{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 @code{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 @@ -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 -- 2.5.5