[RFAv2,6/6] NEWS and documentation for | (pipe) command.
Commit Message
gdb/ChangeLog
* NEWS: Mention new pipe command.
gdb/doc/ChangeLog
* gdb.texinfo (Shell Commands): Document pipe command.
(Logging Output): Add a reference to pipe command.
---
gdb/NEWS | 8 ++++++++
gdb/doc/gdb.texinfo | 39 +++++++++++++++++++++++++++++++++++++++
2 files changed, 47 insertions(+)
Comments
> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Date: Fri, 26 Apr 2019 22:11:08 +0200
>
> +@item pipe [@var{command}] | @var{shell_command}
> +@itemx | [@var{command}] | @var{shell_command}
> +@item pipe -d@var{X} @var{command} @var{X} @var{shell_command}
> +@itemx | -d@var{X} @var{command} @var{X} @var{shell_command}
All but the first @item should be @itemx.
> +If the @var{command} contains a @code{|}, then the option @code{-d@var{X}}
> +can be used to specify an alternate character that separates
> +the @var{command} from the @var{shell_command}.
You didn't explain what X stands for. I suggest to say this instead:
... to specify an alternate character @var{X} that separates ...
Also, our convention is not to upcase the argument of @var; it is
upcased in the produced Info manual, but has a different typeface in
other formats.
> +@smallexample
> +(gdb) pipe p full|wc
> + 5 17 81
> +(gdb) |p full|wc -l
> +5
> +(gdb) p full
> +$4 = (black => 144,
> + red => 233,
> + green => 377,
> + blue => 610,
> + white => 987)
> +(gdb) ||grep red
> + red => 233,
> +(gdb) | -d! echo this contains a | char\n ! sed -e 's/|/PIPE/'
> +this contains a PIPE char
> +(gdb)
> +@end smallexample
This @example is very long, and could be split between two pages. In
order to give TeX a hint where to split it, use @group, like this:
@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)
@end group
@end smallexample
(Feel free to divide differently into groups, but the principle is:
make a group of lines that you don't want split between pages.)
The documentation parts are OK with these nits fixed.
Thanks.
@@ -27,6 +27,14 @@
'array_indexes', 'symbols', 'unions', 'deref_refs', 'actual_objects',
'static_members', 'max_elements', 'repeat_threshold', and 'format'.
+* New commands
+
+pipe [COMMAND] | SHELL_COMMAND
+| [COMMAND] | 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.
+
*** Changes in GDB 8.3
* GDB and GDBserver now support access to additional registers on
@@ -1454,6 +1454,43 @@ 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}
+@item pipe -d@var{X} @var{command} @var{X} @var{shell_command}
+@itemx | -d@var{X} @var{command} @var{X} @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{X}}
+can be used to specify an alternate character that separates
+the @var{command} from the @var{shell_command}.
+
+Example:
+@smallexample
+(gdb) pipe p full|wc
+ 5 17 81
+(gdb) |p full|wc -l
+5
+(gdb) p full
+$4 = (black => 144,
+ red => 233,
+ green => 377,
+ blue => 610,
+ white => 987)
+(gdb) ||grep red
+ red => 233,
+(gdb) | -d! echo this contains a | char\n ! sed -e 's/|/PIPE/'
+this contains a PIPE char
+(gdb)
+@end smallexample
+@end table
+
@node Logging Output
@section Logging Output
@cindex logging @value{GDBN} output
@@ -1482,6 +1519,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