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