From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from eggs.gnu.org (eggs.gnu.org [IPv6:2001:470:142:3::10]) by sourceware.org (Postfix) with ESMTPS id 8212C3857364 for ; Wed, 1 Jun 2022 17:17:07 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 8212C3857364 Received: from fencepost.gnu.org ([2001:470:142:3::e]:39496) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nwRxy-0006AH-Ra; Wed, 01 Jun 2022 13:17:06 -0400 Received: from [87.69.77.57] (port=1599 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nwRxy-0003rM-7C; Wed, 01 Jun 2022 13:17:06 -0400 Date: Wed, 01 Jun 2022 20:17:14 +0300 Message-Id: <83wne0fgmd.fsf@gnu.org> From: Eli Zaretskii To: Pedro Alves Cc: gdb-patches@sourceware.org In-Reply-To: <6914f754-4e33-5aa1-4ea6-dca9504e8bfe@palves.net> (message from Pedro Alves on Mon, 30 May 2022 15:44:59 +0100) Subject: RTe: Location Specs (Was: [pushed v5] gdb/manual: Introduce location specs) References: <20220526194250.2310460-1-pedro@palves.net> <838rqmm7gb.fsf@gnu.org> <6914f754-4e33-5aa1-4ea6-dca9504e8bfe@palves.net> X-Spam-Status: No, score=-7.1 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, KAM_ASCII_DIVIDERS, RCVD_IN_BARRACUDACENTRAL, SPF_HELO_PASS, SPF_PASS, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 01 Jun 2022 17:17:10 -0000 > Date: Mon, 30 May 2022 15:44:59 +0100 > Cc: gdb-patches@sourceware.org > From: Pedro Alves > > From: Pedro Alves > Date: Tue, 17 May 2022 13:12:04 +0100 > Subject: [PATCH] gdb/manual: Introduce location specs > > The current "Specify Location" section of the GDB manual starts with: > > "Several @value{GDBN} commands accept arguments that specify a location > of your program's code." I'd like to propose slight rewording and rearrangement of the section which you modified with that commit. Below please find: (a) the full modified text of the section, and (b) diffs against the current master branch. WDYT? ---------------------------------------------------------------------- @node Location Specifications @section Location Specifications @cindex specifying location @cindex locspec @cindex source location @cindex code location @cindex location spec Several @value{GDBN} commands accept arguments that specify a location or locations of your program's code. Since @value{GDBN} is a source-level debugger, a location specification usually indicates some line in some source file, but it can also do that indirectly, by specifying a function name, an address, a label, etc. The different forms of specifying a location that @value{GDBN} recognizes are collectively known as forms of @dfn{location specification}, or @dfn{location spec}. This section documents the forms of specifying locations that @value{GDBN} recognizes. @cindex location resolution @cindex resolution of location spec When you specify a location, @value{GDBN} needs to find the place in your program, known as @dfn{code location}, that corresponds to the given location spec. We call this process of finding actual code locations corresponding to a location spec @dfn{location resolution}. A concrete code location in your program is uniquely identifiable by a set of several attributes: its source line number, the name of its source file, the fully-qualified and prototyped function in which it is defined, and an instruction address. Because each inferior has its own address space, the inferior number is also a necessary part of these attributes. By contrast, location specs you type will many times omit some of these attributes. For example, it is customary to specify just the source line number to mean a line in the current source file, or specify just the basename of the file, omitting its directories. In other words, a location spec is usually incomplete, a kind of blueprint, and @value{GDBN} needs to complete the missing attributes by using the implied defaults, and by considering the source code and the debug information available to it. This is what location resolution is about. The resolution of an incomplete location spec can produce more than a single code location, if the spec doesn't allow distinguishing between them. Here are some examples of situations that result in a location spec matching multiple code locations in your program: @itemize @bullet @item The location spec specifies a function name, and there are several functions in the program which have that name. (To distinguish between them, you can specify a fully-qualified and prototyped function name, such as @code{A::func(int)} instead of just @code{func}.) @item The location spec specifies a source file name, and there are several source files in the program that share the same name, for example several files with the same basename in different subdirectories. (To distinguish between them, specify enough leading directories with the file name.) @item For a C@t{++} constructor, the @value{NGCC} compiler generates several instances of the function body, used in different cases, but their source-level names are identical, unless you qualify them. @item For a C@t{++} template function, a given line in the function can correspond to any number of instantiations. @item For an inlined function, a given source line can correspond to several actual code locations with that function's inlined code. @end itemize Resolution of a location spec can also fail to produce a complete code location, or even fail to produce any code location. Here are some examples of such situations: @itemize @bullet @item Some parts of the program lack detailed enough debug info, so the resolved code location lacks some attributes, like source file name and line number, leaving just the instruction address and perhaps also a function name. Such an incomplete code location is only usable in contexts that work with addresses and/or function names. Some commands can only work with complete code locations. @item The location spec specifies a function name, and there are no functions in the program by that name, or they only exist in a yet-unloaded shared library. @item The location spec specifies a source file name, and there are no source files in the program by that name, or they only exist in a yet-unloaded shared library. @item The location spec specifies both a source file name and a source line number, and even though there are source files in the program that match the file name, none of those files has the specified line number. @end itemize Locations may be specified using three different formats: linespec locations, explicit locations, or address locations. The following subsections describe these formats. @menu * Linespec Locations:: Linespec locations * Explicit Locations:: Explicit locations * Address Locations:: Address locations @end menu ---------------------------------------------------------------------- diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 5f09f3a..3395735 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -9056,73 +9056,67 @@ @node Location Specifications @section Location Specifications @cindex specifying location -@cindex location spec @cindex locspec @cindex source location @cindex code location +@cindex location spec Several @value{GDBN} commands accept arguments that specify a location or locations of your program's code. Since @value{GDBN} is a source-level debugger, a location specification usually indicates some -line in the source code, but it can also indicate a function name, an -address, a label, and more. +line in some source file, but it can also do that indirectly, by +specifying a function name, an address, a label, etc. The different +forms of specifying a location that @value{GDBN} recognizes are +collectively known as forms of @dfn{location specification}, or +@dfn{location spec}. This section documents the forms of specifying +locations that @value{GDBN} recognizes. + +@cindex location resolution +@cindex resolution of location spec +When you specify a location, @value{GDBN} needs to find the place in +your program, known as @dfn{code location}, that corresponds to the +given location spec. We call this process of finding actual code +locations corresponding to a location spec @dfn{location resolution}. A concrete code location in your program is uniquely identifiable by a -set of logical attributes. A line number, the source file the line -belongs to, the fully-qualified and prototyped function it is defined -in, and an instruction address. Because each inferior has its own -address space, also an inferior number. The source file attribute has -as many directory components as possible, retrieved from the debug -information, and in absolute form if possible, but it may also be in -relative form. - -On the other hand, a @dfn{location specification} (a.k.a.@: -@dfn{location spec}) is a way to find or refer to the concrete code -locations in the program. A location spec serves as a blueprint, and -@value{GDBN} resolves the spec to actual code locations in your -program by using the source and debug information. - -The location spec may be incomplete, and @value{GDBN} will do its best -to find all the locations in the program that match it. - -For example, a location spec may just indicate a line number and a -source filename with no directory components, or even not specify a -filename at all, just a line number. To differentiate between files -with the same base name, the spec may prepend as many directories as -is necessary to uniquely identify the desired file. - -Or, the spec may indicate a simple function name instead of a -fully-qualified and prototyped function name (e.g., @code{func} -instead of @code{A::func(int)}). To differentiate between functions -with the same name, the spec may prepend as many class and namespace -names as is necessary to uniquely identify the desired function, -and/or it may specify the function parameters as well. In addition, -the spec may indicate that the specified function name should be -interpreted as a fully-qualified name. - -You may not have debug info for some of the instructions in the -program, so a resolved code location that itself points to such code -will be incomplete and be missing some attributes, such as the source -file and line number, and sometimes even function names. Such an -incomplete code location is only usable in contexts that work with -addresses and/or function names. Some commands can only work with -complete code locations. - -Here are examples of typical situations that result in a location spec -matching multiple concrete code locations in your program: +set of several attributes: its source line number, the name of its +source file, the fully-qualified and prototyped function in which it +is defined, and an instruction address. Because each inferior has its +own address space, the inferior number is also a necessary part of +these attributes. By contrast, location specs you type will many +times omit some of these attributes. For example, it is customary to +specify just the source line number to mean a line in the current +source file, or specify just the basename of the file, omitting its +directories. In other words, a location spec is usually incomplete, a +kind of blueprint, and @value{GDBN} needs to complete the missing +attributes by using the implied defaults, and by considering the +source code and the debug information available to it. This is what +location resolution is about. + +The resolution of an incomplete location spec can produce more than a +single code location, if the spec doesn't allow distinguishing between +them. Here are some examples of situations that result in a location +spec matching multiple code locations in your program: @itemize @bullet @item -The location spec specifies a function name, and multiple functions in -the program may have the same name. +The location spec specifies a function name, and there are several +functions in the program which have that name. (To distinguish +between them, you can specify a fully-qualified and prototyped +function name, such as @code{A::func(int)} instead of just +@code{func}.) @item -The location spec specifies a source file name, and multiple source -files in the program share the same name. +The location spec specifies a source file name, and there are several +source files in the program that share the same name, for example +several files with the same basename in different subdirectories. (To +distinguish between them, specify enough leading directories with the +file name.) @item For a C@t{++} constructor, the @value{NGCC} compiler generates several -instances of the function body, used in different cases. +instances of the function body, used in different cases, but their +source-level names are identical, unless you qualify them. @item For a C@t{++} template function, a given line in the function can @@ -9130,21 +9124,30 @@ @item For an inlined function, a given source line can correspond to several -places where that function is inlined. +actual code locations with that function's inlined code. @end itemize -And here are examples of typical situations that result in a location -spec matching no code locations in your program at all: +Resolution of a location spec can also fail to produce a complete code +location, or even fail to produce any code location. Here are some +examples of such situations: @itemize @bullet @item +Some parts of the program lack detailed enough debug info, so the +resolved code location lacks some attributes, like source file name +and line number, leaving just the instruction address and perhaps also +a function name. Such an incomplete code location is only usable in +contexts that work with addresses and/or function names. Some +commands can only work with complete code locations. + +@item The location spec specifies a function name, and there are no -functions in the program with that name, or they only exist in a +functions in the program by that name, or they only exist in a yet-unloaded shared library. @item The location spec specifies a source file name, and there are no -source files in the program with that name, or they only exist in a +source files in the program by that name, or they only exist in a yet-unloaded shared library. @item @@ -9154,16 +9157,9 @@ number. @end itemize -The act of finding all the actual code locations that match the user -input is called @dfn{resolving the location spec}. The code locations -that @value{GDBN} finds are the @dfn{resolved code locations}. - -If @value{GDBN} cannot find any code location that matches the user -input, it is said that @value{GDBN} could not resolve the location -spec. - Locations may be specified using three different formats: linespec -locations, explicit locations, or address locations. +locations, explicit locations, or address locations. The following +subsections describe these formats. @menu * Linespec Locations:: Linespec locations