From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 44417 invoked by alias); 27 May 2019 17:51:42 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 44409 invoked by uid 89); 27 May 2019 17:51:42 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-26.9 required=5.0 tests=BAYES_00,GIT_PATCH_0,GIT_PATCH_1,GIT_PATCH_2,GIT_PATCH_3,RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.1 spammy=bottom, 5014, ahead X-HELO: mail-wr1-f65.google.com Received: from mail-wr1-f65.google.com (HELO mail-wr1-f65.google.com) (209.85.221.65) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Mon, 27 May 2019 17:51:40 +0000 Received: by mail-wr1-f65.google.com with SMTP id c2so2377244wrm.8 for ; Mon, 27 May 2019 10:51:40 -0700 (PDT) Return-Path: Received: from ?IPv6:2001:8a0:f913:f700:4eeb:42ff:feef:f164? ([2001:8a0:f913:f700:4eeb:42ff:feef:f164]) by smtp.gmail.com with ESMTPSA id x6sm15946186wru.36.2019.05.27.10.51.37 (version=TLS1_3 cipher=AEAD-AES128-GCM-SHA256 bits=128/128); Mon, 27 May 2019 10:51:37 -0700 (PDT) Subject: Re: [RFAv3 6/6] NEWS and documentation for | (pipe) command. To: Philippe Waroquiers , gdb-patches@sourceware.org References: <20190504161753.15530-1-philippe.waroquiers@skynet.be> <20190504161753.15530-7-philippe.waroquiers@skynet.be> From: Pedro Alves Message-ID: Date: Mon, 27 May 2019 17:51:00 -0000 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.2.1 MIME-Version: 1.0 In-Reply-To: <20190504161753.15530-7-philippe.waroquiers@skynet.be> Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 7bit X-SW-Source: 2019-05/txt/msg00593.txt.bz2 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