1# zx_job_create
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7job_create - create a new job
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_job_create(zx_handle_t parent_job,
17                          uint32_t options,
18                          zx_handle_t* out);
19```
20
21## DESCRIPTION
22
23`zx_job_create()` creates a new child [job object](../objects/job.md) given a
24parent job.
25
26Upon success a handle for the new job is returned.
27
28The kernel keeps track of and restricts the "height" of a job, which is its
29distance from the root job. It is illegal to create a job under a parent whose
30height exceeds an internal "max height" value. (It is, however, legal to create
31a process under such a job.)
32
33Job handles may be waited on (TODO(cpu): expand this)
34
35## RIGHTS
36
37<!-- Updated by update-docs-from-abigen, do not edit. -->
38
39*parent_job* must be of type **ZX_OBJ_TYPE_JOB** and have **ZX_RIGHT_MANAGE_JOB**.
40
41## RETURN VALUE
42
43`zx_job_create()` returns **ZX_OK** and a handle to the new job
44(via *out*) on success.  In the event of failure, a negative error value
45is returned.
46
47## ERRORS
48
49**ZX_ERR_BAD_HANDLE**  *parent_job* is not a valid handle.
50
51**ZX_ERR_WRONG_TYPE**  *parent_job* is not a job handle.
52
53**ZX_ERR_INVALID_ARGS**  *options* is nonzero, or *out* is an invalid pointer.
54
55**ZX_ERR_ACCESS_DENIED**  *parent_job* does not have the **ZX_RIGHT_WRITE** or
56**ZX_RIGHT_MANAGE_JOB** right.
57
58**ZX_ERR_OUT_OF_RANGE**  The height of *parent_job* is too large to create a child job.
59
60**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
61There is no good way for userspace to handle this (unlikely) error.
62In a future build this error will no longer occur.
63
64**ZX_ERR_BAD_STATE**  The parent job object is in the dead state.
65
66## SEE ALSO
67
68 - [`zx_object_get_property()`]
69 - [`zx_process_create()`]
70 - [`zx_task_kill()`]
71
72<!-- References updated by update-docs-from-abigen, do not edit. -->
73
74[`zx_object_get_property()`]: object_get_property.md
75[`zx_process_create()`]: process_create.md
76[`zx_task_kill()`]: task_kill.md
77