[RFA 3/3] NEWS and documentation for / (slash) command.

Philippe Waroquiers
2019-04-13T19:00:44Z

gdb/ChangeLog
2019-04-13 Philippe Waroquiers <philippe.waroquiers@skynet.be>

* NEWS: Mention new slash command.

gdb/doc/ChangeLog
2019-04-13 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 / command.
---
gdb/NEWS | 14 +++++
gdb/doc/gdb.texinfo | 132 ++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 146 insertions(+)

diff --git a/gdb/NEWS b/gdb/NEWS
index 5309a8f923..1ec0418881 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -27,6 +27,20 @@
'array_indexes', 'symbols', 'unions', 'deref_refs', 'actual_objects',
'static_members', 'max_elements', 'repeat_threshold', and 'format'.

+* New commands
+
+/SETTING... COMMAND
+ The / command temporarily changes some settings according to SETTING
+ to run COMMAND. After running COMMAND, the settings are reset to
+ the values they had before the execution.
+ For example, '/lc print somevar' temporarily
+ switches to the C language in order to print somevar.
+ '/r print somevariable' temporarily sets unlimited repeat value
+ to print somevariable. Settings can be combined: '/rlc print somevar'
+ will switch to the C language and print somevar with an unlimited
+ repeat value.
+ Use 'help /' to list all settings that are temporarily changeable.
+
*** Changes in GDB 8.3

* GDB and GDBserver now support access to additional registers on
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index f410d026b8..7521d40036 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -1493,6 +1493,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 behaviour of commands
* Completion:: Command completion
* Help:: How to ask @value{GDBN} for help
@end menu
@@ -1548,6 +1549,137 @@ 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 change default behaviour of commands
+@cindex change default settings
+
+Many commands change their behaviour according to command specific
+variables or settings, that can be changed interactively.
+For example, the @code{print} @pxref{Arguments} command will print arrays
+differently depending on various settings changeable by the commands
+@code{set print elements NUMBER-OF-ELEMENTS},
+@code{set print array-indexes}, @dots{}.
+
+These settings can be set 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,
+the following can be done:
+@smallexample
+(@value{GDBN}) set print elements 10
+print some_array
+$3 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@}
+@end smallexample
+
+The default value of 200 elements to print has been changed to 10
+by the above @code{set print elements 10} command. The value of 10
+becomes the new default. It this value of 10 is to be used only
+for printing @code{some_array}, then the command
+@code{set print elements 200} must be executed to set the default back
+to 200.
+
+@kindex slash command
+@kindex /
+@cindex Settings
+@cindex Temporarily change settings
+@noindent
+@code{/SETTING... COMMAND}: Temporarily change settings for only one command.
+
+The @code{/} (slash) command allows to temporarily change various
+settings to run a specific command. For example, the command
+@smallexample
+/a10e print some_array
+@end smallexample
+@noindent
+is equivalent to the following 5 commands:
+@smallexample
+set print array on
+set print elements 10
+print some_array
+set print elements 200
+set print array off
+@end smallexample
+
+Each temporarily changeable setting is identified by a sequence of
+one or more letters. The most frequently used settings are identified
+by a single lower case letter. Less frequently used settings are identified
+by one or more upper case letters, followed by a single lower case letter.
+
+For example, the setting @code{set print elements} is identified by
+the letter @code{e}. The setting @code{set backtrace past-entry} is
+identified by the letters @code{Be}.
+
+@noindent
+Three types of settings can be temporarily changed by the @code{/} command:
+
+@table @code
+@item Boolean settings
+A boolean setting is temporarily activated (set to @code{on}) by
+giving its sequence of letters. To temporarily deactivate (set to @code{off})
+a boolean setting, its sequence of letter must be prefixed by the
+exclamation mark character @code{!}.
+
+@item Unsigned integer settings
+An unsigned integer setting is temporarily changed by giving the desired
+numeric value followed by its sequence of letters. If no numeric value
+preceedes the setting, the setting is temporarily changed to unlimited.
+The value 0 also indicates to change the setting to unlimited.
+
+@item Enumeration settings
+An enumeration setting is temporarily changed by giving its sequence
+of letters followed by a single character designating the chosen
+enumeration value. For example, the letter @code{l} identifies
+the @code{set language} setting. Using @code{/lA print somevar}
+will temporarily change the language to Ada (identified by the letter
+@code{A}) to execute the command @code{print somevar}, while
+@code{/lf print somevar} will rather switch to fortran.
+
+@end table
+
+To change several settings for the same command, just append each
+desired setting once after each other. For example, @code{/lA10e}
+will temporarily change the language to Ada and set a limit of 10 elements
+to print for arrays and strings.
+
+The following table gives the list of settings that the @code{/} command
+can temporarily change. The first column gives the letter sequence
+identifying the setting corresponding to the command in the second column.
+The third column gives the type of the setting, and list the different
+possible values for the enumeration settings. Note that the below table
+is produced by the @code{help /} command.
+
+@smallexample
+@c In the 'doc' build directory, the following can be produced by:
+@c ../../gdb/gdb -q --nx -ex 'set width 80' -ex 'set height 0' -ex 'help /' -ex quit |
+@c sed -e '1,/The temporarily changeable settings are:/d' -e ':a;s/^\( *\) /@\1/;ta' -e 's/^/@exdent /'
+@c Maybe this could/should be automated by the doc Makefile ?
+@exdent /Be set backtrace past-entry Boolean on|off
+@exdent /Bl set backtrace limit Unsigned integer (0 means unlimited)
+@exdent /Bm set backtrace past-main Boolean on|off
+@exdent /Co set print object Boolean on|off
+@exdent /Cs set print static-members Boolean on|off
+@exdent /Cv set print vtbl Boolean on|off
+@exdent /Pa set print address Boolean on|off
+@exdent /Ps set print symbol Boolean on|off
+@exdent /Rf set print raw frame-arguments Boolean on|off
+@exdent /a set print array Boolean on|off
+@exdent /e set print elements Unsigned integer (0 means unlimited)
+@exdent /f[asn] set print frame-arguments Enum, a = all, s = scalars, n = none
+@exdent /i set print array-indexes Boolean on|off
+@exdent /l[aluAscCdfgmMOo] set language Enum, a = auto, l = local,
+@exdent @ u = unknown, A = ada, s = asm, c = c, C = c++,
+@exdent @ d = d, f = fortran, g = go, m = minimal,
+@exdent @ M = modula-2, O = objective-c, o = opencl
+@exdent /n set print null-stop Boolean on|off
+@exdent /p set print pretty Boolean on|off
+@exdent /r set print repeats Unsigned integer (0 means unlimited)
+@exdent /u set print union Boolean on|off
+@exdent /v set varsize-limit Unsigned integer (0 means unlimited)
+@end smallexample
+
@node Completion
@section Command Completion

--
2.20.1