Skip to content
Standard libraryZig 0.17.1Official documentation
Sourcestd/debug/Info.zig

Source line 1

Cross-platform abstraction for loading debug information into an in-memory format that supports queries such as "what is the source location of this virtual memory address?"

Unlike std.debug.SelfInfo, this API does not assume the debug information in question happens to match the host CPU architecture, OS, or other target properties.

Fields

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

Externally managed, outlives this Info instance.

std.debug.Info.Allocator

alias

Source line 12

Alias of std.mem.Allocator

std.debug.Info.assert

alias

Source line 14

Alias of std.debug.assert

std.debug.Info.Coverage

alias

Source line 15

Alias of std.debug.Coverage

std.debug.Info.deinit

function

Source line 73

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

Parameters

info: *Info
gpa: Allocator

std.debug.Info.ElfFile

alias

Source line 17

Alias of std.debug.ElfFile

std.debug.Info.Info

alias

Source line 8

Alias of std.debug.Info

std.debug.Info.Io

alias

Source line 11

Alias of std.Io

std.debug.Info.load

function

Source line 32

pub fn load( gpa: Allocator, io: Io, path: Path, coverage: *Coverage, format: std.Target.ObjectFormat, arch: std.Target.Cpu.Arch, ) LoadError!Info

Parameters

gpa: Allocator
io: Io
path: Path
coverage: *Coverage
format: std.Target.ObjectFormat
arch: std.Target.Cpu.Arch

Errors

AccessDenied OpenError

In WASI, this error may occur when the file descriptor does not hold the required rights to open a new resource relative to it.

AntivirusInterference OpenError

On Windows, antivirus software is enabled by default. It can be disabled, but Windows Update sometimes ignores the user's preference and re-enables it. When enabled, antivirus software on Windows intercepts file system operations and makes them significantly slower in addition to possibly failing with this error code.

BadPathName PathNameError

File system cannot encode the requested file name bytes. Could be due to invalid WTF-8 on Windows, invalid UTF-8 on WASI, invalid characters on Windows, etc. Filesystem and operating specific.

Canceled Cancelable

Caller has requested the async operation to stop.

DeviceBusy OpenError
EndOfStream ScanError
FileBusy OpenError

One of these three things:

  • pathname refers to an executable image which is currently being executed and write access was requested.
  • pathname refers to a file that is currently in use as a swap file, and the O_TRUNC flag was specified.
  • pathname refers to a file that is currently being read by the kernel (e.g., for module/firmware loading), and write access was requested.
FileLocksUnsupported OpenError
FileNotFound OpenError

Either:

  • One of the path components does not exist.
  • Cwd was used, but cwd has been deleted.
  • The path associated with the open directory handle has been deleted.
  • On macOS, multiple processes or threads raced to create the same file with O.EXCL set to false.
FileTooBig OpenError

The file is too large to be opened. This error is unreachable for 64-bit targets, as well as when opening directories.

InvalidCompressedSection LoadError
InvalidDebugInfo ScanError
InvalidDwarf Error
InvalidElfClass LoadError
InvalidElfEndian LoadError
InvalidElfMagic LoadError
InvalidElfVersion LoadError
InvalidMachO Error
IsDir OpenError

Either:

  • The path refers to a directory and write permissions were requested.
  • The path refers to a directory and allow_directory was set to false.
LockedMemoryLimitExceeded LoadError
MemoryMappingNotSupported LoadError
MissingDebugInfo
NameTooLong PathNameError

Returned when an insufficient buffer is provided that cannot fit the path name.

NetworkNotFound OpenError

On Windows, \\server or \\server\share was not found.

NoDevice OpenError
NoSpaceLeft OpenError

A new path cannot be created because the device has no room for the new file. This error is only reachable when the CREAT flag is provided.

NotDir OpenError

A component used as a directory in the path was not, in fact, a directory, or DIRECTORY was specified and the path was not a directory.

OutOfMemory LoadError
Overflow LoadError
PathAlreadyExists OpenError

The path already exists and the CREAT and EXCL flags were provided.

PermissionDenied OpenError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadFailed Error
ReadOnlyFileSystem OpenError
StreamTooLong ScanError
Streaming LoadError
SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

The path exceeded max_path_bytes bytes. Insufficient kernel memory was available, or the named file is a FIFO and per-user hard limit on memory allocation for pipes has been reached.

TruncatedElfFile LoadError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnsupportedDebugInfo
WouldBlock OpenError

Non-blocking was requested and the operation cannot return immediately.

std.debug.Info.LoadError

error-set

Source line 27

Errors

AccessDenied OpenError

In WASI, this error may occur when the file descriptor does not hold the required rights to open a new resource relative to it.

AntivirusInterference OpenError

