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