[RFAv3,6/6] NEWS and documentation for | (pipe) command.
Commit Message
gdb/ChangeLog
* NEWS: Mention new pipe command and new convenience variables.
gdb/doc/ChangeLog
* gdb.texinfo (Shell Commands): Document pipe command.
(Logging Output): Add a reference to pipe command.
(Convenience Variables): Document $_shell_exitcode and
$_shell_exitstatus.
---
gdb/NEWS | 32 ++++++++++++++--------
gdb/doc/gdb.texinfo | 67 +++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 88 insertions(+), 11 deletions(-)
Comments
> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Date: Sat, 4 May 2019 18:17:53 +0200
>
> gdb/ChangeLog
> * NEWS: Mention new pipe command and new convenience variables.
>
> gdb/doc/ChangeLog
> * gdb.texinfo (Shell Commands): Document pipe command.
> (Logging Output): Add a reference to pipe command.
> (Convenience Variables): Document $_shell_exitcode and
> $_shell_exitstatus.
The document part is OK.
Thanks.
> Date: Sat, 04 May 2019 19:26:10 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> CC: gdb-patches@sourceware.org
>
> The document part is OK.
^^^^^^^^
I meant "documentation", of course. Sorry.
On 5/4/19 5:17 PM, Philippe Waroquiers wrote:
> gdb/ChangeLog
> * NEWS: Mention new pipe command and new convenience variables.
>
> gdb/doc/ChangeLog
> * gdb.texinfo (Shell Commands): Document pipe command.
> (Logging Output): Add a reference to pipe command.
> (Convenience Variables): Document $_shell_exitcode and
> $_shell_exitstatus.
> ---
> gdb/NEWS | 32 ++++++++++++++--------
> gdb/doc/gdb.texinfo | 67 +++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 88 insertions(+), 11 deletions(-)
>
> diff --git a/gdb/NEWS b/gdb/NEWS
> index b21b2cbb47..570718ab5c 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -16,11 +16,23 @@
>
> * Support for Pointer Authentication on AArch64 Linux.
>
> -* Two new convernience functions $_cimag and $_creal that extract the
> +* Two new convenience functions $_cimag and $_creal that extract the
> imaginary and real parts respectively from complex numbers.
>
Please go ahead and push this bit in as an obvious fix.
> +* New built-in convenience variables $_shell_exitcode and $_shell_exitsignal
> + provide the exitcode or exit status of the shell commands launched by
> + GDB commands such as "shell", "pipe", "make".
> +
That "make" should be preceded by "and".
(I'll leave oxford comma or not to someone else. :-) )
> * New commands
>
> +pipe [COMMAND] | SHELL_COMMAND
> +| [COMMAND] | SHELL_COMMAND
> +pipe -d SEP COMMAND SEP SHELL_COMMAND
> +| -s DEP COMMAND SEP SHELL_COMMAND
s/DEP/SEP/
> + Executes COMMAND and sends its output to SHELL_COMMAND.
> + With no COMMAND, repeat the last executed command
> + and send its output to SHELL_COMMAND.
> +
> set print max-depth
> show print max-depth
> Allows deeply nested structures to be simplified when printing by
> @@ -28,16 +40,6 @@ show print max-depth
> The default max-depth is 20, but this can be set to unlimited to get
> the old behavior back.
>
> -* Python API
> -
> - ** The gdb.Value type has a new method 'format_string' which returns a
> - string representing the value. The formatting is controlled by the
> - optional keyword arguments: 'raw', 'pretty_arrays', 'pretty_structs',
> - 'array_indexes', 'symbols', 'unions', 'deref_refs', 'actual_objects',
> - 'static_members', 'max_elements', 'repeat_threshold', and 'format'.
> -
> -* New commands
> -
> set may-call-functions [on|off]
> show may-call-functions
> This controls whether GDB will attempt to call functions in
> @@ -48,6 +50,14 @@ show may-call-functions
> an error when a command (such as print expression) calls a function
> in the program.
>
> +* Python API
> +
> + ** The gdb.Value type has a new method 'format_string' which returns a
> + string representing the value. The formatting is controlled by the
> + optional keyword arguments: 'raw', 'pretty_arrays', 'pretty_structs',
> + 'array_indexes', 'symbols', 'unions', 'deref_refs', 'actual_objects',
> + 'static_members', 'max_elements', 'repeat_threshold', and 'format'.
> +
This also looks like a change that should go in separately, as
an obvious fix.
> *** 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 dd8ae91b93..36e3f8bc35 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -1454,6 +1454,56 @@ Execute the @code{make} program with the specified
> arguments. This is equivalent to @samp{shell make @var{make-args}}.
> @end table
>
> +@table @code
> +@kindex pipe
> +@kindex |
> +@cindex send the output of a gdb command to a shell command
> +@anchor{pipe}
> +@item pipe [@var{command}] | @var{shell_command}
> +@itemx | [@var{command}] | @var{shell_command}
> +@itemx pipe -d @var{sep} @var{command} @var{sep} @var{shell_command}
> +@itemx | -d @var{sep} @var{command} @var{sep} @var{shell_command}
> +Executes @var{command} and sends its output to @var{shell_command}.
> +Note that no space is needed around @code{|}.
> +If no @var{command} is provided, the last command executed is repeated.
> +
> +If the @var{command} contains a @code{|}, then the option @code{-d @var{sep}}
> +can be used to specify an alternate separator string @var{sep} that separates
> +the @var{command} from the @var{shell_command}.
> +
(spurious double space after "the" in the last line.)
Like in the "help" output, I think we can improve this a bit with a slight
copy/edit. "If contains |, then" suggests that you can only use -d
if the command contains "|", which is obviously not really the intention.
I'd suggest:
In case the @var{command} contains a @code{|}, the option @code{-d @var{sep}}
can be used to specify an alternate separator string @var{sep} that separates
the @var{command} from the @var{shell_command}.
"in case" suggests a precautionary measure.
> +Example:
> +@smallexample
> +@group
> +(gdb) pipe p full|wc
> + 5 17 81
> +(gdb) |p full|wc -l
> +5
> +@end group
> +@group
> +(gdb) p full
> +$4 = (black => 144,
> + red => 233,
> + green => 377,
> + blue => 610,
> + white => 987)
> +(gdb) ||grep red
> + red => 233,
I'd suggest printing "p full" before the pipe commands.
I read this top to bottom and it took me a second to realize
what "full" was. Maybe rename it to "var" or something like that,
while at it.
Use "$1" for value history number.
( I guess that's Ada syntax. I'd hazard a guess that a significant
number of GDB users don't know Ada. :-) )
> +@end group
> +@group
> +(gdb) | -d ! echo this contains a | char\n ! sed -e 's/|/PIPE/'
> +this contains a PIPE char
> +(gdb) | -d xxx echo this contains a | char!\n xxx sed -e 's/|/PIPE/'
> +this contains a PIPE char!
> +(gdb)
> +@end group
> +@end smallexample
> +@end table
> +
> +The convenience variables @code{$_shell_exitcode} and @code{$_shell_exitsignal}
> +can be used to examine the exit status of the last shell command launched
> +by @code{shell}, @code{make}, @code{pipe} and @code{|}.
> +@xref{Convenience Vars,, Convenience Variables}.
> +
> @node Logging Output
> @section Logging Output
> @cindex logging @value{GDBN} output
> @@ -1482,6 +1532,8 @@ Set @code{redirect} if you want output to go only to the log file.
> Show the current values of the logging settings.
> @end table
>
> +You can also redirect the output of a @value{GDBN} command to a
> +shell command. @xref{pipe}.
> @node Commands
> @chapter @value{GDBN} Commands
>
> @@ -11292,6 +11344,21 @@ the value 12 for @code{$_gdb_minor}. These variables allow you to
> write scripts that work with different versions of @value{GDBN}
> without errors caused by features unavailable in some of those
> versions.
> +
> +@item $_shell_exitcode
> +@itemx $_shell_exitsignal
> +@vindex $_shell_exitcode@r{, convenience variable}
> +@vindex $_shell_exitsignal@r{, convenience variable}
> +@cindex shell command, exit code
> +@cindex shell command, exit signal
> +@cindex exit status of shell commands
> +@value{GDBN} commands such as @code{shell}, @code{|} are launching
List of two items -> use "and", not ",", thus:
@code{shell} and @code{|}
> +shell commands. When a launched command terminates, @value{GDBN}
> +automatically maintains the variables @code{$_shell_exitcode}
> +and @code{$_shell_exitsignal} according to the exit status of the last
> +launched command. These variables are set and used similarly to
> +the variables @code{$_exitcode} and @code{$_exitsignal}.
> +
> @end table
>
> @node Convenience Funs
>
Thanks,
Pedro Alves
@@ -16,11 +16,23 @@
* Support for Pointer Authentication on AArch64 Linux.
-* Two new convernience functions $_cimag and $_creal that extract the
+* Two new convenience functions $_cimag and $_creal that extract the
imaginary and real parts respectively from complex numbers.
+* New built-in convenience variables $_shell_exitcode and $_shell_exitsignal
+ provide the exitcode or exit status of the shell commands launched by
+ GDB commands such as "shell", "pipe", "make".
+
* New commands
+pipe [COMMAND] | SHELL_COMMAND
+| [COMMAND] | SHELL_COMMAND
+pipe -d SEP COMMAND SEP SHELL_COMMAND
+| -s DEP COMMAND SEP SHELL_COMMAND
+ Executes COMMAND and sends its output to SHELL_COMMAND.
+ With no COMMAND, repeat the last executed command
+ and send its output to SHELL_COMMAND.
+
set print max-depth
show print max-depth
Allows deeply nested structures to be simplified when printing by
@@ -28,16 +40,6 @@ show print max-depth
The default max-depth is 20, but this can be set to unlimited to get
the old behavior back.
-* Python API
-
- ** The gdb.Value type has a new method 'format_string' which returns a
- string representing the value. The formatting is controlled by the
- optional keyword arguments: 'raw', 'pretty_arrays', 'pretty_structs',
- 'array_indexes', 'symbols', 'unions', 'deref_refs', 'actual_objects',
- 'static_members', 'max_elements', 'repeat_threshold', and 'format'.
-
-* New commands
-
set may-call-functions [on|off]
show may-call-functions
This controls whether GDB will attempt to call functions in
@@ -48,6 +50,14 @@ show may-call-functions
an error when a command (such as print expression) calls a function
in the program.
+* Python API
+
+ ** The gdb.Value type has a new method 'format_string' which returns a
+ string representing the value. The formatting is controlled by the
+ optional keyword arguments: 'raw', 'pretty_arrays', 'pretty_structs',
+ 'array_indexes', 'symbols', 'unions', 'deref_refs', 'actual_objects',
+ 'static_members', 'max_elements', 'repeat_threshold', and 'format'.
+
*** Changes in GDB 8.3
* GDB and GDBserver now support access to additional registers on
@@ -1454,6 +1454,56 @@ Execute the @code{make} program with the specified
arguments. This is equivalent to @samp{shell make @var{make-args}}.
@end table
+@table @code
+@kindex pipe
+@kindex |
+@cindex send the output of a gdb command to a shell command
+@anchor{pipe}
+@item pipe [@var{command}] | @var{shell_command}
+@itemx | [@var{command}] | @var{shell_command}
+@itemx pipe -d @var{sep} @var{command} @var{sep} @var{shell_command}
+@itemx | -d @var{sep} @var{command} @var{sep} @var{shell_command}
+Executes @var{command} and sends its output to @var{shell_command}.
+Note that no space is needed around @code{|}.
+If no @var{command} is provided, the last command executed is repeated.
+
+If the @var{command} contains a @code{|}, then the option @code{-d @var{sep}}
+can be used to specify an alternate separator string @var{sep} that separates
+the @var{command} from the @var{shell_command}.
+
+Example:
+@smallexample
+@group
+(gdb) pipe p full|wc
+ 5 17 81
+(gdb) |p full|wc -l
+5
+@end group
+@group
+(gdb) p full
+$4 = (black => 144,
+ red => 233,
+ green => 377,
+ blue => 610,
+ white => 987)
+(gdb) ||grep red
+ red => 233,
+@end group
+@group
+(gdb) | -d ! echo this contains a | char\n ! sed -e 's/|/PIPE/'
+this contains a PIPE char
+(gdb) | -d xxx echo this contains a | char!\n xxx sed -e 's/|/PIPE/'
+this contains a PIPE char!
+(gdb)
+@end group
+@end smallexample
+@end table
+
+The convenience variables @code{$_shell_exitcode} and @code{$_shell_exitsignal}
+can be used to examine the exit status of the last shell command launched
+by @code{shell}, @code{make}, @code{pipe} and @code{|}.
+@xref{Convenience Vars,, Convenience Variables}.
+
@node Logging Output
@section Logging Output
@cindex logging @value{GDBN} output
@@ -1482,6 +1532,8 @@ Set @code{redirect} if you want output to go only to the log file.
Show the current values of the logging settings.
@end table
+You can also redirect the output of a @value{GDBN} command to a
+shell command. @xref{pipe}.
@node Commands
@chapter @value{GDBN} Commands
@@ -11292,6 +11344,21 @@ the value 12 for @code{$_gdb_minor}. These variables allow you to
write scripts that work with different versions of @value{GDBN}
without errors caused by features unavailable in some of those
versions.
+
+@item $_shell_exitcode
+@itemx $_shell_exitsignal
+@vindex $_shell_exitcode@r{, convenience variable}
+@vindex $_shell_exitsignal@r{, convenience variable}
+@cindex shell command, exit code
+@cindex shell command, exit signal
+@cindex exit status of shell commands
+@value{GDBN} commands such as @code{shell}, @code{|} are launching
+shell commands. When a launched command terminates, @value{GDBN}
+automatically maintains the variables @code{$_shell_exitcode}
+and @code{$_shell_exitsignal} according to the exit status of the last
+launched command. These variables are set and used similarly to
+the variables @code{$_exitcode} and @code{$_exitsignal}.
+
@end table
@node Convenience Funs