Loading...
gen/backtrace.3 Libc-1439.100.3 /dev/null
--- Libc/Libc-1439.100.3/gen/backtrace.3
+++ /dev/null
@@ -1,142 +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
-.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.
-.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.
-.Sh SEE ALSO
-.Xr dladdr 3 ,
-.Xr malloc 3