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_t;
  58
  59 /*
  60  * Internal representation of one port to be set on posix_spawn().
  61  * Currently this is limited to setting special and exception ports,
  62  * but could be extended to other inheritable port types.
  63  */
  64 typedef struct _ps_port_action {
  65         pspa_t                  port_type;
  66         exception_mask_t        mask;
  67         mach_port_name_t        new_port;
  68         exception_behavior_t    behavior;
  69         thread_state_flavor_t   flavor;
  70         int                     which;
  71 } _ps_port_action_t;
  72
  73 /*
  74  * A collection of port actions to take on the newly spawned process.
  75  */
  76 typedef struct _posix_spawn_port_actions {
  77         int                     pspa_alloc;
  78         int                     pspa_count;
  79         _ps_port_action_t       pspa_actions[];
  80 } *_posix_spawn_port_actions_t;
  81
  82 /*
  83  * Returns size in bytes of a _posix_spawn_port_actions holding x elements.
  84  */
  85 #define PS_PORT_ACTIONS_SIZE(x) \
  86         __offsetof(struct _posix_spawn_port_actions, pspa_actions[(x)])
  87
  88 #define NBINPREFS       4
  89
  90 /*
  91  * A posix_spawnattr structure contains all of the attribute elements that
  92  * can be set, as well as any metadata whose validity is signalled by the
  93  * presence of a bit in the flags field.  All fields are initialized to the
  94  * appropriate default values by posix_spawnattr_init().
  95  */
  96 typedef struct _posix_spawnattr {
  97         short           psa_flags;              /* spawn attribute flags */
  98         sigset_t        psa_sigdefault;         /* signal set to default */
  99         sigset_t        psa_sigmask;            /* signal set to mask */
 100         pid_t           psa_pgroup;             /* pgroup to spawn into */
 101         cpu_type_t      psa_binprefs[NBINPREFS];   /* cpu affinity prefs*/
 102         int             psa_pcontrol;           /* process control bits on resource starvation */
 103         int             psa_apptype;            /* app type and process spec behav */
 104         uint64_t        psa_cpumonitor_percent; /* CPU usage monitor percentage */
 105         uint64_t        psa_cpumonitor_interval; /* CPU usage monitor interval, in seconds */
 106         _posix_spawn_port_actions_t     psa_ports; /* special/exception ports */
 107         /* XXX - k64/u32 unaligned below here */
 108 #if CONFIG_MEMORYSTATUS || CONFIG_EMBEDDED || TARGET_OS_EMBEDDED
 109         /* Jetsam related */
 110         short       psa_jetsam_flags; /* flags */
 111         int         psa_priority;   /* relative importance */
 112         int         psa_high_water_mark; /* resident page count limit */
 113 #endif
 114 } *_posix_spawnattr_t;
 115
 116 /*
 117  * Jetsam flags
 118  */
 119 #if CONFIG_MEMORYSTATUS || CONFIG_EMBEDDED || TARGET_OS_EMBEDDED
 120 #define POSIX_SPAWN_JETSAM_USE_EFFECTIVE_PRIORITY       0x1
 121 #endif
 122
 123 /*
 124  * DEPRECATED: maintained for transition purposes only
 125  * posix_spawn apptype settings.
 126  */
 127 #if TARGET_OS_EMBEDDED || CONFIG_EMBEDDED
 128 /* for compat sake */
 129 #define POSIX_SPAWN_OSX_TALAPP_START    0x0400
 130 #define POSIX_SPAWN_IOS_RESV1_APP_START 0x0400
 131 #define POSIX_SPAWN_IOS_APPLE_DAEMON_START      0x0800          /* not a bug, same as widget just rename */
 132 #define POSIX_SPAWN_IOS_APP_START       0x1000
 133 #else /* TARGET_OS_EMBEDDED */
 134 #define POSIX_SPAWN_OSX_TALAPP_START    0x0400
 135 #define POSIX_SPAWN_OSX_WIDGET_START    0x0800
 136 #define POSIX_SPAWN_OSX_DBCLIENT_START  0x0800          /* not a bug, same as widget just rename */
 137 #define POSIX_SPAWN_OSX_RESVAPP_START   0x1000          /* reserved for app start usages */
 138 #endif /* TARGET_OS_EMBEDDED */
 139
 140
 141 /*
 142  * posix_spawn apptype and process attribute settings.
 143  */
 144 #if TARGET_OS_EMBEDDED || CONFIG_EMBEDDED
 145 #define POSIX_SPAWN_APPTYPE_IOS_APPLEDAEMON    0x0001          /* it is an iOS apple daemon  */
 146 #else /* TARGET_OS_EMBEDDED */
 147 #define POSIX_SPAWN_APPTYPE_OSX_TAL     0x0001          /* it is a TAL app */
 148 #define POSIX_SPAWN_APPTYPE_OSX_WIDGET  0x0002          /* it is a widget */
 149 #define POSIX_SPAWN_APPTYPE_DELAYIDLESLEEP   0x10000000 /* Process is marked to delay idle sleep on disk IO */
 150 #endif /* TARGET_OS_EMBEDDED */
 151
 152 /*
 153  * Allowable posix_spawn() file actions
 154  */
 155 typedef enum {
 156         PSFA_OPEN = 0,
 157         PSFA_CLOSE = 1,
 158         PSFA_DUP2 = 2,
 159         PSFA_INHERIT = 3
 160 } psfa_t;
 161
 162
 163 /*
 164  * A posix_spawn() file action record for a single action
 165  *
 166  * Notes:       We carry around the full open arguments for both the open
 167  *              and the close to permit the use of a single array of action
 168  *              elements to be associated with a file actions object.
 169  *
 170  *              A possible future optimization would be to break this into
 171  *              a variable sized vector list to save space (i.e. a separate
 172  *              string area, allocation of least amount of path buffer per
 173  *              open action, etc.).
 174  *
 175  * XXX:         Currently overloading psfao_oflag for PSFA_DUP2
 176  */
 177 typedef struct _psfa_action {
 178         psfa_t  psfaa_type;                     /* file action type */
 179         int     psfaa_filedes;                  /* fd to operate on */
 180         struct _psfaa_open {
 181                 int     psfao_oflag;            /* open flags to use */
 182                 mode_t  psfao_mode;             /* mode for open */
 183                 char    psfao_path[PATH_MAX];   /* path to open */
 184         } psfaa_openargs;
 185 } _psfa_action_t;
 186
 187
 188 /*
 189  * Internal representation of posix_spawn() file actions structure
 190  *
 191  * Notes:       This is implemented as a structure followed by an array of
 192  *              file action records.  The psfa_act_alloc value is the number
 193  *              of elements allocated in this array, and the psfa_act_count is
 194  *              the number of elements currently in use (to permit some form
 195  *              of preallocation, e.g. a power of 2 growth for reallocation,
 196  *              etc.).
 197  *
 198  *              A possible future optimization would keep a size value and
 199  *              a structure base reference pointer to permit copyin to the
 200  *              kernel directly as a single blob, without damaging relative
 201  *              internal pointer math.  It's probably better that this be a
 202  *              long long rather than a true pointer, to make it invariant
 203  *              for 32 vs. 64 bt programming SPIs.
 204  */
 205 typedef struct _posix_spawn_file_actions {
 206         int             psfa_act_alloc;         /* available actions space */
 207         int             psfa_act_count;         /* count of defined actions */
 208         _psfa_action_t  psfa_act_acts[];        /* actions array (uses c99) */
 209 } *_posix_spawn_file_actions_t;
 210
 211 /*
 212  * Calculate the size of a structure, given the number of elements that it is
 213  * capable of containing.
 214  */
 215 #define PSF_ACTIONS_SIZE(x)     \
 216         __offsetof(struct _posix_spawn_file_actions, psfa_act_acts[(x)])
 217
 218 /*
 219  * Initial count of actions in a struct _posix_spawn_file_actions after it is
 220  * first allocated; this should be non-zero, since we expect that one would not
 221  * have been allocated unless there was an intent to use it.
 222  */
 223 #define PSF_ACTIONS_INIT_COUNT  2
 224
 225 /*
 226  * Structure defining the true third argument to the posix_spawn() system call
 227  * entry point; we wrap it and pass a descriptor so that we can know the
 228  * copyin size ahead of time, and deal with copying in variant lists of things
 229  * as single monolithic units, instead of many individual elements.  This is a
 230  * performance optimization.
 231  */
 232 struct _posix_spawn_args_desc {
 233         __darwin_size_t         attr_size;      /* size of attributes block */
 234         _posix_spawnattr_t      attrp;          /* pointer to block */
 235         __darwin_size_t file_actions_size;      /* size of file actions block */
 236         _posix_spawn_file_actions_t
 237                                 file_actions;   /* pointer to block */
 238         __darwin_size_t port_actions_size;      /* size of port actions block */
 239         _posix_spawn_port_actions_t
 240                                 port_actions;   /* pointer to port block */
 241 };
 242
 243 #ifdef KERNEL
 244 #include <sys/appleapiopts.h>
 245 #ifdef __APPLE_API_PRIVATE
 246
 247 #if __DARWIN_ALIGN_NATURAL
 248 #pragma options align=natural
 249 #endif
 250
 251 struct user32__posix_spawn_args_desc {
 252         uint32_t                attr_size;      /* size of attributes block */
 253         uint32_t                attrp;          /* pointer to block */
 254         uint32_t        file_actions_size;      /* size of file actions block */
 255         uint32_t                file_actions;   /* pointer to block */
 256         uint32_t        port_actions_size;      /* size of port actions block */
 257         uint32_t                port_actions;   /* pointer to block */
 258 };
 259
 260 struct user__posix_spawn_args_desc {
 261         user_size_t             attr_size;      /* size of attributes block */
 262         user_addr_t             attrp;          /* pointer to block */
 263         user_size_t     file_actions_size;      /* size of file actions block */
 264         user_addr_t             file_actions;   /* pointer to block */
 265         user_size_t     port_actions_size;      /* size of port actions block */
 266         user_addr_t             port_actions;   /* pointer to block */
 267 };
 268
 269
 270 #if __DARWIN_ALIGN_NATURAL
 271 #pragma options align=reset
 272 #endif
 273
 274 #endif  /* __APPLE_API_PRIVATE */
 275 #endif  /* KERNEL */
 276
 277 #endif  /* _SYS_SPAWN_INTERNAL_H_ */