Format: ‘QThreadOptions[;options[:thread-id]]…’

Meaning: For each inferior thread, the last options in the list with a matching thread-id are applied. Any options previously set on a thread are discarded and replaced by the new options specified. Threads that do not match any thread-id retain their previously-set options. If multiprocess extensions are supported, options can be specified to apply to all threads of a process by using the ‘ppid.-1’ form of thread-id. Options with no thread-id apply to all threads. Specifying no options value is an error. Zero is a valid value.

options is an hexadecimal integer specifying the enabled thread options, and is the bitwise OR of the following values. All values are given in hexadecimal representation.

GDB_THREAD_OPTION_CLONE (0x1)

Report thread clone events (see thread clone event). This is only meaningful for targets that support clone events (e.g., GNU/Linux systems).

GDB_THREAD_OPTION_EXIT (0x2)

Report thread exit events (see thread exit event).

For example, GDB enables the GDB_THREAD_OPTION_EXIT and GDB_THREAD_OPTION_CLONE options when single-stepping a thread past a breakpoint, for the following reasons:

• If the single-stepped thread exits (e.g., it executes a thread exit system call), enabling GDB_THREAD_OPTION_EXIT prevents GDB from waiting forever, not knowing that it should no longer expect a stop for that same thread, and blocking other threads from progressing.
• If the single-stepped thread spawns a new clone child (i.e., it executes a clone system call), enabling GDB_THREAD_OPTION_CLONE halts the cloned thread before it executes any instructions, and thus prevents the following problematic situations:
  • If the breakpoint is stepped-over in-line, the spawned thread would incorrectly run free while the breakpoint being stepped over is not inserted, and thus the cloned thread may potentially run past the breakpoint without stopping for it;
  • If displaced (out-of-line) stepping is used, the cloned thread starts running at the out-of-line PC, leading to undefined behavior, usually crashing or corrupting data.

New threads start with thread options cleared.

GDB does not enable this feature unless the stub reports that it supports it by including ‘QThreadOptions=supported_options’ in its ‘qSupported’ reply.

Reply:

OK