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/syslimits.h>      /* PATH_MAX */
  45 #include <sys/spawn.h>
  46 #include <mach/machine.h>
  47 #include <mach/port.h>
  48 #include <mach/exception_types.h>
  49
  50 /*
  51  * Allowable posix_spawn() port action types
  52  */
  53 typedef enum {
  54         PSPA_SPECIAL = 0,
  55         PSPA_EXCEPTION = 1,
  56         PSPA_AU_SESSION = 2,
  57         PSPA_IMP_WATCHPORTS = 3,
  58 } pspa_t;
  59
  60 /*
  61  * Internal representation of one port to be set on posix_spawn().
  62  * Currently this is limited to setting special and exception ports,
  63  * but could be extended to other inheritable port types.
  64  */
  65 typedef struct _ps_port_action {
  66         pspa_t                  port_type;
  67         exception_mask_t        mask;
  68         mach_port_name_t        new_port;
  69         exception_behavior_t    behavior;
  70         thread_state_flavor_t   flavor;
  71         int                     which;
  72 } _ps_port_action_t;
  73
  74 /*
  75  * A collection of port actions to take on the newly spawned process.
  76  */
  77 typedef struct _posix_spawn_port_actions {
  78         int                     pspa_alloc;
  79         int                     pspa_count;
  80         _ps_port_action_t       pspa_actions[];
  81 } *_posix_spawn_port_actions_t;
  82
  83 /*
  84  * Returns size in bytes of a _posix_spawn_port_actions holding x elements.
  85  */
  86 #define PS_PORT_ACTIONS_SIZE(x) \
  87         __offsetof(struct _posix_spawn_port_actions, pspa_actions[(x)])
  88
  89 #define NBINPREFS       4
  90
  91 /*
  92  * Mapping of opaque data pointer to a MAC policy (specified by name).
  93  */
  94 typedef struct _ps_mac_policy_extension {
  95         char                    policyname[128];
  96         union {
  97                 uint64_t        data;
  98                 void            *datap;         /* pointer in kernel memory */
  99         };
 100         uint64_t                datalen;
 101 } _ps_mac_policy_extension_t;
 102
 103 /*
 104  * A collection of extra data passed to MAC policies for the newly spawned process.
 105  */
 106 typedef struct _posix_spawn_mac_policy_extensions {
 107         int                     psmx_alloc;
 108         int                     psmx_count;
 109         _ps_mac_policy_extension_t psmx_extensions[];
 110 } *_posix_spawn_mac_policy_extensions_t;
 111
 112 /*
 113  * Returns size in bytes of a _posix_spawn_mac_policy_extensions holding x elements.
 114  */
 115 #define PS_MAC_EXTENSIONS_SIZE(x)     \
 116         __offsetof(struct _posix_spawn_mac_policy_extensions, psmx_extensions[(x)])
 117
 118 #define PS_MAC_EXTENSIONS_INIT_COUNT    2
 119
 120
 121 /*
 122  * A posix_spawnattr structure contains all of the attribute elements that
 123  * can be set, as well as any metadata whose validity is signalled by the
 124  * presence of a bit in the flags field.  All fields are initialized to the
 125  * appropriate default values by posix_spawnattr_init().
 126  */
 127 typedef struct _posix_spawnattr {
 128         short           psa_flags;              /* spawn attribute flags */
 129         short           flags_padding;  /* get the flags to be int aligned */
 130         sigset_t        psa_sigdefault;         /* signal set to default */
 131         sigset_t        psa_sigmask;            /* signal set to mask */
 132         pid_t           psa_pgroup;             /* pgroup to spawn into */
 133         cpu_type_t      psa_binprefs[NBINPREFS];   /* cpu affinity prefs*/
 134         int             psa_pcontrol;           /* process control bits on resource starvation */
 135         int             psa_apptype;            /* app type and process spec behav */
 136         uint64_t        psa_cpumonitor_percent; /* CPU usage monitor percentage */
 137         uint64_t        psa_cpumonitor_interval; /* CPU usage monitor interval, in seconds */
 138         uint64_t        psa_coalitionid;        /* coalition to spawn into */
 139
 140         short       psa_jetsam_flags; /* jetsam flags */
 141         short           short_padding;  /* Padding for alignment issues */
 142         int         psa_priority;   /* jetsam relative importance */
 143         int         psa_high_water_mark; /* jetsam resident page count limit */
 144         int             int_padding;    /* Padding for alignment issues */
 145
 146         uint64_t        psa_qos_clamp;          /* QoS Clamp to set on the new process */
 147
 148         /*
 149          * NOTE: Extensions array pointers must stay at the end so that
 150          * everything above this point stays the same size on different bitnesses
 151          * see <rdar://problem/12858307>
 152          */
 153          _posix_spawn_port_actions_t    psa_ports; /* special/exception ports */
 154         _posix_spawn_mac_policy_extensions_t psa_mac_extensions; /* MAC policy-specific extensions. */
 155 } *_posix_spawnattr_t;
 156
 157 /*
 158  * Jetsam flags
 159  */
 160 #define POSIX_SPAWN_JETSAM_SET                      0x8000
 161
 162 #define POSIX_SPAWN_JETSAM_USE_EFFECTIVE_PRIORITY   0x1
 163 #define POSIX_SPAWN_JETSAM_HIWATER_BACKGROUND       0x2
 164 #define POSIX_SPAWN_JETSAM_MEMLIMIT_FATAL           0x4
 165
 166 /*
 167  * Deprecated posix_spawn psa_flags values
 168  *
 169  * POSIX_SPAWN_OSX_TALAPP_START         0x0400
 170  * POSIX_SPAWN_IOS_RESV1_APP_START      0x0400
 171  * POSIX_SPAWN_IOS_APPLE_DAEMON_START   0x0800
 172  * POSIX_SPAWN_IOS_APP_START            0x1000
 173  * POSIX_SPAWN_OSX_WIDGET_START         0x0800
 174  * POSIX_SPAWN_OSX_DBCLIENT_START       0x0800
 175  * POSIX_SPAWN_OSX_RESVAPP_START        0x1000
 176  */
 177
 178 /*
 179  * Deprecated posix_spawn psa_apptype values
 180  *
 181  * POSIX_SPAWN_PROCESS_TYPE_APPLEDAEMON             0x00000001
 182  * POSIX_SPAWN_PROCESS_TYPE_UIAPP                   0x00000002
 183  * POSIX_SPAWN_PROCESS_TYPE_ADAPTIVE                0x00000004
 184  * POSIX_SPAWN_PROCESS_TYPE_TAL                     0x00000001
 185  * POSIX_SPAWN_PROCESS_TYPE_WIDGET                  0x00000002
 186  * POSIX_SPAWN_PROCESS_TYPE_DELAYIDLESLEEP          0x10000000
 187  *
 188  * POSIX_SPAWN_PROCESS_FLAG_IMPORTANCE_DONOR        0x00000010
 189  * POSIX_SPAWN_PROCESS_FLAG_ADAPTIVE                0x00000020
 190  * POSIX_SPAWN_PROCESS_FLAG_START_BACKGROUND        0x00000040
 191  * POSIX_SPAWN_PROCESS_FLAG_START_LIGHT_THROTTLE    0x00000080
 192  */
 193
 194 /*
 195  * posix_spawn psa_apptype process type settings.
 196  * when POSIX_SPAWN_PROC_TYPE is set, old psa_apptype bits are ignored
 197  */
 198
 199 #define POSIX_SPAWN_PROCESS_TYPE_NORMAL             0x00000000
 200 #define POSIX_SPAWN_PROCESS_TYPE_DEFAULT            POSIX_SPAWN_PROCESS_TYPE_NORMAL
 201
 202 #define POSIX_SPAWN_PROC_TYPE_MASK                  0x00000F00
 203
 204 #define POSIX_SPAWN_PROC_TYPE_APP_DEFAULT           0x00000100
 205 #define POSIX_SPAWN_PROC_TYPE_APP_TAL               0x00000200
 206
 207 #define POSIX_SPAWN_PROC_TYPE_DAEMON_STANDARD       0x00000300
 208 #define POSIX_SPAWN_PROC_TYPE_DAEMON_INTERACTIVE    0x00000400
 209 #define POSIX_SPAWN_PROC_TYPE_DAEMON_BACKGROUND     0x00000500
 210 #define POSIX_SPAWN_PROC_TYPE_DAEMON_ADAPTIVE       0x00000600
 211
 212 #define POSIX_SPAWN_PROC_CLAMP_NONE                 0x00000000
 213 #define POSIX_SPAWN_PROC_CLAMP_UTILITY              0x00000001
 214 #define POSIX_SPAWN_PROC_CLAMP_BACKGROUND           0x00000002
 215 #define POSIX_SPAWN_PROC_CLAMP_MAINTENANCE          0x00000003
 216 #define POSIX_SPAWN_PROC_CLAMP_LAST                 0x00000004
 217
 218 /*
 219  * Allowable posix_spawn() file actions
 220  */
 221 typedef enum {
 222         PSFA_OPEN = 0,
 223         PSFA_CLOSE = 1,
 224         PSFA_DUP2 = 2,
 225         PSFA_INHERIT = 3
 226 } psfa_t;
 227
 228
 229 /*
 230  * A posix_spawn() file action record for a single action
 231  *
 232  * Notes:       We carry around the full open arguments for both the open
 233  *              and the close to permit the use of a single array of action
 234  *              elements to be associated with a file actions object.
 235  *
 236  *              A possible future optimization would be to break this into
 237  *              a variable sized vector list to save space (i.e. a separate
 238  *              string area, allocation of least amount of path buffer per
 239  *              open action, etc.).
 240  *
 241  * XXX:         Currently overloading psfao_oflag for PSFA_DUP2
 242  */
 243 typedef struct _psfa_action {
 244         psfa_t  psfaa_type;                     /* file action type */
 245         int     psfaa_filedes;                  /* fd to operate on */
 246         struct _psfaa_open {
 247                 int     psfao_oflag;            /* open flags to use */
 248                 mode_t  psfao_mode;             /* mode for open */
 249                 char    psfao_path[PATH_MAX];   /* path to open */
 250         } psfaa_openargs;
 251 } _psfa_action_t;
 252
 253
 254 /*
 255  * Internal representation of posix_spawn() file actions structure
 256  *
 257  * Notes:       This is implemented as a structure followed by an array of
 258  *              file action records.  The psfa_act_alloc value is the number
 259  *              of elements allocated in this array, and the psfa_act_count is
 260  *              the number of elements currently in use (to permit some form
 261  *              of preallocation, e.g. a power of 2 growth for reallocation,
 262  *              etc.).
 263  *
 264  *              A possible future optimization would keep a size value and
 265  *              a structure base reference pointer to permit copyin to the
 266  *              kernel directly as a single blob, without damaging relative
 267  *              internal pointer math.  It's probably better that this be a
 268  *              long long rather than a true pointer, to make it invariant
 269  *              for 32 vs. 64 bt programming SPIs.
 270  */
 271 typedef struct _posix_spawn_file_actions {
 272         int             psfa_act_alloc;         /* available actions space */
 273         int             psfa_act_count;         /* count of defined actions */
 274         _psfa_action_t  psfa_act_acts[];        /* actions array (uses c99) */
 275 } *_posix_spawn_file_actions_t;
 276
 277 /*
 278  * Calculate the size of a structure, given the number of elements that it is
 279  * capable of containing.
 280  */
 281 #define PSF_ACTIONS_SIZE(x)     \
 282         __offsetof(struct _posix_spawn_file_actions, psfa_act_acts[(x)])
 283
 284 /*
 285  * Initial count of actions in a struct _posix_spawn_file_actions after it is
 286  * first allocated; this should be non-zero, since we expect that one would not
 287  * have been allocated unless there was an intent to use it.
 288  */
 289 #define PSF_ACTIONS_INIT_COUNT  2
 290
 291 /*
 292  * Structure defining the true third argument to the posix_spawn() system call
 293  * entry point; we wrap it and pass a descriptor so that we can know the
 294  * copyin size ahead of time, and deal with copying in variant lists of things
 295  * as single monolithic units, instead of many individual elements.  This is a
 296  * performance optimization.
 297  */
 298 struct _posix_spawn_args_desc {
 299         __darwin_size_t         attr_size;      /* size of attributes block */
 300         _posix_spawnattr_t      attrp;          /* pointer to block */
 301         __darwin_size_t file_actions_size;      /* size of file actions block */
 302         _posix_spawn_file_actions_t
 303                                 file_actions;   /* pointer to block */
 304         __darwin_size_t port_actions_size;      /* size of port actions block */
 305         _posix_spawn_port_actions_t
 306                                 port_actions;   /* pointer to port block */
 307         __darwin_size_t mac_extensions_size;
 308         _posix_spawn_mac_policy_extensions_t
 309                                 mac_extensions; /* pointer to policy-specific
 310                                                  * attributes */
 311
 312 };
 313
 314 #ifdef KERNEL
 315 #include <sys/appleapiopts.h>
 316 #ifdef __APPLE_API_PRIVATE
 317
 318 #if __DARWIN_ALIGN_NATURAL
 319 #pragma options align=natural
 320 #endif
 321
 322 struct user32__posix_spawn_args_desc {
 323         uint32_t                attr_size;      /* size of attributes block */
 324         uint32_t                attrp;          /* pointer to block */
 325         uint32_t        file_actions_size;      /* size of file actions block */
 326         uint32_t                file_actions;   /* pointer to block */
 327         uint32_t        port_actions_size;      /* size of port actions block */
 328         uint32_t                port_actions;   /* pointer to block */
 329         uint32_t        mac_extensions_size;
 330         uint32_t        mac_extensions;
 331 };
 332
 333 struct user__posix_spawn_args_desc {
 334         user_size_t             attr_size;      /* size of attributes block */
 335         user_addr_t             attrp;          /* pointer to block */
 336         user_size_t     file_actions_size;      /* size of file actions block */
 337         user_addr_t             file_actions;   /* pointer to block */
 338         user_size_t     port_actions_size;      /* size of port actions block */
 339         user_addr_t             port_actions;   /* pointer to block */
 340         user_size_t     mac_extensions_size;    /* size of MAC-specific attrs. */
 341         user_addr_t     mac_extensions;         /* pointer to block */
 342 };
 343
 344
 345 #if __DARWIN_ALIGN_NATURAL
 346 #pragma options align=reset
 347 #endif
 348
 349 #endif  /* __APPLE_API_PRIVATE */
 350 #endif  /* KERNEL */
 351
 352 #endif  /* _SYS_SPAWN_INTERNAL_H_ */