diff options
author | Pedro Alves <palves@redhat.com> | 2019-07-03 13:34:20 +0100 |
---|---|---|
committer | Pedro Alves <palves@redhat.com> | 2019-07-03 13:35:45 +0100 |
commit | fdbc98707b0ab48fd8ca3ac37acefa120496baf6 (patch) | |
tree | 5894a73e3e58bcd087918752ce0e0790ec4c14bf /gdb/doc | |
parent | c6ac893109fdc2c3fce2b7457adccdc10f235354 (diff) | |
download | gdb-fdbc98707b0ab48fd8ca3ac37acefa120496baf6.zip gdb-fdbc98707b0ab48fd8ca3ac37acefa120496baf6.tar.gz gdb-fdbc98707b0ab48fd8ca3ac37acefa120496baf6.tar.bz2 |
Introduce the "with" command
( See original discussion and prototype here:
https://sourceware.org/ml/gdb-patches/2019-05/msg00570.html )
(gdb) help with
Temporarily set SETTING to VALUE, run COMMAND, and restore SETTING.
Usage: with SETTING [VALUE] [-- COMMAND]
Usage: w SETTING [VALUE] [-- COMMAND]
With no COMMAND, repeats the last executed command.
SETTING is any setting you can change with the "set" subcommands.
E.g.:
with language pascal -- print obj
with print elements unlimited -- print obj
As can be seen above, the "with" command is just like "set", but
instead of setting the setting permanently, it sets the setting, runs
a command and then restores the setting.
(gdb) p g_s
$1 = {a = 1, b = 2, c = 3}
(gdb) with language ada -- print g_s
$2 = (a => 1, b => 2, c => 3)
Warning: the current language does not match this frame.
(gdb) show language
The current source language is "auto; currently c".
(gdb) with print elements 100 -- with print object on -- print 1
$3 = 1
You can shorten things a bit though, as long as unambiguous. So this:
(gdb) with print elements 100 -- with print object off -- print 1
is the same as:
(gdb) w p el 100 -- w p o 0 -- p 1
Note that the patch adds a "w" alias for "with", as "w" is not
currently taken:
(gdb) w
Ambiguous command "w": watch, wh, whatis, where, while, while-stepping, winheight, ws.
Let me know if you'd prefer to reserve "w" for one of the other
commands above. IMHO, this command will end up being used frequently
enough that it deserves the "w" shorthand.
A nice feature is that this is fully integrated with TAB-completion:
(gdb) with p[TAB]
pagination print prompt python
(gdb) with print [TAB]
address max-depth static-members
array max-symbolic-offset symbol
array-indexes null-stop symbol-filename
asm-demangle object symbol-loading
demangle pascal_static-members thread-events
elements pretty type
entry-values raw union
frame-arguments repeats vtbl
inferior-events sevenbit-strings
(gdb) with print [TAB]
(gdb) with print elements unlimited -- thread apply all -[TAB]
-ascending -c -q -s
(gdb) with print elements unlimited -- print -[TAB]
-address -max-depth -repeats -vtbl
-array -null-stop -static-members
-array-indexes -object -symbol
-elements -pretty -union
The main advantage of this new command compared to command options,
like the new "print -OPT", is that this command works with any
setting, and, it works nicely when you want to override a setting
while running a user-defined command, like:
(gdb) with print pretty -- usercmd
The disadvantage is that it isn't as compact or easy to type. I think
of command options and this command as complementary. I think that
even with this new command, it makes sense to continue developing the
command options in the direction of exposing most-oft-used settings as
command options.
Inspired by Philippe's "/" command proposal, if no command is
specified, then the last command is re-invoked, under the overridden
setting:
(gdb) p g_s
$1 = {a = 1, b = 2, c = 3}
(gdb) with language ada
$2 = (a => 1, b => 2, c => 3)
Warning: the current language does not match this frame.
Note: "with" requires "--" to separate the setting from the command.
It might be possible to do without that, but, I haven't tried it yet,
and I think that this can go in without it. We can always downgrade
to making "--" optional if we manage to make it work.
On to the patch itself, the implementation of the command is simpler
than one might expect. A few details:
- I factored out a bit from pipe_command into repeat_previous
directly, because otherwise I'd need to copy&paste the same code and
same error message in the with command.
- The parse_cli_var_uinteger / parse_cli_var_zuinteger_unlimited /
do_set_command changes are necessary since we can now pass an empty
string as argument.
- do_show_command was split in two, as a FIXME comment suggests, but
for a different reason: we need to get a string version of a "set"
command's value, and we already had code for that in
do_show_command. That code is now factored out to the new
get_setshow_command_value_string function.
- There's a new "maint with" command added too:
(gdb) help maint with
Like "with", but works with "maintenance set" variables.
Usage: maintenance with SETTING [VALUE] [-- COMMAND]
With no COMMAND, repeats the last executed command.
SETTING is any setting you can change with the "maintenance set"
subcommands.
"with" and "maint with" share 99% of the implementation.
This might be useful on its own, but it's also useful for testing,
since with this, we can use the "maint set/show test-settings"
settings for exercising the "with" machinery with all the command
type variants (all enum var_types). This is done in the new
gdb/base/with.exp testcase.
The documentation bits are originally based on Philippe's docs for the
"/" command, hence the attribution in the ChangeLog.
gdb/ChangeLog:
2019-07-03 Pedro Alves <palves@redhat.com>
* NEWS (New commands): Mention "with" and "maint with".
* cli/cli-cmds.c (with_command_1, with_command_completer_1)
(with_command, with_command_completer): New.
(pipe_command): Adjust to new repeat_previous
interface.
(_initialize_cli_cmds): Install the "with" command and its "w"
alias.
* cli/cli-cmds.h (with_command_1, with_command_completer_1): New
declarations.
* cli/cli-setshow.c (parse_cli_var_uinteger)
(parse_cli_var_zuinteger_unlimited, do_set_command): Handle empty
argument strings for all var_types.
(get_setshow_command_value_string): New, factored out from ...
(do_show_command): ... this.
* cli/cli-setshow.h: Include <string>.
(get_setshow_command_value_string): Declare.
* command.h (repeat_previous): Now returns const char *. Adjust
comment.
* maint.c: Include "cli/cli-cmds.h".
(maintenance_with_cmd, maintenance_with_cmd_completer): New.
(_initialize_maint_cmds): Register the "maintenance with" command.
* top.c (repeat_previous): Move bits from pipe_command here:
Return the saved command line, if any; error out if there's no
command to relaunch.
gdb/doc/ChangeLog:
2019-07-03 Pedro Alves <palves@redhat.com>
Philippe Waroquiers <philippe.waroquiers@skynet.be>
* gdb.texinfo (Command Settings): New node documenting the general
concept of settings, how to change them, and the new "with"
command.
(Maintenance Commands): Document "maint with".
gdb/testsuite/ChangeLog:
2019-07-03 Pedro Alves <palves@redhat.com>
* gdb.base/with.c: New file.
* gdb.base/with.exp: New file.
Diffstat (limited to 'gdb/doc')
-rw-r--r-- | gdb/doc/ChangeLog | 8 | ||||
-rw-r--r-- | gdb/doc/gdb.texinfo | 100 |
2 files changed, 108 insertions, 0 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 1ebaae3..1025916 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,4 +1,12 @@ 2019-07-03 Pedro Alves <palves@redhat.com> + Philippe Waroquiers <philippe.waroquiers@skynet.be> + + * gdb.texinfo (Command Settings): New node documenting the general + concept of settings, how to change them, and the new "with" + command. + (Maintenance Commands): Document "maint with". + +2019-07-03 Pedro Alves <palves@redhat.com> * gdb.texinfo (Maintenance Commands): Document "maint set/show test-settings" instead of "maint test-settings set/show". diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index ca43166..299c4a1 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -1561,6 +1561,7 @@ show you the alternatives available, if there is more than one possibility). @menu * Command Syntax:: How to give commands to @value{GDBN} +* Command Settings:: How to change default behavior of commands * Completion:: Command completion * Command Options:: Command options * Help:: How to ask @value{GDBN} for help @@ -1617,6 +1618,98 @@ commands. This command accepts the current line, like @key{RET}, and then fetches the next line relative to the current line from the history for editing. + +@node Command Settings +@section Command Settings +@cindex default behavior of commands, changing +@cindex default settings, changing + +Many commands change their behavior according to command-specific +variables or settings. These settings can be changed with the +@code{set} subcommands. For example, the @code{print} command +(@pxref{Data, ,Examining Data}) prints arrays differently depending on +settings changeable with the commands @code{set print elements +NUMBER-OF-ELEMENTS} and @code{set print array-indexes}, among others. + +You can change these settings to your preference in the gdbinit files +loaded at @value{GDBN} startup. @xref{Startup}. + +The settings can also be changed interactively during the debugging +session. For example, to change the limit of array elements to print, +you can do the following: +@smallexample +(@value{GDBN}) set print elements 10 +(@value{GDBN}) print some_array +$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@} +@end smallexample + +The above @code{set print elements 10} command changes the number of +elements to print from the default of 200 to 10. If you only intend +this limit of 10 to be used for printing @code{some_array}, then you +must restore the limit back to 200, with @code{set print elements +200}. + +Some commands allow overriding settings with command options. For +example, the @code{print} command supports a number of options that +allow overriding relevant global print settings as set by @code{set +print} subcommands. @xref{print options}. The example above could be +rewritten as: +@smallexample +(@value{GDBN}) print -elements 10 -- some_array +$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@} +@end smallexample + +Alternatively, you can use the @code{with} command to change a setting +temporarily, for the duration of a command invocation. + +@table @code +@kindex with command +@kindex w @r{(@code{with})} +@cindex settings +@cindex temporarily change settings +@item with @var{setting} [@var{value}] [-- @var{command}] +@itemx w @var{setting} [@var{value}] [-- @var{command}] +Temporarily set @var{setting} to @var{value} for the duration of +@var{command}. + +@var{setting} is any setting you can change with the @code{set} +subcommands. @var{value} is the value to assign to @code{setting} +while running @code{command}. + +If no @var{command} is provided, the last command executed is +repeated. + +If a @var{command} is provided, it must be preceded by a double dash +(@code{--}) separator. This is required because some settings accept +free-form arguments, such as expressions or filenames. + +For example, the command +@smallexample +(@value{GDBN}) with print array on -- print some_array +@end smallexample +@noindent +is equivalent to the following 3 commands: +@smallexample +(@value{GDBN}) set print array on +(@value{GDBN}) print some_array +(@value{GDBN}) set print array off +@end smallexample + +The @code{with} command is particularly useful when you want to +override a setting while running user-defined commands, or commands +defined in Python or Guile. @xref{Extending GDB,, Extending GDB}. + +@smallexample +(@value{GDBN}) with print pretty on -- my_complex_command +@end smallexample + +To change several settings for the same command, you can nest +@code{with} commands. For example, @code{with language ada -- with +print elements 10} temporarily changes the language to Ada and sets a +limit of 10 elements to print for arrays and strings. + +@end table + @node Completion @section Command Completion @@ -37634,6 +37727,13 @@ support in the command options framework. These are representative commands for each @var{kind} of setting type @value{GDBN} supports. They are used by the testsuite for exercising the settings infrastructure. + +@kindex maint with +@item maint with @var{setting} [@var{value}] [-- @var{command}] +Like the @code{with} command, but works with @code{maintenance set} +variables. This is used by the testsuite to exercise the @code{with} +command's infrastructure. + @end table The following command is useful for non-interactive invocations of |