Command Line Interface
Overview
All basic GammaRay operations such as launching a target application or attaching to a running one are also available from the command line interface. This is particularly useful when working with embedded devices. Additionally some specialized options to control GammaRay's injection behavior are only available via the command line interface.
Launching a target application with GammaRay is done as follows:
gammaray [gammaray args] <target application> [application args]
When run without any arguments, gammaray will bring up the Graphical Launcher. Valid arguments for the gammaray command are described in the next section.
Command Line Options
| Option | Description |
|---|---|
--help | Print command line options. |
--version | Print the GammaRay version and the GammaRay protocol version. |
-p, --pid <pid> | Attach to a running application with process id <pid>. |
-i, --injector <injector> | Specify injector type to use (see below). |
--inprocess | Use the Gammaray 1.x in-process UI. This is not necessary in most cases, apart from using tools that do not work remotely. |
--inject-only | This will only inject the GammaRay probe into a process, but not start the GammaRay Client. This is useful for example when doing remote debugging on embedded devices. |
--listen <address> | Specify on which network address the GammaRay server should listen on. This is useful when GammaRay is selecting the wrong network interface by default, or for restricting remote access in untrusted networks. |
--no-listen | Disables the GammaRay server. This implies --inprocess as there is no other way to connect to the GammaRay probe in this case. |
--list-probes | List all installed probes. |
--probe <abi> | Explicitly specify which probe to use. This should only be needed when the automatic probe ABI detection fails, or on platforms that don't have probe ABI detection implemented yet. |
--connect tcp://<host>[:port] | Connect to a target with an already injected GammaRay probe. Useful for example for remote debugging. |
--self-test [injector] | Runs the GammaRay self-tests, if an injector is specified only that specific one will be tested. The exit code is 0 on success, and 1 otherwise. |
Injector Types
GammaRay contains various methods of injecting itself into a target process. By default it picks the most suitable method on its own, based on the current platform and properties of the target application. It can however be necessary to override the default, in particular if other tools are used at the same time that already occupy specific ways, or if the target application is incompatible with a specific injection method.
The following injection methods are supported:
| Method | Launch | Attach | Supported Platforms |
|---|---|---|---|
| preload | X | Linux, macOS, QNX | |
| gdb | X | X | Linux, QNX |
| lldb | X | X | Linux, macOS |
| windll | X | X | Windows |
| style | X | all |