1# zx_process_create
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7process_create - create a new process
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_process_create(zx_handle_t job,
17                              const char* name,
18                              size_t name_size,
19                              uint32_t options,
20                              zx_handle_t* proc_handle,
21                              zx_handle_t* vmar_handle);
22```
23
24## DESCRIPTION
25
26`zx_process_create()` creates a new process.
27
28Upon success, handles for the new process and the root of its address space
29are returned.  The thread will not start executing until [`zx_process_start()`] is
30called.
31
32*name* is silently truncated to a maximum of `ZX_MAX_NAME_LEN-1` characters.
33
34When the last handle to a process is closed, the process is destroyed.
35
36Process handles may be waited on and will assert the signal
37**ZX_PROCESS_TERMINATED** when the process exits.
38
39*job* is the controlling [job object](../objects/job.md) for the new
40process, which will become a child of that job.
41
42## RIGHTS
43
44<!-- Updated by update-docs-from-abigen, do not edit. -->
45
46*job* must be of type **ZX_OBJ_TYPE_JOB** and have **ZX_RIGHT_MANAGE_PROCESS**.
47
48## RETURN VALUE
49
50On success, `zx_process_create()` returns **ZX_OK**, a handle to the new process
51(via *proc_handle*), and a handle to the root of its address space (via
52*vmar_handle*).  In the event of failure, a negative error value is returned.
53
54## ERRORS
55
56**ZX_ERR_BAD_HANDLE**  *job* is not a valid handle.
57
58**ZX_ERR_WRONG_TYPE**  *job* is not a job handle.
59
60**ZX_ERR_ACCESS_DENIED**  *job* does not have the **ZX_RIGHT_WRITE** right
61(only when not **ZX_HANDLE_INVALID**).
62
63**ZX_ERR_INVALID_ARGS**  *name*, *proc_handle*, or *vmar_handle*  was an invalid pointer,
64or *options* was non-zero.
65
66**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
67There is no good way for userspace to handle this (unlikely) error.
68In a future build this error will no longer occur.
69
70**ZX_ERR_BAD_STATE**  The job object is in the dead state.
71
72## SEE ALSO
73
74 - [`zx_handle_close()`]
75 - [`zx_handle_duplicate()`]
76 - [`zx_job_create()`]
77 - [`zx_object_wait_async()`]
78 - [`zx_object_wait_many()`]
79 - [`zx_object_wait_one()`]
80 - [`zx_process_start()`]
81 - [`zx_task_kill()`]
82 - [`zx_thread_create()`]
83 - [`zx_thread_exit()`]
84 - [`zx_thread_start()`]
85
86<!-- References updated by update-docs-from-abigen, do not edit. -->
87
88[`zx_handle_close()`]: handle_close.md
89[`zx_handle_duplicate()`]: handle_duplicate.md
90[`zx_job_create()`]: job_create.md
91[`zx_object_wait_async()`]: object_wait_async.md
92[`zx_object_wait_many()`]: object_wait_many.md
93[`zx_object_wait_one()`]: object_wait_one.md
94[`zx_process_start()`]: process_start.md
95[`zx_task_kill()`]: task_kill.md
96[`zx_thread_create()`]: thread_create.md
97[`zx_thread_exit()`]: thread_exit.md
98[`zx_thread_start()`]: thread_start.md
99