1# zx_job_set_policy
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7job_set_policy - Set job security and resource policies.
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_set_policy(zx_handle_t handle,
17                              uint32_t options,
18                              uint32_t topic,
19                              const void* policy,
20                              uint32_t count);
21```
22
23## DESCRIPTION
24
25Sets one or more security and/or resource policies to an empty job. The job's
26effective policies is the combination of the parent's effective policies and
27the policies specified in *policy*. The effect in the case of conflict between
28the existing policies and the new policies is controlled by *options* values:
29
30+ **ZX_JOB_POL_RELATIVE** : policy is applied for the conditions not specifically
31  overridden by the parent policy.
32+ **ZX_JOB_POL_ABSOLUTE** : policy is applied for all conditions in *policy* or
33  the syscall fails.
34
35After this call succeeds any new child process or child job will have the new
36effective policy applied to it.
37
38*topic* indicates the *policy* format. Supported value is **ZX_JOB_POL_BASIC**
39which indicates that *policy* is an array of *count* entries of:
40
41```
42typedef struct zx_policy_basic {
43    uint32_t condition;
44    uint32_t policy;
45} zx_policy_basic_t;
46
47```
48
49Where *condition* is one of
50+ **ZX_POL_BAD_HANDLE** a process under this job is attempting to
51  issue a syscall with an invalid handle.  In this case,
52  **ZX_POL_ACTION_ALLOW** and **ZX_POL_ACTION_DENY** are equivalent:
53  if the syscall returns, it will always return the error
54  **ZX_ERR_BAD_HANDLE**.
55+ **ZX_POL_WRONG_OBJECT** a process under this job is attempting to
56  issue a syscall with a handle that does not support such operation.
57+ **ZX_POL_VMAR_WX** a process under this job is attempting to map an
58  address region with write-execute access.
59+ **ZX_POL_NEW_VMO** a process under this job is attempting to create
60  a new vm object.
61+ **ZX_POL_NEW_CHANNEL** a process under this job is attempting to create
62  a new channel.
63+ **ZX_POL_NEW_EVENT** a process under this job is attempting to create
64  a new event.
65+ **ZX_POL_NEW_EVENTPAIR** a process under this job is attempting to create
66  a new event pair.
67+ **ZX_POL_NEW_PORT** a process under this job is attempting to create
68  a new port.
69+ **ZX_POL_NEW_SOCKET** a process under this job is attempting to create
70  a new socket.
71+ **ZX_POL_NEW_FIFO** a process under this job is attempting to create
72  a new fifo.
73+ **ZX_POL_NEW_TIMER** a process under this job is attempting to create
74  a new timer.
75+ **ZX_POL_NEW_PROCESS** a process under this job is attempting to create
76  a new process.
77+ **ZX_POL_NEW_ANY** is a special *condition* that stands for all of
78  the above **ZX_NEW** condtions such as **ZX_POL_NEW_VMO**,
79  **ZX_POL_NEW_CHANNEL**, **ZX_POL_NEW_EVENT**, **ZX_POL_NEW_EVENTPAIR**,
80  **ZX_POL_NEW_PORT**, **ZX_POL_NEW_SOCKET**, **ZX_POL_NEW_FIFO**,
81  and any future **ZX_NEW** policy. This will include any new
82  kernel objects which do not require a parent object for creation.
83
84Where *policy* is either
85+ **ZX_POL_ACTION_ALLOW**  allow *condition*.
86+ **ZX_POL_ACTION_DENY**  prevent *condition*.
87
88Optionally it can be augmented via OR with
89+ **ZX_POL_ACTION_EXCEPTION** generate an exception via the debug port. An
90  exception generated this way acts as a breakpoint. The thread may be
91  resumed after the exception.
92+ **ZX_POL_ACTION_KILL** terminate the process. It also
93implies **ZX_POL_ACTION_DENY**.
94
95## RIGHTS
96
97<!-- Updated by update-docs-from-abigen, do not edit. -->
98
99*handle* must be of type **ZX_OBJ_TYPE_JOB** and have **ZX_RIGHT_SET_POLICY**.
100
101## RETURN VALUE
102
103`zx_job_set_policy()` returns **ZX_OK** on success.  In the event of failure,
104a negative error value is returned.
105
106## NOTES
107
108The **ZX_POL_BAD_HANDLE** policy does not apply when calling [`zx_object_get_info()`]
109with the topic **ZX_INFO_HANDLE_VALID**.  All other topics and all other syscalls that
110take handles are subject to the policy.
111
112## ERRORS
113
114**ZX_ERR_INVALID_ARGS**  *policy* was not a valid pointer, or *count* was 0,
115or *policy* was not **ZX_JOB_POL_RELATIVE** or **ZX_JOB_POL_ABSOLUTE**, or
116*topic* was not **ZX_JOB_POL_BASIC**.
117
118**ZX_ERR_BAD_HANDLE**  *handle* is not valid handle.
119
120**ZX_ERR_WRONG_TYPE**  *handle* is not a job handle.
121
122**ZX_ERR_ACCESS_DENIED**  *handle* does not have **ZX_POL_RIGHT_SET** right.
123
124**ZX_ERR_BAD_STATE**  the job has existing jobs or processes alive.
125
126**ZX_ERR_OUT_OF_RANGE** *count* is bigger than **ZX_POL_MAX** or *condition* is
127bigger than **ZX_POL_MAX**.
128
129**ZX_ERR_ALREADY_EXISTS** existing policy conflicts with the new policy.
130
131**ZX_ERR_NOT_SUPPORTED** an entry in *policy* has an invalid value.
132
133**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
134There is no good way for userspace to handle this (unlikely) error.
135In a future build this error will no longer occur.
136
137## SEE ALSO
138
139 - [`zx_job_create()`]
140 - [`zx_object_get_info()`]
141 - [`zx_process_create()`]
142
143<!-- References updated by update-docs-from-abigen, do not edit. -->
144
145[`zx_job_create()`]: job_create.md
146[`zx_object_get_info()`]: object_get_info.md
147[`zx_process_create()`]: process_create.md
148