[RFAv3,3/3] NEWS and documentation for leading-args related concept and commands.
Commit Message
gdb/ChangeLog
2019-09-15 Philippe Waroquiers <philippe.waroquiers@skynet.be>
* NEWS: Mention new leading-args commands. Mention change
to the alias command.
gdb/doc/ChangeLog
2019-09-15 Philippe Waroquiers <philippe.waroquiers@skynet.be>
* gdb.texinfo (Command leading args): New node documenting
'set|show leading-args' and 'set|show enable-leading-args'.
(Aliases): Document the new 'LEADING-ARGS...' option.
---
gdb/NEWS | 18 +++++++
gdb/doc/gdb.texinfo | 126 +++++++++++++++++++++++++++++++++++++++++++-
2 files changed, 143 insertions(+), 1 deletion(-)
@@ -84,6 +84,18 @@ w SETTING [VALUE] [-- COMMAND]
maint with SETTING [VALUE] [-- COMMAND]
Like "with", but works with "maintenance set" settings.
+set leading-args COMMAND [LEADING-ARGS...]
+show leading-args [COMMAND]
+set enable-leading-args [on|off]
+show enable-leading-args
+ GDB can now automatically prepend leading args to a command or alias.
+ This allows to set default arguments or options for the GDB commands
+ or define easier to use aliases.
+ For example, 'set leading-args backtrace -full -frame-arguments all'
+ ensures that backtrace will automatically use the options -full
+ -frame-arguments all, without having to retype them for each backtrace
+ command.
+
set may-call-functions [on|off]
show may-call-functions
This controls whether GDB will attempt to call functions in
@@ -162,6 +174,12 @@ info sources [-dirname | -basename] [--] [REGEXP]
allow to restrict matching respectively to the dirname and basename
parts of the files.
+alias [-a] [--] ALIAS = COMMAND [LEADING-ARGS...]
+ The alias command can now directly define leading-args
+ to prepend to arguments provided by the user on the command line.
+ See 'set leading-args COMMAND [LEADING-ARGS...]' for more
+ information about leading args concept.
+
show style
The "show style" and its subcommands are now styling
a style name in their output using its own style, to help
@@ -1564,6 +1564,7 @@ show you the alternatives available, if there is more than one possibility).
* Command Settings:: How to change default behavior of commands
* Completion:: Command completion
* Command Options:: Command options
+* Command leading args:: Automatically prepend arguments to commands and aliases
* Help:: How to ask @value{GDBN} for help
@end menu
@@ -1984,6 +1985,116 @@ uppercase.
(For more on using the @code{print} command, see @ref{Data, ,Examining
Data}.)
+@node Command leading args
+@section Automatically prepend arguments to commands and aliases
+
+You can tell @value{GDBN} to always add some default options or
+arguments to a command.
+
+@cindex command options, automatically prepend
+@cindex command, default arguments
+
+@table @code
+@kindex set leading-args
+@item set leading-args @var{command} [@var{leading-args@dots{}}]
+
+If you repetitively use the same arguments or options for a command,
+you can tell @value{GDBN} to automatically prepend these arguments
+or options to the arguments you type explicitely.
+
+For example, if you always want to have the command @code{thread apply all}
+working on the threads in ascending order and to continue in case it
+encounters an error, you can tell @value{GDBN} to automatically preprend
+the @code{-ascending} and @code{-c} options by using:
+
+@smallexample
+(@value{GDBP}) set leading-args thread apply all -ascending -c
+@end smallexample
+
+Once you have set these leading args, any time you type
+the @code{thread apply all} followed by @code{some arguments},
+@value{GDBN} will execute @code{thread apply all -ascending -c some arguments}.
+
+As usual, unambiguous abbreviations can be used for @var{command}
+and @var{leading-args}.
+
+Commands and their aliases do not share their leading args.
+So, for example, you can configure the commands @code{bt}, @code{where},
+@code{backtrace} and @code{info stack} to output different levels
+of information and define a new alias @code{bt_ALL} showing all possible
+information using:
+@smallexample
+(@value{GDBP}) set leading-args bt -entry-values no -frame-arguments none
+(@value{GDBP}) set leading-args where -entry-values no -frame-argu scalars
+(@value{GDBP}) set leading-args backtrace -entry-values no -frame-argu all
+(@value{GDBP}) set leading-args info stack -entry-val both -fr all
+(@value{GDBP}) alias bt_ALL = backtrace
+(@value{GDBP}) set leading-args bt_ALL -entry-values both -frame-arg all \
+-past-main -past-entry -full
+@end smallexample
+
+You can define an alias and specify its leading args in one command using the shorter to type:
+@smallexample
+(@value{GDBP}) alias bt_ALL = backtrace -entry-values both -frame-arg all \
+-past-main -past-entry -full
+@end smallexample
+(For more on using the @code{alias} command, see @ref{Aliases}.)
+
+Leading args are not limited to the arguments and options of @var{command},
+but can specify nested commands if @var{command} accepts such a nested command
+as argument.
+For example, the below defines @code{faalocalsoftype} that can be used to list
+the frames having locals of a certain type, together with the matching local
+vars:
+@smallexample
+(@value{GDBP}) alias faalocalsoftype = frame apply all info locals -q -t
+(@value{GDBP}) faalocalsoftype int
+#1 0x55554f5e in sleeper_or_burner (v=0xdf50) at sleepers.c:86
+i = 0
+ret = 21845
+@end smallexample
+
+This is also very useful to define an alias for a set of nested @code{with}
+commands to have a particular combination of temporary settings. For example,
+the below defines the alias @code{pp10} that pretty prints an expression
+argument, with a maximum of 10 elements if the expression is a string or
+an array:
+@smallexample
+(@value{GDBP}) alias pp10 = with print pretty -- with print elem 10 -- print
+@end smallexample
+
+
+Use @code{set leading-args @var{command}} (without giving @var{LEADING-ARGS})
+to clear the leading args of @var{command}.
+
+@item show leading-args [@var{command}]
+
+Use @code{show leading-args @var{command}} to show the current values of
+the leading args for @var{command}. For example:
+@smallexample
+(@value{GDBP}) show leading-args backtrace
+leading-args backtrace = -entry-values no -frame-arguments all
+(@value{GDBP}) show leading-args break
+leading-args break = <no leading args>
+@end smallexample
+
+To show all the commands and aliases that have some leading args configured,
+use the command
+@code{show leading-args} without giving a @var{command} argument.
+
+@item set enable-leading-args @r{[}on|off@r{]}
+@itemx show enable-leading-args
+By default, @value{GDBN} will use the configured leading args.
+This can be disabled using @code{set enable-leading-args off}.
+The leading args of all commands are not cleared, but
+will not be used till you do @code{set enable-leading-args on}.
+This can be useful in user defined commands to ensure only the specified
+set of options are used by a command launched by the user-defined command.
+You can also use this setting in the @code{with} command, to temporarily
+run a command without its possibly configured leading args.
+
+@end table
+
@node Help
@section Getting Help
@cindex online documentation
@@ -27117,7 +27228,7 @@ You can define a new alias with the @samp{alias} command.
@table @code
@kindex alias
-@item alias [-a] [--] @var{ALIAS} = @var{COMMAND}
+@item alias [-a] [--] @var{ALIAS} = @var{COMMAND} [LEADING-ARGS...]
@end table
@@ -27135,6 +27246,19 @@ lists displayed by the @samp{help} command.
The @samp{--} option specifies the end of options,
and is useful when @var{ALIAS} begins with a dash.
+You can specify @var{leading-args} for your alias.
+These @var{leading-args} will be automatically added before the alias
+arguments typed explicitely on the command line.
+
+For example, the below defines an alias @code{btfullall} that shows all local
+variables and all frame arguments:
+@smallexample
+(@value{GDBP}) alias btfullall = backtrace -full -frame-arguments all
+@end smallexample
+
+For more information about @var{leading-args}, see @ref{Command leading args,
+,Automatically prepend arguments to commands and aliases}
+
Here is a simple example showing how to make an abbreviation
of a command so that there is less to type.
Suppose you were tired of typing @samp{disas}, the current