1# zx_thread_read_state
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7thread_read_state - Read one aspect of thread state.
8
9## SYNOPSIS
10
11<!-- Updated by update-docs-from-abigen, do not edit. -->
12
13```
14#include <zircon/syscalls.h>
15
16zx_status_t zx_thread_read_state(zx_handle_t handle,
17                                 uint32_t kind,
18                                 void* buffer,
19                                 size_t buffer_size);
20```
21
22## DESCRIPTION
23
24`zx_thread_read_state()` reads one aspect of state of the thread. The thread
25state may only be read when the thread is halted for an exception or the thread
26is suspended.
27
28The thread state is highly processor specific. See the structures in
29zircon/syscalls/debug.h for the contents of the structures on each platform.
30
31## STATES
32
33### ZX_THREAD_STATE_GENERAL_REGS
34
35The buffer must point to a `zx_thread_state_general_regs_t` structure that
36contains the general registers for the current architecture.
37
38### ZX_THREAD_STATE_FP_REGS
39
40The buffer must point to a `zx_thread_state_fp_regs_t` structure. On 64-bit
41ARM platforms, float point state is in the vector registers and this structure
42is empty.
43
44### ZX_THREAD_STATE_VECTOR_REGS
45
46The buffer must point to a `zx_thread_state_vector_regs_t` structure.
47
48### ZX_THREAD_STATE_DEBUG_REGS
49
50The buffer must point to a `zx_thread_state_debug_regs_t` structure. All input
51fields will be ignored and overwritten with the actual values for the thread.
52
53### ZX_THREAD_STATE_SINGLE_STEP
54
55The buffer must point to a `zx_thread_state_single_step_t` value which
56may contain either 0 (normal running), or 1 (single stepping enabled).
57
58### ZX_THREAD_X86_REGISTER_FS
59
60The buffer must point to a `zx_thread_x86_register_fs_t` structure which contains
61a uint64. This is only relevant on x86 platforms.
62
63### ZX_THREAD_X86_REGISTER_GS
64
65The buffer must point to a `zx_thread_x86_register_gs_t` structure which contains
66a uint64. This is only relevant on x86 platforms.
67
68## RIGHTS
69
70<!-- Updated by update-docs-from-abigen, do not edit. -->
71
72*handle* must be of type **ZX_OBJ_TYPE_THREAD** and have **ZX_RIGHT_READ**.
73
74## RETURN VALUE
75
76`zx_thread_read_state()` returns **ZX_OK** on success.
77In the event of failure, a negative error value is returned.
78
79## ERRORS
80
81**ZX_ERR_BAD_HANDLE**  *handle* is not a valid handle.
82
83**ZX_ERR_WRONG_TYPE**  *handle* is not that of a thread.
84
85**ZX_ERR_ACCESS_DENIED**  *handle* lacks **ZX_RIGHT_READ**.
86
87**ZX_ERR_INVALID_ARGS**  *kind* is not valid or *buffer* is an invalid pointer.
88
89**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
90There is no good way for userspace to handle this (unlikely) error.
91In a future build this error will no longer occur.
92
93**ZX_ERR_BUFFER_TOO_SMALL**  The buffer length *buffer_size* is too small to
94hold the data required by *kind*.
95
96**ZX_ERR_BAD_STATE**  The thread is not stopped at a point where state
97is available. The thread state may only be read when the thread is stopped due
98to an exception.
99
100**ZX_ERR_NOT_SUPPORTED**  *kind* is not supported.
101This can happen, for example, when trying to read a register set that
102is not supported by the hardware the program is currently running on.
103
104## SEE ALSO
105
106
107[thread_write_state](thread_write_state.md).
108