1# zx_thread_start
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7thread_start - start execution on a thread
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_start(zx_handle_t handle,
17                            zx_vaddr_t thread_entry,
18                            zx_vaddr_t stack,
19                            uintptr_t arg1,
20                            uintptr_t arg2);
21```
22
23## DESCRIPTION
24
25`zx_thread_start()` causes a thread to begin execution at the program counter
26specified by *thread_entry* and with the stack pointer set to *stack*. The
27arguments *arg1* and *arg2* are arranged to be in the architecture specific
28registers used for the first two arguments of a function call before the thread
29is started.  All other registers are zero upon start.
30
31When the last handle to a thread is closed, the thread is destroyed.
32
33Thread handles may be waited on and will assert the signal
34**ZX_THREAD_TERMINATED** when the thread stops executing (due to
35[`zx_thread_exit()`] being called).
36
37*thread_entry* shall point to a function that must call [`zx_thread_exit()`] or
38[`zx_futex_wake_handle_close_thread_exit()`] or
39[`zx_vmar_unmap_handle_close_thread_exit()`] before reaching the last instruction.
40Below is an example:
41
42```
43void thread_entry(uintptr_t arg1, uintptr_t arg2) __attribute__((noreturn)) {
44	// do work here.
45
46	zx_thread_exit();
47}
48```
49
50Failing to call one of the exit functions before reaching the end of
51the function will cause an architecture / toolchain specific exception.
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_MANAGE_THREAD**.
58
59## RETURN VALUE
60
61`zx_thread_start()` 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**  *thread* is not a valid handle.
67
68**ZX_ERR_WRONG_TYPE**  *thread* is not a thread handle.
69
70**ZX_ERR_ACCESS_DENIED**  The handle *thread* lacks **ZX_RIGHT_WRITE**.
71
72**ZX_ERR_BAD_STATE**  *thread* is not ready to run or the process *thread*
73is part of is no longer alive.
74
75## SEE ALSO
76
77 - [`zx_futex_wake_handle_close_thread_exit()`]
78 - [`zx_handle_close()`]
79 - [`zx_handle_duplicate()`]
80 - [`zx_object_wait_async()`]
81 - [`zx_object_wait_many()`]
82 - [`zx_object_wait_one()`]
83 - [`zx_thread_create()`]
84 - [`zx_thread_exit()`]
85 - [`zx_vmar_unmap_handle_close_thread_exit()`]
86
87<!-- References updated by update-docs-from-abigen, do not edit. -->
88
89[`zx_futex_wake_handle_close_thread_exit()`]: futex_wake_handle_close_thread_exit.md
90[`zx_handle_close()`]: handle_close.md
91[`zx_handle_duplicate()`]: handle_duplicate.md
92[`zx_object_wait_async()`]: object_wait_async.md
93[`zx_object_wait_many()`]: object_wait_many.md
94[`zx_object_wait_one()`]: object_wait_one.md
95[`zx_thread_create()`]: thread_create.md
96[`zx_thread_exit()`]: thread_exit.md
97[`zx_vmar_unmap_handle_close_thread_exit()`]: vmar_unmap_handle_close_thread_exit.md
98