1# zx_thread_start
2
3## NAME
4
5thread_start - start execution on a thread
6
7## SYNOPSIS
8
9```
10#include <zircon/syscalls.h>
11
12zx_status_t zx_thread_start(zx_handle_t handle, zx_vaddr_t entry, zx_vaddr_t stack,
13                            uintptr_t arg1, uintptr_t arg2);
14```
15
16## DESCRIPTION
17
18**thread_start**() causes a thread to begin execution at the program
19counter specified by *entry* and with the stack pointer set to *stack*.
20The arguments *arg1* and *arg2* are arranged to be in the architecture
21specific registers used for the first two arguments of a function call
22before the thread is started.  All other registers are zero upon start.
23
24When the last handle to a thread is closed, the thread is destroyed.
25
26Thread handles may be waited on and will assert the signal
27*ZX_THREAD_TERMINATED* when the thread stops executing (due to
28*thread_exit**() being called.
29
30*entry* shall point to a function that must call **thread_exit**() or
31**futex_wake_handle_close_thread_exit**() or
32**vmar_unmap_handle_close_thread_exit**() before reaching the last
33instruction. Below is an example:
34
35```
36void thread_entry(uintptr_t arg1, uintptr_t arg2) __attribute__((noreturn)) {
37	// do work here.
38
39	zx_thread_exit();
40}
41```
42
43Failing to call one of the exit functions before reaching the end of
44the function will cause an architecture / toolchain specific exception.
45
46## RIGHTS
47
48TODO(ZX-2399)
49
50## RETURN VALUE
51
52**thread_start**() returns ZX_OK on success.
53In the event of failure, a negative error value is returned.
54
55## ERRORS
56
57**ZX_ERR_BAD_HANDLE**  *thread* is not a valid handle.
58
59**ZX_ERR_WRONG_TYPE**  *thread* is not a thread handle.
60
61**ZX_ERR_ACCESS_DENIED**  The handle *thread* lacks *ZX_RIGHT_WRITE*.
62
63**ZX_ERR_BAD_STATE**  *thread* is not ready to run or the process *thread*
64is part of is no longer alive.
65
66## SEE ALSO
67
68[handle_close](handle_close.md),
69[handle_duplicate](handle_duplicate.md),
70[object_wait_one](object_wait_one.md),
71[object_wait_many](object_wait_many.md),
72[thread_create](thread_create.md),
73[thread_exit](thread_exit.md),
74[futex_wake_handle_close_thread_exit](futex_wake_handle_close_thread_exit.md),
75[vmar_unmap_handle_close_thread_exit](vmar_unmap_handle_close_thread_exit.md).
76