From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wr1-f44.google.com (mail-wr1-f44.google.com [209.85.221.44]) by sourceware.org (Postfix) with ESMTPS id D0EB33856DD2 for ; Wed, 25 May 2022 19:31:32 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org D0EB33856DD2 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=palves.net Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gmail.com Received: by mail-wr1-f44.google.com with SMTP id k30so31446484wrd.5 for ; Wed, 25 May 2022 12:31:32 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:subject:date:message-id:mime-version :content-transfer-encoding; bh=13mVJrAAcnk9/4h273RxKWgfIYKfJTiph8a04f8+pd4=; b=0EyBNYKy9LGtPdvwJKf2F8jSYyJtKoh3cvYyx/YTPWeHAwxHljfDyCG5pxxhRujjTs FldDhxKXXRtDFAaBjdAnalGNAZBxcJ9gzKULmdQ4sNqTi3E6WDyJEXV1c7cj7TlgNCdJ 6Qja3Wh9jnM5GQscRrgG0lHjhM4RnfxZ76uaJHsVt2sBAn//I0ojotCK6WSZHaVZB4MY TU6RvcncOopAATu3sTsBKoDwC5G8XdnxNQ8HO8CpFsxckIHbFBBdN6WEq+7WYBpoomBW STLPWXj7YgQ+UODJ1glDiUu5fvSVp+M2zznSrYuXkM6HBmpvrS+4c8kkpUH4+sSkdYn0 okeg== X-Gm-Message-State: AOAM532qt/+SJu6NDJ9bJJHQ5/KL4o2xUqcyId87RaiRyNwRkiXEMsDv YP7ko7IHeQgDLx1crLTl9WHC+ZPyqS0= X-Google-Smtp-Source: ABdhPJw8NDZH/v+tGAmdcE0qTjMgMxHKADWmcNahuO3IHvAr0iqdKM7JlT6eKAi+u0xV+VZ5wPfhhA== X-Received: by 2002:a5d:4f08:0:b0:20f:c7dc:8477 with SMTP id c8-20020a5d4f08000000b0020fc7dc8477mr18780840wru.713.1653507089706; Wed, 25 May 2022 12:31:29 -0700 (PDT) Received: from localhost ([2001:8a0:f924:2600:209d:85e2:409e:8726]) by smtp.gmail.com with ESMTPSA id w5-20020a5d6085000000b0020cdcb0efa2sm2835135wrt.34.2022.05.25.12.31.27 for (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 25 May 2022 12:31:28 -0700 (PDT) From: Pedro Alves To: gdb-patches@sourceware.org Subject: [PATCH] gdb/manual: Introduce locspecs Date: Wed, 25 May 2022 20:31:26 +0100 Message-Id: <20220525193126.1613411-1-pedro@palves.net> X-Mailer: git-send-email 2.36.0 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-9.7 required=5.0 tests=BAYES_00, FREEMAIL_FORGED_FROMDOMAIN, FREEMAIL_FROM, GIT_PATCH_0, HEADER_FROM_DIFFERENT_DOMAINS, KAM_DMARC_STATUS, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2, SPF_HELO_NONE, 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, 25 May 2022 19:31:38 -0000 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." And then, such commands are documented as taking a "location" argument. For example, here's a representative subset: @item break @var{location} @item clear @var{location} @item until @var{location} @item list @var{location} @item edit @var{location} @itemx info line @var{location} @item info macros @var{location} @item trace @var{location} @item info scope @var{location} @item maint agent @r{[}-at @var{location}@r{,}@r{]} @var{expression} The issue here is that "location" isn't really correct for most of these commands. Instead, the "location" argument is really a placeholder that represent an umbrella term for all of the "linespecs", "explicit location", and "address location" input formats. GDB parses these and then finds the actual locations (plural) in the program that match. For example, a "location" specified like "-function func" will actually match all the locations in the program that correspond to the address/file/lineno of all the functions named "func" in all the loaded programs and shared libraries of all the inferiors. A "location" specified like "-label lab" matches all the addresses & source lines of where a C label name "lab" is defined. Etc. This means that several of the commands that claim they accept a "location", actually end up working with multiple locations, and the manual doesn't explain that all that well. In some cases, the command will work with all the matched locations. In other cases, the command aborts with an error if the location specification matches multiple locations in the program. In other cases, GDB just arbitrarily and silently picks whatever is the first location that matches (which sounds like should be improved). To clarify this, I propose we use the term "Location Specification", with shorthand "locspec", when we're talking about the user input, the argument or arguments that is/are passed to commands to instruct GDB how to find locations of interest. This is distinct from the actual locations in the program, which are what GDB finds based on the user-specified locspec. Then use "locspec" thoughout instead of "location" when we're talking about the user input. Thus, this commit does the following: - renames the "Specify Location" section of the manual to "Location Specifications". - It then introduces the term "Location Specification", with corresponding shorthand "locspec", as something distinct from an actual location in the program. It explains that a location specification may match multiple locations in the program. It gives examples of how that happens. Most examples were moved from the "Set Breaks" section, and a couple new ones that didn't exist yet were added. I think it is better to have these centralized in this "Location Specification" section, since all the other commands that accept a locspec have an xref that points there. - Goes through the manual, and where "@var{location}" was used for a command argument, updated it to say "@var{locspec}" instead. At the same time, tweaks the description of the affected commands to describe what happens when the locspec matches more than one location in the program. Most commands just did not say anything about that. One command -- "maint agent -at @var{location}" -- currently says it accepts a "location", suggesting it can accept address and explicit locations too, but that's incorrect. In reality, it only accepts linespecs, so this one is updated differently from the others. Change-Id: Ic42ad8565e79ca67bfebb22cbb4794ea816fd08b --- gdb/doc/gdb.texinfo | 372 ++++++++++++++++++++++++-------------------- gdb/doc/guile.texi | 2 +- gdb/doc/python.texi | 5 +- 3 files changed, 210 insertions(+), 169 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 68679982919..15175012ebb 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -2024,7 +2024,7 @@ func() func() (@value{GDBP}) p 'func< @end smallexample -When setting breakpoints however (@pxref{Specify Location}), you don't +When setting breakpoints however (@pxref{Location Specifications}), 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: @@ -4343,17 +4343,19 @@ Vars,, Convenience Variables}, for a discussion of what you can do with convenience variables. @table @code -@item break @var{location} -Set a breakpoint at the given @var{location}, which can specify a -function name, a line number, or an address of an instruction. -(@xref{Specify Location}, for a list of all the possible ways to -specify a @var{location}.) The breakpoint will stop your program just -before it executes any of the code in the specified @var{location}. +@item break @var{locspec} +Set a breakpoint at all the locations the given @var{locspec} matches. +@var{locspec} can specify a function name, a line number, an address +of an instruction, and more. @xref{Location Specifications}, for the +various forms of @var{locspec}. The breakpoint will stop your program +just before it executes any of the code at any of the breakpoint's +locations. -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{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of -that situation. +When using source languages that permit overloading of symbols, such +as C@t{++}, a function name may refer to more than one symbol, and +thus more than one place to break. @xref{Ambiguous +Expressions,,Ambiguous Expressions}, for a discussion of that +situation. It is also possible to insert a breakpoint that will stop the program only if a specific thread (@pxref{Thread-Specific Breakpoints}) @@ -4614,28 +4616,8 @@ the breakpoints are conditional, this is even useful @cindex multiple locations, breakpoints @cindex breakpoints, multiple locations -It is possible that a breakpoint corresponds to several locations -in your program. Examples of this situation are: - -@itemize @bullet -@item -Multiple functions in the program may have the same name. - -@item -For a C@t{++} constructor, the @value{NGCC} compiler generates several -instances of the function body, used in different cases. - -@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 places where that function is inlined. -@end itemize - -In all those cases, @value{GDBN} will insert a breakpoint at all -the relevant locations. +It is possible that a breakpoint corresponds to several locations in +your program. @xref{Location Specifications}, for examples. A breakpoint with multiple locations is displayed in the breakpoint table using several rows---one header row, followed by one row for @@ -4711,32 +4693,35 @@ differ from regular breakpoints. You can set conditions or commands, enable and disable them and perform other breakpoint operations. @value{GDBN} provides some additional commands for controlling what -happens when the @samp{break} command cannot resolve breakpoint -address specification to an address: +happens when the @samp{break} command cannot find any location that +matches the locspec (@pxref{Location Specifications}): @kindex set breakpoint pending @kindex show breakpoint pending @table @code @item set breakpoint pending auto -This is the default behavior. When @value{GDBN} cannot find the breakpoint -location, it queries you whether a pending breakpoint should be created. +This is the default behavior. When @value{GDBN} cannot find any +location that matches the locspec, it queries you whether a pending +breakpoint should be created. @item set breakpoint pending on -This indicates that an unrecognized breakpoint location should automatically -result in a pending breakpoint being created. +This indicates that when @value{GDBN} cannot find any location that +matches the locspec, it should create a pending breakpoint without +asking for confirmation. @item set breakpoint pending off -This indicates that pending breakpoints are not to be created. Any -unrecognized breakpoint location results in an error. This setting does -not affect any pending breakpoints previously created. +This indicates that pending breakpoints are not to be created. If +@value{GDBN} cannot find any location that matches the locspec, it +aborts the breakpoint creation with an error. This setting does not +affect any pending breakpoints previously created. @item show breakpoint pending Show the current behavior setting for creating pending breakpoints. @end table The settings above only affect the @code{break} command and its -variants. Once breakpoint is set, it will be automatically updated -as shared libraries are loaded and unloaded. +variants. Once a breakpoint is created, it will be automatically +updated as shared libraries are loaded and unloaded. @cindex automatic hardware breakpoints For some targets, @value{GDBN} can automatically decide if hardware or @@ -5455,10 +5440,10 @@ selected stack frame (@pxref{Selection, ,Selecting a Frame}). When the innermost frame is selected, this is a good way to delete a breakpoint where your program just stopped. -@item clear @var{location} -Delete any breakpoints set at the specified @var{location}. -@xref{Specify Location}, for the various forms of @var{location}; the -most useful ones are listed below: +@item clear @var{locspec} +Delete any breakpoints set at the locations that match @var{locspec}. +@xref{Location Specifications}, for the various forms of +@var{locspec}; the most useful ones are listed below: @table @code @item clear @var{function} @@ -5815,10 +5800,11 @@ everything without needing to communicate with @value{GDBN}. @table @code @kindex dprintf -@item dprintf @var{location},@var{template},@var{expression}[,@var{expression}@dots{}] -Whenever execution reaches @var{location}, print the values of one or -more @var{expressions} under the control of the string @var{template}. -To print several values, separate them with commas. +@item dprintf @var{locspec},@var{template},@var{expression}[,@var{expression}@dots{}] +Whenever execution reaches a location that matches @var{locspec}, +print the values of one or more @var{expressions} under the control of +the string @var{template}. To print several values, separate them +with commas. @item set dprintf-style @var{style} Set the dprintf output to be handled in one of several different @@ -6313,11 +6299,11 @@ statement---not in terms of the actual machine code. instruction stepping, and hence is slower than @code{until} with an argument. -@item until @var{location} -@itemx u @var{location} -Continue running your program until either the specified @var{location} is -reached, or the current stack frame returns. The location is any of -the forms described in @ref{Specify Location}. +@item until @var{locspec} +@itemx u @var{locspec} +Continue running your program until either a location that matches @var{locspec} is +reached, or the current stack frame returns. @var{locspec} is any of +the forms described in @ref{Location Specifications}. This form of the command uses temporary breakpoints, and hence is quicker than @code{until} without an argument. The specified location is actually reached only if it is in the current frame. This @@ -6338,11 +6324,11 @@ invocations have returned. @end smallexample -@kindex advance @var{location} -@item advance @var{location} -Continue running the program up to the given @var{location}. An argument is -required, which should be of one of the forms described in -@ref{Specify Location}. +@kindex advance @var{locspec} +@item advance @var{locspec} +Continue running the program up to the location that matches +@var{locspec}. An argument is required, which should be of one of the +forms described in @ref{Location Specifications}. Execution will also stop upon exit from the current stack frame. This command is similar to @code{until}, but @code{advance} will not skip over recursive function calls, and the target location doesn't @@ -6442,7 +6428,7 @@ A more flexible solution is to execute @kbd{skip boring}. This instructs @code{foo}. Functions may be skipped by providing either a function name, linespec -(@pxref{Specify Location}), regular expression that matches the function's +(@pxref{Location Specifications}), regular expression that matches the function's name, file name or a @code{glob}-style pattern that matches the file name. On Posix systems the form of the regular expression is @@ -6479,7 +6465,7 @@ over when stepping. @itemx -fu @var{linespec} Functions named by @var{linespec} or the function containing the line named by @var{linespec} will be skipped over when stepping. -@xref{Specify Location}. +@xref{Location Specifications}. @item -rfunction @var{regexp} @itemx -rfu @var{regexp} @@ -6512,7 +6498,7 @@ will be skipped. @item skip function @r{[}@var{linespec}@r{]} After running this command, the function named by @var{linespec} or the function containing the line named by @var{linespec} will be skipped over when -stepping. @xref{Specify Location}. +stepping. @xref{Location Specifications}. If you do not specify @var{linespec}, the function you're currently debugging will be skipped. @@ -7141,11 +7127,10 @@ breakpoints on all threads, or on a particular thread. @cindex breakpoints and threads @cindex thread breakpoints @kindex break @dots{} thread @var{thread-id} -@item break @var{location} thread @var{thread-id} -@itemx break @var{location} thread @var{thread-id} if @dots{} -@var{location} specifies source lines; there are several ways of -writing them (@pxref{Specify Location}), but the effect is always to -specify some source line. +@item break @var{locspec} thread @var{thread-id} +@itemx break @var{locspec} thread @var{thread-id} if @dots{} +@var{locspec} specifies a location or locations in your program's +code. @xref{Location Specifications}, for details. Use the qualifier @samp{thread @var{thread-id}} with a breakpoint command to specify that you only want @value{GDBN} to stop the program when a @@ -8945,7 +8930,7 @@ prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using @menu * List:: Printing source lines -* Specify Location:: How to specify code locations +* Location Specifications:: How to specify code locations * Edit:: Editing source files * Search:: Searching source files * Source Path:: Specifying source directories @@ -8961,7 +8946,7 @@ prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using To print lines from a source file, use the @code{list} command (abbreviated @code{l}). By default, ten lines are printed. There are several ways to specify what part of the file you want to -print; see @ref{Specify Location}, for the full list. +print; see @ref{Location Specifications}, for the full list. Here are the forms of the @code{list} command most commonly used: @@ -9009,25 +8994,33 @@ argument of @samp{-}; that argument is preserved in repetition so that each repetition moves up in the source file. In general, the @code{list} command expects you to supply zero, one or two -@dfn{locations}. Locations specify source lines; there are several ways -of writing them (@pxref{Specify Location}), but the effect is always +locspecs. The locspecs specify source lines; there are several ways +of writing them (@pxref{Location Specifications}), but the effect is always to specify some source line. Here is a complete description of the possible arguments for @code{list}: @table @code -@item list @var{location} -Print lines centered around the line specified by @var{location}. +@item list @var{locspec} +Print lines centered around the line or lines for the locations that +match @var{locspec}. @item list @var{first},@var{last} Print lines from @var{first} to @var{last}. Both arguments are -locations. When a @code{list} command has two locations, and the -source file of the second location is omitted, this refers to -the same source file as the first location. +locspecs. When a @code{list} command has two locspecs, and the source +file of the second locspec is omitted, this refers to the same source +file as the first locspec. If either @var{first} or @var{last} match +more than one location in the program, then the list command will +print the list of ambiguous locations and does not print any source +lines. @item list ,@var{last} Print lines ending with @var{last}. +Likewise, if @var{last} matches more than one location in the program, +then the list command will print the list of ambiguous locations and +does not print any source lines. + @item list @var{first}, Print lines starting with @var{first}. @@ -9041,17 +9034,50 @@ Print lines just before the lines last printed. As described in the preceding table. @end table -@node Specify Location -@section Specifying a Location +@node Location Specifications +@section Location Specifications @cindex specifying location @cindex location +@cindex locspec @cindex source location Several @value{GDBN} commands accept arguments that specify a location -of your program's code. Since @value{GDBN} is a source-level -debugger, a location usually specifies some line in the source code. -Locations may be specified using three different formats: -linespec locations, explicit locations, or address locations. +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. + +As shorthand, and to better distinguish from actual locations in the +program, a location specification is refered to as a @dfn{locspec} +throughout the manual. + +A locspec serves as a blueprint, and it may match more than one actual +location in your program. Examples of this situation are: + +@itemize @bullet +@item +The locspec specifies a function name, and multiple functions in the +program may have the same name. + +@item +The locspec specifies a file name, and multiple files in the program +share the same name. + +@item +For a C@t{++} constructor, the @value{NGCC} compiler generates several +instances of the function body, used in different cases. + +@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 +places where that function is inlined. +@end itemize + +Locations may be specified using three different formats: linespec +locations, explicit locations, or address locations. @menu * Linespec Locations:: Linespec locations @@ -9270,12 +9296,17 @@ Alternatively, there are several ways to specify what part of the file you want to print if you want to see other parts of the program: @table @code -@item edit @var{location} -Edit the source file specified by @code{location}. Editing starts at -that @var{location}, e.g., at the specified source line of the -specified file. @xref{Specify Location}, for all the possible forms -of the @var{location} argument; here are the forms of the @code{edit} -command most commonly used: +@item edit @var{locspec} +Edit the source file specified by @code{locspec}. Editing starts at +the specified location, e.g., at the specified source line of the +specified file. @xref{Location Specifications}, for all the possible +forms of the @var{locspec} argument. + +If @code{locspec} matches more than one location in your program, then +the command prints the list of locations and does not proceed with the +editing. + +Here are the forms of the @code{edit} command most commonly used: @table @code @item edit @var{number} @@ -9655,11 +9686,11 @@ well as hex. @table @code @kindex info line @item info line -@itemx info line @var{location} +@itemx info line @var{locspec} Print the starting and ending addresses of the compiled code for -source line @var{location}. You can specify source lines in any of -the ways documented in @ref{Specify Location}. With no @var{location} -information about the current source line is printed. +source lines that match @var{locspec}. You can specify source lines in any of +the ways documented in @ref{Location Specifications}. With no +@var{locspec}, information about the current source line is printed. @end table For example, we can use @code{info line} to discover the location of @@ -9675,7 +9706,7 @@ Line 895 of "builtin.c" starts at pc 0x634c and \ @noindent @cindex code address and its source line We can also inquire (using @code{*@var{addr}} as the form for -@var{location}) what source line covers a particular address: +@var{locspec}) what source line covers a particular address: @smallexample (@value{GDBP}) info line *0x63ff Line 926 of "builtin.c" starts at pc 0x63e4 and \ @@ -9883,10 +9914,10 @@ Dump of assembler code from 0x400281 to 0x40028b: End of assembler dump. @end smallexample -Addresses cannot be specified as a location (@pxref{Specify Location}). -So, for example, if you want to disassemble function @code{bar} -in file @file{foo.c}, you must type @samp{disassemble 'foo.c'::bar} -and not @samp{disassemble foo.c:bar}. +Addresses cannot be specified as a locspec (@pxref{Location +Specifications}). So, for example, if you want to disassemble +function @code{bar} in file @file{foo.c}, you must type +@samp{disassemble 'foo.c'::bar} and not @samp{disassemble foo.c:bar}. Some architectures have more than one commonly-used set of instruction mnemonics or other syntax. @@ -14172,10 +14203,11 @@ argument processing and the beginning of @var{macro} for non C-like macros where the macro may begin with a hyphen. @kindex info macros -@item info macros @var{location} -Show all macro definitions that are in effect at the location specified -by @var{location}, and describe the source location or compiler -command-line where those definitions were established. +@item info macros @var{locspec} +Show all macro definitions that are in effect at the first location in +your program that matches @var{locspec}, and describe the source +location or compiler command-line where those definitions were +established. @kindex macro define @cindex user-defined macros @@ -14477,10 +14509,10 @@ conditions and actions. @table @code @cindex set tracepoint @kindex trace -@item trace @var{location} +@item trace @var{locspec} The @code{trace} command is very similar to the @code{break} command. -Its argument @var{location} can be any valid location. -@xref{Specify Location}. The @code{trace} command defines a tracepoint, +Its argument @var{locspec} can be any valid location specification. +@xref{Location Specifications}. The @code{trace} command defines a tracepoint, which is a point in the target program where the debugger will briefly stop, collect some data, and then allow the program to continue. Setting a tracepoint or changing its actions takes effect immediately if the remote stub @@ -14516,14 +14548,14 @@ Here are some examples of using the @code{trace} command: @noindent You can abbreviate @code{trace} as @code{tr}. -@item trace @var{location} if @var{cond} +@item trace @var{locspec} if @var{cond} Set a tracepoint with condition @var{cond}; evaluate the expression @var{cond} each time the tracepoint is reached, and collect data only if the value is nonzero---that is, if @var{cond} evaluates as true. @xref{Tracepoint Conditions, ,Tracepoint Conditions}, for more information on tracepoint conditions. -@item ftrace @var{location} [ if @var{cond} ] +@item ftrace @var{locspec} [ if @var{cond} ] @cindex set fast tracepoint @cindex fast tracepoints, setting @kindex ftrace @@ -14555,20 +14587,21 @@ sudo sysctl -w vm.mmap_min_addr=32768 which sets the low address to 32K, which leaves plenty of room for trampolines. The minimum address should be set to a page boundary. -@item strace @var{location} [ if @var{cond} ] +@item strace [@var{locspec} | -m @var{marker}] [ if @var{cond} ] @cindex set static tracepoint @cindex static tracepoints, setting @cindex probe static tracepoint marker @kindex strace The @code{strace} command sets a static tracepoint. For targets that support it, setting a static tracepoint probes a static -instrumentation point, or marker, found at @var{location}. It may not -be possible to set a static tracepoint at the desired location, in -which case the command will exit with an explanatory message. +instrumentation point, or marker, found at the locations that match +@var{locspec}. It may not be possible to set a static tracepoint at +the desired location, in which case the command will exit with an +explanatory message. @value{GDBN} handles arguments to @code{strace} exactly as for @code{trace}, with the addition that the user can also specify -@code{-m @var{marker}} as @var{location}. This probes the marker +@code{-m @var{marker}} as location. This probes the marker identified by the @var{marker} string identifier. This identifier depends on the static tracepoint backend library your program is using. You can find all the marker identifiers in the @samp{ID} field @@ -17439,9 +17472,9 @@ peculiarities and holes to be aware of. @itemize @bullet @item -Linespecs (@pxref{Specify Location}) are never relative to the current -crate. Instead, they act as if there were a global namespace of -crates, somewhat similar to the way @code{extern crate} behaves. +Linespecs (@pxref{Location Specifications}) are never relative to the +current crate. Instead, they act as if there were a global namespace +of crates, somewhat similar to the way @code{extern crate} behaves. That is, if @value{GDBN} is stopped at a breakpoint in a function in crate @samp{A}, module @samp{B}, then @code{break B::f} will attempt @@ -18762,15 +18795,14 @@ information. Flags @code{-c} and @code{-s} cannot be used together. -@item break @var{location} task @var{taskno} -@itemx break @var{location} task @var{taskno} if @dots{} +@item break @var{locspec} task @var{taskno} +@itemx break @var{locspec} task @var{taskno} if @dots{} @cindex breakpoints and tasks, in Ada @cindex task breakpoints, in Ada @kindex break @dots{} task @var{taskno}@r{ (Ada)} These commands are like the @code{break @dots{} thread @dots{}} -command (@pxref{Thread Stops}). The -@var{location} argument specifies source lines, as described -in @ref{Specify Location}. +command (@pxref{Thread Stops}). @xref{Location Specifications}, for +the various forms of @var{locspec}. Use the qualifier @samp{task @var{taskno}} with a breakpoint command to specify that you only want @value{GDBN} to stop the program when a @@ -19531,12 +19563,13 @@ These commands can be used to enable or disable type printers. @kindex info scope @cindex local variables -@item info scope @var{location} +@item info scope @var{locspec} List all the variables local to a particular scope. This command -accepts a @var{location} argument---a function name, a source line, or -an address preceded by a @samp{*}, and prints all the variables local -to the scope defined by that location. (@xref{Specify Location}, for -details about supported forms of @var{location}.) For example: +accepts a location specification argument---a function name, a source +line, or an address preceded by a @samp{*}, and prints all the +variables local to the scope defined by the first location in your +program that matches @var{locspec}. (@xref{Location Specifications}, +for details about supported forms of @var{locspec}.) For example: @smallexample (@value{GDBP}) @b{info scope command_line_handler} @@ -20124,23 +20157,26 @@ an address of your own choosing, with the following commands: @table @code @kindex jump @kindex j @r{(@code{jump})} -@item jump @var{location} -@itemx j @var{location} -Resume execution at @var{location}. Execution stops again immediately -if there is a breakpoint there. @xref{Specify Location}, for a description -of the different forms of @var{location}. It is common -practice to use the @code{tbreak} command in conjunction with -@code{jump}. @xref{Set Breaks, ,Setting Breakpoints}. +@item jump @var{locspec} +@itemx j @var{locspec} +Resume execution at the location that matches @var{locspec}. +@xref{Location Specifications}, for a description of the different +forms of @var{locspec}. If @var{locspec} matches more than one +location, the command aborts before jumping to any location. +Execution stops again immediately if there is a breakpoint there. It +is common practice to use the @code{tbreak} command in conjunction +with @code{jump}. @xref{Set Breaks, ,Setting Breakpoints}. The @code{jump} command does not change the current stack frame, or the stack pointer, or the contents of any memory location or any -register other than the program counter. If @var{location} is in -a different function from the one currently executing, the results may -be bizarre if the two functions expect different patterns of arguments or -of local variables. For this reason, the @code{jump} command requests -confirmation if the specified line is not in the function currently -executing. However, even bizarre results are predictable if you are -well acquainted with the machine-language code of your program. +register other than the program counter. If @var{locspec} matches a +location in a different function from the one currently executing, the +results may be bizarre if the two functions expect different patterns +of arguments or of local variables. For this reason, the @code{jump} +command requests confirmation if the specified line is not in the +function currently executing. However, even bizarre results are +predictable if you are well acquainted with the machine-language code +of your program. @end table On many systems, you can get much the same effect as the @code{jump} @@ -25365,15 +25401,18 @@ use the @code{break-range} command. @table @code @kindex break-range -@item break-range @var{start-location}, @var{end-location} +@item break-range @var{start-locspec}, @var{end-locspec} Set a breakpoint for an address range given by -@var{start-location} and @var{end-location}, which can specify a function name, +@var{start-locspec} and @var{end-locspec}, which can specify a function name, a line number, an offset of lines from the current line or from the start -location, or an address of an instruction (see @ref{Specify Location}, -for a list of all the possible ways to specify a @var{location}.) +location, or an address of an instruction (see @ref{Location Specifications}, +for a list of all the possible ways to specify a locspec). +If either @var{start-locspec} or @var{end-locspec} match multiple +locations in the program, then the command aborts with an error +without creating a breakpoint. The breakpoint will stop execution of the inferior whenever it executes an instruction at any address within the specified range, -(including @var{start-location} and @var{end-location}.) +(including @var{start-locspec} and @var{end-locspec}.) @kindex set powerpc @item set powerpc soft-float @@ -31192,11 +31231,11 @@ N.A. @smallexample -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] [ --qualified ] [ -c @var{condition} ] [ --force-condition ] [ -i @var{ignore-count} ] - [ -p @var{thread-id} ] [ @var{location} ] + [ -p @var{thread-id} ] [ @var{locspec} ] @end smallexample @noindent -If specified, @var{location}, can be one of: +If specified, @var{locspec}, can be one of: @table @var @item linespec location @@ -31235,10 +31274,10 @@ Insert a temporary breakpoint. @item -h Insert a hardware breakpoint. @item -f -If @var{location} cannot be parsed (for example if it +If @var{locspec} cannot be parsed (for example if it refers to unknown files or functions), create a pending breakpoint. Without this flag, @value{GDBN} will report -an error, and won't create a breakpoint, if @var{location} +an error, and won't create a breakpoint, if @var{locspec} cannot be parsed. @item -d Create a disabled breakpoint. @@ -31320,12 +31359,12 @@ times="0"@}]@} @smallexample -dprintf-insert [ -t ] [ -f ] [ -d ] [ --qualified ] [ -c @var{condition} ] [--force-condition] [ -i @var{ignore-count} ] - [ -p @var{thread-id} ] [ @var{location} ] [ @var{format} ] + [ -p @var{thread-id} ] [ @var{locspec} ] [ @var{format} ] [ @var{argument} ] @end smallexample @noindent -If supplied, @var{location} and @code{--qualified} may be specified +If supplied, @var{locspec} and @code{--qualified} may be specified the same way as for the @code{-break-insert} command. @xref{-break-insert}. @@ -31335,10 +31374,10 @@ The possible optional parameters of this command are: @item -t Insert a temporary breakpoint. @item -f -If @var{location} cannot be parsed (for example, if it +If @var{locspec} cannot be parsed (for example, if it refers to unknown files or functions), create a pending breakpoint. Without this flag, @value{GDBN} will report -an error, and won't create a breakpoint, if @var{location} +an error, and won't create a breakpoint, if @var{locspec} cannot be parsed. @item -d Create a disabled breakpoint. @@ -32551,12 +32590,12 @@ fullname="/home/foo/bar/try.c",line="13",arch="i386:x86_64"@} @subsubheading Synopsis @smallexample - -exec-jump @var{location} + -exec-jump @var{locspec} @end smallexample Resumes execution of the inferior program at the location specified by -parameter. @xref{Specify Location}, for a description of the -different forms of @var{location}. +the parameter. @xref{Location Specifications}, for a description of +the different forms of @var{locspec}. @subsubheading @value{GDBN} Command @@ -32870,13 +32909,13 @@ fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"@} @subsubheading Synopsis @smallexample - -exec-until [ @var{location} ] + -exec-until [ @var{locspec} ] @end smallexample -Executes the inferior until the @var{location} specified in the -argument is reached. If there is no argument, the inferior executes -until a source line greater than the current one is reached. The -reason for stopping in this case will be @samp{location-reached}. +Executes the inferior until a location that matches @var{locspec} is +reached. If there is no argument, the inferior executes until a +source line greater than the current one is reached. The reason for +stopping in this case will be @samp{location-reached}. @subsubheading @value{GDBN} Command @@ -34935,7 +34974,7 @@ next trace frame that corresponds to a tracepoint at an address outside the specified range. Both bounds are considered to be inside the range. @item line -Line specification is required as parameter. @xref{Specify Location}. +Line specification is required as parameter. @xref{Location Specifications}. Finds next trace frame that corresponds to a tracepoint at the specified location. @@ -39438,8 +39477,8 @@ messages, see @ref{Debugging Output}.) @table @code @kindex maint agent @kindex maint agent-eval -@item maint agent @r{[}-at @var{location}@r{,}@r{]} @var{expression} -@itemx maint agent-eval @r{[}-at @var{location}@r{,}@r{]} @var{expression} +@item maint agent @r{[}-at @var{linespec}@r{,}@r{]} @var{expression} +@itemx maint agent-eval @r{[}-at @var{linespec}@r{,}@r{]} @var{expression} Translate the given @var{expression} into remote agent bytecodes. This command is useful for debugging the Agent Expression mechanism (@pxref{Agent Expressions}). The @samp{agent} version produces an @@ -39450,7 +39489,8 @@ globb} will include bytecodes to record four bytes of memory at each of the addresses of @code{globa} and @code{globb}, while discarding the result of the addition, while an evaluation expression will do the addition and return the sum. -If @code{-at} is given, generate remote agent bytecode for @var{location}. +If @code{-at} is given, generate remote agent bytecode for all +locations that match @var{linespec} (@pxref{Linespec Locations}). If not, generate remote agent bytecode for current frame PC address. @kindex maint agent-printf diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi index 3c517230929..63916eed181 100644 --- a/gdb/doc/guile.texi +++ b/gdb/doc/guile.texi @@ -1965,7 +1965,7 @@ This constant means that filename completion should be performed. @item COMPLETE_LOCATION This constant means that location completion should be done. -@xref{Specify Location}. +@xref{Location Specifications}. @item COMPLETE_COMMAND This constant means that completion should examine @value{GDBN} diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index cb5283e03c0..f933c7d30c9 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -577,7 +577,8 @@ either @code{None} or another tuple that contains all the locations that match the expression represented as @code{gdb.Symtab_and_line} objects (@pxref{Symbol Tables In Python}). If @var{expression} is provided, it is decoded the way that @value{GDBN}'s inbuilt -@code{break} or @code{edit} commands do (@pxref{Specify Location}). +@code{break} or @code{edit} commands do (@pxref{Location +Specifications}). @end defun @defun gdb.prompt_hook (current_prompt) @@ -4186,7 +4187,7 @@ This constant means that filename completion should be performed. @vindex COMPLETE_LOCATION @item gdb.COMPLETE_LOCATION This constant means that location completion should be done. -@xref{Specify Location}. +@xref{Location Specifications}. @vindex COMPLETE_COMMAND @item gdb.COMPLETE_COMMAND base-commit: fbcda577011d73fdcf1ebf86160b6fc8ddd95299 -- 2.36.0