Guidelines and HOWTOs/Debugging/Debugging KIO Workers
This page describes how you can debug a KIO worker.
How to Get Debug Output
GUI (Qt6/KF6 instructions)
- Launch the
kdebugsettings
tool, either from terminal or from KRunner (the latter can be invoked with Alt + F2) - Type the name of the KIO worker (e.g. ftp, http, ...). (If it's not listed, it doesn't use categorized debug output, so either its output is always on, or commented out in the code, in which case it needs to be ported to qCDebug)
- From the drop-down menu next to each KIO worker you're interested in, select Full Debug
- Press OK to close the dialog and the save your changes
- Log out then log back in, and additional debug info will typically end up in ~/.X.err, ~/.xsession-errors or ~/.local/share/sddm/xorg-session.log
- Instead of using
kdebugsettings
, you can change the Qt logging categories rules temporarily, in terminal:
export QT_LOGGING_RULES="*kio*=true"
- for more information see this.
How does a KIO worker get started?
The application simply starts the KIO worker directly.
A KIO worker can run in a thread (in the application process). Currently this only happens for kio_file. It can be disabled with export KIO_ENABLE_WORKER_THREADS=0
.
Attaching gdb to an KIO worker
For workers started directly by the application (forked)
When you start your application, a dedicated KIO worker will be created in-process by the kioworker
executable.
That executable dlopens the library that contains the requested KIO worker.
Then it calls a function called kdemain()
in the library.
To make the KIO worker start then wait for debug, you need to export the environment variable KIOWORKER_DEBUG_WAIT
for your application, for example:
// Will start any KIO worker then call `kill -SIGSTOP pid` to make it wait for debugging, // e.g. you can create a breakpoint ...etc export KIOWORKER_DEBUG_WAIT=all
When you start an application in the same terminal now and it requests an http KIO worker, the kioworker
executable will be started. But before it calls kdemain() (cq. main()) it will suspend the worker by sending it a SIGSTOP signal.
In the terminal from which you started your application you will get a message like this:
kioworker: Suspending process to debug io worker(s): all
An example but only for kio_file:
export KIOWORKER_DEBUG_WAIT=file [...] kioworker: Suspending process to debug io worker(s): file
Note: The string after the equal signal designates the name of a service, not the name of the worker! E.g. if you want to debug the kio_imap4, you must use:
export KIOWORKER_DEBUG_WAIT=imap
For example, these commands won't work:
export KIOWORKER_DEBUG_WAIT=imap4 export KIOWORKER_DEBUG_WAIT=143
You can now debug your worker by using gdb kioworker 28008
in a terminal.
Note that modern Linux Kernels disable ptrace. If gdb says "ptrace: Operation not permitted." then you need to use a command like this:
echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
If you don't want to debug a worker you can let it continue by sending it a SIGCONT, with e.g. kill -SIGCONT 28008
. Be aware that workers will not be killed while they are suspended.
Once you have started gdb, you can set e.g. breakpoints and then resume the worker by typing continue
(or c
for short). The debugger will return immediate with a message that a "SIGSTOP has been received" so you will have to type continue
a second time.
For workers started in a thread (kio_file)
Just put a breakpoint in KIO::WorkerThread::WorkerThread