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