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