os/voucher_private.h

   1 /*
   2  * Copyright (c) 2013-2014 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_APACHE_LICENSE_HEADER_START@
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  * @APPLE_APACHE_LICENSE_HEADER_END@
  19  */
  20
  21 #ifndef __OS_VOUCHER_PRIVATE__
  22 #define __OS_VOUCHER_PRIVATE__
  23
  24 #ifndef __linux__
  25 #include <os/base.h>
  26 #include <os/availability.h>
  27 #endif
  28 #if __has_include(<mach/mach.h>)
  29 #include <os/object.h>
  30 #include <mach/mach.h>
  31 #endif
  32 #if __has_include(<bank/bank_types.h>)
  33 #include <bank/bank_types.h>
  34 #endif
  35 #if __has_include(<sys/persona.h>)
  36 #include <sys/persona.h>
  37 #endif
  38
  39 #ifndef __DISPATCH_BUILDING_DISPATCH__
  40 #include <dispatch/dispatch.h>
  41 #endif /* !__DISPATCH_BUILDING_DISPATCH__ */
  42
  43 #define OS_VOUCHER_SPI_VERSION 20150630
  44
  45 #if OS_VOUCHER_WEAK_IMPORT
  46 #define OS_VOUCHER_EXPORT OS_EXPORT OS_WEAK_IMPORT
  47 #else
  48 #define OS_VOUCHER_EXPORT OS_EXPORT
  49 #endif
  50
  51 DISPATCH_ASSUME_NONNULL_BEGIN
  52
  53 __BEGIN_DECLS
  54
  55 /*!
  56  * @group Voucher Transport SPI
  57  * SPI intended for clients that need to transport vouchers.
  58  */
  59
  60 /*!
  61  * @typedef voucher_t
  62  *
  63  * @abstract
  64  * Vouchers are immutable sets of key/value attributes that can be adopted on a
  65  * thread in the current process or sent to another process.
  66  *
  67  * @discussion
  68  * Voucher objects are os_objects (c.f. <os/object.h>). They are memory-managed
  69  * with the os_retain()/os_release() functions or -[retain]/-[release] methods.
  70  */
  71 OS_OBJECT_DECL_CLASS(voucher);
  72
  73 /*!
  74  * @const VOUCHER_NULL
  75  * Represents the empty base voucher with no attributes.
  76  */
  77 #define VOUCHER_NULL            ((voucher_t)0)
  78 /*!
  79  * @const VOUCHER_INVALID
  80  * Represents an invalid voucher
  81  */
  82 #define VOUCHER_INVALID         ((voucher_t)-1)
  83
  84 /*!
  85  * @function voucher_adopt
  86  *
  87  * @abstract
  88  * Adopt the specified voucher on the current thread and return the voucher
  89  * that had been adopted previously.
  90  *
  91  * @discussion
  92  * Adopted vouchers are automatically carried forward by the system to other
  93  * threads and processes (across IPC).
  94  *
  95  * Consumes a reference to the specified voucher.
  96  * Returns a reference to the previous voucher.
  97  *
  98  * @param voucher
  99  * The voucher object to adopt on the current thread.
 100  *
 101  * @result
 102  * The previously adopted voucher object.
 103  */
 104 API_AVAILABLE(macos(10.10), ios(8.0))
 105 OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT_NEEDS_RELEASE
 106 OS_NOTHROW
 107 voucher_t _Nullable
 108 voucher_adopt(voucher_t _Nullable voucher OS_OBJECT_CONSUMED);
 109
 110 /*!
 111  * @function voucher_copy
 112  *
 113  * @abstract
 114  * Returns a reference to the voucher that had been adopted previously on the
 115  * current thread (or carried forward by the system).
 116  *
 117  * @result
 118  * The currently adopted voucher object.
 119  */
 120 API_AVAILABLE(macos(10.10), ios(8.0))
 121 OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW
 122 voucher_t _Nullable
 123 voucher_copy(void);
 124
 125 /*!
 126  * @function voucher_copy_without_importance
 127  *
 128  * @abstract
 129  * Returns a reference to a voucher object with all the properties of the
 130  * voucher that had been adopted previously on the current thread, but
 131  * without the importance properties that are frequently attached to vouchers
 132  * carried with IPC requests. Importance properties may elevate the scheduling
 133  * of threads that adopt or retain the voucher while they service the request.
 134  * See xpc_transaction_begin(3) for further details on importance.
 135  *
 136  * @result
 137  * A copy of the currently adopted voucher object, with importance removed.
 138  */
 139 API_AVAILABLE(macos(10.10), ios(8.0))
 140 OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW
 141 voucher_t _Nullable
 142 voucher_copy_without_importance(void);
 143
 144 /*!
 145  * @function voucher_replace_default_voucher
 146  *
 147  * @abstract
 148  * Replace process attributes of default voucher (used for IPC by this process
 149  * when no voucher is adopted on the sending thread) with the process attributes
 150  * of the voucher adopted on the current thread.
 151  *
 152  * @discussion
 153  * This allows a daemon to indicate from the context of an incoming IPC request
 154  * that all future outgoing IPC from the process should be marked as acting
 155  * "on behalf of" the sending process of the current IPC request (as long as the
 156  * thread sending that outgoing IPC is not itself in the direct context of an
 157  * IPC request, i.e. no voucher is adopted).
 158  *
 159  * If no voucher is adopted on the current thread or the current voucher does
 160  * not contain any process attributes, the default voucher is reset to the
 161  * default process attributes for the current process.
 162  *
 163  * CAUTION: Do NOT use this SPI without contacting the Darwin Runtime team.
 164  */
 165 API_AVAILABLE(macos(10.10), ios(8.0))
 166 OS_VOUCHER_EXPORT OS_NOTHROW
 167 void
 168 voucher_replace_default_voucher(void);
 169
 170 /*!
 171  * @function voucher_decrement_importance_count4CF
 172  *
 173  * @abstract
 174  * Decrement external importance count of the mach voucher in the specified
 175  * voucher object.
 176  *
 177  * @discussion
 178  * This is only intended for use by CoreFoundation to explicitly manage the
 179  * App Nap state of an application following reception of a de-nap IPC message.
 180  *
 181  * CAUTION: Do NOT use this SPI without contacting the Darwin Runtime team.
 182  */
 183 API_AVAILABLE(macos(10.10), ios(8.0))
 184 OS_VOUCHER_EXPORT OS_NOTHROW
 185 void
 186 voucher_decrement_importance_count4CF(voucher_t _Nullable voucher);
 187
 188 /*!
 189  * @group Voucher dispatch block SPI
 190  */
 191
 192 /*!
 193  * @typedef dispatch_block_flags_t
 194  * SPI Flags to pass to the dispatch_block_create* functions.
 195  *
 196  * @const DISPATCH_BLOCK_NO_VOUCHER
 197  * Flag indicating that a dispatch block object should not be assigned a voucher
 198  * object. If invoked directly, the block object will be executed with the
 199  * voucher adopted on the calling thread. If the block object is submitted to a
 200  * queue, this replaces the default behavior of associating the submitted block
 201  * instance with the voucher adopted at the time of submission.
 202  * This flag is ignored if a specific voucher object is assigned with the
 203  * dispatch_block_create_with_voucher* functions, and is equivalent to passing
 204  * the NULL voucher to these functions.
 205  *
 206  * @const DISPATCH_BLOCK_IF_LAST_RESET_QUEUE_QOS_OVERRIDE
 207  * Flag indicating that this dispatch block object should try to reset the
 208  * recorded maximum QoS of all currently enqueued items on a serial dispatch
 209  * queue at the base of a queue hierarchy.
 210  *
 211  * This is only works if the queue becomes empty by dequeuing the block in
 212  * question, and then allows that block to enqueue more work on this hierarchy
 213  * without perpetuating QoS overrides resulting from items previously executed
 214  * on the hierarchy.
 215  *
 216  * A dispatch block object created with this flag set cannot be used with
 217  * dispatch_block_wait() or dispatch_block_cancel().
 218  */
 219 #define DISPATCH_BLOCK_NO_VOUCHER (0x40ul)
 220
 221 #define DISPATCH_BLOCK_IF_LAST_RESET_QUEUE_QOS_OVERRIDE (0x80ul)
 222
 223 /*!
 224  * @function dispatch_block_create_with_voucher
 225  *
 226  * @abstract
 227  * Create a new dispatch block object on the heap from an existing block and
 228  * the given flags, and assign it the specified voucher object.
 229  *
 230  * @discussion
 231  * The provided block is Block_copy'ed to the heap, it and the specified voucher
 232  * object are retained by the newly created dispatch block object.
 233  *
 234  * The returned dispatch block object is intended to be submitted to a dispatch
 235  * queue with dispatch_async() and related functions, but may also be invoked
 236  * directly. Both operations can be performed an arbitrary number of times but
 237  * only the first completed execution of a dispatch block object can be waited
 238  * on with dispatch_block_wait() or observed with dispatch_block_notify().
 239  *
 240  * The returned dispatch block will be executed with the specified voucher
 241  * adopted for the duration of the block body. If the NULL voucher is passed,
 242  * the block will be executed with the voucher adopted on the calling thread, or
 243  * with no voucher if the DISPATCH_BLOCK_DETACHED flag was also provided.
 244  *
 245  * If the returned dispatch block object is submitted to a dispatch queue, the
 246  * submitted block instance will be associated with the QOS class current at the
 247  * time of submission, unless one of the following flags assigned a specific QOS
 248  * class (or no QOS class) at the time of block creation:
 249  *  - DISPATCH_BLOCK_ASSIGN_CURRENT
 250  *  - DISPATCH_BLOCK_NO_QOS_CLASS
 251  *  - DISPATCH_BLOCK_DETACHED
 252  * The QOS class the block object will be executed with also depends on the QOS
 253  * class assigned to the queue and which of the following flags was specified or
 254  * defaulted to:
 255  *  - DISPATCH_BLOCK_INHERIT_QOS_CLASS (default for asynchronous execution)
 256  *  - DISPATCH_BLOCK_ENFORCE_QOS_CLASS (default for synchronous execution)
 257  * See description of dispatch_block_flags_t for details.
 258  *
 259  * If the returned dispatch block object is submitted directly to a serial queue
 260  * and is configured to execute with a specific QOS class, the system will make
 261  * a best effort to apply the necessary QOS overrides to ensure that blocks
 262  * submitted earlier to the serial queue are executed at that same QOS class or
 263  * higher.
 264  *
 265  * @param flags
 266  * Configuration flags for the block object.
 267  * Passing a value that is not a bitwise OR of flags from dispatch_block_flags_t
 268  * results in NULL being returned.
 269  *
 270  * @param voucher
 271  * A voucher object or NULL. Passing NULL is equivalent to specifying the
 272  * DISPATCH_BLOCK_NO_VOUCHER flag.
 273  *
 274  * @param block
 275  * The block to create the dispatch block object from.
 276  *
 277  * @result
 278  * The newly created dispatch block object, or NULL.
 279  * When not building with Objective-C ARC, must be released with a -[release]
 280  * message or the Block_release() function.
 281  */
 282 API_AVAILABLE(macos(10.10), ios(8.0))
 283 DISPATCH_EXPORT DISPATCH_NONNULL3 DISPATCH_RETURNS_RETAINED_BLOCK
 284 DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 285 dispatch_block_t
 286 dispatch_block_create_with_voucher(dispatch_block_flags_t flags,
 287                 voucher_t _Nullable voucher, dispatch_block_t block);
 288
 289 /*!
 290  * @function dispatch_block_create_with_voucher_and_qos_class
 291  *
 292  * @abstract
 293  * Create a new dispatch block object on the heap from an existing block and
 294  * the given flags, and assign it the specified voucher object, QOS class and
 295  * relative priority.
 296  *
 297  * @discussion
 298  * The provided block is Block_copy'ed to the heap, it and the specified voucher
 299  * object are retained by the newly created dispatch block object.
 300  *
 301  * The returned dispatch block object is intended to be submitted to a dispatch
 302  * queue with dispatch_async() and related functions, but may also be invoked
 303  * directly. Both operations can be performed an arbitrary number of times but
 304  * only the first completed execution of a dispatch block object can be waited
 305  * on with dispatch_block_wait() or observed with dispatch_block_notify().
 306  *
 307  * The returned dispatch block will be executed with the specified voucher
 308  * adopted for the duration of the block body. If the NULL voucher is passed,
 309  * the block will be executed with the voucher adopted on the calling thread, or
 310  * with no voucher if the DISPATCH_BLOCK_DETACHED flag was also provided.
 311  *
 312  * If invoked directly, the returned dispatch block object will be executed with
 313  * the assigned QOS class as long as that does not result in a lower QOS class
 314  * than what is current on the calling thread.
 315  *
 316  * If the returned dispatch block object is submitted to a dispatch queue, the
 317  * QOS class it will be executed with depends on the QOS class assigned to the
 318  * block, the QOS class assigned to the queue and which of the following flags
 319  * was specified or defaulted to:
 320  *  - DISPATCH_BLOCK_INHERIT_QOS_CLASS: default for asynchronous execution
 321  *  - DISPATCH_BLOCK_ENFORCE_QOS_CLASS: default for synchronous execution
 322  * See description of dispatch_block_flags_t for details.
 323  *
 324  * If the returned dispatch block object is submitted directly to a serial queue
 325  * and is configured to execute with a specific QOS class, the system will make
 326  * a best effort to apply the necessary QOS overrides to ensure that blocks
 327  * submitted earlier to the serial queue are executed at that same QOS class or
 328  * higher.
 329  *
 330  * @param flags
 331  * Configuration flags for the block object.
 332  * Passing a value that is not a bitwise OR of flags from dispatch_block_flags_t
 333  * results in NULL being returned.
 334  *
 335  * @param voucher
 336  * A voucher object or NULL. Passing NULL is equivalent to specifying the
 337  * DISPATCH_BLOCK_NO_VOUCHER flag.
 338  *
 339  * @param qos_class
 340  * A QOS class value:
 341  *  - QOS_CLASS_USER_INTERACTIVE
 342  *  - QOS_CLASS_USER_INITIATED
 343  *  - QOS_CLASS_DEFAULT
 344  *  - QOS_CLASS_UTILITY
 345  *  - QOS_CLASS_BACKGROUND
 346  *  - QOS_CLASS_UNSPECIFIED
 347  * Passing QOS_CLASS_UNSPECIFIED is equivalent to specifying the
 348  * DISPATCH_BLOCK_NO_QOS_CLASS flag. Passing any other value results in NULL
 349  * being returned.
 350  *
 351  * @param relative_priority
 352  * A relative priority within the QOS class. This value is a negative
 353  * offset from the maximum supported scheduler priority for the given class.
 354  * Passing a value greater than zero or less than QOS_MIN_RELATIVE_PRIORITY
 355  * results in NULL being returned.
 356  *
 357  * @param block
 358  * The block to create the dispatch block object from.
 359  *
 360  * @result
 361  * The newly created dispatch block object, or NULL.
 362  * When not building with Objective-C ARC, must be released with a -[release]
 363  * message or the Block_release() function.
 364  */
 365 API_AVAILABLE(macos(10.10), ios(8.0))
 366 DISPATCH_EXPORT DISPATCH_NONNULL5 DISPATCH_RETURNS_RETAINED_BLOCK
 367 DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 368 dispatch_block_t
 369 dispatch_block_create_with_voucher_and_qos_class(dispatch_block_flags_t flags,
 370                 voucher_t _Nullable voucher, dispatch_qos_class_t qos_class,
 371                 int relative_priority, dispatch_block_t block);
 372
 373 /*!
 374  * @group Voucher dispatch queue SPI
 375  */
 376
 377 /*!
 378  * @function dispatch_queue_create_with_accounting_override_voucher
 379  *
 380  * @abstract
 381  * Deprecated, do not use, will abort process if called.
 382  */
 383 API_DEPRECATED("removed SPI", \
 384                 macos(10.11,10.12), ios(9.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0))
 385 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 386 DISPATCH_NOTHROW
 387 dispatch_queue_t
 388 dispatch_queue_create_with_accounting_override_voucher(
 389                 const char *_Nullable label,
 390                 dispatch_queue_attr_t _Nullable attr,
 391                 voucher_t _Nullable voucher);
 392
 393 #if __has_include(<mach/mach.h>)
 394 /*!
 395  * @group Voucher Mach SPI
 396  * SPI intended for clients that need to interact with mach messages or mach
 397  * voucher ports directly.
 398  */
 399
 400 /*!
 401  * @function voucher_create_with_mach_msg
 402  *
 403  * @abstract
 404  * Creates a new voucher object from a mach message carrying a mach voucher port
 405  *
 406  * @discussion
 407  * Ownership of the mach voucher port in the message is transfered to the new
 408  * voucher object and the message header mach voucher field is cleared.
 409  *
 410  * @param msg
 411  * The mach message to query.
 412  *
 413  * @result
 414  * The newly created voucher object or NULL if the message was not carrying a
 415  * mach voucher.
 416  */
 417 API_AVAILABLE(macos(10.10), ios(8.0))
 418 OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW
 419 voucher_t _Nullable
 420 voucher_create_with_mach_msg(mach_msg_header_t *msg);
 421
 422 /*!
 423  * @group Voucher Persona SPI
 424  * SPI intended for clients that need to interact with personas.
 425  */
 426
 427 struct proc_persona_info;
 428
 429 /*!
 430  * @function voucher_get_current_persona
 431  *
 432  * @abstract
 433  * Retrieve the persona identifier of the 'originator' process for the current
 434  * voucher.
 435  *
 436  * @discussion
 437  * Retrieve the persona identifier of the ’originator’ process possibly stored
 438  * in the PERSONA_TOKEN attribute of the currently adopted voucher.
 439  *
 440  * If the thread has not adopted a voucher, or the current voucher does not
 441  * contain a PERSONA_TOKEN attribute, this function returns the persona
 442  * identifier of the current process.
 443  *
 444  * If the process is not running under a persona, then this returns
 445  * PERSONA_ID_NONE.
 446  *
 447  * @result
 448  * The persona identifier of the 'originator' process for the current voucher,
 449  * or the persona identifier of the current process
 450  * or PERSONA_ID_NONE
 451  */
 452 API_AVAILABLE(ios(9.2))
 453 OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW
 454 uid_t
 455 voucher_get_current_persona(void);
 456
 457 /*!
 458  * @function voucher_get_current_persona_originator_info
 459  *
 460  * @abstract
 461  * Retrieve the ’originator’ process persona info for the currently adopted
 462  * voucher.
 463  *
 464  * @discussion
 465  * If there is no currently adopted voucher, or no PERSONA_TOKEN attribute
 466  * in that voucher, this function fails.
 467  *
 468  * @param persona_info
 469  * The proc_persona_info structure to fill in case of success
 470  *
 471  * @result
 472  * 0 on success: currently adopted voucher has a PERSONA_TOKEN
 473  * -1 on failure: persona_info is untouched/uninitialized
 474  */
 475 API_AVAILABLE(ios(9.2))
 476 OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW OS_NONNULL1
 477 int
 478 voucher_get_current_persona_originator_info(
 479         struct proc_persona_info *persona_info);
 480
 481 /*!
 482  * @function voucher_get_current_persona_proximate_info
 483  *
 484  * @abstract
 485  * Retrieve the ’proximate’ process persona info for the currently adopted
 486  * voucher.
 487  *
 488  * @discussion
 489  * If there is no currently adopted voucher, or no PERSONA_TOKEN attribute
 490  * in that voucher, this function fails.
 491  *
 492  * @param persona_info
 493  * The proc_persona_info structure to fill in case of success
 494  *
 495  * @result
 496  * 0 on success: currently adopted voucher has a PERSONA_TOKEN
 497  * -1 on failure: persona_info is untouched/uninitialized
 498  */
 499 API_AVAILABLE(ios(9.2))
 500 OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW OS_NONNULL1
 501 int
 502 voucher_get_current_persona_proximate_info(
 503         struct proc_persona_info *persona_info);
 504
 505 #endif // __has_include(<mach/mach.h>)
 506
 507 __END_DECLS
 508
 509 DISPATCH_ASSUME_NONNULL_END
 510
 511 #endif // __OS_VOUCHER_PRIVATE__
 512
 513 #if OS_VOUCHER_ACTIVITY_SPI
 514 #include "voucher_activity_private.h"
 515 #endif