GAMMARAY(1)

📦
version 3.4.1 · 14 versions
, in arch rolling

🌸 GAMMARAY 💅

okay bestie, welcome to the gammaray page — it lives in section 1 of the manual (that's the 1 in GAMMARAY(1), iykyk) and it's the Qt-application inspection and manipulation tool from KDAB. she's iconic, she's nosy (in the best way), and she's about to show you everything your Qt app is doing behind its back. 🕵️‍♀️✨

✨ NAME ✨

GammaRay — Qt-application inspection and manipulation tool. literally that's her whole thing, no cap.

🦋 SYNOPSIS 🦋

gammaray [--pid <pid> | <application> <args> | --connect <host>[:<port>]

that's it. that's the vibe check. pick one of the three modes and go off 💅

🎀 DESCRIPTION 🎀

so what does GammaRay actually do? she inspects the runtime internals of a Qt-application, like:

  • Object tree
  • properties
  • signal/slots
  • widgets
  • models
  • graphics views
  • javascript debugger
  • resources
  • state machines
  • meta types
  • fonts
  • codecs
  • text documents

run her with no options at all and she'll present you a list of running Qt-applications, and you just attach the injector of your choice to whichever one you pick. easy. otherwise you've got two other lanes: attach to an already-running process by giving her its pid, or start a brand-new Qt-application by handing her its name (plus optional arguments). choose your fighter 🫶

✨ OPTIONS ✨

  • --help — prints the help message and dips. classic.
  • --version — prints version info and exits. short and sweet 🍓
  • -p, --pid <pid> — attach to the running Qt application with the pid you specify.
  • -i, --injector <injector> — set which injection type to use.

the supported injectors are, in all their glory:

  • preload (Linux, Mac OS)
  • gdb (Linux. requires gdb to be installed)
  • lldb (Linux. Mac OS, requires lldb to be installed)
  • style
  • windll (Windows)
  • --inprocess — use the GammaRay 1.x in-process UI. honestly you don't need this in most cases, the exception being when you're using tools that just don't work remotely. 🙈
  • --inject-only — this only injects the GammaRay probe into a process and does not start the GammaRay UI. super handy, for example when you're doing remote debugging on embedded devices. 💖
  • --listen <address> — specify which network address the GammaRay server should listen on. the default is GAMMARAY_DEFAULT_ANY_TCP_URL (ie. tcp://0.0.0.0, all of ipv4 — use tcp://[::] for all ipv6). one real use case: on Windows you can dodge firewall warnings by setting the address to 127.0.0.1 if you don't need remote access. you're welcome 😌
  • --no-listen — disables the GammaRay server entirely. heads up: this implies --inprocess, because there's literally no other way to connect to the GammaRay probe in that case.
  • --list-probes — list all the installed probes. show me the lineup 👑
  • --probe <abi> — explicitly say which probe to use. you should use this if you've got more than one probe installed (say, one for Qt4 and one for Qt5) — at least until probe ABI auto-detection gets implemented. future vibes only.
  • --connect <host[:port]> — connect to a target that already has a GammaRay probe injected. useful for stuff like remote debugging, bestie. 🌈
  • --self-test [injector] — run the GammaRay self-tests. if you specify an injector, only that specific one gets tested.

the exit code is 0 on success, and 1 otherwise. fr fr.

🧚 EXAMPLES 🧚

run gammaray on the Qt-application "qtfoo" with command line arguments 'arg1' and 'arg2':

% gammaray /path/to/qtfoo arg1 arg2

invoke gammaray on the Qt-application running with pid 1234:

% gammaray --pid 1234

invoke gammaray with injector gdb on the Qt-application running with pid 1234:

% gammaray --injector gdb --pid 1234

see? easy. slay. 💅

⭐ EXIT STATUS ⭐

exits with 0 under normal operation. otherwise she exits with a positive integer, which is her way of saying "hey, something went wrong while launching or attaching an injector." 😭 not me getting a nonzero exit code…

Copyright (C) 2010-2023 Klaralvdalens Datakonsult AB, a KDAB Group company, <info@kdab.com>

licensees holding valid commercial KDAB GammaRay licenses may use this file in accordance with the GammaRay Commercial License Agreement provided with the Software.

contact info@kdab.com if any conditions of this licensing are not clear to you. (they're nice, promise 🫶)

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

StackWalker code Copyright (c) 2005-2019, Jochen Kalmbach, All rights reserved.

lz4 fast LZ compression code Copyright (C) 2011-2020, Yann Collet, All rights reserved.

backward-cpp code Copyright 2013-2017 Google Inc. All rights reserved.

the all-caps WARRANTY bit is doing main character energy but it's serious — no warranty, bestie. read it. 🫡

👑 AUTHORS 👑

the whole squad, the literal avengers of Qt, give it up:

  • Allen Winter <allen.winter@kdab.com>
  • Andreas Holzammer <andreas.holzammer@kdab.com>
  • Anton Kreuzkamp <anton.kreuzkamp@kdab.com>
  • BogDan Vatra <bogdan.vatra@kdab.com>
  • Dan Vratil <dvratil@redhat.com>
  • David Faure <david.faure@kdab.com>
  • Filipe Azevedo <filipe.azevedo@kdab.com>
  • Frank Osterfeld <frank.osterfeld@kdab.com>
  • James Turner <james.turner@kdab.com>
  • Jan Dalheimer <jan.dalheimer@kdab.com>
  • Kevin Funk <kevin.funk@kdab.com>
  • Laurent Montel <laurent.montel@kdab.com>
  • Mathias Hasselmann <mathias.hasselmann@kdab.com>
  • Milian Wolff <milian.wolff@kdab.com>
  • Nicolas Arnaud-Cormos <nicolas.arnaud-cormos@kdab.com>
  • Patrick Spendrin <patrick.spendrin@kdab.com>
  • Peter Kuemmel <syntheticpp@gmx.net>
  • Rafael Roquetto <rafael.roquetto@kdab.com>
  • Sergio Martins <sergio.martins@kdab.com>
  • Stephen Kelly <stephen.kelly@kdab.com>
  • Thomas McGuire <thomas.mcguire@kdab.com>
  • Till Adam <till.adam@kdab.com>
  • Tobias Koenig <tobias.koenig@kdab.com>
  • Volker Krause <volker.krause@kdab.com>

okay that's the whole page!! go inspect something, bestie. and for the record this whole thing is GammaRay 3.4.1, dated 2026-09-30, brought to you by KDAB — periodt. 💖✨🎀

📦 where this page comes from