1# zx_thread_write_state
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7thread_write_state - Write 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_write_state(zx_handle_t handle,
17                                  uint32_t kind,
18                                  const void* buffer,
19                                  size_t buffer_size);
20```
21
22## DESCRIPTION
23
24`zx_thread_write_state()` writes one aspect of state of the thread. The thread
25state may only be written when the thread is halted for an exception or the
26thread is 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
33See [`zx_thread_read_state()`] for the list of available states
34and their corresponding values.
35
36### ZX_THREAD_STATE_DEBUG_REGS
37
38#### ARM
39
40ARM has a variable amount of debug breakpoints and watchpoints. For this
41architecture, `zx_thread_state_debug_regs_t` is big enough to hold the maximum
42amount of breakpoints possible. But in most cases a given CPU implementation
43holds a lesser amount, meaning that the upper values beyond the limit are not
44used.
45
46The kernel will write all the available registers in the hardware independent of
47the given breakpoint/watchpoint count value. This means that all the correct
48state must be set for the call.
49
50You can get the current state of the registers by calling
51[`zx_thread_read_state()`](thread_read_state.md#zx_thread_state_debug_regs).
52
53## RIGHTS
54
55<!-- Updated by update-docs-from-abigen, do not edit. -->
56
57*handle* must be of type **ZX_OBJ_TYPE_THREAD** and have **ZX_RIGHT_WRITE**.
58
59## RETURN VALUE
60
61`zx_thread_write_state()` returns **ZX_OK** on success.
62In the event of failure, a negative error value is returned.
63
64## ERRORS
65
66**ZX_ERR_BAD_HANDLE**  *handle* is not a valid handle.
67
68**ZX_ERR_WRONG_TYPE**  *handle* is not that of a thread.
69
70**ZX_ERR_ACCESS_DENIED**  *handle* lacks **ZX_RIGHT_WRITE**.
71
72**ZX_ERR_INVALID_ARGS**  *kind* is not valid, *buffer* is an invalid pointer,
73*buffer_size* doesn't match the size of the structure expected for *kind* or
74the given values to set are not valid.
75
76**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
77There is no good way for userspace to handle this (unlikely) error.
78In a future build this error will no longer occur.
79
80**ZX_ERR_BAD_STATE**  The thread is not stopped at a point where state
81is available. The thread state may only be read when the thread is stopped due
82to an exception.
83
84**ZX_ERR_NOT_SUPPORTED**  *kind* is not supported.
85This can happen, for example, when trying to read a register set that
86is not supported by the hardware the program is currently running on.
87
88## SEE ALSO
89
90 - [`zx_thread_read_state()`]
91
92<!-- References updated by update-docs-from-abigen, do not edit. -->
93
94[`zx_thread_read_state()`]: thread_read_state.md
95