Commands¶
drgn’s programmatic interface excels at complex analysis. For simpler tasks, it can be more convenient to use pre-defined commands. drgn provides a set of commands for this purpose.
In interactive mode, commands are accessed by starting a line with the %
character.
In script mode, commands can be run with drgn.commands.run_command().
Plugins and scripts can also register additional commands. See the commands API.
Syntax¶
Most commands use shell syntax (words split on whitespace unless quoted or escaped, etc.) and command-line options:
>>> %example --foo 'hello world'
Redirecting standard input, standard output, and standard error is supported:
>>> %example > file
>>> %example >> file
>>> %example 2> err
>>> %example < file
The output of a command can also be piped to an external command:
>>> %example | grep foo | sort -r
Word expansions (including variable expansions, wildcards, etc.) are only
supported in external commands (i.e., after the | in a pipeline).
A few commands have their own syntax. These commands do not support redirection or pipes.
Common¶
The following commands are available when debugging any program.
py¶
execute a python statement and allow shell redirection
Synopsis¶
py code
Description¶
Execute the given code, up to the first shell redirection or pipeline statement, as Python code.
For each occurrence of a pipeline operator (|) or any redirection operator (<, >,
<<, >>), attempt to parse the preceding text as Python code. If the preceding text is
syntactically valid code, then interpret the remainder of the command as shell redirections or
pipelines, and execute the Python code with those redirections and pipelines applied.
The operators above can be used in syntactically valid Python. This means you need to be careful when using this function, and ensure that you wrap their uses with parentheses.
For example, consider the command: %py field | MY_FLAG | grep foo. While the intent here may be
to execute the Python code field | MY_FLAG and pass its result to grep, that is not what
will happen. The portion of text prior to the first | is valid Python, so it will be executed,
and its output piped to the shell pipeline MY_FLAG | grep foo. Instead, running %py (field |
MY_FLAG) | grep foo ensures that field | MY_FLAG gets piped to grep foo, because
(field on its own is not valid Python syntax.
sh¶
execute a shell command
Synopsis¶
sh [command]
Description¶
If command is given, run it with sh -c --. Otherwise, run an interactive shell with sh -i.
In either case, return the command’s exit status.
source¶
run a drgn script
Synopsis¶
source script [args …]
Description¶
This loads and runs a drgn script in the current environment. Currently defined globals are available to the script, and globals defined by the script are added to the environment.
Positional Arguments¶
- script¶
script file path
- args¶
arguments to pass to the script
Linux Kernel¶
The following commands are available when debugging the Linux kernel.
crash¶
run a crash command
Synopsis¶
crash [command]
Description¶
This provides a compatibility mode emulating the crash utility.
If command is given, run the given crash command (which may include arguments, redirections, pipes, etc.). Otherwise, enter an interactive prompt where crash commands can be called directly.
Run %crash help or see Crash Compatibility for the list of commands.
