1# zx_thread_create
2
3## NAME
4
5thread_create - create a thread
6
7## SYNOPSIS
8
9```
10#include <zircon/syscalls.h>
11
12zx_status_t zx_thread_create(zx_handle_t process, const char* name, size_t name_size,
13                             uint32_t options, zx_handle_t* out);
14
15```
16
17## DESCRIPTION
18
19**thread_create**() creates a thread within the specified process.
20
21Upon success a handle for the new thread is returned.  The thread
22will not start executing until *thread_start()* is called.
23
24*name* is silently truncated to a maximum of *ZX_MAX_NAME_LEN-1* characters.
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*process* is the controlling [process object](../objects/process.md) for the
31new thread, which will become a child of that process.
32
33For thread lifecycle details see [thread object](../objects/thread.md).
34
35## RIGHTS
36
37TODO(ZX-2399)
38
39## RETURN VALUE
40
41On success, **thread_create**() returns **ZX_OK** and a handle (via *out*)
42to the new thread.  In the event of failure, a negative error value is
43returned.
44
45## ERRORS
46
47**ZX_ERR_BAD_HANDLE**  *process* is not a valid handle.
48
49**ZX_ERR_WRONG_TYPE**  *process* is not a process handle.
50
51**ZX_ERR_INVALID_ARGS**  *name* or *out* was an invalid pointer, or *options* was
52non-zero.
53
54**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
55There is no good way for userspace to handle this (unlikely) error.
56In a future build this error will no longer occur.
57
58## SEE ALSO
59
60[handle_close](handle_close.md),
61[handle_duplicate](handle_duplicate.md),
62[object_wait_one](object_wait_one.md),
63[object_wait_many](object_wait_many.md),
64[thread_exit](thread_exit.md),
65[thread_start](thread_start.md).
66