From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 28564 invoked by alias); 21 Jun 2013 21:21:02 -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 28550 invoked by uid 89); 21 Jun 2013 21:21:02 -0000 X-Spam-SWARE-Status: No, score=-6.3 required=5.0 tests=AWL,BAYES_50,KHOP_THREADED,RCVD_IN_HOSTKARMA_W,RCVD_IN_HOSTKARMA_WL,RP_MATCHES_RCVD,SPF_HELO_PASS,SPF_PASS autolearn=ham version=3.3.1 Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Fri, 21 Jun 2013 21:20:58 +0000 Received: from int-mx02.intmail.prod.int.phx2.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id r5LLKtS5012607 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 21 Jun 2013 17:20:55 -0400 Received: from valrhona.uglyboxes.com (ovpn01.gateway.prod.ext.phx2.redhat.com [10.5.9.1]) by int-mx02.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id r5LLKrMe023327 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Fri, 21 Jun 2013 17:20:55 -0400 Message-ID: <51C4C3B5.2070603@redhat.com> Date: Fri, 21 Jun 2013 23:32:00 -0000 From: Keith Seitz User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130514 Thunderbird/17.0.6 MIME-Version: 1.0 To: Eli Zaretskii CC: gdb-patches@sourceware.org Subject: Re: [RFA 4/4 doc] Explicit locations References: <514B9EC2.5060502@redhat.com> <514BA08F.4010305@redhat.com> <83620j6a8i.fsf@gnu.org> <51C2349B.7080303@redhat.com> <83a9mjooql.fsf@gnu.org> In-Reply-To: <83a9mjooql.fsf@gnu.org> Content-Type: multipart/mixed; boundary="------------040200010504010500080203" X-Virus-Found: No X-SW-Source: 2013-06/txt/msg00626.txt.bz2 This is a multi-part message in MIME format. --------------040200010504010500080203 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Content-length: 28278 On 06/21/2013 01:24 AM, Eli Zaretskii wrote: >> I've made an attempt at this. It probably needs a little more work, >> though, and the eyes of an outsider. > > It looks fine to me. Thank you. >> +#define LOCATION_HELP_STRING \ >> +"Linespecs are a colon-separated list of location parameters, such as\n\ > > "Linespecs are colon-separated lists", in plural. Done. [Grr. *How* on earth did I do that?] >> +Address locations begin with \"*\" and specify an exact address in the.\n\ > ^ > That period should be removed. Fixed. >> +program. Example: To specify the fourth byte past the start function\n\ >> +\"main\",use \"*main + 4\".\n\ > ^ > Space before the comma here. Fixed. >> -LOCATION may be a line number, function name, or \"*\" and an address.\n\ >> -If a line number is specified, break at start of code for that line.\n\ >> -If a function is specified, break at start of code for that function.\n\ >> -If an address is specified, break at that exact address.\n\ >> +LOCATION may be a linespec, address, or explicit location.\n\ >> +\n" LOCATION_HELP_STRING "\n\ >> With no LOCATION, uses current execution address of the selected\n\ >> stack frame. This is useful for breaking on return to a stack frame.\n\ >> \n\ > > I would move the "With no LOCATION ..." part before > LOCATION_HELP_STRING, since the latter is long. You can add > "as described below" to the preceding sentence, to make the reference > more explicit. That's a good idea. In fact, I also thought it best to leave this verbosity until after the other parameters are explained, too. All instances changed. >> +Locations may be specified using three different formats, >> +linespec locations, explicit locations, or address locations. > > I would put a colon after "Different formats", not a comma. Done. >> +sources. In these cases, explicit locations point to the source >> +line you meant more accurately and unequivocally. Also, using > ^^^^^^^^^^^^^ > I would use "unambiguously" here. Done. >> +For example, the linespec ``foo:bar'' may refer to a function ``bar'' >> +defined in the file named ``foo'' or the label ``bar'' in a function >> +named ``foo''. @value{GDBN} must search either the file system or > > The markup here is incorrect. Drop the quotes, and use @file for file > names, @code for functions and labels, and @samp for everything else, > like @samp{foo:bar}. Fixed. > I would use a more explicit > > @item -source @var{filename} You know, now that you mention it, it's practically obvious! Fixed. >> +to uniquely identify the desired file, e.g., ``foo/bar/baz.c''. Otherwise > ^^^^^^^^^^^^^^^^^ > Drop the quotes and use @file markup for file names. Fixed. > >> @smallexample >> -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] >> [ -c @var{condition} ] [ -i @var{ignore-count} ] >> - [ -p @var{thread-id} ] [ @var{location} ] >> + [ -p @var{thread-id} ] @var{location} > > Is LOCATION no longer an optional parameter for -break-insert? Ha ha. I don't know how that happened, but, yes, you are correct. LOCATION is still optional. For the record, I'm reposting the whole patch. Thanks a million for the review! Keith ChangeLog 2013-06-21 Keith Seitz * NEWS: Mention explicit locations. * breakpoint.c [LOCATION_HELP_STRING]: New macro. [BREAK_ARGS_HELP]: Use LOCATION_HELP_STRING. (_initialize_breakpoint): Update documentation for "clear", "break", "trace", "strace", "ftrace", and "dprintf". doc/ChangeLog 2013-06-21 Keith Seitz * gdb.texinfo (Thread-Specific Breakpoints): Use "location(s)" instead of "linespec(s)". (Printing Source Lines): Likewise. (Specifying a Location): Rewrite. Add explanations for each location type. (Source and Machine Code): Use "location(s)" instead of "linespec(s)". (C Preprocessor Macros): Likewise. (Create and Delete Tracepoints): Likewise. (Extensions for Ada Tasks): Likewise. (Continuing at a Different Address): Remove "linespec" examples. Add reference to "Specify a Location" (The -break-insert Command): Rewrite. Add anchor. Add reference to appropriate manual section discussing locations. (The -dprintf-insert Command): Refer to -break-insert for specification of `location'. testsuite/ChangeLog 2013-06-21 Keith Seitz * gdb.base/help.exp: Update help_breakpoint_text. diff --git a/gdb/NEWS b/gdb/NEWS index ed1c32f..23f9a8b 100644 --- a/gdb/NEWS +++ b/gdb/NEWS @@ -181,6 +181,10 @@ Tilera TILE-Gx GNU/Linux tilegx*-*-linux * 'info proc' now works on some core files. +* GDB now allows users to specify explicit locations, bypassing + the linespec parser. This feature is also available to GDB/MI + clients. + * Python scripting ** Vectors can be created with gdb.Type.vector. diff --git a/gdb/breakpoint.c b/gdb/breakpoint.c index d7486e3..88a5024 100644 --- a/gdb/breakpoint.c +++ b/gdb/breakpoint.c @@ -15842,25 +15842,44 @@ all_tracepoints (void) } +/* This help string is used to consolidate all the help string for specifying + locations used by several commands. */ +#define LOCATION_HELP_STRING \ +"Linespecs are colon-separated lists of location parameters, such as\n\ +source filename, function name, label name, and line number.\n\ +Example: To specify the start of a label named \"the_top\" in the\n\ +function \"fact\" in the file \"factorial.c\", use\n\ +\"factorial.c:fact:the_top\".\n\ +\n\ +Address locations begin with \"*\" and specify an exact address in the\n\ +program. Example: To specify the fourth byte past the start function\n\ +\"main\", use \"*main + 4\".\n\ +\n\ +Explicit locations are similar to linespecs but use an option/argument\n\ +syntax to specify location parameters.\n\ +Example: To specify the start of the label named \"the_top\" in the\n\ +function \"fact\" in the file \"factorial.c\", use \"-source factorial.c\n\ +-function fact -label the_top\".\n" + /* This help string is used for the break, hbreak, tbreak and thbreak commands. It is defined as a macro to prevent duplication. COMMAND should be a string constant containing the name of the command. */ + #define BREAK_ARGS_HELP(command) \ command" [PROBE_MODIFIER] [LOCATION] [thread THREADNUM] [if CONDITION]\n\ PROBE_MODIFIER shall be present if the command is to be placed in a\n\ probe point. Accepted values are `-probe' (for a generic, automatically\n\ guessed probe type) or `-probe-stap' (for a SystemTap probe).\n\ -LOCATION may be a line number, function name, or \"*\" and an address.\n\ -If a line number is specified, break at start of code for that line.\n\ -If a function is specified, break at start of code for that function.\n\ -If an address is specified, break at that exact address.\n\ +LOCATION may be a linespec, address, or explicit location as described\n\ +below.\n\ +\n\ With no LOCATION, uses current execution address of the selected\n\ stack frame. This is useful for breaking on return to a stack frame.\n\ \n\ THREADNUM is the number from \"info threads\".\n\ CONDITION is a boolean expression.\n\ -\n\ +\n" LOCATION_HELP_STRING "\n\ Multiple breakpoints at one place are permitted, and useful if their\n\ conditions are different.\n\ \n\ @@ -16380,20 +16399,17 @@ This command may be abbreviated \"delete\"."), &deletelist); add_com ("clear", class_breakpoint, clear_command, _("\ -Clear breakpoint at specified line or function.\n\ -Argument may be line number, function name, or \"*\" and an address.\n\ -If line number is specified, all breakpoints in that line are cleared.\n\ -If function is specified, breakpoints at beginning of function are cleared.\n\ -If an address is specified, breakpoints at that address are cleared.\n\ +Clear breakpoint at specified location.\n\ +Argument may be a linespec, explicit, or address location as described below.\n\ \n\ With no argument, clears all breakpoints in the line that the selected frame\n\ -is executing in.\n\ -\n\ +is executing in.\n" +"\n" LOCATION_HELP_STRING "\n\ See also the \"delete\" command which clears breakpoints by number.")); add_com_alias ("cl", "clear", class_breakpoint, 1); c = add_com ("break", class_breakpoint, break_command, _("\ -Set breakpoint at specified line or function.\n" +Set breakpoint at specified location.\n" BREAK_ARGS_HELP ("break"))); set_cmd_completer (c, location_completer); @@ -16586,7 +16602,7 @@ hardware.)"), /* Tracepoint manipulation commands. */ c = add_com ("trace", class_breakpoint, trace_command, _("\ -Set a tracepoint at specified line or function.\n\ +Set a tracepoint at specified location.\n\ \n" BREAK_ARGS_HELP ("trace") "\n\ Do \"help tracepoints\" for info on other tracepoint commands.")); @@ -16598,31 +16614,27 @@ Do \"help tracepoints\" for info on other tracepoint commands.")); add_com_alias ("trac", "trace", class_alias, 1); c = add_com ("ftrace", class_breakpoint, ftrace_command, _("\ -Set a fast tracepoint at specified line or function.\n\ +Set a fast tracepoint at specified location.\n\ \n" BREAK_ARGS_HELP ("ftrace") "\n\ Do \"help tracepoints\" for info on other tracepoint commands.")); set_cmd_completer (c, location_completer); c = add_com ("strace", class_breakpoint, strace_command, _("\ -Set a static tracepoint at specified line, function or marker.\n\ +Set a static tracepoint at location or marker.\n\ \n\ strace [LOCATION] [if CONDITION]\n\ -LOCATION may be a line number, function name, \"*\" and an address,\n\ -or -m MARKER_ID.\n\ -If a line number is specified, probe the marker at start of code\n\ -for that line. If a function is specified, probe the marker at start\n\ -of code for that function. If an address is specified, probe the marker\n\ -at that exact address. If a marker id is specified, probe the marker\n\ -with that name. With no LOCATION, uses current execution address of\n\ -the selected stack frame.\n\ +LOCATION may be a linespec, explicit, or address location (described below) \n\ +or -m MARKER_ID.\n\n\ +If a marker id is specified, probe the marker with that name. With\n\ +no LOCATION, uses current execution address of the selected stack frame.\n\ Static tracepoints accept an extra collect action -- ``collect $_sdata''.\n\ This collects arbitrary user data passed in the probe point call to the\n\ tracing library. You can inspect it when analyzing the trace buffer,\n\ by printing the $_sdata variable like any other convenience variable.\n\ \n\ CONDITION is a boolean expression.\n\ -\n\ +\n" LOCATION_HELP_STRING "\n\ Multiple tracepoints at one place are permitted, and useful if their\n\ conditions are different.\n\ \n\ @@ -16777,11 +16789,10 @@ an instruction at any address within the [START-LOCATION, END-LOCATION]\n\ range (including START-LOCATION and END-LOCATION).")); c = add_com ("dprintf", class_breakpoint, dprintf_command, _("\ -Set a dynamic printf at specified line or function.\n\ +Set a dynamic printf at specified location.\n\ dprintf location,format string,arg1,arg2,...\n\ -location may be a line number, function name, or \"*\" and an address.\n\ -If a line number is specified, break at start of code for that line.\n\ -If a function is specified, break at start of code for that function.")); +location may be a linespec, explicit, or address location.\n" +"\n" LOCATION_HELP_STRING)); set_cmd_completer (c, location_completer); add_setshow_enum_cmd ("dprintf-style", class_support, diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index d25cdae..736faa8 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -5838,9 +5838,9 @@ breakpoints on all threads, or on a particular thread. @cindex breakpoints and threads @cindex thread breakpoints @kindex break @dots{} thread @var{threadno} -@item break @var{linespec} thread @var{threadno} -@itemx break @var{linespec} thread @var{threadno} if @dots{} -@var{linespec} specifies source lines; there are several ways of +@item break @var{location} thread @var{threadno} +@itemx break @var{location} thread @var{threadno} 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. @@ -7166,21 +7166,21 @@ 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{linespecs}. Linespecs specify source lines; there are several ways +@dfn{locations}. Locations specify source lines; there are several ways of writing them (@pxref{Specify Location}), 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{linespec} -Print lines centered around the line specified by @var{linespec}. +@item list @var{location} +Print lines centered around the line specified by @var{location}. @item list @var{first},@var{last} Print lines from @var{first} to @var{last}. Both arguments are -linespecs. When a @code{list} command has two linespecs, and the -source file of the second linespec is omitted, this refers to -the same source file as the first linespec. +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. @item list ,@var{last} Print lines ending with @var{last}. @@ -7205,11 +7205,16 @@ As described in the preceding table. 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; -for that reason, locations are also known as @dfn{linespecs}. +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. -Here are all the different ways of specifying a code location that -@value{GDBN} understands: +@subsection Linespec Locations +@anchor{Linespec Locations} + +A @dfn{linespec} is a colon-separated list of source location parameters such +as file name, function name, etc. Here are all the different ways of +specifying a linespec: @table @code @item @var{linenum} @@ -7248,25 +7253,93 @@ function name to avoid ambiguity when there are identically named functions in different source files. @item @var{label} -Specifies the line at which the label named @var{label} appears. -@value{GDBN} searches for the label in the function corresponding to -the currently selected stack frame. If there is no current selected -stack frame (for instance, if the inferior is not running), then -@value{GDBN} will not search for a label. - -@item *@var{address} -Specifies the program address @var{address}. For line-oriented -commands, such as @code{list} and @code{edit}, this specifies a source -line that contains @var{address}. For @code{break} and other -breakpoint oriented commands, this can be used to set breakpoints in +Specifies the line at which the label named @var{label} appears +in the function corresponding to the currently selected stack frame. +If there is no current selected stack frame (for instance, if the inferior +is not running), then @value{GDBN} will not search for a label. + +@cindex breakpoint at static probe point +@item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name} +The @sc{gnu}/Linux tool @code{SystemTap} provides a way for +applications to embed static probes. @xref{Static Probe Points}, for more +information on finding and using static probes. This form of linespec +specifies the location of such a static probe. + +If @var{objfile} is given, only probes coming from that shared library +or executable matching @var{objfile} as a regular expression are considered. +If @var{provider} is given, then only probes from that provider are considered. +If several probes match the spec, @value{GDBN} will insert a breakpoint at +each one of those probes. +@end table + +@subsection Explicit Locations +@cindex explicit locations +@anchor{Explicit Locations} + +@dfn{Explict locations} allow the user to directly specify the source +location's parameters using option-value pairs. + +Explicit locations are useful when several functions, labels, or +file names have the same name (base name for files) in the program's +sources. In these cases, explicit locations point to the source +line you meant more accurately and unambiguously. Also, using +explicit locations might be faster in large programs. + +For example, the linespec @samp{foo:bar} may refer to a function @code{bar} +defined in the file named @file{foo} or the label @code{bar} in a function +named @code{foo}. @value{GDBN} must search either the file system or +the symbol table to know. + +The list of valid explicit location options is summarized in the +following table: + +@table @code +@item -source @var{filename} +The value specifies the source file name. To differentiate between +files with the same base name, prepend as many directories as is necessary +to uniquely identify the desired file, e.g., @file{foo/bar/baz.c}. Otherwise +@value{GDBN} will use the first file it finds with the given base +name. This option requires the use of either @code{-function} or @code{-line}. + +@item -function @var{function} +The value specifies the name of a function. Operations +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. + +@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 +selected stack frame. + +@item -line @var{number} +The value specifies a line offset for the location. The offset may either +be absolute (@code{-line 3}) or relative (@code{-line +3}), depending on +the command. When specified without any other options, the line offset is +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}. + +@subsection Address Locations +@cindex address locations +@anchor{Address Locations} + +@dfn{Address locations} indicate a specific program address. They have +the generalized form *@var{address}. + +For line-oriented commands, such as @code{list} and @code{edit}, this +specifies a source line that contains @var{address}. For @code{break} and +other breakpoint-oriented commands, this can be used to set breakpoints in parts of your program which do not have debugging information or source files. Here @var{address} may be any expression valid in the current working language (@pxref{Languages, working language}) that specifies a code address. In addition, as a convenience, @value{GDBN} extends the -semantics of expressions used in locations to cover the situations -that frequently happen during debugging. Here are the various forms +semantics of expressions used in locations to cover several situations +that frequently occur during debugging. Here are the various forms of @var{address}: @table @code @@ -7291,22 +7364,6 @@ specify the function unambiguously, e.g., if there are several functions with identical names in different source files. @end table -@cindex breakpoint at static probe point -@item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name} -The @sc{gnu}/Linux tool @code{SystemTap} provides a way for -applications to embed static probes. @xref{Static Probe Points}, for more -information on finding and using static probes. This form of linespec -specifies the location of such a static probe. - -If @var{objfile} is given, only probes coming from that shared library -or executable matching @var{objfile} as a regular expression are considered. -If @var{provider} is given, then only probes from that provider are considered. -If several probes match the spec, @value{GDBN} will insert a breakpoint at -each one of those probes. - -@end table - - @node Edit @section Editing Source Files @cindex editing source files @@ -7624,9 +7681,9 @@ well as hex. @table @code @kindex info line -@item info line @var{linespec} +@item info line @var{location} Print the starting and ending addresses of the compiled code for -source line @var{linespec}. You can specify source lines in any of +source line @var{location}. You can specify source lines in any of the ways documented in @ref{Specify Location}. @end table @@ -7644,7 +7701,7 @@ Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. @noindent @cindex code address and its source line We can also inquire (using @code{*@var{addr}} as the form for -@var{linespec}) what source line covers a particular address: +@var{location}) what source line covers a particular address: @smallexample (@value{GDBP}) info line *0x63ff Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. @@ -7754,7 +7811,7 @@ Dump of assembler code from 0x400281 to 0x40028b: End of assembler dump. @end smallexample -Addresses cannot be specified as a linespec (@pxref{Specify Location}). +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}. @@ -11093,9 +11150,9 @@ 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{linespec} +@item info macros @var{location} Show all macro definitions that are in effect at the location specified -by @var{linespec}, and describe the source location or compiler +by @var{location}, and describe the source location or compiler command-line where those definitions were established. @kindex macro define @@ -11400,12 +11457,11 @@ conditions and actions. @kindex trace @item trace @var{location} The @code{trace} command is very similar to the @code{break} command. -Its argument @var{location} can be a source line, a function name, or -an address in the target program. @xref{Specify Location}. 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 +Its argument @var{location} can be any valid location. +@xref{Specify Location}. 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 supports the @samp{InstallInTrace} feature (@pxref{install tracepoint in tracing}). If remote stub doesn't support the @samp{InstallInTrace} feature, all @@ -15240,14 +15296,14 @@ from the current task to the given task. #4 0x804aacc in un () at un.adb:5 @end smallexample -@item break @var{linespec} task @var{taskno} -@itemx break @var{linespec} task @var{taskno} if @dots{} +@item break @var{location} task @var{taskno} +@itemx break @var{location} 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}). -@var{linespec} specifies source lines, as described +@var{location} specifies source lines, as described in @ref{Specify Location}. Use the qualifier @samp{task @var{taskno}} with a breakpoint command @@ -16075,20 +16131,17 @@ an address of your own choosing, with the following commands: @table @code @kindex jump @kindex j @r{(@code{jump})} -@item jump @var{linespec} -@itemx j @var{linespec} -@itemx jump @var{location} +@item jump @var{location} @itemx j @var{location} -Resume execution at line @var{linespec} or at address given by -@var{location}. Execution stops again immediately if there is a -breakpoint there. @xref{Specify Location}, for a description of the -different forms of @var{linespec} and @var{location}. It is common +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}. 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 line @var{linespec} is in +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 @@ -29723,6 +29776,7 @@ N.A. @subheading The @code{-break-insert} Command @findex -break-insert +@anchor{-break-insert} @subsubheading Synopsis @@ -29730,21 +29784,41 @@ N.A. -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] [ -c @var{condition} ] [ -i @var{ignore-count} ] [ -p @var{thread-id} ] [ @var{location} ] + @end smallexample @noindent If specified, @var{location}, can be one of: -@itemize @bullet -@item function -@c @item +offset -@c @item -offset -@c @item linenum -@item filename:linenum -@item filename:function -@item *address -@end itemize +@table @var +@item linespec location +A linespec location. @xref{Linespec Locations}. +@item explicit location +An explicit location. @sc{gdb/mi} explicit locations are +analogous to the CLI's explicit locations using the option names +listed below. @xref{Explicit Locations}. + +@table @samp +@item -s @var{filename} +The source file name of the location. This option requires the use +of either @samp{-m} or @samp{-o}. + +@item -m @var{function} +The name of a function or method. + +@item -l @var{label} +The name of a label. + +@item -o @var{lineoffset} +An absolute or relative offset from the start of the location. +@end table + +@item address location +An address location, *@var{address}. @xref{Address Locations}. +@end table + +@noindent The possible optional parameters of this command are: @table @samp @@ -29836,17 +29910,8 @@ times="0"@}]@} @end smallexample @noindent -If specified, @var{location}, can be one of: - -@itemize @bullet -@item @var{function} -@c @item +offset -@c @item -offset -@c @item @var{linenum} -@item @var{filename}:@var{linenum} -@item @var{filename}:function -@item *@var{address} -@end itemize +If supplied, @var{location} may be specified the same way as for +the @code{-break-insert} command. @xref{-break-insert}. The possible optional parameters of this command are: diff --git a/gdb/testsuite/gdb.base/help.exp b/gdb/testsuite/gdb.base/help.exp index 86a02eb..2a9537e 100644 --- a/gdb/testsuite/gdb.base/help.exp +++ b/gdb/testsuite/gdb.base/help.exp @@ -58,7 +58,7 @@ test_class_help "user-defined" { } # Test help of an abbreviated command. "break" is picked at random. -set help_breakpoint_text "Set breakpoint at specified line or function\..*" +set help_breakpoint_text "Set breakpoint at specified location\..*" # test help breakpoint "b" abbreviation gdb_test "help b" $help_breakpoint_text "help breakpoint \"b\" abbreviation" # test help breakpoint "br" abbreviation --------------040200010504010500080203 Content-Type: text/x-patch; name="explicit-doc.patch" Content-Transfer-Encoding: 7bit Content-Disposition: inline; filename="explicit-doc.patch" Content-length: 23579 diff --git a/gdb/NEWS b/gdb/NEWS index ed1c32f..23f9a8b 100644 --- a/gdb/NEWS +++ b/gdb/NEWS @@ -181,6 +181,10 @@ Tilera TILE-Gx GNU/Linux tilegx*-*-linux * 'info proc' now works on some core files. +* GDB now allows users to specify explicit locations, bypassing + the linespec parser. This feature is also available to GDB/MI + clients. + * Python scripting ** Vectors can be created with gdb.Type.vector. diff --git a/gdb/breakpoint.c b/gdb/breakpoint.c index d7486e3..88a5024 100644 --- a/gdb/breakpoint.c +++ b/gdb/breakpoint.c @@ -15842,25 +15842,44 @@ all_tracepoints (void) } +/* This help string is used to consolidate all the help string for specifying + locations used by several commands. */ +#define LOCATION_HELP_STRING \ +"Linespecs are colon-separated lists of location parameters, such as\n\ +source filename, function name, label name, and line number.\n\ +Example: To specify the start of a label named \"the_top\" in the\n\ +function \"fact\" in the file \"factorial.c\", use\n\ +\"factorial.c:fact:the_top\".\n\ +\n\ +Address locations begin with \"*\" and specify an exact address in the\n\ +program. Example: To specify the fourth byte past the start function\n\ +\"main\", use \"*main + 4\".\n\ +\n\ +Explicit locations are similar to linespecs but use an option/argument\n\ +syntax to specify location parameters.\n\ +Example: To specify the start of the label named \"the_top\" in the\n\ +function \"fact\" in the file \"factorial.c\", use \"-source factorial.c\n\ +-function fact -label the_top\".\n" + /* This help string is used for the break, hbreak, tbreak and thbreak commands. It is defined as a macro to prevent duplication. COMMAND should be a string constant containing the name of the command. */ + #define BREAK_ARGS_HELP(command) \ command" [PROBE_MODIFIER] [LOCATION] [thread THREADNUM] [if CONDITION]\n\ PROBE_MODIFIER shall be present if the command is to be placed in a\n\ probe point. Accepted values are `-probe' (for a generic, automatically\n\ guessed probe type) or `-probe-stap' (for a SystemTap probe).\n\ -LOCATION may be a line number, function name, or \"*\" and an address.\n\ -If a line number is specified, break at start of code for that line.\n\ -If a function is specified, break at start of code for that function.\n\ -If an address is specified, break at that exact address.\n\ +LOCATION may be a linespec, address, or explicit location as described\n\ +below.\n\ +\n\ With no LOCATION, uses current execution address of the selected\n\ stack frame. This is useful for breaking on return to a stack frame.\n\ \n\ THREADNUM is the number from \"info threads\".\n\ CONDITION is a boolean expression.\n\ -\n\ +\n" LOCATION_HELP_STRING "\n\ Multiple breakpoints at one place are permitted, and useful if their\n\ conditions are different.\n\ \n\ @@ -16380,20 +16399,17 @@ This command may be abbreviated \"delete\"."), &deletelist); add_com ("clear", class_breakpoint, clear_command, _("\ -Clear breakpoint at specified line or function.\n\ -Argument may be line number, function name, or \"*\" and an address.\n\ -If line number is specified, all breakpoints in that line are cleared.\n\ -If function is specified, breakpoints at beginning of function are cleared.\n\ -If an address is specified, breakpoints at that address are cleared.\n\ +Clear breakpoint at specified location.\n\ +Argument may be a linespec, explicit, or address location as described below.\n\ \n\ With no argument, clears all breakpoints in the line that the selected frame\n\ -is executing in.\n\ -\n\ +is executing in.\n" +"\n" LOCATION_HELP_STRING "\n\ See also the \"delete\" command which clears breakpoints by number.")); add_com_alias ("cl", "clear", class_breakpoint, 1); c = add_com ("break", class_breakpoint, break_command, _("\ -Set breakpoint at specified line or function.\n" +Set breakpoint at specified location.\n" BREAK_ARGS_HELP ("break"))); set_cmd_completer (c, location_completer); @@ -16586,7 +16602,7 @@ hardware.)"), /* Tracepoint manipulation commands. */ c = add_com ("trace", class_breakpoint, trace_command, _("\ -Set a tracepoint at specified line or function.\n\ +Set a tracepoint at specified location.\n\ \n" BREAK_ARGS_HELP ("trace") "\n\ Do \"help tracepoints\" for info on other tracepoint commands.")); @@ -16598,31 +16614,27 @@ Do \"help tracepoints\" for info on other tracepoint commands.")); add_com_alias ("trac", "trace", class_alias, 1); c = add_com ("ftrace", class_breakpoint, ftrace_command, _("\ -Set a fast tracepoint at specified line or function.\n\ +Set a fast tracepoint at specified location.\n\ \n" BREAK_ARGS_HELP ("ftrace") "\n\ Do \"help tracepoints\" for info on other tracepoint commands.")); set_cmd_completer (c, location_completer); c = add_com ("strace", class_breakpoint, strace_command, _("\ -Set a static tracepoint at specified line, function or marker.\n\ +Set a static tracepoint at location or marker.\n\ \n\ strace [LOCATION] [if CONDITION]\n\ -LOCATION may be a line number, function name, \"*\" and an address,\n\ -or -m MARKER_ID.\n\ -If a line number is specified, probe the marker at start of code\n\ -for that line. If a function is specified, probe the marker at start\n\ -of code for that function. If an address is specified, probe the marker\n\ -at that exact address. If a marker id is specified, probe the marker\n\ -with that name. With no LOCATION, uses current execution address of\n\ -the selected stack frame.\n\ +LOCATION may be a linespec, explicit, or address location (described below) \n\ +or -m MARKER_ID.\n\n\ +If a marker id is specified, probe the marker with that name. With\n\ +no LOCATION, uses current execution address of the selected stack frame.\n\ Static tracepoints accept an extra collect action -- ``collect $_sdata''.\n\ This collects arbitrary user data passed in the probe point call to the\n\ tracing library. You can inspect it when analyzing the trace buffer,\n\ by printing the $_sdata variable like any other convenience variable.\n\ \n\ CONDITION is a boolean expression.\n\ -\n\ +\n" LOCATION_HELP_STRING "\n\ Multiple tracepoints at one place are permitted, and useful if their\n\ conditions are different.\n\ \n\ @@ -16777,11 +16789,10 @@ an instruction at any address within the [START-LOCATION, END-LOCATION]\n\ range (including START-LOCATION and END-LOCATION).")); c = add_com ("dprintf", class_breakpoint, dprintf_command, _("\ -Set a dynamic printf at specified line or function.\n\ +Set a dynamic printf at specified location.\n\ dprintf location,format string,arg1,arg2,...\n\ -location may be a line number, function name, or \"*\" and an address.\n\ -If a line number is specified, break at start of code for that line.\n\ -If a function is specified, break at start of code for that function.")); +location may be a linespec, explicit, or address location.\n" +"\n" LOCATION_HELP_STRING)); set_cmd_completer (c, location_completer); add_setshow_enum_cmd ("dprintf-style", class_support, diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index d25cdae..736faa8 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -5838,9 +5838,9 @@ breakpoints on all threads, or on a particular thread. @cindex breakpoints and threads @cindex thread breakpoints @kindex break @dots{} thread @var{threadno} -@item break @var{linespec} thread @var{threadno} -@itemx break @var{linespec} thread @var{threadno} if @dots{} -@var{linespec} specifies source lines; there are several ways of +@item break @var{location} thread @var{threadno} +@itemx break @var{location} thread @var{threadno} 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. @@ -7166,21 +7166,21 @@ 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{linespecs}. Linespecs specify source lines; there are several ways +@dfn{locations}. Locations specify source lines; there are several ways of writing them (@pxref{Specify Location}), 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{linespec} -Print lines centered around the line specified by @var{linespec}. +@item list @var{location} +Print lines centered around the line specified by @var{location}. @item list @var{first},@var{last} Print lines from @var{first} to @var{last}. Both arguments are -linespecs. When a @code{list} command has two linespecs, and the -source file of the second linespec is omitted, this refers to -the same source file as the first linespec. +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. @item list ,@var{last} Print lines ending with @var{last}. @@ -7205,11 +7205,16 @@ As described in the preceding table. 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; -for that reason, locations are also known as @dfn{linespecs}. +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. -Here are all the different ways of specifying a code location that -@value{GDBN} understands: +@subsection Linespec Locations +@anchor{Linespec Locations} + +A @dfn{linespec} is a colon-separated list of source location parameters such +as file name, function name, etc. Here are all the different ways of +specifying a linespec: @table @code @item @var{linenum} @@ -7248,25 +7253,93 @@ function name to avoid ambiguity when there are identically named functions in different source files. @item @var{label} -Specifies the line at which the label named @var{label} appears. -@value{GDBN} searches for the label in the function corresponding to -the currently selected stack frame. If there is no current selected -stack frame (for instance, if the inferior is not running), then -@value{GDBN} will not search for a label. - -@item *@var{address} -Specifies the program address @var{address}. For line-oriented -commands, such as @code{list} and @code{edit}, this specifies a source -line that contains @var{address}. For @code{break} and other -breakpoint oriented commands, this can be used to set breakpoints in +Specifies the line at which the label named @var{label} appears +in the function corresponding to the currently selected stack frame. +If there is no current selected stack frame (for instance, if the inferior +is not running), then @value{GDBN} will not search for a label. + +@cindex breakpoint at static probe point +@item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name} +The @sc{gnu}/Linux tool @code{SystemTap} provides a way for +applications to embed static probes. @xref{Static Probe Points}, for more +information on finding and using static probes. This form of linespec +specifies the location of such a static probe. + +If @var{objfile} is given, only probes coming from that shared library +or executable matching @var{objfile} as a regular expression are considered. +If @var{provider} is given, then only probes from that provider are considered. +If several probes match the spec, @value{GDBN} will insert a breakpoint at +each one of those probes. +@end table + +@subsection Explicit Locations +@cindex explicit locations +@anchor{Explicit Locations} + +@dfn{Explict locations} allow the user to directly specify the source +location's parameters using option-value pairs. + +Explicit locations are useful when several functions, labels, or +file names have the same name (base name for files) in the program's +sources. In these cases, explicit locations point to the source +line you meant more accurately and unambiguously. Also, using +explicit locations might be faster in large programs. + +For example, the linespec @samp{foo:bar} may refer to a function @code{bar} +defined in the file named @file{foo} or the label @code{bar} in a function +named @code{foo}. @value{GDBN} must search either the file system or +the symbol table to know. + +The list of valid explicit location options is summarized in the +following table: + +@table @code +@item -source @var{filename} +The value specifies the source file name. To differentiate between +files with the same base name, prepend as many directories as is necessary +to uniquely identify the desired file, e.g., @file{foo/bar/baz.c}. Otherwise +@value{GDBN} will use the first file it finds with the given base +name. This option requires the use of either @code{-function} or @code{-line}. + +@item -function @var{function} +The value specifies the name of a function. Operations +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. + +@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 +selected stack frame. + +@item -line @var{number} +The value specifies a line offset for the location. The offset may either +be absolute (@code{-line 3}) or relative (@code{-line +3}), depending on +the command. When specified without any other options, the line offset is +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}. + +@subsection Address Locations +@cindex address locations +@anchor{Address Locations} + +@dfn{Address locations} indicate a specific program address. They have +the generalized form *@var{address}. + +For line-oriented commands, such as @code{list} and @code{edit}, this +specifies a source line that contains @var{address}. For @code{break} and +other breakpoint-oriented commands, this can be used to set breakpoints in parts of your program which do not have debugging information or source files. Here @var{address} may be any expression valid in the current working language (@pxref{Languages, working language}) that specifies a code address. In addition, as a convenience, @value{GDBN} extends the -semantics of expressions used in locations to cover the situations -that frequently happen during debugging. Here are the various forms +semantics of expressions used in locations to cover several situations +that frequently occur during debugging. Here are the various forms of @var{address}: @table @code @@ -7291,22 +7364,6 @@ specify the function unambiguously, e.g., if there are several functions with identical names in different source files. @end table -@cindex breakpoint at static probe point -@item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name} -The @sc{gnu}/Linux tool @code{SystemTap} provides a way for -applications to embed static probes. @xref{Static Probe Points}, for more -information on finding and using static probes. This form of linespec -specifies the location of such a static probe. - -If @var{objfile} is given, only probes coming from that shared library -or executable matching @var{objfile} as a regular expression are considered. -If @var{provider} is given, then only probes from that provider are considered. -If several probes match the spec, @value{GDBN} will insert a breakpoint at -each one of those probes. - -@end table - - @node Edit @section Editing Source Files @cindex editing source files @@ -7624,9 +7681,9 @@ well as hex. @table @code @kindex info line -@item info line @var{linespec} +@item info line @var{location} Print the starting and ending addresses of the compiled code for -source line @var{linespec}. You can specify source lines in any of +source line @var{location}. You can specify source lines in any of the ways documented in @ref{Specify Location}. @end table @@ -7644,7 +7701,7 @@ Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. @noindent @cindex code address and its source line We can also inquire (using @code{*@var{addr}} as the form for -@var{linespec}) what source line covers a particular address: +@var{location}) what source line covers a particular address: @smallexample (@value{GDBP}) info line *0x63ff Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. @@ -7754,7 +7811,7 @@ Dump of assembler code from 0x400281 to 0x40028b: End of assembler dump. @end smallexample -Addresses cannot be specified as a linespec (@pxref{Specify Location}). +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}. @@ -11093,9 +11150,9 @@ 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{linespec} +@item info macros @var{location} Show all macro definitions that are in effect at the location specified -by @var{linespec}, and describe the source location or compiler +by @var{location}, and describe the source location or compiler command-line where those definitions were established. @kindex macro define @@ -11400,12 +11457,11 @@ conditions and actions. @kindex trace @item trace @var{location} The @code{trace} command is very similar to the @code{break} command. -Its argument @var{location} can be a source line, a function name, or -an address in the target program. @xref{Specify Location}. 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 +Its argument @var{location} can be any valid location. +@xref{Specify Location}. 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 supports the @samp{InstallInTrace} feature (@pxref{install tracepoint in tracing}). If remote stub doesn't support the @samp{InstallInTrace} feature, all @@ -15240,14 +15296,14 @@ from the current task to the given task. #4 0x804aacc in un () at un.adb:5 @end smallexample -@item break @var{linespec} task @var{taskno} -@itemx break @var{linespec} task @var{taskno} if @dots{} +@item break @var{location} task @var{taskno} +@itemx break @var{location} 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}). -@var{linespec} specifies source lines, as described +@var{location} specifies source lines, as described in @ref{Specify Location}. Use the qualifier @samp{task @var{taskno}} with a breakpoint command @@ -16075,20 +16131,17 @@ an address of your own choosing, with the following commands: @table @code @kindex jump @kindex j @r{(@code{jump})} -@item jump @var{linespec} -@itemx j @var{linespec} -@itemx jump @var{location} +@item jump @var{location} @itemx j @var{location} -Resume execution at line @var{linespec} or at address given by -@var{location}. Execution stops again immediately if there is a -breakpoint there. @xref{Specify Location}, for a description of the -different forms of @var{linespec} and @var{location}. It is common +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}. 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 line @var{linespec} is in +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 @@ -29723,6 +29776,7 @@ N.A. @subheading The @code{-break-insert} Command @findex -break-insert +@anchor{-break-insert} @subsubheading Synopsis @@ -29730,21 +29784,41 @@ N.A. -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] [ -c @var{condition} ] [ -i @var{ignore-count} ] [ -p @var{thread-id} ] [ @var{location} ] + @end smallexample @noindent If specified, @var{location}, can be one of: -@itemize @bullet -@item function -@c @item +offset -@c @item -offset -@c @item linenum -@item filename:linenum -@item filename:function -@item *address -@end itemize +@table @var +@item linespec location +A linespec location. @xref{Linespec Locations}. +@item explicit location +An explicit location. @sc{gdb/mi} explicit locations are +analogous to the CLI's explicit locations using the option names +listed below. @xref{Explicit Locations}. + +@table @samp +@item -s @var{filename} +The source file name of the location. This option requires the use +of either @samp{-m} or @samp{-o}. + +@item -m @var{function} +The name of a function or method. + +@item -l @var{label} +The name of a label. + +@item -o @var{lineoffset} +An absolute or relative offset from the start of the location. +@end table + +@item address location +An address location, *@var{address}. @xref{Address Locations}. +@end table + +@noindent The possible optional parameters of this command are: @table @samp @@ -29836,17 +29910,8 @@ times="0"@}]@} @end smallexample @noindent -If specified, @var{location}, can be one of: - -@itemize @bullet -@item @var{function} -@c @item +offset -@c @item -offset -@c @item @var{linenum} -@item @var{filename}:@var{linenum} -@item @var{filename}:function -@item *@var{address} -@end itemize +If supplied, @var{location} may be specified the same way as for +the @code{-break-insert} command. @xref{-break-insert}. The possible optional parameters of this command are: diff --git a/gdb/testsuite/gdb.base/help.exp b/gdb/testsuite/gdb.base/help.exp index 86a02eb..2a9537e 100644 --- a/gdb/testsuite/gdb.base/help.exp +++ b/gdb/testsuite/gdb.base/help.exp @@ -58,7 +58,7 @@ test_class_help "user-defined" { } # Test help of an abbreviated command. "break" is picked at random. -set help_breakpoint_text "Set breakpoint at specified line or function\..*" +set help_breakpoint_text "Set breakpoint at specified location\..*" # test help breakpoint "b" abbreviation gdb_test "help b" $help_breakpoint_text "help breakpoint \"b\" abbreviation" # test help breakpoint "br" abbreviation --------------040200010504010500080203--