[RFAv3,6/6] NEWS and documentation for | (pipe) command.

Message ID 20190504161753.15530-7-philippe.waroquiers@skynet.be
State New
Headers show
Series
  • Implement | (pipe) command.
Related show

Commit Message

Philippe Waroquiers May 4, 2019, 4:17 p.m.
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(-)

-- 
2.20.1

Comments

Eli Zaretskii May 4, 2019, 4:26 p.m. | #1
> 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.
Eli Zaretskii May 4, 2019, 4:32 p.m. | #2
> 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.
Pedro Alves May 27, 2019, 5:51 p.m. | #3
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

Patch

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.
 
+* 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
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}.
+
+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