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_ */