On Windows, antivirus software is enabled by default. It can be disabled, but Windows Update sometimes ignores the user's preference and re-enables it. When enabled, antivirus software on Windows intercepts file system operations and makes them significantly slower in addition to possibly failing with this error code.

BadPathName PathNameError

File system cannot encode the requested file name bytes. Could be due to invalid WTF-8 on Windows, invalid UTF-8 on WASI, invalid characters on Windows, etc. Filesystem and operating specific.

Canceled Cancelable

Caller has requested the async operation to stop.

DeviceBusy OpenError
EndOfStream ScanError
FileBusy OpenError

One of these three things:

  • pathname refers to an executable image which is currently being executed and write access was requested.
  • pathname refers to a file that is currently in use as a swap file, and the O_TRUNC flag was specified.
  • pathname refers to a file that is currently being read by the kernel (e.g., for module/firmware loading), and write access was requested.
FileLocksUnsupported OpenError
FileNotFound OpenError

Either:

  • One of the path components does not exist.
  • Cwd was used, but cwd has been deleted.
  • The path associated with the open directory handle has been deleted.
  • On macOS, multiple processes or threads raced to create the same file with O.EXCL set to false.
FileTooBig OpenError

The file is too large to be opened. This error is unreachable for 64-bit targets, as well as when opening directories.

InvalidCompressedSection LoadError
InvalidDebugInfo ScanError
InvalidDwarf Error
InvalidElfClass LoadError
InvalidElfEndian LoadError
InvalidElfMagic LoadError
InvalidElfVersion LoadError
InvalidMachO Error
IsDir OpenError

Either:

  • The path refers to a directory and write permissions were requested.
  • The path refers to a directory and allow_directory was set to false.
LockedMemoryLimitExceeded LoadError
MemoryMappingNotSupported LoadError
MissingDebugInfo
NameTooLong PathNameError

Returned when an insufficient buffer is provided that cannot fit the path name.

NetworkNotFound OpenError

On Windows, \\server or \\server\share was not found.

NoDevice OpenError
NoSpaceLeft OpenError

A new path cannot be created because the device has no room for the new file. This error is only reachable when the CREAT flag is provided.

NotDir OpenError

A component used as a directory in the path was not, in fact, a directory, or DIRECTORY was specified and the path was not a directory.

OutOfMemory LoadError
Overflow LoadError
PathAlreadyExists OpenError

The path already exists and the CREAT and EXCL flags were provided.

PermissionDenied OpenError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadFailed Error
ReadOnlyFileSystem OpenError
StreamTooLong ScanError
Streaming LoadError
SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

The path exceeded max_path_bytes bytes. Insufficient kernel memory was available, or the named file is a FIFO and per-user hard limit on memory allocation for pipes has been reached.

TruncatedElfFile LoadError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnsupportedDebugInfo
WouldBlock OpenError

Non-blocking was requested and the operation cannot return immediately.

std.debug.Info.MachOFile

alias

Source line 18

Alias of std.debug.MachOFile

std.debug.Info.Path

alias

Source line 13

Alias of std.Build.Cache.Path

std.debug.Info.resolveAddresses

function

Source line 85

Given an array of virtual memory addresses, sorted ascending, outputs a corresponding array of source locations.

pub fn resolveAddresses( info: *Info, gpa: Allocator, io: Io, sorted_pc_addrs: []const u64, output: []SourceLocation, ) ResolveAddressesError!void

Parameters

info: *Info
gpa: Allocator
io: Io
sorted_pc_addrs: []const u64

Asserts the addresses are in ascending order.

output: []SourceLocation

Asserts its length equals length of sorted_pc_addrs.

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

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

std.debug.Info.ResolveAddressesError

error-set

Source line 81

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

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

std.debug.Info.SourceLocation

alias

Source line 16

Alias of std.debug.Coverage.SourceLocation

std.debug.Info.std

alias

Source line 10

Alias of std

Source code

std/debug/Info.zig

//! Cross-platform abstraction for loading debug information into an in-memory
//! format that supports queries such as "what is the source location of this
//! virtual memory address?"
//!
//! Unlike `std.debug.SelfInfo`, this API does not assume the debug information
//! in question happens to match the host CPU architecture, OS, or other target
//! properties.
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,
},
/// Externally managed, outlives this `Info` instance.
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};

/// Given an array of virtual memory addresses, sorted ascending, outputs a
/// corresponding array of source locations.
pub fn resolveAddresses(
    info: *Info,
    gpa: Allocator,
    io: Io,
    /// Asserts the addresses are in ascending order.
    sorted_pc_addrs: []const u64,
    /// Asserts its length equals length of `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| {
            // Resolving all of the addresses at once unfortunately isn't so easy in Mach-O binaries
            // due to split debug information. For now, we'll just resolve the addreses one by one.
            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);
            }
        },
    }
}