Cross-platform dynamic library loading and symbol lookup.
Platform-specific functionality is available through the inner field.
inner: InnerTypeanyerror means the error set is known only at runtime.
In WASI, this error may occur when the file descriptor does not hold the required rights to open a new resource relative to it.
Path contains characters that are disallowed by the underlying filesystem.
One of these three things:
The underlying filesystem does not support file locks
Either:
O.EXCL set to false.The file is too large to be opened. This error is unreachable for 64-bit targets, as well as when opening directories.
WASI-only; file paths must be valid UTF-8.
Windows-only; file paths provided by the user must be valid WTF-8. https://simonsapin.github.io/wtf-8/
The path refers to directory but the DIRECTORY flag was not provided.
Using FIXED_NOREPLACE flag and the process has already mapped memory at the given address
The underlying filesystem of the specified file does not support memory mapping.
The path exceeded max_path_bytes bytes.
On Windows, \\server or \\server\share was not found.
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.
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.
The path already exists and the CREAT and EXCL flags were provided.
The prot argument asks for PROT_EXEC but the mapped area belongs to a file on
a filesystem that was mounted no-exec.
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.
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.
pub const Error = ElfDynLibError || DlDynLibError || WindowsDynLibErrorTrusts the file. Malicious file will be able to execute arbitrary code.
path: []const u8Trusts the file. Malicious file will be able to execute arbitrary code.
path_c: [*:0]const u8pub const DynLib = struct {
const InnerType = switch (native_os) {
.linux => if (!builtin.link_libc or builtin.abi == .musl and builtin.link_mode == .static)
ElfDynLib
else
DlDynLib,
.windows => WindowsDynLib,
.macos, .tvos, .watchos, .ios, .visionos, .freebsd, .netbsd, .openbsd, .dragonfly, .solaris, .illumos => DlDynLib,
else => struct {
const open = @compileError("unsupported platform");
const openZ = @compileError("unsupported platform");
},
};
inner: InnerType,
pub const Error = ElfDynLibError || DlDynLibError || WindowsDynLibError;
/// Trusts the file. Malicious file will be able to execute arbitrary code.
pub fn open(path: []const u8) Error!DynLib {
return .{ .inner = try InnerType.open(path) };
}
/// Trusts the file. Malicious file will be able to execute arbitrary code.
pub fn openZ(path_c: [*:0]const u8) Error!DynLib {
return .{ .inner = try InnerType.openZ(path_c) };
}
/// Trusts the file.
pub fn close(self: *DynLib) void {
return self.inner.close();
}
pub fn lookup(self: *DynLib, comptime T: type, name: [:0]const u8) ?T {
return self.inner.lookup(T, name);
}
}