1# zx_task_suspend
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7task_suspend - suspend the given task. Currently only thread or process handles may be suspended.
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_task_suspend(zx_handle_t handle, zx_handle_t* token);
17```
18
19## DESCRIPTION
20
21`zx_task_suspend()` causes the requested task to suspend
22execution. Task suspension is not synchronous and the task might not
23be suspended before the call returns. The task will be suspended soon
24after `zx_task_suspend()` is invoked, unless it is currently blocked in
25the kernel, in which case it will suspend after being unblocked.
26
27Tasks can be suspended and/or resumed before they are started. If a task is
28started while suspended, it will enter suspension before executing any code.
29Similarly, starting a new thread on a suspended process will suspend the thread
30before it executes any code.
31
32Invoking [`zx_task_kill()`] on a task that is suspended will successfully kill
33the task.
34
35A task cannot suspend itself or any of its parent tasks because it would never
36receive the suspend token and would be unable to resume execution.
37
38## RESUMING
39
40The allow the task to resume, close the suspend token handle. The task will
41remain suspended as long as there are any open suspend tokens. Like suspending,
42resuming is asynchronous so the thread may not be in a running state when the
43[`zx_handle_close()`] call returns, even if no other suspend tokens
44are open.
45
46## SIGNALS AND EXCEPTIONS
47
48There are two relevant signals that a thread can assert:
49
50- **ZX_THREAD_RUNNING**
51- **ZX_THREAD_SUSPENDED**
52
53Neither of these will be asserted until the thread is started via
54[`zx_process_start()`] or [`zx_thread_start()`]. When
55a thread starts, it will assert **ZX_THREAD_RUNNING** whether it is suspended
56or not, but if it is suspended will then switch to **ZX_THREAD_SUSPENDED**
57before executing any code.
58
59The **ZX_EXCP_PROCESS_STARTING** and **ZX_EXCP_THREAD_STARTING** debug
60exceptions will also be sent on start whether the task is suspended or not.
61
62## RIGHTS
63
64<!-- Updated by update-docs-from-abigen, do not edit. -->
65
66*handle* must be of type **ZX_OBJ_TYPE_THREAD** or **ZX_OBJ_TYPE_PROCESS** and have **ZX_RIGHT_WRITE**.
67
68## RETURN VALUE
69
70`zx_task_suspend()` returns **ZX_OK** on success.
71In the event of failure, a negative error value is returned.
72
73## ERRORS
74
75**ZX_ERR_BAD_HANDLE** *handle* is not a valid handle.
76
77**ZX_ERR_WRONG_TYPE** *handle* is not a thread or process handle.
78
79**ZX_ERR_INVALID_ARGS**  *token*  was an invalid pointer.
80
81**ZX_ERR_BAD_STATE**  The task is already dying or dead and cannot be suspended.
82
83**ZX_ERR_NO_MEMORY**  Failed to allocate memory.
84
85**ZX_ERR_NOT_SUPPORTED**  The calling thread is attempting to suspend itself or
86                          one of its parent tasks.
87
88## LIMITATIONS
89
90Currently only thread and process handles are supported.
91
92<!-- References updated by update-docs-from-abigen, do not edit. -->
93
94[`zx_handle_close()`]: handle_close.md
95[`zx_process_start()`]: process_start.md
96[`zx_task_kill()`]: task_kill.md
97[`zx_thread_start()`]: thread_start.md
98