aboutsummaryrefslogtreecommitdiff
path: root/gdb/doc
diff options
context:
space:
mode:
authorPedro Alves <pedro@palves.net>2023-02-08 16:06:23 +0000
committerPedro Alves <pedro@palves.net>2023-02-15 20:58:00 +0000
commit91265a7d7cddc10314335ffcfbfae7159c7cecb1 (patch)
tree3449a623ebe58d5e59ea3c72eb9be336cc0dbc03 /gdb/doc
parent751495be92b2b319fb66ce4e12b562a0e27c15fe (diff)
downloadgdb-91265a7d7cddc10314335ffcfbfae7159c7cecb1.zip
gdb-91265a7d7cddc10314335ffcfbfae7159c7cecb1.tar.gz
gdb-91265a7d7cddc10314335ffcfbfae7159c7cecb1.tar.bz2
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 || <other condition> 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 <aburgess@redhat.com> Approved-By: Tom Tromey <tom@tromey.com> Approved-By: Eli Zaretskii <eliz@gnu.org> Change-Id: I7e36d451ee6b428cbf41fded415ae2d6b4efaa4e
Diffstat (limited to 'gdb/doc')
-rw-r--r--gdb/doc/gdb.texinfo60
1 files changed, 59 insertions, 1 deletions
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