]> git.saurik.com Git - apple/xnu.git/blob - bsd/sys/spawn_internal.h
xnu-7195.101.1.tar.gz
[apple/xnu.git] / bsd / sys / spawn_internal.h
1 /*
2 * Copyright (c) 2006 Apple Computer, Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28
29
30 /*
31 * [SPN] Support for _POSIX_SPAWN
32 *
33 * This file contains internal data structures which are externally represented
34 * as opaque void pointers to prevent introspection. This permits us to
35 * change the underlying implementation of the code to maintain it or to
36 * support new features, as needed, without the consumer needing to recompile
37 * their code because of structure size changes or data reorganization.
38 */
39
40 #ifndef _SYS_SPAWN_INTERNAL_H_
41 #define _SYS_SPAWN_INTERNAL_H_
42
43 #include <sys/_types.h> /* __offsetof(), __darwin_size_t */
44 #include <sys/param.h>
45 #include <sys/syslimits.h> /* PATH_MAX */
46 #include <sys/spawn.h>
47 #include <mach/machine.h>
48 #include <mach/port.h>
49 #include <mach/exception_types.h>
50 #include <mach/coalition.h> /* COALITION_NUM_TYPES */
51 #include <mach/task_policy.h>
52 #include <os/overflow.h>
53
54 /*
55 * Safely compute the size in bytes of a structure, '_type', whose last
56 * element, '_member', is a zero-sized array meant to hold 'x' bytes.
57 *
58 * If the size calculation overflows a size_t value, this macro returns 0.
59 */
60 #define PS_ACTION_SIZE(x, _type, _member_type) ({\
61 size_t _ps_count = (size_t)x; \
62 size_t _ps_size = 0; \
63 /* (count * sizeof(_member_type)) + sizeof(_type) */ \
64 if (os_mul_and_add_overflow(_ps_count, \
65 sizeof(_member_type), \
66 sizeof(_type), \
67 &_ps_size)) { \
68 _ps_size = 0; \
69 } \
70 _ps_size; })
71
72 /*
73 * Allowable posix_spawn() port action types
74 */
75 typedef enum {
76 PSPA_SPECIAL = 0,
77 PSPA_EXCEPTION = 1,
78 PSPA_AU_SESSION = 2,
79 PSPA_IMP_WATCHPORTS = 3,
80 PSPA_REGISTERED_PORTS = 4,
81 PSPA_PTRAUTH_TASK_PORT = 5,
82 PSPA_SUID_CRED = 6,
83 } pspa_t;
84
85 /*
86 * Internal representation of one port to be set on posix_spawn().
87 * Currently this is limited to setting special and exception ports,
88 * but could be extended to other inheritable port types.
89 */
90 typedef struct _ps_port_action {
91 pspa_t port_type;
92 exception_mask_t mask;
93 mach_port_name_t new_port;
94 exception_behavior_t behavior;
95 thread_state_flavor_t flavor;
96 int which;
97 } _ps_port_action_t;
98
99 /*
100 * A collection of port actions to take on the newly spawned process.
101 */
102 typedef struct _posix_spawn_port_actions {
103 int pspa_alloc;
104 int pspa_count;
105 _ps_port_action_t pspa_actions[];
106 } *_posix_spawn_port_actions_t;
107
108 /*
109 * Returns size in bytes of a _posix_spawn_port_actions holding x elements.
110 */
111 #define PS_PORT_ACTIONS_SIZE(x) \
112 PS_ACTION_SIZE(x, struct _posix_spawn_port_actions, _ps_port_action_t)
113
114 #define NBINPREFS 4
115
116 /*
117 * Mapping of opaque data pointer to a MAC policy (specified by name).
118 */
119 typedef struct _ps_mac_policy_extension {
120 char policyname[128];
121 union {
122 uint64_t data;
123 void *datap; /* pointer in kernel memory */
124 };
125 uint64_t datalen;
126 } _ps_mac_policy_extension_t;
127
128 /*
129 * A collection of extra data passed to MAC policies for the newly spawned process.
130 */
131 typedef struct _posix_spawn_mac_policy_extensions {
132 int psmx_alloc;
133 int psmx_count;
134 _ps_mac_policy_extension_t psmx_extensions[];
135 } *_posix_spawn_mac_policy_extensions_t;
136
137 /*
138 * Returns size in bytes of a _posix_spawn_mac_policy_extensions holding x elements.
139 */
140 #define PS_MAC_EXTENSIONS_SIZE(x) \
141 PS_ACTION_SIZE(x, struct _posix_spawn_mac_policy_extensions, _ps_mac_policy_extension_t)
142
143 #define PS_MAC_EXTENSIONS_INIT_COUNT 2
144
145 /*
146 * Coalition posix spawn attributes
147 */
148 struct _posix_spawn_coalition_info {
149 struct {
150 uint64_t psci_id;
151 uint32_t psci_role;
152 uint32_t psci_reserved1;
153 uint64_t psci_reserved2;
154 } psci_info[COALITION_NUM_TYPES];
155 };
156
157 /*
158 * UID/GID attributes
159 */
160 struct _posix_spawn_posix_cred_info {
161 uint32_t pspci_flags; /* spawn persona flags */
162 uid_t pspci_uid; /* alternate posix/unix UID */
163 gid_t pspci_gid; /* alternate posix/unix GID */
164 uint32_t pspci_ngroups; /* alternate advisory groups */
165 gid_t pspci_groups[NGROUPS];
166 uid_t pspci_gmuid; /* group membership UID */
167 char pspci_login[MAXLOGNAME + 1];
168 };
169
170 #define POSIX_SPAWN_POSIX_CRED_UID 0x00010000
171 #define POSIX_SPAWN_POSIX_CRED_GID 0x00020000
172 #define POSIX_SPAWN_POSIX_CRED_GROUPS 0x00040000
173 #define POSIX_SPAWN_POSIX_CRED_LOGIN 0x00080000
174
175 /*
176 * Persona attributes
177 */
178 struct _posix_spawn_persona_info {
179 uid_t pspi_id; /* persona ID (unix UID) */
180 uint32_t pspi_flags; /* spawn persona flags */
181 uid_t pspi_uid; /* alternate posix/unix UID */
182 gid_t pspi_gid; /* alternate posix/unix GID */
183 uint32_t pspi_ngroups; /* alternate advisory groups */
184 gid_t pspi_groups[NGROUPS];
185 uid_t pspi_gmuid; /* group membership UID */
186 };
187
188 #define POSIX_SPAWN_PERSONA_FLAGS_NONE 0x0
189 #define POSIX_SPAWN_PERSONA_FLAGS_OVERRIDE 0x1
190 #define POSIX_SPAWN_PERSONA_FLAGS_VERIFY 0x2
191
192 #define POSIX_SPAWN_PERSONA_ALL_FLAGS \
193 (POSIX_SPAWN_PERSONA_FLAGS_OVERRIDE \
194 | POSIX_SPAWN_PERSONA_FLAGS_VERIFY \
195 )
196
197 #define POSIX_SPAWN_PERSONA_UID POSIX_SPAWN_POSIX_CRED_UID
198 #define POSIX_SPAWN_PERSONA_GID POSIX_SPAWN_POSIX_CRED_GID
199 #define POSIX_SPAWN_PERSONA_GROUPS POSIX_SPAWN_POSIX_CRED_GROUPS
200
201
202 /*
203 * A posix_spawnattr structure contains all of the attribute elements that
204 * can be set, as well as any metadata whose validity is signalled by the
205 * presence of a bit in the flags field. All fields are initialized to the
206 * appropriate default values by posix_spawnattr_init().
207 *
208 * Fields must be added at the end of this, but before extensions array
209 * pointers.
210 */
211
212 typedef struct _posix_spawnattr {
213 short psa_flags; /* spawn attribute flags */
214 short flags_padding; /* get the flags to be int aligned */
215 sigset_t psa_sigdefault; /* signal set to default */
216 sigset_t psa_sigmask; /* signal set to mask */
217 pid_t psa_pgroup; /* pgroup to spawn into */
218 cpu_type_t psa_binprefs[NBINPREFS]; /* cpu affinity prefs*/
219 int psa_pcontrol; /* process control bits on resource starvation */
220 int psa_apptype; /* app type and process spec behav */
221 uint64_t psa_cpumonitor_percent; /* CPU usage monitor percentage */
222 uint64_t psa_cpumonitor_interval; /* CPU usage monitor interval, in seconds */
223 uint64_t psa_reserved;
224
225 short psa_jetsam_flags; /* jetsam flags */
226 short short_padding; /* Padding for alignment issues */
227 int psa_priority; /* jetsam relative importance */
228 int psa_memlimit_active; /* jetsam memory limit (in MB) when process is active */
229 int psa_memlimit_inactive; /* jetsam memory limit (in MB) when process is inactive */
230
231 uint64_t psa_qos_clamp; /* QoS Clamp to set on the new process */
232 task_role_t psa_darwin_role; /* PRIO_DARWIN_ROLE to set on the new process */
233 int psa_thread_limit; /* thread limit */
234
235 uint64_t psa_max_addr; /* Max valid VM address */
236 bool psa_no_smt;
237 bool psa_tecs;
238 int psa_platform; /* Plaform for the binary */
239
240 cpu_subtype_t psa_subcpuprefs[NBINPREFS]; /* subcpu affinity prefs*/
241 uint32_t psa_options; /* More options to be passed to posix_spawn */
242 /*
243 * NOTE: Extensions array pointers must stay at the end so that
244 * everything above this point stays the same size on different bitnesses
245 * see <rdar://problem/12858307>
246 */
247 _posix_spawn_port_actions_t psa_ports; /* special/exception ports */
248 _posix_spawn_mac_policy_extensions_t psa_mac_extensions; /* MAC policy-specific extensions. */
249 struct _posix_spawn_coalition_info *psa_coalition_info; /* coalition info */
250 struct _posix_spawn_persona_info *psa_persona_info; /* spawn new process into given persona */
251 struct _posix_spawn_posix_cred_info *psa_posix_cred_info; /* posix creds: uid/gid/groups */
252 char *psa_subsystem_root_path; /* pass given path in apple strings */
253 } *_posix_spawnattr_t;
254
255 /*
256 * Jetsam flags eg: psa_jetsam_flags
257 */
258 #define POSIX_SPAWN_JETSAM_SET 0x8000
259
260 #define POSIX_SPAWN_JETSAM_USE_EFFECTIVE_PRIORITY 0x01
261 #define POSIX_SPAWN_JETSAM_HIWATER_BACKGROUND 0x02 /* to be deprecated */
262 #define POSIX_SPAWN_JETSAM_MEMLIMIT_FATAL 0x04 /* to be deprecated */
263
264 /*
265 * Additional flags available for use with
266 * the posix_spawnattr_setjetsam_ext() call
267 */
268 #define POSIX_SPAWN_JETSAM_MEMLIMIT_ACTIVE_FATAL 0x04 /* if set, limit is fatal when the process is active */
269 #define POSIX_SPAWN_JETSAM_MEMLIMIT_INACTIVE_FATAL 0x08 /* if set, limit is fatal when the process is inactive */
270
271
272 /*
273 * Flags set based on posix_spawnattr_set_jetsam_ttr_np().
274 * Indicate relaunch behavior of process when jetsammed
275 */
276 /* Mask and bucket counts for relaunch behavior */
277 #define POSIX_SPAWN_JETSAM_RELAUNCH_BEHAVIOR_BUCKETS (0x3)
278 #define POSIX_SPAWN_JETSAM_RELAUNCH_BEHAVIOR_MASK (0x30)
279
280 /* Actual buckets based on behavior data */
281 #define POSIX_SPAWN_JETSAM_RELAUNCH_BEHAVIOR_HIGH (0x30)
282 #define POSIX_SPAWN_JETSAM_RELAUNCH_BEHAVIOR_MED (0x20)
283 #define POSIX_SPAWN_JETSAM_RELAUNCH_BEHAVIOR_LOW (0x10)
284
285 /*
286 * Deprecated posix_spawn psa_flags values
287 *
288 * POSIX_SPAWN_OSX_TALAPP_START 0x0400
289 * POSIX_SPAWN_IOS_RESV1_APP_START 0x0400
290 * POSIX_SPAWN_IOS_APPLE_DAEMON_START 0x0800
291 * POSIX_SPAWN_IOS_APP_START 0x1000
292 * POSIX_SPAWN_OSX_WIDGET_START 0x0800
293 * POSIX_SPAWN_OSX_DBCLIENT_START 0x0800
294 * POSIX_SPAWN_OSX_RESVAPP_START 0x1000
295 */
296
297 /*
298 * Deprecated posix_spawn psa_apptype values
299 *
300 * POSIX_SPAWN_PROCESS_TYPE_APPLEDAEMON 0x00000001
301 * POSIX_SPAWN_PROCESS_TYPE_UIAPP 0x00000002
302 * POSIX_SPAWN_PROCESS_TYPE_ADAPTIVE 0x00000004
303 * POSIX_SPAWN_PROCESS_TYPE_TAL 0x00000001
304 * POSIX_SPAWN_PROCESS_TYPE_WIDGET 0x00000002
305 * POSIX_SPAWN_PROCESS_TYPE_DELAYIDLESLEEP 0x10000000
306 *
307 * POSIX_SPAWN_PROCESS_FLAG_IMPORTANCE_DONOR 0x00000010
308 * POSIX_SPAWN_PROCESS_FLAG_ADAPTIVE 0x00000020
309 * POSIX_SPAWN_PROCESS_FLAG_START_BACKGROUND 0x00000040
310 * POSIX_SPAWN_PROCESS_FLAG_START_LIGHT_THROTTLE 0x00000080
311 */
312
313 /*
314 * posix_spawn psa_apptype process type settings.
315 * when POSIX_SPAWN_PROC_TYPE is set, old psa_apptype bits are ignored
316 */
317 #define POSIX_SPAWN_PROCESS_TYPE_NORMAL 0x00000000
318 #define POSIX_SPAWN_PROCESS_TYPE_DEFAULT POSIX_SPAWN_PROCESS_TYPE_NORMAL
319
320 #define POSIX_SPAWN_PROC_TYPE_MASK 0x00000F00
321
322 #define POSIX_SPAWN_PROC_TYPE_APP_DEFAULT 0x00000100
323 #define POSIX_SPAWN_PROC_TYPE_APP_TAL 0x00000200 /* unused */
324
325 #define POSIX_SPAWN_PROC_TYPE_DAEMON_STANDARD 0x00000300
326 #define POSIX_SPAWN_PROC_TYPE_DAEMON_INTERACTIVE 0x00000400
327 #define POSIX_SPAWN_PROC_TYPE_DAEMON_BACKGROUND 0x00000500
328 #define POSIX_SPAWN_PROC_TYPE_DAEMON_ADAPTIVE 0x00000600
329
330 #define POSIX_SPAWN_PROC_TYPE_DRIVER 0x00000700
331
332 #define POSIX_SPAWN_PROC_CLAMP_NONE 0x00000000
333 #define POSIX_SPAWN_PROC_CLAMP_UTILITY 0x00000001
334 #define POSIX_SPAWN_PROC_CLAMP_BACKGROUND 0x00000002
335 #define POSIX_SPAWN_PROC_CLAMP_MAINTENANCE 0x00000003
336 #define POSIX_SPAWN_PROC_CLAMP_LAST 0x00000004
337
338 #define POSIX_SPAWN_ENTITLEMENT_DRIVER "com.apple.private.spawn-driver"
339 /* Setting to indicate no change to darwin role */
340 #define POSIX_SPAWN_DARWIN_ROLE_NONE 0x00000000
341 /* Other possible values are specified by PRIO_DARWIN_ROLE in sys/resource.h */
342
343 /* Other posix spawn options passed through psa_options */
344 __options_decl(posix_spawn_options, uint32_t, {
345 PSA_OPTION_NONE = 0,
346 PSA_OPTION_PLUGIN_HOST_DISABLE_A_KEYS = 0x1,
347 });
348
349 /*
350 * Allowable posix_spawn() file actions
351 */
352 typedef enum {
353 PSFA_OPEN = 0,
354 PSFA_CLOSE = 1,
355 PSFA_DUP2 = 2,
356 PSFA_INHERIT = 3,
357 PSFA_FILEPORT_DUP2 = 4,
358 PSFA_CHDIR = 5,
359 PSFA_FCHDIR = 6
360 } psfa_t;
361
362
363 /*
364 * A posix_spawn() file action record for a single action
365 *
366 * Notes: We carry around the full open arguments for both the open
367 * and the close to permit the use of a single array of action
368 * elements to be associated with a file actions object.
369 *
370 * A possible future optimization would be to break this into
371 * a variable sized vector list to save space (i.e. a separate
372 * string area, allocation of least amount of path buffer per
373 * open action, etc.).
374 */
375 typedef struct _psfa_action {
376 psfa_t psfaa_type; /* file action type */
377 union {
378 int psfaa_filedes; /* fd to operate on */
379 mach_port_name_t psfaa_fileport; /* fileport to operate on */
380 };
381 union {
382 struct {
383 int psfao_oflag; /* open flags to use */
384 mode_t psfao_mode; /* mode for open */
385 char psfao_path[PATH_MAX]; /* path to open */
386 } psfaa_openargs;
387 struct {
388 int psfad_newfiledes; /* new file descriptor to use */
389 } psfaa_dup2args;
390 struct {
391 char psfac_path[PATH_MAX]; /* path to chdir */
392 } psfaa_chdirargs;
393 };
394 } _psfa_action_t;
395
396
397 /*
398 * Internal representation of posix_spawn() file actions structure
399 *
400 * Notes: This is implemented as a structure followed by an array of
401 * file action records. The psfa_act_alloc value is the number
402 * of elements allocated in this array, and the psfa_act_count is
403 * the number of elements currently in use (to permit some form
404 * of preallocation, e.g. a power of 2 growth for reallocation,
405 * etc.).
406 *
407 * A possible future optimization would keep a size value and
408 * a structure base reference pointer to permit copyin to the
409 * kernel directly as a single blob, without damaging relative
410 * internal pointer math. It's probably better that this be a
411 * long long rather than a true pointer, to make it invariant
412 * for 32 vs. 64 bt programming SPIs.
413 */
414 typedef struct _posix_spawn_file_actions {
415 int psfa_act_alloc; /* available actions space */
416 int psfa_act_count; /* count of defined actions */
417 _psfa_action_t psfa_act_acts[]; /* actions array (uses c99) */
418 } *_posix_spawn_file_actions_t;
419
420 /*
421 * Calculate the size of a structure, given the number of elements that it is
422 * capable of containing.
423 */
424 #define PSF_ACTIONS_SIZE(x) \
425 PS_ACTION_SIZE(x, struct _posix_spawn_file_actions, _psfa_action_t)
426
427 /*
428 * Initial count of actions in a struct _posix_spawn_file_actions after it is
429 * first allocated; this should be non-zero, since we expect that one would not
430 * have been allocated unless there was an intent to use it.
431 */
432 #define PSF_ACTIONS_INIT_COUNT 2
433
434 /*
435 * Structure defining the true third argument to the posix_spawn() system call
436 * entry point; we wrap it and pass a descriptor so that we can know the
437 * copyin size ahead of time, and deal with copying in variant lists of things
438 * as single monolithic units, instead of many individual elements. This is a
439 * performance optimization.
440 */
441 struct _posix_spawn_args_desc {
442 __darwin_size_t attr_size; /* size of attributes block */
443 _posix_spawnattr_t attrp; /* pointer to block */
444 __darwin_size_t file_actions_size; /* size of file actions block */
445 _posix_spawn_file_actions_t
446 file_actions; /* pointer to block */
447 __darwin_size_t port_actions_size; /* size of port actions block */
448 _posix_spawn_port_actions_t
449 port_actions; /* pointer to port block */
450 __darwin_size_t mac_extensions_size;
451 _posix_spawn_mac_policy_extensions_t
452 mac_extensions; /* pointer to policy-specific
453 * attributes */
454 __darwin_size_t coal_info_size;
455 struct _posix_spawn_coalition_info *coal_info; /* pointer to coalition info */
456
457 __darwin_size_t persona_info_size;
458 struct _posix_spawn_persona_info *persona_info;
459
460 __darwin_size_t posix_cred_info_size;
461 struct _posix_spawn_posix_cred_info *posix_cred_info;
462
463 __darwin_size_t subsystem_root_path_size;
464 char *subsystem_root_path;
465 };
466
467 #ifdef KERNEL
468 #include <sys/appleapiopts.h>
469 #ifdef __APPLE_API_PRIVATE
470
471 #if __DARWIN_ALIGN_NATURAL
472 #pragma options align=natural
473 #endif
474
475 struct user32__posix_spawn_args_desc {
476 uint32_t attr_size; /* size of attributes block */
477 uint32_t attrp; /* pointer to block */
478 uint32_t file_actions_size; /* size of file actions block */
479 uint32_t file_actions; /* pointer to block */
480 uint32_t port_actions_size; /* size of port actions block */
481 uint32_t port_actions; /* pointer to block */
482 uint32_t mac_extensions_size;
483 uint32_t mac_extensions;
484 uint32_t coal_info_size;
485 uint32_t coal_info;
486 uint32_t persona_info_size;
487 uint32_t persona_info;
488 uint32_t posix_cred_info_size;
489 uint32_t posix_cred_info;
490 uint32_t subsystem_root_path_size;
491 uint32_t subsystem_root_path;
492 };
493
494 struct user__posix_spawn_args_desc {
495 user_size_t attr_size; /* size of attributes block */
496 user_addr_t attrp; /* pointer to block */
497 user_size_t file_actions_size; /* size of file actions block */
498 user_addr_t file_actions; /* pointer to block */
499 user_size_t port_actions_size; /* size of port actions block */
500 user_addr_t port_actions; /* pointer to block */
501 user_size_t mac_extensions_size; /* size of MAC-specific attrs. */
502 user_addr_t mac_extensions; /* pointer to block */
503 user_size_t coal_info_size;
504 user_addr_t coal_info;
505 user_size_t persona_info_size;
506 user_addr_t persona_info;
507 user_size_t posix_cred_info_size;
508 user_addr_t posix_cred_info;
509 user_size_t subsystem_root_path_size;
510 user_addr_t subsystem_root_path;
511 };
512
513
514 #if __DARWIN_ALIGN_NATURAL
515 #pragma options align=reset
516 #endif
517
518 #endif /* __APPLE_API_PRIVATE */
519 #endif /* KERNEL */
520
521 #endif /* _SYS_SPAWN_INTERNAL_H_ */