1# zx_task_suspend_token 2 3This function replaces [task_suspend](task_suspend.md). When all callers are 4updated, [`zx_task_suspend()`] will be deleted and this function will be renamed 5[`zx_task_suspend()`]. 6 7## NAME 8 9<!-- Updated by update-docs-from-abigen, do not edit. --> 10 11task_suspend_token - suspend the given task. Currently only thread or process handles may be suspended. 12 13## SYNOPSIS 14 15<!-- Updated by update-docs-from-abigen, do not edit. --> 16 17``` 18#include <zircon/syscalls.h> 19 20zx_status_t zx_task_suspend_token(zx_handle_t handle, zx_handle_t* token); 21``` 22 23## DESCRIPTION 24 25`zx_task_suspend_token()` causes the requested task to suspend execution. Task 26suspension is not synchronous and the task might not be suspended before the 27call returns. The task will be suspended soon after `zx_task_suspend_token()` is 28invoked, unless it is currently blocked in the kernel, in which case it will 29suspend after being unblocked. 30 31Invoking [`zx_task_kill()`] on a task that is suspended will successfully kill 32the task. 33 34## RESUMING 35 36The allow the task to resume, close the suspend token handle. The task will 37remain suspended as long as there are any open suspend tokens. Like suspending, 38resuming is asynchronous so the thread may not be in a running state when the 39[`zx_handle_close()`] call returns, even if no other suspend tokens 40are open. 41 42## RIGHTS 43 44<!-- Updated by update-docs-from-abigen, do not edit. --> 45 46*handle* must be of type **ZX_OBJ_TYPE_THREAD** or **ZX_OBJ_TYPE_PROCESS** and have **ZX_RIGHT_WRITE**. 47 48## RETURN VALUE 49 50[`zx_task_suspend()`] returns **ZX_OK** on success. 51In the event of failure, a negative error value is returned. 52 53## ERRORS 54 55**ZX_ERR_BAD_HANDLE** *handle* is not a valid handle. 56 57**ZX_ERR_WRONG_TYPE** *handle* is not a thread handle. 58 59**ZX_ERR_INVALID_ARGS** *token* was an invalid pointer. 60 61**ZX_ERR_BAD_STATE** The task is not in a state where suspending is possible. 62 63## LIMITATIONS 64 65Currently only thread handles are supported. 66 67<!-- References updated by update-docs-from-abigen, do not edit. --> 68 69[`zx_handle_close()`]: handle_close.md 70[`zx_task_kill()`]: task_kill.md 71[`zx_task_suspend()`]: task_suspend.md 72