[PATCH v3 9/9] Explicit locations: documentation updates
Doug Evans
xdje42@gmail.com
Sun Mar 1 21:25:00 GMT 2015
Keith Seitz <keiths@redhat.com> writes:
> This patch adds documentation for explicit locations to both the
> User Manual and gdb's online help system.
>
> gdb/ChangeLog:
>
> * 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".
>
> gdb/doc/ChangeLog:
>
> * 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'.
>
> gdb/testsuite/ChangeLog:
>
> * gdb.base/help.exp: Update help_breakpoint_text.
Hi.
A few comments inline.
grep for ^====
> diff --git a/gdb/NEWS b/gdb/NEWS
> index 624f508..0b4581e 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -193,6 +193,10 @@ VAX running Ultrix vax-*-ultrix*
> -D data-directory
> This is an alias for the --data-directory option.
>
> +* GDB now allows users to specify explicit locations, bypassing
> + the linespec parser. This feature is also available to GDB/MI
> + clients.
> +
> * GDB supports printing and modifying of variable length automatic arrays
> as specified in ISO C99.
>
> diff --git a/gdb/breakpoint.c b/gdb/breakpoint.c
> index 046219b..a902b7b 100644
> --- a/gdb/breakpoint.c
> +++ b/gdb/breakpoint.c
> @@ -16114,25 +16114,44 @@ all_tracepoints (void)
> }
>
>
> +/* This help string is used to consolidate all the help string for specifying
> + locations used by several commands. */
====
A blank line here would help readability (for this reader).
> +#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\
> @@ -16627,20 +16646,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);
>
> @@ -16833,7 +16849,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."));
> @@ -16845,31 +16861,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\
> @@ -17021,11 +17033,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 d1f22de..bce6482 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -6016,9 +6016,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.
>
> @@ -7444,21 +7444,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}.
> @@ -7483,11 +7483,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}
> @@ -7526,25 +7531,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
====
Typo. Explicit.
> +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
> @@ -7569,22 +7642,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
> @@ -7902,9 +7959,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
>
> @@ -7922,7 +7979,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.
> @@ -8032,7 +8089,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}.
> @@ -11630,9 +11687,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
> @@ -11937,12 +11994,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
> @@ -15822,14 +15878,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}). The
> -@var{linespec} argument specifies source lines, as described
> +@var{location} argument specifies source lines, as described
> in @ref{Specify Location}.
>
> Use the qualifier @samp{task @var{taskno}} with a breakpoint command
> @@ -16757,20 +16813,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
> @@ -26474,6 +26527,7 @@ N.A.
>
> @subheading The @code{-break-insert} Command
> @findex -break-insert
> +@anchor{-break-insert}
>
> @subsubheading Synopsis
>
> @@ -26486,16 +26540,35 @@ N.A.
> @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 --source @var{filename}
> +The source file name of the location. This option requires the use
> +of either @samp{--function} or @samp{--line}.
> +
> +@item --function @var{function}
> +The name of a function or method.
> +
> +@item --label @var{label}
> +The name of a label.
> +
> +@item --line @var{lineoffset}
> +An absolute or relative line 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
> @@ -26587,17 +26660,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 565e339..22e6aa3 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
More information about the Gdb-patches
mailing list