Loading...
gen/backtrace.3 Libc-1725.40.4 /dev/null
--- Libc/Libc-1725.40.4/gen/backtrace.3
+++ /dev/null
@@ -1,171 +0,0 @@
-.\" Copyright (c) 2007 Apple Inc.
-.\" All rights reserved.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in the
-.\"    documentation and/or other materials provided with the distribution.
-.\" 3. Neither the name of Apple Inc. ("Apple") nor the names of its
-.\"    contributors may be used to endorse or promote products derived from
-.\"    this software without specific prior written permission.
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY APPLE AND CONTRIBUTORS ``AS IS'' AND
-.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
-.\"
-.\"
-.Dd March 1, 2018
-.Dt backtrace 3
-.Os "Darwin"
-.Sh NAME
-.Nm backtrace ,
-.Nm backtrace_symbols ,
-.Nm backtrace_symbols_fd ,
-.Nm backtrace_image_offsets ,
-.Nm backtrace_from_fp
-.Nd call stack backtrace and display functions
-.Sh SYNOPSIS
-.In execinfo.h
-.Ft int
-.Fo backtrace
-.Fa "void** array"
-.Fa "int size"
-.Fc
-.Ft char**
-.Fo backtrace_symbols
-.Fa "void* const* array"
-.Fa "int size"
-.Fc
-.Ft void
-.Fo backtrace_symbols_fd
-.Fa "void* const* array"
-.Fa "int size"
-.Fa "int fd"
-.Fc
-.Ft void
-.Fo backtrace_image_offsets
-.Fa "void* const* array"
-.Fa "struct image_offset *image_offsets"
-.Fa "int size"
-.Fc
-.Ft int
-.Fo backtrace_from_fp
-.Fa "void* startfp"
-.Fa "void** array"
-.Fa "int size"
-.Fc
-.Ft size_t
-.Fo backtrace_async
-.Fa "void** array"
-.Fa "size_t size"
-.Fa "uint32_t* task_id"
-.Fc
-.Sh DESCRIPTION
-These routines provide a mechanism to examine the current thread's call stack.
-.Pp
-.Fn backtrace
-writes the function return addresses of the current call stack to the array of
-pointers referenced by
-.Fa array .
-At most,
-.Fa size
-pointers are written.  The number of pointers actually written to
-.Fa array
-is returned.
-.Pp
-.Fn backtrace_symbols
-attempts to transform a call stack obtained by
-.Fn backtrace
-into an array of human-readable strings using
-.Fn dladdr .
-The array of strings returned has
-.Fa size
-elements.  It is allocated using
-.Fn malloc
-and should be released using
-.Fn free .
-There is no need to free the individual strings in the array.
-.Pp
-.Fn backtrace_symbols_fd
-performs the same operation as
-.Fn backtrace_symbols ,
-but the resulting strings are immediately written to the file descriptor
-.Fa fd ,
-and are not returned.
-.Pp
-.Fn backtrace_image_offsets
-attempts to transform a call stack obtained by
-.Fn backtrace
-into an array of image offsets, for deferred symbolication.  Each entry in the
-array has an offset relative to the
-.Li __TEXT
-section of the image with the given UUID.  The results are written to
-.Fa image_offsets
-which should be an array of
-.Fa size
-length.
-.Pp
-.Fn backtrace_from_fp
-takes a backtrace of frames starting from the given frame pointer.
-.Pp
-.Fn backtrace_async
-behaves exactly like
-.Fn backtrace
-unless it is invoked from a Swift async context.  In that case, instead of
-writing the return addresses of the OS call stack, the continuation addresses
-of the async invocations that led to the current state are provided.  If
-unwinding an async stack rather than an OS stack, the value pointed to by
-.Fa task_id
-will be set to a non-zero identifier that for the current process uniquely
-identifies the async task currently running.  Otherwise, 0 is stored.
-.Pp
-Note that the continuation addresses provided by
-.Fn backtrace_async
-have an offset of 1 added to them.  Most symbolication engines will substract
-1 from the call stack return addresses in order to symbolicate the call site
-rather than the return location.  With a Swift async continuation, substracting
-1 from its address would result in an address in a different function.  This
-offset allows the returned addresses to be handled correctly by most existing
-symbolication engines.
-.Pp
-.Sh EXAMPLE
-.Pp
-    #include <execinfo.h>
-    #include <stdio.h>
-    ...
-    void* callstack[128];
-    int i, frames = backtrace(callstack, 128);
-    char** strs = backtrace_symbols(callstack, frames);
-    for (i = 0; i < frames; ++i) {
-        printf("%s\\n", strs[i]);
-    }
-    free(strs);
-    ...
-.Pp
-.Sh HISTORY
-.Fn backtrace ,
-.Fn backtrace_symbols ,
-and
-.Fn backtrace_symbols_fd
-first appeared in Mac OS X 10.5.
-.Fn backtrace_image_offsets
-and
-.Fn backtrace_from_fp
-first appeared macOS 10.14 and iOS 12.
-.Fn backtrace_async
-first appeared in macOS 12.
-.Sh SEE ALSO
-.Xr dladdr 3 ,
-.Xr malloc 3