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: *CoverageExternally managed, outlives this Info instance.
std.debug.Info.Allocator
alias
Alias of std.mem.Allocator
std.debug.Info.assert
alias
Alias of std.debug.assert
std.debug.Info.Coverage
alias
Alias of std.debug.Coverage
std.debug.Info.deinit
function
pub fn deinit(info: *Info, gpa: Allocator) void
Parameters
std.debug.Info.ElfFile
alias
Alias of std.debug.ElfFile
std.debug.Info.Info
alias
Alias of std.debug.Info
std.debug.Info.Io
alias
Alias of std.Io
std.debug.Info.load
function
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.EXCLset tofalse.
- 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_directorywas 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,
\\serveror\\server\sharewas 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
CREATflag is provided.- NotDir OpenError
A component used as a directory in the path was not, in fact, a directory, or
DIRECTORYwas specified and the path was not a directory.- OutOfMemory LoadError
- Overflow LoadError
- PathAlreadyExists OpenError
The path already exists and the
CREATandEXCLflags 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_bytesbytes. 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
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.EXCLset tofalse.
- 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_directorywas 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,
\\serveror\\server\sharewas 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
CREATflag is provided.- NotDir OpenError
A component used as a directory in the path was not, in fact, a directory, or
DIRECTORYwas specified and the path was not a directory.- OutOfMemory LoadError
- Overflow LoadError
- PathAlreadyExists OpenError
The path already exists and the
CREATandEXCLflags 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_bytesbytes. 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
Alias of std.debug.MachOFile
std.debug.Info.Path
alias
Alias of std.Build.Cache.Path
std.debug.Info.resolveAddresses
function
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 u64Asserts the addresses are in ascending order.
output: []SourceLocationAsserts its length equals length of sorted_pc_addrs.
Errors
std.debug.Info.ResolveAddressesError
error-set
Errors
std.debug.Info.SourceLocation
alias
Alias of std.debug.Coverage.SourceLocation
std.debug.Info.std
alias
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);
}
},
}
}