blob: a864c084a7c76b195dc57b41fed80856c44ffe55 [file] [log] [blame] [view]
# zx_thread_start
<!-- Updated by update-docs-from-abigen, do not edit. -->
Start execution on a thread.
<!-- Updated by update-docs-from-abigen, do not edit. -->
#include <zircon/syscalls.h>
zx_status_t zx_thread_start(zx_handle_t handle,
zx_vaddr_t thread_entry,
zx_vaddr_t stack,
uintptr_t arg1,
uintptr_t arg2);
`zx_thread_start()` causes a thread to begin execution at the program counter
specified by *thread_entry* and with the stack pointer set to *stack*. The
arguments *arg1* and *arg2* are arranged to be in the architecture specific
registers used for the first two arguments of a function call before the thread
is started. All other registers are zero upon start.
When the last handle to a thread is closed, the thread is destroyed.
Thread handles may be waited on and will assert the signal
**ZX_THREAD_TERMINATED** when the thread stops executing (due to
[`zx_thread_exit()`] being called).
*thread_entry* shall point to a function that must call [`zx_thread_exit()`] or
[`zx_futex_wake_handle_close_thread_exit()`] or
[`zx_vmar_unmap_handle_close_thread_exit()`] before reaching the last instruction.
Below is an example:
void thread_entry(uintptr_t arg1, uintptr_t arg2) __attribute__((noreturn)) {
// do work here.
Failing to call one of the exit functions before reaching the end of
the function will cause an architecture / toolchain specific exception.
<!-- Updated by update-docs-from-abigen, do not edit. -->
*handle* must be of type **ZX_OBJ_TYPE_THREAD** and have **ZX_RIGHT_MANAGE_THREAD**.
`zx_thread_start()` returns **ZX_OK** on success.
In the event of failure, a negative error value is returned.
**ZX_ERR_BAD_HANDLE** *thread* is not a valid handle.
**ZX_ERR_WRONG_TYPE** *thread* is not a thread handle.
**ZX_ERR_ACCESS_DENIED** The handle *thread* lacks **ZX_RIGHT_WRITE**.
**ZX_ERR_BAD_STATE** *thread* is not ready to run or the process *thread*
is part of is no longer alive.
- [`zx_futex_wake_handle_close_thread_exit()`]
- [`zx_handle_close()`]
- [`zx_handle_duplicate()`]
- [`zx_object_wait_async()`]
- [`zx_object_wait_many()`]
- [`zx_object_wait_one()`]
- [`zx_thread_create()`]
- [`zx_thread_exit()`]
- [`zx_vmar_unmap_handle_close_thread_exit()`]
<!-- References updated by update-docs-from-abigen, do not edit. -->