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

OptionDescription
--helpPrint command line options.
--versionPrint 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).
--inprocessUse the Gammaray 1.x in-process UI. This is not necessary in most cases, apart from using tools that do not work remotely.
--inject-onlyThis 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-listenDisables the GammaRay server. This implies --inprocess as there is no other way to connect to the GammaRay probe in this case.
--list-probesList 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:

MethodLaunchAttachSupported Platforms
preloadXLinux, macOS, QNX
gdbXXLinux, QNX
lldbXXLinux, macOS
windllXXWindows
styleXall