71 lines
1.7 KiB
Groff
71 lines
1.7 KiB
Groff
.\" Copyright (c) 2021, Apple Inc. All rights reserved.
|
|
.
|
|
.Dd June 30, 2021
|
|
.Dt BACKTRACE_PACK 9
|
|
.Os Darwin
|
|
.
|
|
.Sh NAME
|
|
.Nm backtrace_pack ,
|
|
.Nm backtrace_unpack
|
|
.Nd convert a backtrace to and from compact formats
|
|
.
|
|
.Sh SYNOPSIS
|
|
.In kern/backtrace.h
|
|
.Ft size_t
|
|
.Fo backtrace_pack
|
|
.Fa "backtrace_pack_t packing"
|
|
.Fa "uint8_t *dst"
|
|
.Fa "size_t dst_size"
|
|
.Fa "uintptr_t *src"
|
|
.Fa "unsigned int src_len"
|
|
.Fc
|
|
.
|
|
.Ft unsigned int
|
|
.Fo backtrace_unpack
|
|
.Fa "backtrace_pack_t packing"
|
|
.Fa "uintptr_t *dst"
|
|
.Fa "unsigned int dst_len"
|
|
.Fa "uint8_t *src"
|
|
.Fa "size_t src_size"
|
|
.Fc
|
|
.
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm backtrace_pack
|
|
and
|
|
.Nm backtrace_unpack
|
|
functions convert to and from a compact representation of a backtrace.
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn backtrace_pack
|
|
function returns the number of bytes written to the destination buffer.
|
|
The
|
|
.Fn backtrace_unpack
|
|
function returns the number of addresses written to the destination buffer.
|
|
.Sh FORMATS
|
|
.Bl -tag -width indent
|
|
.It Sy BTP_NONE
|
|
Just copy the addresses unpacked to the destination buffer.
|
|
.It Sy BTP_KERN_OFFSET_32
|
|
Subtract the kernel base address from each address so they fit in 4 bytes.
|
|
.El
|
|
.
|
|
.Sh EXAMPLE
|
|
.Bd -literal
|
|
uintptr_t bt[8] = { 0 };
|
|
enum backtrace_info bti = BTI_NONE;
|
|
unsigned int len = backtrace(bt, sizeof(bt) / sizeof(bt[0]), NULL, &bti);
|
|
uint8_t bt_packed[1024] = { 0 };
|
|
size_t packed_size = backtrace_pack(BTP_KERN_OFFSET_32, bt_packed,
|
|
sizeof(bt_packed), bt, len);
|
|
uintptr_t bt_unpacked[8] = { 0 };
|
|
unsigned int unpacked_len = backtrace_unpack(BTP_KERN_OFFSET_32, bt_unpacked,
|
|
sizeof(bt_unpacked) / sizeof(bt_unpacked[0]), bt_packed, packed_size);
|
|
assert(len == unpacked_len);
|
|
for (unsigned int i = 0; i < len; i++) {
|
|
assert(bt[i] == unpacked_bt[i]);
|
|
}
|
|
.Ed
|
|
.
|
|
.Sh SEE ALSO
|
|
.Xr backtrace 9
|