--- layout: default title: usr/share/doc/sysbox/html/tool/threads.html ---

Sysbox: threads

Usage: threads [OPTION]... TASKNAME...
or: threads -P [OPTION]... TASKHANDLE...

Print thread info of a task (aka. process) by handle or name. Can be invoked only from elevated shells (or tasks).

With this tool tasks can be examined if they are stuck. Since the PC and the stack pointer can be displayed, the call chain can be reconstructed. This is a very low-level and advanced way to debug, but somethimes higher level debugging is impossible.

Options:

• -D
  Display context depth column. This option is rarely used, since the contexts that are not the bottom one, usually return very fast.
• -p
  Show Program Counter column. The PC will be a virtual address in the address space of the task. PC can placed in a shared executable (SX) as well. Check tview to determine the nature of the location.
• -P
  Use task handles instead of task names. Use the 0x prefix to indicate hexadecimal handles.
• -s
  Display stack pointers. Note that, the stack is growing towards lower addresses on many architectures. Keep this in mind when investigating the stack.
• -S
  Show thread state legend. See thread states below.
• -x
  Show the execution time column.

Columns:

• Thread
  Master handle of the thread.
• Pri
  Priority of the thread. Ranging from 0 to 255 (inclusive).
• St
  State of the thread. See thread states below.
• Err
  Error code of the last system call.
• ExeTime
  Show total time spent in running state. *
• PC
  Program Counter.
• StackPtr
  Stack Pointer.
• Depth
  Context depth. This depth is usally zero, and cannot be too large since it is hard-limited.

[*]: Unit may varies on architectures and on machines.

Thread states:

• running
  The thread is currently running.
• ready
  The thread is ready to run. The scheduler will eventually select this thread.
• wait
  Waiting for a resource with definite timeout.
• blocked
  Waiting for a resource with infinite timeout.
• nowhere
  Unlinked from all schedulable lists. Probably a deleted thread.

Examples (Important! Only super tasks can perform these):

# threads -psxD httpd  
            Thread Pri St  Err          ExeTime               PC         StackPtr Depth
 000000000190011F4  50  B    0          1813452      1000194AE0C      100005D0EB8     0
 0000000000D00135E   0  B    0           107268      1000194AE0C      1000187BE28     0
 00000000011001363   0  B    0            78192      1000194AE0C      1000187FE28     0
 00000000010001368   0  B    0            75468      1000194AE0C      10001883E28     0
 0000000000E00136D   0  B    0            73464      1000194AE0C      10001887E28     0
 00000000010001372   0  B    0            87216      1000194AE0C      1000188BE28     0
 00000000012001377   0  B    0            67356      1000194AE0C      1000188FE28     0
 0000000001100137C   0  B    0            72336      1000194AE0C      10001893E28     0
 0000000000E001381   0  B    0            73740      1000194AE0C      10001897E28     0
 0000000000D001386   0  B    0            70692      1000194AE0C      100060B4E28     0
 0000000000D00138B   0  B    0            70548      1000194AE0C      100060B8E28     0
 0000000000B001390   0  B    0            69816      1000194AE0C      100060BCE28     0
 0000000000A001395   0  B    0            70800      1000194AE0C      100060C0E28     0
 0000000000A00139A   0  B    0            70836      1000194AE0C      100060C4E28     0
 0000000000900139F   0  B    0            70452      1000194AE0C      100060C8E28     0
 000000000080013A4   0  B    0            67896      1000194AE0C      100060CCE28     0
 000000000080013A9   0  B    0            70860      1000194AE0C      100060D0E28     0
#
# threads -ps threads
            Thread Pri St  Err               PC         StackPtr
 0000000001F001ADA  50  r    0      1000194AD04      10003834EA8
#
# sleep 10000 &
#
# threads -ps sleep
            Thread Pri St  Err               PC         StackPtr
 00000000021001ADA  50  B    0      100037AC61A      10003886F50
#