Thread information

Updated: April 19, 2023

Several of the devctl() commands use a procfs_status structure (which is the same as debug_thread_t), so let's look at this structure before going into the commands themselves.

The debug_thread_t structure is defined for 64-bit architectures as follows in <sys/debug.h>:

#define BLOCKED_CONNECT_FLAGS_SERVERMON 0x01u

typedef struct _debug_thread_info64 {
    pid_t                       pid;
    pthread_t                   tid;
    uint32_t                    flags;
    uint16_t                    why;
    uint16_t                    what;
    uint64_t                    ip;
    uint64_t                    sp;
    uint64_t                    stkbase;
    uint64_t                    tls;
    uint32_t                    stksize;
    uint32_t                    tid_flags;
    uint8_t                     priority;
    uint8_t                     real_priority;
    uint8_t                     policy;
    uint8_t                     state;
    int16_t                     syscall;
    uint16_t                    last_cpu;
    uint32_t                    timeout;
    int32_t                     last_chid;
    sigset_t                    sig_blocked;
    sigset_t                    sig_pending;
    __siginfo32_t                __info32;

    union {
        struct {
            pthread_t                   tid;
        }                           join;
        struct {
            intptr64_t                  id;
            uintptr64_t                 sync;
        }                           sync;
        struct {
            uint32_t                    nd;
            pid_t                       pid;
            int32_t                     coid;
            int32_t                     chid;
            int32_t                     scoid;
            uint32_t                    flags;
        }                           connect;
        struct {
            int32_t                     chid;
        }                           channel;
        struct {
            pid_t                       pid;
            uint32_t                    flags;
            uintptr64_t                 vaddr;
        }                           waitpage;
        struct {
            size64_t                    size;
        }                           stack;
        struct {
            pthread_t                   tid;
        }                           thread_event;
        struct {
            pid_t                       child;
        }                           fork_event;
        uint64_t                        filler[4];
    }                           blocked;

    uint64_t                    start_time;
    uint64_t                    sutime;
    uint8_t                     extsched[8];
    uint64_t                    nsec_since_block;

    union {
        __siginfo32_t           info32;
        __siginfo64_t           info64;
        siginfo_t               info;
    };

    uint64_t                    reserved2[4];
}                           debug_thread64_t;
Note: If you ask for information about a specific thread, and the thread no longer exists, the process manager returns information about the one with the next higher thread ID. If there are no threads with a higher ID, devctl() returns ESRCH.

The members include:

pid, tid
The process and thread IDs.
flags
A combination of the following bits:
  • _DEBUG_FLAG_STOPPED — the thread isn't running.
  • _DEBUG_FLAG_ISTOP — the thread is stopped at a point of interest.
  • _DEBUG_FLAG_IPINVAL — the instruction pointer isn't valid.
  • _DEBUG_FLAG_ISSYS — system process.
  • _DEBUG_FLAG_SSTEP — stopped because of single-stepping.
  • _DEBUG_FLAG_CURTID — the thread is the current thread.
  • _DEBUG_FLAG_TRACE_EXEC — stopped because of a breakpoint.
  • _DEBUG_FLAG_TRACE_RD — stopped because of read access.
  • _DEBUG_FLAG_TRACE_WR — stopped because of write access.
  • _DEBUG_FLAG_TRACE_MODIFY — stopped because of modified memory.
  • _DEBUG_FLAG_RLC — the Run-on-Last-Close flag is set.
  • _DEBUG_FLAG_KLC — the Kill-on-Last-Close flag is set.
  • _DEBUG_FLAG_FORK — the child inherits flags (stop on fork or spawn).
  • _DEBUG_FLAG_EXEC — (QNX Neutrino 6.6 or later) stop on exec.
  • _DEBUG_FLAG_THREAD_EV — (QNX Neutrino 6.6 or later) stop when creating or destroying a thread.
  • _DEBUG_FLAG_64BIT — (QNX Neutrino 7.0 or later) the thread is running in a 64-bit architecture.
