跳转到内容
标准库Zig 0.17.1官方原文
源码std/debug/Info.zig

第 1 行

将调试信息加载为内存格式的跨平台抽象, 支持查询诸如“这个虚拟内存地址对应哪个 源码位置?”等信息。

与 std.debug.SelfInfo 不同,此接口不假定 所处理的调试信息恰好与宿主的处理器架构、操作系统或其他目标 属性相匹配。

字段

impl: union(enum) {
    elf: ElfFile,
    macho: MachOFile,
}
coverage: *Coverage

由外部管理,存活时间长于此 Info 实例。

std.debug.Info.Allocator

别名

第 12 行

别名目标 std.mem.Allocator

std.debug.Info.assert

别名

第 14 行

别名目标 std.debug.assert

std.debug.Info.Coverage

别名

第 15 行

别名目标 std.debug.Coverage

std.debug.Info.deinit

函数

第 73 行

pub fn deinit(info: *Info, gpa: Allocator) void

参数

info: *Info
gpa: Allocator

std.debug.Info.ElfFile

别名

第 17 行

别名目标 std.debug.ElfFile

std.debug.Info.Info

别名

第 8 行

别名目标 std.debug.Info

std.debug.Info.Io

别名

第 11 行

别名目标 std.Io

std.debug.Info.load

函数

第 32 行

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

错误集合

第 27 行

错误

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

别名

第 18 行

别名目标 std.debug.MachOFile

std.debug.Info.Path

别名

第 13 行

别名目标 std.Build.Cache.Path

std.debug.Info.resolveAddresses

函数

第 85 行

给定按升序排列的虚拟内存地址数组,输出 对应的源码位置数组。

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 的长度。

错误

Canceled Cancelable

调用方请求停止异步操作。

EndOfStream ScanError
InvalidDebugInfo ScanError
MissingDebugInfo ScanError
OutOfMemory Error
Overflow ScanError
ReadFailed ScanError
StreamTooLong ScanError
UnsupportedDebugInfo

std.debug.Info.ResolveAddressesError

错误集合

第 81 行

错误

Canceled Cancelable

调用方请求停止异步操作。

EndOfStream ScanError
InvalidDebugInfo ScanError
MissingDebugInfo ScanError
OutOfMemory Error
Overflow ScanError
ReadFailed ScanError
StreamTooLong ScanError
UnsupportedDebugInfo

std.debug.Info.SourceLocation

别名

第 16 行

别名目标 std.debug.Coverage.SourceLocation

std.debug.Info.std

别名

第 10 行

别名目标 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);
            }
        },
    }
}