pthread/stack_np.h

   1 /*
   2  * Copyright (c) 2018 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 __PTHREAD_STACK_NP__
  22 #define __PTHREAD_STACK_NP__
  23
  24 #include <Availability.h>
  25 #include <sys/cdefs.h>
  26 #include <stddef.h>
  27 #include <stdint.h>
  28 #include <stdbool.h>
  29 #include <os/base.h>
  30
  31 OS_ASSUME_NONNULL_BEGIN
  32
  33 /*! @header
  34  * Low-level API to introspect thread stacks.
  35  */
  36
  37 __BEGIN_DECLS
  38
  39 /*!
  40  * @function pthread_stack_frame_decode_np
  41  *
  42  * @abstract
  43  * Decodes the return address and the next stack frame address
  44  * from the given stack frame address.
  45  *
  46  * @discussion
  47  * Validation of the frame address is not performed by this function.
  48  * The caller is responsible for making sure the frame address is valid,
  49  * for example using pthread_get_stackaddr_np() and pthread_get_stacksize_np().
  50  *
  51  * @param frame_addr
  52  * A valid stack frame address such as __builtin_frame_address(0) or the return
  53  * value of a previous call to pthread_stack_frame_decode_np().
  54  *
  55  * @param return_addr
  56  * An optional out paramter that will be filled with the return address stored
  57  * at the specified stack frame.
  58  *
  59  * @returns
  60  * This returns the next frame address stored at the specified stack frame.
  61  */
  62 __OSX_AVAILABLE(10.14) __IOS_AVAILABLE(12.0)
  63 __TVOS_AVAILABLE(12.0) __WATCHOS_AVAILABLE(5.0)
  64 uintptr_t
  65 pthread_stack_frame_decode_np(uintptr_t frame_addr,
  66                 uintptr_t *_Nullable return_addr);
  67
  68 __END_DECLS
  69
  70 OS_ASSUME_NONNULL_END
  71
  72 #endif // __PTHREAD_STACK_NP__