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 <os/overflow.h>
52
53/*
54 * Safely compute the size in bytes of a structure, '_type', whose last
55 * element, '_member', is a zero-sized array meant to hold 'x' bytes.
56 *
57 * If the size calculation overflows a size_t value, this macro returns 0.
58 */
59#define PS_ACTION_SIZE(x,_type,_member_type) ({ \
60 size_t _ps_count = (size_t)x; \
61 size_t _ps_size = 0; \
62 /* (count * sizeof(_member_type)) + sizeof(_type) */ \
63 if (os_mul_and_add_overflow(_ps_count, \
64 sizeof(_member_type), \
65 sizeof(_type), \
66 &_ps_size)) { \
67 _ps_size = 0; \
68 } \
69 _ps_size; })
70
71/*
72 * Allowable posix_spawn() port action types
73 */
74typedef enum {
75 PSPA_SPECIAL = 0,
76 PSPA_EXCEPTION = 1,
77 PSPA_AU_SESSION = 2,
78 PSPA_IMP_WATCHPORTS = 3,
79} pspa_t;
80
81/*
82 * Internal representation of one port to be set on posix_spawn().
83 * Currently this is limited to setting special and exception ports,
84 * but could be extended to other inheritable port types.
85 */
86typedef struct _ps_port_action {
87 pspa_t port_type;
88 exception_mask_t mask;
89 mach_port_name_t new_port;
90 exception_behavior_t behavior;
91 thread_state_flavor_t flavor;
92 int which;
93} _ps_port_action_t;
94
95/*
96 * A collection of port actions to take on the newly spawned process.
97 */
98typedef struct _posix_spawn_port_actions {
99 int pspa_alloc;
100 int pspa_count;
101 _ps_port_action_t pspa_actions[];
102} *_posix_spawn_port_actions_t;
103
104/*
105 * Returns size in bytes of a _posix_spawn_port_actions holding x elements.
106 */
107#define PS_PORT_ACTIONS_SIZE(x) \
108 PS_ACTION_SIZE(x, struct _posix_spawn_port_actions, _ps_port_action_t)
109
110#define NBINPREFS 4
111
112/*
113 * Mapping of opaque data pointer to a MAC policy (specified by name).
114 */
115typedef struct _ps_mac_policy_extension {
116 char policyname[128];
117 union {
118 uint64_t data;
119 void *datap; /* pointer in kernel memory */
120 };
121 uint64_t datalen;
122} _ps_mac_policy_extension_t;
123
124/*
125 * A collection of extra data passed to MAC policies for the newly spawned process.
126 */
127typedef struct _posix_spawn_mac_policy_extensions {
128 int psmx_alloc;
129 int psmx_count;
130 _ps_mac_policy_extension_t psmx_extensions[];
131} *_posix_spawn_mac_policy_extensions_t;
132
133/*
134 * Returns size in bytes of a _posix_spawn_mac_policy_extensions holding x elements.
135 */
136#define PS_MAC_EXTENSIONS_SIZE(x) \
137 PS_ACTION_SIZE(x, struct _posix_spawn_mac_policy_extensions, _ps_mac_policy_extension_t)
138
139#define PS_MAC_EXTENSIONS_INIT_COUNT 2
140
141/*
142 * Coalition posix spawn attributes
143 */
144struct _posix_spawn_coalition_info {
145 struct {
146 uint64_t psci_id;
147 uint32_t psci_role;
148 uint32_t psci_reserved1;
149 uint64_t psci_reserved2;
150 } psci_info[COALITION_NUM_TYPES];
151};
152
153/*
154 * Persona attributes
155 */
156struct _posix_spawn_persona_info {
157 uid_t pspi_id; /* persona ID (unix UID) */
158 uint32_t pspi_flags; /* spawn persona flags */
159 uid_t pspi_uid; /* alternate posix/unix UID */
160 gid_t pspi_gid; /* alternate posix/unix GID */
161 uint32_t pspi_ngroups; /* alternate advisory groups */
162 gid_t pspi_groups[NGROUPS];
163 uid_t pspi_gmuid; /* group membership UID */
164};
165
166#define POSIX_SPAWN_PERSONA_FLAGS_NONE 0x0
167#define POSIX_SPAWN_PERSONA_FLAGS_OVERRIDE 0x1
168#define POSIX_SPAWN_PERSONA_FLAGS_VERIFY 0x2
169
170#define POSIX_SPAWN_PERSONA_ALL_FLAGS \
171 (POSIX_SPAWN_PERSONA_FLAGS_OVERRIDE \
172 | POSIX_SPAWN_PERSONA_FLAGS_VERIFY \
173 )
174
175#define POSIX_SPAWN_PERSONA_UID 0x00010000
176#define POSIX_SPAWN_PERSONA_GID 0x00020000
177#define POSIX_SPAWN_PERSONA_GROUPS 0x00040000
178
179
180/*
181 * A posix_spawnattr structure contains all of the attribute elements that
182 * can be set, as well as any metadata whose validity is signalled by the
183 * presence of a bit in the flags field. All fields are initialized to the
184 * appropriate default values by posix_spawnattr_init().
185 *
186 * Fields must be added at the end of this, but before extensions array
187 * pointers.
188 */
189
190typedef struct _posix_spawnattr {
191 short psa_flags; /* spawn attribute flags */
192 short flags_padding; /* get the flags to be int aligned */
193 sigset_t psa_sigdefault; /* signal set to default */
194 sigset_t psa_sigmask; /* signal set to mask */
195 pid_t psa_pgroup; /* pgroup to spawn into */
196 cpu_type_t psa_binprefs[NBINPREFS]; /* cpu affinity prefs*/
197 int psa_pcontrol; /* process control bits on resource starvation */
198 int psa_apptype; /* app type and process spec behav */
199 uint64_t psa_cpumonitor_percent; /* CPU usage monitor percentage */
200 uint64_t psa_cpumonitor_interval; /* CPU usage monitor interval, in seconds */
201 uint64_t psa_reserved;
202
203 short psa_jetsam_flags; /* jetsam flags */
204 short short_padding; /* Padding for alignment issues */
205 int psa_priority; /* jetsam relative importance */
206 int psa_memlimit_active; /* jetsam memory limit (in MB) when process is active */
207 int psa_memlimit_inactive; /* jetsam memory limit (in MB) when process is inactive */
208
209 uint64_t psa_qos_clamp; /* QoS Clamp to set on the new process */
210 uint64_t psa_darwin_role; /* PRIO_DARWIN_ROLE to set on the new process */
211 int psa_thread_limit; /* thread limit */
212
213 uint64_t psa_max_addr; /* Max valid VM address */
214
215 /*
216 * NOTE: Extensions array pointers must stay at the end so that
217 * everything above this point stays the same size on different bitnesses
218 * see <rdar://problem/12858307>
219 */
220 _posix_spawn_port_actions_t psa_ports; /* special/exception ports */
221 _posix_spawn_mac_policy_extensions_t psa_mac_extensions; /* MAC policy-specific extensions. */
222 struct _posix_spawn_coalition_info *psa_coalition_info; /* coalition info */
223 struct _posix_spawn_persona_info *psa_persona_info; /* spawn new process into given persona */
224} *_posix_spawnattr_t;
225
226/*
227 * Jetsam flags eg: psa_jetsam_flags
228 */
229#define POSIX_SPAWN_JETSAM_SET 0x8000
230
231#define POSIX_SPAWN_JETSAM_USE_EFFECTIVE_PRIORITY 0x01
232#define POSIX_SPAWN_JETSAM_HIWATER_BACKGROUND 0x02 /* to be deprecated */
233#define POSIX_SPAWN_JETSAM_MEMLIMIT_FATAL 0x04 /* to be deprecated */
234
235/*
236 * Additional flags available for use with
237 * the posix_spawnattr_setjetsam_ext() call
238 */
239#define POSIX_SPAWN_JETSAM_MEMLIMIT_ACTIVE_FATAL 0x04 /* if set, limit is fatal when the process is active */
240#define POSIX_SPAWN_JETSAM_MEMLIMIT_INACTIVE_FATAL 0x08 /* if set, limit is fatal when the process is inactive */
241
242/*
243 * Deprecated posix_spawn psa_flags values
244 *
245 * POSIX_SPAWN_OSX_TALAPP_START 0x0400
246 * POSIX_SPAWN_IOS_RESV1_APP_START 0x0400
247 * POSIX_SPAWN_IOS_APPLE_DAEMON_START 0x0800
248 * POSIX_SPAWN_IOS_APP_START 0x1000
249 * POSIX_SPAWN_OSX_WIDGET_START 0x0800
250 * POSIX_SPAWN_OSX_DBCLIENT_START 0x0800
251 * POSIX_SPAWN_OSX_RESVAPP_START 0x1000
252 */
253
254/*
255 * Deprecated posix_spawn psa_apptype values
256 *
257 * POSIX_SPAWN_PROCESS_TYPE_APPLEDAEMON 0x00000001
258 * POSIX_SPAWN_PROCESS_TYPE_UIAPP 0x00000002
259 * POSIX_SPAWN_PROCESS_TYPE_ADAPTIVE 0x00000004
260 * POSIX_SPAWN_PROCESS_TYPE_TAL 0x00000001
261 * POSIX_SPAWN_PROCESS_TYPE_WIDGET 0x00000002
262 * POSIX_SPAWN_PROCESS_TYPE_DELAYIDLESLEEP 0x10000000
263 *
264 * POSIX_SPAWN_PROCESS_FLAG_IMPORTANCE_DONOR 0x00000010
265 * POSIX_SPAWN_PROCESS_FLAG_ADAPTIVE 0x00000020
266 * POSIX_SPAWN_PROCESS_FLAG_START_BACKGROUND 0x00000040
267 * POSIX_SPAWN_PROCESS_FLAG_START_LIGHT_THROTTLE 0x00000080
268 */
269
270/*
271 * posix_spawn psa_apptype process type settings.
272 * when POSIX_SPAWN_PROC_TYPE is set, old psa_apptype bits are ignored
273 */
274
275#define POSIX_SPAWN_PROCESS_TYPE_NORMAL 0x00000000
276#define POSIX_SPAWN_PROCESS_TYPE_DEFAULT POSIX_SPAWN_PROCESS_TYPE_NORMAL
277
278#define POSIX_SPAWN_PROC_TYPE_MASK 0x00000F00
279
280#define POSIX_SPAWN_PROC_TYPE_APP_DEFAULT 0x00000100
281#define POSIX_SPAWN_PROC_TYPE_APP_TAL 0x00000200
282
283#define POSIX_SPAWN_PROC_TYPE_DAEMON_STANDARD 0x00000300
284#define POSIX_SPAWN_PROC_TYPE_DAEMON_INTERACTIVE 0x00000400
285#define POSIX_SPAWN_PROC_TYPE_DAEMON_BACKGROUND 0x00000500
286#define POSIX_SPAWN_PROC_TYPE_DAEMON_ADAPTIVE 0x00000600
287
288#define POSIX_SPAWN_PROC_CLAMP_NONE 0x00000000
289#define POSIX_SPAWN_PROC_CLAMP_UTILITY 0x00000001
290#define POSIX_SPAWN_PROC_CLAMP_BACKGROUND 0x00000002
291#define POSIX_SPAWN_PROC_CLAMP_MAINTENANCE 0x00000003
292#define POSIX_SPAWN_PROC_CLAMP_LAST 0x00000004
293
294/* Setting to indicate no change to darwin role */
295#define POSIX_SPAWN_DARWIN_ROLE_NONE 0x00000000
296/* Other possible values are specified by PRIO_DARWIN_ROLE in sys/resource.h */
297
298/*
299 * Allowable posix_spawn() file actions
300 */
301typedef enum {
302 PSFA_OPEN = 0,
303 PSFA_CLOSE = 1,
304 PSFA_DUP2 = 2,
305 PSFA_INHERIT = 3
306} psfa_t;
307
308
309/*
310 * A posix_spawn() file action record for a single action
311 *
312 * Notes: We carry around the full open arguments for both the open
313 * and the close to permit the use of a single array of action
314 * elements to be associated with a file actions object.
315 *
316 * A possible future optimization would be to break this into
317 * a variable sized vector list to save space (i.e. a separate
318 * string area, allocation of least amount of path buffer per
319 * open action, etc.).
320 *
321 * XXX: Currently overloading psfao_oflag for PSFA_DUP2
322 */
323typedef struct _psfa_action {
324 psfa_t psfaa_type; /* file action type */
325 int psfaa_filedes; /* fd to operate on */
326 struct _psfaa_open {
327 int psfao_oflag; /* open flags to use */
328 mode_t psfao_mode; /* mode for open */
329 char psfao_path[PATH_MAX]; /* path to open */
330 } psfaa_openargs;
331} _psfa_action_t;
332
333
334/*
335 * Internal representation of posix_spawn() file actions structure
336 *
337 * Notes: This is implemented as a structure followed by an array of
338 * file action records. The psfa_act_alloc value is the number
339 * of elements allocated in this array, and the psfa_act_count is
340 * the number of elements currently in use (to permit some form
341 * of preallocation, e.g. a power of 2 growth for reallocation,
342 * etc.).
343 *
344 * A possible future optimization would keep a size value and
345 * a structure base reference pointer to permit copyin to the
346 * kernel directly as a single blob, without damaging relative
347 * internal pointer math. It's probably better that this be a
348 * long long rather than a true pointer, to make it invariant
349 * for 32 vs. 64 bt programming SPIs.
350 */
351typedef struct _posix_spawn_file_actions {
352 int psfa_act_alloc; /* available actions space */
353 int psfa_act_count; /* count of defined actions */
354 _psfa_action_t psfa_act_acts[]; /* actions array (uses c99) */
355} *_posix_spawn_file_actions_t;
356
357/*
358 * Calculate the size of a structure, given the number of elements that it is
359 * capable of containing.
360 */
361#define PSF_ACTIONS_SIZE(x) \
362 PS_ACTION_SIZE(x, struct _posix_spawn_file_actions, _psfa_action_t)
363
364/*
365 * Initial count of actions in a struct _posix_spawn_file_actions after it is
366 * first allocated; this should be non-zero, since we expect that one would not
367 * have been allocated unless there was an intent to use it.
368 */
369#define PSF_ACTIONS_INIT_COUNT 2
370
371/*
372 * Structure defining the true third argument to the posix_spawn() system call
373 * entry point; we wrap it and pass a descriptor so that we can know the
374 * copyin size ahead of time, and deal with copying in variant lists of things
375 * as single monolithic units, instead of many individual elements. This is a
376 * performance optimization.
377 */
378struct _posix_spawn_args_desc {
379 __darwin_size_t attr_size; /* size of attributes block */
380 _posix_spawnattr_t attrp; /* pointer to block */
381 __darwin_size_t file_actions_size; /* size of file actions block */
382 _posix_spawn_file_actions_t
383 file_actions; /* pointer to block */
384 __darwin_size_t port_actions_size; /* size of port actions block */
385 _posix_spawn_port_actions_t
386 port_actions; /* pointer to port block */
387 __darwin_size_t mac_extensions_size;
388 _posix_spawn_mac_policy_extensions_t
389 mac_extensions; /* pointer to policy-specific
390 * attributes */
391 __darwin_size_t coal_info_size;
392 struct _posix_spawn_coalition_info *coal_info; /* pointer to coalition info */
393
394 __darwin_size_t persona_info_size;
395 struct _posix_spawn_persona_info *persona_info;
396};
397
398#ifdef KERNEL
399#include <sys/appleapiopts.h>
400#ifdef __APPLE_API_PRIVATE
401
402#if __DARWIN_ALIGN_NATURAL
403#pragma options align=natural
404#endif
405
406struct user32__posix_spawn_args_desc {
407 uint32_t attr_size; /* size of attributes block */
408 uint32_t attrp; /* pointer to block */
409 uint32_t file_actions_size; /* size of file actions block */
410 uint32_t file_actions; /* pointer to block */
411 uint32_t port_actions_size; /* size of port actions block */
412 uint32_t port_actions; /* pointer to block */
413 uint32_t mac_extensions_size;
414 uint32_t mac_extensions;
415 uint32_t coal_info_size;
416 uint32_t coal_info;
417 uint32_t persona_info_size;
418 uint32_t persona_info;
419};
420
421struct user__posix_spawn_args_desc {
422 user_size_t attr_size; /* size of attributes block */
423 user_addr_t attrp; /* pointer to block */
424 user_size_t file_actions_size; /* size of file actions block */
425 user_addr_t file_actions; /* pointer to block */
426 user_size_t port_actions_size; /* size of port actions block */
427 user_addr_t port_actions; /* pointer to block */
428 user_size_t mac_extensions_size; /* size of MAC-specific attrs. */
429 user_addr_t mac_extensions; /* pointer to block */
430 user_size_t coal_info_size;
431 user_addr_t coal_info;
432 user_size_t persona_info_size;
433 user_addr_t persona_info;
434};
435
436
437#if __DARWIN_ALIGN_NATURAL
438#pragma options align=reset
439#endif
440
441#endif /* __APPLE_API_PRIVATE */
442#endif /* KERNEL */
443
444#endif /* _SYS_SPAWN_INTERNAL_H_ */
445