From 91265a7d7cddc10314335ffcfbfae7159c7cecb1 Mon Sep 17 00:00:00 2001 From: Pedro Alves Date: Wed, 8 Feb 2023 16:06:23 +0000 Subject: Add new "$_shell(CMD)" internal function For testing a following patch, I wanted a way to send a SIGINT to GDB from a breakpoint condition. And I didn't want to do it from a Python breakpoint or Python function, as I wanted to exercise non-Python code paths. So I thought I'd add a new $_shell internal function, that runs a command under the shell, and returns the exit code. With this, I could write: (gdb) b foo if $_shell("kill -SIGINT $gdb_pid") != 0 || I think this is generally useful, hence I'm proposing it here. Here's the new function in action: (gdb) p $_shell("true") $1 = 0 (gdb) p $_shell("false") $2 = 1 (gdb) p $_shell("echo hello") hello $3 = 0 (gdb) p $_shell("foobar") bash: line 1: foobar: command not found $4 = 127 (gdb) help function _shell $_shell - execute a shell command and returns the result. Usage: $_shell (command) Returns the command's exit code: zero on success, non-zero otherwise. (gdb) NEWS and manual changes included. Approved-By: Andrew Burgess Approved-By: Tom Tromey Approved-By: Eli Zaretskii Change-Id: I7e36d451ee6b428cbf41fded415ae2d6b4efaa4e --- gdb/doc/gdb.texinfo | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 59 insertions(+), 1 deletion(-) (limited to 'gdb/doc') diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 38e6925..bbb39e7 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -1621,7 +1621,7 @@ just use the @code{shell} command. @cindex shell escape @item shell @var{command-string} @itemx !@var{command-string} -Invoke a standard shell to execute @var{command-string}. +Invoke a shell to execute @var{command-string}. Note that no space is needed between @code{!} and @var{command-string}. On GNU and Unix systems, the environment variable @env{SHELL}, if it exists, determines which shell to run. Otherwise @value{GDBN} uses @@ -1629,6 +1629,10 @@ the default shell (@file{/bin/sh} on GNU and Unix systems, @file{cmd.exe} on MS-Windows, @file{COMMAND.COM} on MS-DOS, etc.). @end table +You may also invoke shell commands from expressions, using the +@code{$_shell} convenience function. @xref{$_shell convenience +function}. + The utility @code{make} is often needed in development environments. You do not have to use the @code{shell} command for this purpose in @value{GDBN}: @@ -12977,6 +12981,60 @@ Like the @code{$_gdb_setting_str} function, but works with Like the @code{$_gdb_setting} function, but works with @code{maintenance set} variables. +@anchor{$_shell convenience function} +@findex $_shell@r{, convenience function} +@item $_shell (@var{command-string}) + +Invoke a shell to execute @var{command-string}. @var{command-string} +must be a string. The shell runs on the host machine, the machine +@value{GDBN} is running on. Returns the command's exit status. On +Unix systems, a command which exits with a zero exit status has +succeeded, and non-zero exit status indicates failure. When a command +terminates on a fatal signal whose number is @var{N}, @value{GDBN} +uses the value 128+@var{N} as the exit status, as is standard in Unix +shells. Note that @var{N} is a host signal number, not a target +signal number. If you're native debugging, they will be the same, but +if cross debugging, the host vs target signal numbers may be +completely unrelated. Please consult your host operating system's +documentation for the mapping between host signal numbers and signal +names. The shell to run is determined in the same way as for the +@code{shell} command. @xref{Shell Commands, ,Shell Commands}. + +@smallexample +(@value{GDBP}) print $_shell("true") +$1 = 0 +(@value{GDBP}) print $_shell("false") +$2 = 1 +(@value{GDBP}) p $_shell("echo hello") +hello +$3 = 0 +(@value{GDBP}) p $_shell("foobar") +bash: line 1: foobar: command not found +$4 = 127 +@end smallexample + +This may also be useful in breakpoint conditions. For example: + +@smallexample +(@value{GDBP}) break function if $_shell("some command") == 0 +@end smallexample + +In this scenario, you'll want to make sure that the shell command you +run in the breakpoint condition takes the least amount of time +possible. For example, avoid running a command that may block +indefinitely, or that sleeps for a while before exiting. Prefer a +command or script which analyzes some state and exits immediately. +This is important because the debugged program stops for the +breakpoint every time, and then @value{GDBN} evaluates the breakpoint +condition. If the condition is false, the program is re-resumed +transparently, without informing you of the stop. A quick shell +command thus avoids significantly slowing down the debugged program +unnecessarily. + +Note: unlike the @code{shell} command, the @code{$_shell} convenience +function does not affect the @code{$_shell_exitcode} and +@code{$_shell_exitsignal} convenience variables. + @end table The following functions require @value{GDBN} to be configured with -- cgit v1.1