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
39int backtrace(void **_LIBC_COUNT(__size), int __size) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_2_0);
40
41API_AVAILABLE(macosx(10.14), ios(12.0), tvos(12.0), watchos(5.0))
42OS_EXPORT
43int backtrace_from_fp(void *startfp, void **_LIBC_COUNT(size) array, int size);
44
45char *_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);
46void backtrace_symbols_fd(void* const* _LIBC_COUNT(__size),int __size,int) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_2_0);
47
48struct 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
60API_AVAILABLE(macosx(10.14), ios(12.0), tvos(12.0), watchos(5.0))
61OS_EXPORT
62void 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 */
96API_AVAILABLE(macosx(12.0), ios(15.0), tvos(15.0), watchos(8.0))
97size_t backtrace_async(void** _LIBC_COUNT(length) array, size_t length, uint32_t *task_id);
98
99__END_DECLS
100
101#endif /* !_EXECINFO_H_ */