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