将调试信息加载为内存格式的跨平台抽象, 支持查询诸如“这个虚拟内存地址对应哪个 源码位置?”等信息。
与 std.debug.SelfInfo 不同,此接口不假定
所处理的调试信息恰好与宿主的处理器架构、操作系统或其他目标
属性相匹配。
字段
std.debug.Info.Allocator
别名
别名目标 std.mem.Allocator
std.debug.Info.assert
别名
别名目标 std.debug.assert
std.debug.Info.Coverage
别名
别名目标 std.debug.Coverage
std.debug.Info.deinit
函数
pub fn deinit(info: *Info, gpa: Allocator) void
参数
std.debug.Info.ElfFile
别名
别名目标 std.debug.ElfFile
std.debug.Info.Info
别名
别名目标 std.debug.Info
std.debug.Info.Io
别名
别名目标 std.Io
std.debug.Info.load
函数
pub fn load( gpa: Allocator, io: Io, path: Path, coverage: *Coverage, format: std.Target.ObjectFormat, arch: std.Target.Cpu.Arch, ) LoadError!Info
参数
gpa: Allocator
io: Io
path: Path
coverage: *Coverage
format: std.Target.ObjectFormat
arch: std.Target.Cpu.Arch
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- EndOfStream ScanError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- InvalidCompressedSection LoadError
- InvalidDebugInfo ScanError
- InvalidDwarf Error
- InvalidElfClass LoadError
- InvalidElfEndian LoadError
- InvalidElfMagic LoadError
- InvalidElfVersion LoadError
- InvalidMachO Error
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LockedMemoryLimitExceeded LoadError
- MemoryMappingNotSupported LoadError
- MissingDebugInfo
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice OpenError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- OutOfMemory LoadError
- Overflow LoadError
- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied OpenError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadFailed Error
- ReadOnlyFileSystem OpenError
- StreamTooLong ScanError
- Streaming LoadError
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- TruncatedElfFile LoadError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnsupportedDebugInfo
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.debug.Info.LoadError
错误集合
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- EndOfStream ScanError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- InvalidCompressedSection LoadError
- InvalidDebugInfo ScanError
- InvalidDwarf Error
- InvalidElfClass LoadError
- InvalidElfEndian LoadError
- InvalidElfMagic LoadError
- InvalidElfVersion LoadError
- InvalidMachO Error
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LockedMemoryLimitExceeded LoadError
- MemoryMappingNotSupported LoadError
- MissingDebugInfo
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice OpenError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- OutOfMemory LoadError
- Overflow LoadError
- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied OpenError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadFailed Error
- ReadOnlyFileSystem OpenError
- StreamTooLong ScanError
- Streaming LoadError
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- TruncatedElfFile LoadError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnsupportedDebugInfo
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.debug.Info.MachOFile
别名
别名目标 std.debug.MachOFile
std.debug.Info.Path
别名
别名目标 std.Build.Cache.Path
std.debug.Info.resolveAddresses
函数
给定按升序排列的虚拟内存地址数组,输出 对应的源码位置数组。
pub fn resolveAddresses( info: *Info, gpa: Allocator, io: Io, sorted_pc_addrs: []const u64, output: []SourceLocation, ) ResolveAddressesError!void
参数
info: *Info
gpa: Allocator
io: Io
sorted_pc_addrs: []const u64断言地址按升序排列。
output: []SourceLocation断言其长度等于 sorted_pc_addrs 的长度。
错误
std.debug.Info.ResolveAddressesError
错误集合
错误
std.debug.Info.SourceLocation
别名
std.debug.Info.std
别名
别名目标 std
源码
std/debug/Info.zig
//! 将调试信息加载为内存格式的跨平台抽象,
//! 支持查询诸如“这个虚拟内存地址对应哪个
//! 源码位置?”等信息。
//!
//! 与 `std.debug.SelfInfo` 不同,此接口不假定
//! 所处理的调试信息恰好与宿主的处理器架构、操作系统或其他目标
//! 属性相匹配。
const Info = @This();
const std = @import("../std.zig");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const Path = std.Build.Cache.Path;
const assert = std.debug.assert;
const Coverage = std.debug.Coverage;
const SourceLocation = std.debug.Coverage.SourceLocation;
const ElfFile = std.debug.ElfFile;
const MachOFile = std.debug.MachOFile;
impl: union(enum) {
elf: ElfFile,
macho: MachOFile,
},
/// 由外部管理,存活时间长于此 `Info` 实例。
coverage: *Coverage,
pub const LoadError = error{
MissingDebugInfo,
UnsupportedDebugInfo,
} || Io.File.OpenError || ElfFile.LoadError || MachOFile.Error || std.debug.Dwarf.ScanError;
pub fn load(
gpa: Allocator,
io: Io,
path: Path,
coverage: *Coverage,
format: std.Target.ObjectFormat,
arch: std.Target.Cpu.Arch,
) LoadError!Info {
switch (format) {
.elf => {
var file = try path.root_dir.handle.openFile(io, path.sub_path, .{});
defer file.close(io);
var elf_file: ElfFile = try .load(gpa, io, file, null, &.none);
errdefer elf_file.deinit(gpa);
if (elf_file.dwarf == null) return error.MissingDebugInfo;
try elf_file.dwarf.?.open(gpa, elf_file.endian);
try elf_file.dwarf.?.populateRanges(gpa, elf_file.endian);
return .{
.impl = .{ .elf = elf_file },
.coverage = coverage,
};
},
.macho => {
const path_str = try path.toString(gpa);
defer gpa.free(path_str);
var macho_file: MachOFile = try .load(gpa, io, path_str, arch);
errdefer macho_file.deinit(gpa);
return .{
.impl = .{ .macho = macho_file },
.coverage = coverage,
};
},
else => return error.UnsupportedDebugInfo,
}
}
pub fn deinit(info: *Info, gpa: Allocator) void {
switch (info.impl) {
.elf => |*ef| ef.deinit(gpa),
.macho => |*mf| mf.deinit(gpa),
}
info.* = undefined;
}
pub const ResolveAddressesError = Coverage.ResolveAddressesDwarfError || error{UnsupportedDebugInfo};
/// 给定按升序排列的虚拟内存地址数组,输出
/// 对应的源码位置数组。
pub fn resolveAddresses(
info: *Info,
gpa: Allocator,
io: Io,
/// 断言地址按升序排列。
sorted_pc_addrs: []const u64,
/// 断言其长度等于 `sorted_pc_addrs` 的长度。
output: []SourceLocation,
) ResolveAddressesError!void {
assert(sorted_pc_addrs.len == output.len);
switch (info.impl) {
.elf => |*ef| return info.coverage.resolveAddressesDwarf(gpa, io, ef.endian, sorted_pc_addrs, output, &ef.dwarf.?),
.macho => |*mf| {
// 由于调试信息分散存放,在 Mach-O 二进制中一次性解析所有地址并不容易。
// 目前暂时逐个解析地址。
for (sorted_pc_addrs, output) |pc_addr, *src_loc| {
const dwarf, const dwarf_pc_addr = mf.getDwarfForAddress(gpa, io, pc_addr) catch |err| switch (err) {
error.MissingDebugInfo => {
src_loc.* = .invalid;
continue;
},
error.InvalidMachO, error.InvalidDwarf => return error.InvalidDebugInfo,
else => |e| return e,
};
if (dwarf.ranges.items.len == 0) {
dwarf.populateRanges(gpa, .little) catch |err| switch (err) {
error.EndOfStream,
error.Overflow,
error.StreamTooLong,
error.ReadFailed,
=> return error.InvalidDebugInfo,
else => |e| return e,
};
}
try info.coverage.resolveAddressesDwarf(gpa, io, .little, &.{dwarf_pc_addr}, src_loc[0..1], dwarf);
}
},
}
}