1# zx_thread_create
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7thread_create - create 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_create(zx_handle_t process,
17                             const char* name,
18                             size_t name_size,
19                             uint32_t options,
20                             zx_handle_t* out);
21```
22
23## DESCRIPTION
24
25`zx_thread_create()` creates a thread within the specified process.
26
27Upon success a handle for the new thread is returned.  The thread
28will not start executing until [`zx_thread_start()`] is called.
29
30*name* is silently truncated to a maximum of `ZX_MAX_NAME_LEN-1` characters.
31
32Thread handles may be waited on and will assert the signal
33**ZX_THREAD_TERMINATED** when the thread stops executing (due to
34[`zx_thread_exit()`] being called).
35
36*process* is the controlling [process object](../objects/process.md) for the
37new thread, which will become a child of that process.
38
39For thread lifecycle details see [thread object](../objects/thread.md).
40
41## RIGHTS
42
43<!-- Updated by update-docs-from-abigen, do not edit. -->
44
45*process* must be of type **ZX_OBJ_TYPE_PROCESS** and have **ZX_RIGHT_MANAGE_THREAD**.
46
47## RETURN VALUE
48
49On success, `zx_thread_create()` returns **ZX_OK** and a handle (via *out*)
50to the new thread.  In the event of failure, a negative error value is
51returned.
52
53## ERRORS
54
55**ZX_ERR_BAD_HANDLE**  *process* is not a valid handle.
56
57**ZX_ERR_WRONG_TYPE**  *process* is not a process handle.
58
59**ZX_ERR_ACCESS_DENIED**  *process* does not have the **ZX_RIGHT_MANAGE_THREAD** right.
60
61**ZX_ERR_INVALID_ARGS**  *name* or *out* was an invalid pointer, or *options* was
62non-zero.
63
64**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
65There is no good way for userspace to handle this (unlikely) error.
66In a future build this error will no longer occur.
67
68## SEE ALSO
69
70 - [`zx_handle_close()`]
71 - [`zx_handle_duplicate()`]
72 - [`zx_object_wait_async()`]
73 - [`zx_object_wait_many()`]
74 - [`zx_object_wait_one()`]
75 - [`zx_thread_exit()`]
76 - [`zx_thread_start()`]
77
78<!-- References updated by update-docs-from-abigen, do not edit. -->
79
80[`zx_handle_close()`]: handle_close.md
81[`zx_handle_duplicate()`]: handle_duplicate.md
82[`zx_object_wait_async()`]: object_wait_async.md
83[`zx_object_wait_many()`]: object_wait_many.md
84[`zx_object_wait_one()`]: object_wait_one.md
85[`zx_thread_exit()`]: thread_exit.md
86[`zx_thread_start()`]: thread_start.md
87