From patchwork Sat May 4 16:17:53 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philippe Waroquiers X-Patchwork-Id: 32549 Received: (qmail 114427 invoked by alias); 4 May 2019 16:18:16 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Delivered-To: mailing list gdb-patches@sourceware.org Received: (qmail 114314 invoked by uid 89); 4 May 2019 16:18:15 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-22.2 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, RCVD_IN_DNSWL_LOW, SPF_PASS autolearn=ham version=3.3.1 spammy=black, 987, sk:may-cal, UD:texinfo X-HELO: mailsec106.isp.belgacom.be Received: from mailsec106.isp.belgacom.be (HELO mailsec106.isp.belgacom.be) (195.238.20.102) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Sat, 04 May 2019 16:18:13 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=skynet.be; i=@skynet.be; q=dns/txt; s=securemail; t=1556986693; x=1588522693; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=x39czmA0IlRD5GJnR90C/27E9llvU2XrXCCVtlEHrtk=; b=BB205uZyRLxBqvigN9S6qV2kRHfKpWf3UxATu3gfno4be0LQlmHAn/Wp 8wqjcSwfXVjUJcHY/zabzv9g2yVtoA==; Received: from 59.151-129-109.adsl-dyn.isp.belgacom.be (HELO md.home) ([109.129.151.59]) by relay.skynet.be with ESMTP/TLS/DHE-RSA-AES128-GCM-SHA256; 04 May 2019 18:17:59 +0200 From: Philippe Waroquiers To: gdb-patches@sourceware.org Cc: Philippe Waroquiers Subject: [RFAv3 6/6] NEWS and documentation for | (pipe) command. Date: Sat, 4 May 2019 18:17:53 +0200 Message-Id: <20190504161753.15530-7-philippe.waroquiers@skynet.be> In-Reply-To: <20190504161753.15530-1-philippe.waroquiers@skynet.be> References: <20190504161753.15530-1-philippe.waroquiers@skynet.be> MIME-Version: 1.0 X-IsSubscribed: yes 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. +* 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