why, what
The why field indicates why the process was stopped; the what field gives additional information:
why Description what
_DEBUG_WHY_CHILD A child process is ready to run; the parent gets a chance to connect to it The child's process ID
_DEBUG_WHY_EXEC The process was created by a call to an exec*() function 0
_DEBUG_WHY_FAULTED The thread faulted The fault number; see siginfo_t
_DEBUG_WHY_JOBCONTROL The thread is under job control The signal number
_DEBUG_WHY_REQUESTED The thread was working normally before being stopped by request 0
_DEBUG_WHY_SIGNALLED The thread received a signal The signal number
_DEBUG_WHY_TERMINATED The thread terminated The process's exit status
_DEBUG_WHY_THREAD (QNX Neutrino 6.6 or later) A thread was created or destroyed The thread ID
ip
The current instruction pointer.
sp
The thread's stack pointer.
stkbase
The base address of the thread's stack region.
tls
A pointer to the thread's local storage, which is on the thread's stack. For more information, see struct _thread_local_storage in <sys/storage.h>.
stksize
The stack size.
tid_flags
The thread flags; see _NTO_TF_* in <sys/neutrino.h> and the entry for pidin in the Utilities Reference.
priority
The priority the thread is actually running at (e.g., its priority may have been boosted).
real_priority
The actual priority the thread would be at with no boosting and so on.
policy
The scheduling policy; one of SCHED_FIFO, SCHED_RR, SCHED_OTHER, or SCHED_SPORADIC.
state
The thread's state. The states themselves are defined in <sys/states.h>; for descriptions, see Thread life cycle in the QNX Neutrino Microkernel chapter of the System Architecture guide. If the thread is waiting for something, the blocked member may hold additional information, as described below.
syscall
The last system call; one of the __KER_* values defined in <sys/kercalls.h>.
last_cpu
The processor the thread last ran on.
timeout
_NTO_TF_ACTIVE|_NTO_TF_IMMEDIATE|(1 << state) — set by TimerTimeout().
last_chid
The ID of the last channel this thread received a message on.
sig_blocked
The set of signals that are blocked for the thread.
sig_pending
The set of signals that are pending for the thread.
blocked
A union of the following:
  • join — if the state is STATE_JOIN or STATE_WAITTHREAD, this structure contains tid, the ID of the thread that this thread is waiting for.
  • sync — if the state is STATE_CONDVAR, STATE_MUTEX, or STATE_SEM, this structure contains:
    id
    The address of the synchronization object.
    sync
    For a condvar, this is a pointer to the associated mutex; for a mutex, it's a pointer to the mutex.
  • connect — if the state is STATE_SEND or STATE_REPLY, this structure contains:
    nd
    The node descriptor.
    pid
    The process ID.
    coid
    The connection ID.
    chid
    The channel ID.
    scoid
    The server connection ID that the thread is waiting for.
    flags
    A bitfield of flags. The BLOCKED_CONNECT_FLAGS_SERVERMON bit is set when the thread has requested server monitor services, and unset either when the thread is unblocked before the server monitor gets to service it or when the server monitor has taken a specified action.
  • channel — if the state is STATE_RECEIVE, this structure contains chid, the ID of the channel that the thread is waiting for.
  • waitpage — if the state is STATE_WAITPAGE, this structure contains:
    pid
    The ID of the process whose address space was active when the page fault occurred.
    flags
    Internal use only.
    vaddr
    The virtual address for which the thread is waiting for physical memory to be allocated.
  • stack — if the state is STATE_STACK, this structure contains size, the amount of stack that the thread is waiting for to be allocated.
  • thread_event — if why is _DEBUG_WHY_THREAD, this structure contains tid, the thread ID of the created or destroyed thread.
  • fork_event — if why is _DEBUG_WHY_CHILD, this structure contains child, the process ID of the child.
start_time
The thread's starting time, in nanoseconds.
sutime
The thread's system plus user running time, in nanoseconds.
extsched
Extended scheduling information; a struct extsched_aps_dbg_thread structure if the adaptive partitioning thread scheduler is installed.
nsec_since_block
How long the thread has been blocked, in nanoseconds, but to millisecond resolution. 0 for STATE_READY or STATE_RUNNING.
info
A siginfo_t structure that contains information about the last signal or fault received.