execinfo.h (3755B) - Raw
1 /* 2 * Copyright (c) 2007 Apple Inc. All rights reserved. 3 * 4 * @APPLE_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. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23 #ifndef _EXECINFO_H_ 24 #define _EXECINFO_H_ 1 25 26 #include <sys/cdefs.h> 27 #include <_bounds.h> 28 #include <Availability.h> 29 #include <os/base.h> 30 #include <os/availability.h> 31 #include <stddef.h> 32 #include <stdint.h> 33 #include <uuid/uuid.h> 34 35 _LIBC_SINGLE_BY_DEFAULT() 36 37 __BEGIN_DECLS 38 39 int backtrace(void **_LIBC_COUNT(__size), int __size) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_2_0); 40 41 API_AVAILABLE(macosx(10.14), ios(12.0), tvos(12.0), watchos(5.0)) 42 OS_EXPORT 43 int backtrace_from_fp(void *startfp, void **_LIBC_COUNT(size) array, int size); 44 45 char *_LIBC_CSTR *_LIBC_COUNT_OR_NULL(__size) backtrace_symbols(void* const* _LIBC_COUNT(__size), int __size) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_2_0); 46 void backtrace_symbols_fd(void* const* _LIBC_COUNT(__size),int __size,int) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_2_0); 47 48 struct image_offset { 49 /* 50 * The UUID of the image. 51 */ 52 uuid_t uuid; 53 54 /* 55 * The offset is relative to the __TEXT section of the image. 56 */ 57 uint32_t offset; 58 }; 59 60 API_AVAILABLE(macosx(10.14), ios(12.0), tvos(12.0), watchos(5.0)) 61 OS_EXPORT 62 void backtrace_image_offsets(void* const* _LIBC_COUNT(size) array, 63 struct image_offset *image_offsets, int size); 64 65 /*! 66 * @function backtrace_async 67 * Extracts the function return addresses of the current call stack. While 68 * backtrace() will only follow the OS call stack, backtrace_async() will 69 * prefer the unwind the Swift concurrency continuation stack if invoked 70 * from within an async context. In a non-async context this function is 71 * strictly equivalent to backtrace(). 72 * 73 * @param array 74 * The array of pointers to fill with the return addresses. 75 * 76 * @param length 77 * The maximum number of pointers to write. 78 * 79 * @param task_id 80 * Can be NULL. If non-NULL, the uint32_t pointed to by `task_id` is set to 81 * a non-zero value that for the current process uniquely identifies the async 82 * task currently running. If called from a non-async context, the value is 83 * set to 0 and `array` contains the same values backtrace() would return. 84 * 85 * Note that the continuation addresses provided by backtrace_async() 86 * have an offset of 1 added to them. Most symbolication engines will 87 * substract 1 from the call stack return addresses in order to symbolicate 88 * the call site rather than the return location. With a Swift async 89 * continuation, substracting 1 from its address would result in an address 90 * in a different function. This offset allows the returned addresses to be 91 * handled correctly by most existing symbolication engines. 92 * 93 * @result 94 * The number of pointers actually written. 95 */ 96 API_AVAILABLE(macosx(12.0), ios(15.0), tvos(15.0), watchos(8.0)) 97 size_t backtrace_async(void** _LIBC_COUNT(length) array, size_t length, uint32_t *task_id); 98 99 __END_DECLS 100 101 #endif /* !_EXECINFO_H_ */