跳转到内容

std.dynamic_library

标准库Zig 0.17.1官方原文
源码std/dynamic_library.zig

第 1 行

std.dynamic_library.builtin

常量

第 1 行

std.dynamic_library.checkver

函数

第 529 行

fn checkver(def_arg: *elf.Verdef, vsym_arg: elf.Versym, vername: []const u8, strings: [*:0]u8) bool

参数

def_arg: *elf.Verdef
vsym_arg: elf.Versym
vername: []const u8
strings: [*:0]u8

std.dynamic_library.DlDynLib

容器

第 551 行

字段

handle: *anyopaque

std.dynamic_library.DlDynLib.close

函数

第 569 行

pub fn close(self: *DlDynLib) void

参数

self: *DlDynLib

std.dynamic_library.DlDynLib.Error

别名

第 552 行

别名目标 std.dynamic_library.DlDynLibError

std.dynamic_library.DlDynLib.getError

函数

第 590 行

DlDynLib 专用。 返回描述最近一次 lookup 错误的可读字符串; 如果初始化后或上次调用 getError 后没有发生错误,则返回 null。

pub fn getError() ?[:0]const u8

std.dynamic_library.DlDynLib.lookup

函数

第 577 行

pub fn lookup(self: *DlDynLib, comptime T: type, name: [:0]const u8) ?T

参数

self: *DlDynLib
T: type
name: [:0]const u8

std.dynamic_library.DlDynLib.open

函数

第 556 行

pub fn open(path: []const u8) Error!DlDynLib

参数

path: []const u8

错误

FileNotFound DlDynLibError
NameTooLong DlDynLibError

std.dynamic_library.DlDynLib.openZ

函数

第 561 行

pub fn openZ(path_c: [*:0]const u8) Error!DlDynLib

参数

path_c: [*:0]const u8

错误

FileNotFound DlDynLibError
NameTooLong DlDynLibError

std.dynamic_library.DlDynLibError

错误集合

第 549 行

单独放置以避免引用 DlDynLib,因为其字段类型在其他目标上 可能无效。

错误

FileNotFound
NameTooLong

std.dynamic_library.DynLib

容器

第 14 行

跨平台动态库加载和符号查找。 平台专属功能可通过 inner 字段访问。

字段

inner: InnerType

std.dynamic_library.DynLib.close

函数

第 50 行

信任该文件。

pub fn close(self: *DynLib) void

参数

self: *DynLib

std.dynamic_library.DynLib.Error

错误集合

第 29 行

错误

AccessDenied OpenError

在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。

AntivirusInterference OpenError

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

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

DeviceBusy OpenError
ElfHashTableNotFound ElfDynLibError
ElfStringSectionNotFound ElfDynLibError
ElfSymSectionNotFound ElfDynLibError
FileBusy OpenError

以下三种情况之一:

  • pathname 指向正在执行的可执行映像, 且请求写访问。
  • pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
  • pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
FileLocksUnsupported OpenError
FileNotFound OpenError

以下任一情况:

  • 某个路径分量不存在。
  • 使用了当前工作目录,但该目录已被删除。
  • 已打开目录句柄所关联的路径已被删除。
  • macOS 上,多个进程或线程将 O.EXCL 设为 false,并发争相创建同一文件。
FileTooBig OpenError

文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。

IsDir OpenError

以下任一情况:

  • 路径指向目录,但请求了写权限。
  • 路径指向目录,但 allow_directory 被设为 false。
LockedMemoryLimitExceeded MMapError
MappingAlreadyExists MMapError

使用 FIXED_NOREPLACE 标志,但进程已在给定地址映射内存。

MemoryMappingNotSupported MMapError

指定文件的底层文件系统不支持内存映射。

MissingDynamicLinkingInformation ElfDynLibError
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound OpenError

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice OpenError
NoSpaceLeft OpenError

设备没有空间容纳新文件,无法创建新路径。 仅在提供 CREAT 标志时才可能出现此错误。

NotDir OpenError

路径中用作目录的某个部分实际上不是目录, 或者指定了 DIRECTORY,但路径不是目录。

NotDynamicLibrary ElfDynLibError
NotElfFile ElfDynLibError
OutOfMemory MMapError
PathAlreadyExists OpenError

路径已存在,且提供了 CREAT 和 EXCL 标志。

PermissionDenied MMapError

prot 参数请求 PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。

PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
Streaming ElfDynLibError
SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

路径超过 max_path_bytes 字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock OpenError

已请求非阻塞模式,但该操作无法立即返回。

std.dynamic_library.DynLib.InnerType

类型

第 15 行

std.dynamic_library.DynLib.InnerType.open

常量

第 22 行

std.dynamic_library.DynLib.InnerType.openZ

常量

第 23 行

std.dynamic_library.DynLib.lookup

函数

第 54 行

pub fn lookup(self: *DynLib, comptime T: type, name: [:0]const u8) ?T

参数

self: *DynLib
T: type
name: [:0]const u8

std.dynamic_library.DynLib.open

函数

第 32 行

信任该文件。恶意文件将能够执行任意代码。

pub fn open(path: []const u8) Error!DynLib

参数

path: []const u8

错误

AccessDenied OpenError

在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。

AntivirusInterference OpenError

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

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

DeviceBusy OpenError
ElfHashTableNotFound ElfDynLibError
ElfStringSectionNotFound ElfDynLibError
ElfSymSectionNotFound ElfDynLibError
FileBusy OpenError

以下三种情况之一:

  • pathname 指向正在执行的可执行映像, 且请求写访问。
  • pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
  • pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
FileLocksUnsupported OpenError
FileNotFound OpenError

以下任一情况:

  • 某个路径分量不存在。
  • 使用了当前工作目录,但该目录已被删除。
  • 已打开目录句柄所关联的路径已被删除。
  • macOS 上,多个进程或线程将 O.EXCL 设为 false,并发争相创建同一文件。
FileTooBig OpenError

文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。

IsDir OpenError

以下任一情况:

  • 路径指向目录,但请求了写权限。
  • 路径指向目录,但 allow_directory 被设为 false。
LockedMemoryLimitExceeded MMapError
MappingAlreadyExists MMapError

使用 FIXED_NOREPLACE 标志,但进程已在给定地址映射内存。

MemoryMappingNotSupported MMapError

指定文件的底层文件系统不支持内存映射。

MissingDynamicLinkingInformation ElfDynLibError
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound OpenError

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice OpenError
NoSpaceLeft OpenError

设备没有空间容纳新文件,无法创建新路径。 仅在提供 CREAT 标志时才可能出现此错误。

NotDir OpenError

路径中用作目录的某个部分实际上不是目录, 或者指定了 DIRECTORY,但路径不是目录。

NotDynamicLibrary ElfDynLibError
NotElfFile ElfDynLibError
OutOfMemory MMapError
PathAlreadyExists OpenError

路径已存在,且提供了 CREAT 和 EXCL 标志。

PermissionDenied MMapError

prot 参数请求 PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。

PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
Streaming ElfDynLibError
SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

路径超过 max_path_bytes 字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock OpenError

已请求非阻塞模式,但该操作无法立即返回。

std.dynamic_library.DynLib.openZ

函数

第 41 行

信任该文件。恶意文件将能够执行任意代码。

pub fn openZ(path_c: [*:0]const u8) Error!DynLib

参数

path_c: [*:0]const u8

错误

AccessDenied OpenError

在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。

AntivirusInterference OpenError

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

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

DeviceBusy OpenError
ElfHashTableNotFound ElfDynLibError
ElfStringSectionNotFound ElfDynLibError
ElfSymSectionNotFound ElfDynLibError
FileBusy OpenError

以下三种情况之一:

  • pathname 指向正在执行的可执行映像, 且请求写访问。
  • pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
  • pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
FileLocksUnsupported OpenError
FileNotFound OpenError

以下任一情况:

  • 某个路径分量不存在。
  • 使用了当前工作目录,但该目录已被删除。
  • 已打开目录句柄所关联的路径已被删除。
  • macOS 上,多个进程或线程将 O.EXCL 设为 false,并发争相创建同一文件。
FileTooBig OpenError

文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。

IsDir OpenError

以下任一情况:

  • 路径指向目录,但请求了写权限。
  • 路径指向目录,但 allow_directory 被设为 false。
LockedMemoryLimitExceeded MMapError
MappingAlreadyExists MMapError

使用 FIXED_NOREPLACE 标志,但进程已在给定地址映射内存。

MemoryMappingNotSupported MMapError

指定文件的底层文件系统不支持内存映射。

MissingDynamicLinkingInformation ElfDynLibError
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound OpenError

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice OpenError
NoSpaceLeft OpenError

设备没有空间容纳新文件,无法创建新路径。 仅在提供 CREAT 标志时才可能出现此错误。

NotDir OpenError

路径中用作目录的某个部分实际上不是目录, 或者指定了 DIRECTORY,但路径不是目录。

NotDynamicLibrary ElfDynLibError
NotElfFile ElfDynLibError
OutOfMemory MMapError
PathAlreadyExists OpenError

路径已存在,且提供了 CREAT 和 EXCL 标志。

PermissionDenied MMapError

prot 参数请求 PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。

PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
Streaming ElfDynLibError
SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

路径超过 max_path_bytes 字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock OpenError

已请求非阻塞模式,但该操作无法立即返回。

std.dynamic_library.elf

别名

第 8 行

别名目标 std.elf

std.dynamic_library.ElfDynLib

容器

第 152 行

字段

strings: [*:0]u8
syms: [*]elf.Sym
hash_table: HashTable
versym: ?[*]elf.Versym
verdef: ?*elf.Verdef
memory: []align(std.heap.page_size_min) u8

std.dynamic_library.ElfDynLib.close

函数

第 365 行

信任该文件

pub fn close(self: *ElfDynLib) void

参数

self: *ElfDynLib

std.dynamic_library.ElfDynLib.elfToProt

函数

第 520 行

fn elfToProt(elf_prot: elf.PF) posix.PROT

参数

elf_prot: elf.PF

std.dynamic_library.ElfDynLib.Error

别名

第 160 行

别名目标 std.dynamic_library.ElfDynLibError

std.dynamic_library.ElfDynLib.GnuHashSection32

容器

第 378 行

字段

symoffset: u32
bloom_shift: u32
bloom: []u32
buckets: []u32
chain: [*]elf.gnu_hash.ChainEntry

std.dynamic_library.ElfDynLib.GnuHashSection32.fromPtr

函数

第 385 行

pub fn fromPtr(header: *elf.gnu_hash.Header) @This()

参数

header: *elf.gnu_hash.Header

std.dynamic_library.ElfDynLib.GnuHashSection64

容器

第 405 行

字段

symoffset: u32
bloom_shift: u32
bloom: []u64
buckets: []u32
chain: [*]elf.gnu_hash.ChainEntry

std.dynamic_library.ElfDynLib.GnuHashSection64.fromPtr

函数

第 412 行

pub fn fromPtr(header: *elf.gnu_hash.Header) @This()

参数

header: *elf.gnu_hash.Header

std.dynamic_library.ElfDynLib.HashTable

容器

第 162 行

字段

dt_hash: [*]posix.Elf_Symndx
dt_gnu_hash: *elf.gnu_hash.Header

std.dynamic_library.ElfDynLib.lookup

函数

第 370 行

pub fn lookup(self: *const ElfDynLib, comptime T: type, name: [:0]const u8) ?T

参数

self: *const ElfDynLib
T: type
name: [:0]const u8

std.dynamic_library.ElfDynLib.lookupAddress

函数

第 434 行

ElfDynLib 专用 返回符号的地址

pub fn lookupAddress(self: *const ElfDynLib, vername: []const u8, name: []const u8) ?usize

参数

self: *const ElfDynLib
vername: []const u8
name: []const u8

std.dynamic_library.ElfDynLib.open

函数

第 224 行

信任该文件。恶意文件将能够执行任意代码。

pub fn open(path: []const u8, LD_LIBRARY_PATH: ?[]const u8) Error!ElfDynLib

参数

path: []const u8
LD_LIBRARY_PATH: ?[]const u8

错误

AccessDenied OpenError

在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。

AntivirusInterference OpenError

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

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

DeviceBusy OpenError
ElfHashTableNotFound ElfDynLibError
ElfStringSectionNotFound ElfDynLibError
ElfSymSectionNotFound ElfDynLibError
FileBusy OpenError

以下三种情况之一:

  • pathname 指向正在执行的可执行映像, 且请求写访问。
  • pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
  • pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
FileLocksUnsupported OpenError
FileNotFound OpenError

以下任一情况:

  • 某个路径分量不存在。
  • 使用了当前工作目录,但该目录已被删除。
  • 已打开目录句柄所关联的路径已被删除。
  • macOS 上,多个进程或线程将 O.EXCL 设为 false,并发争相创建同一文件。
FileTooBig OpenError

文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。

IsDir OpenError

以下任一情况:

  • 路径指向目录,但请求了写权限。
  • 路径指向目录,但 allow_directory 被设为 false。
LockedMemoryLimitExceeded MMapError
MappingAlreadyExists MMapError

使用 FIXED_NOREPLACE 标志,但进程已在给定地址映射内存。

MemoryMappingNotSupported MMapError

指定文件的底层文件系统不支持内存映射。

MissingDynamicLinkingInformation ElfDynLibError
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound OpenError

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice OpenError
NoSpaceLeft OpenError

设备没有空间容纳新文件,无法创建新路径。 仅在提供 CREAT 标志时才可能出现此错误。

NotDir OpenError

路径中用作目录的某个部分实际上不是目录, 或者指定了 DIRECTORY,但路径不是目录。

NotDynamicLibrary ElfDynLibError
NotElfFile ElfDynLibError
OutOfMemory MMapError
PathAlreadyExists OpenError

路径已存在,且提供了 CREAT 和 EXCL 标志。

PermissionDenied MMapError

prot 参数请求 PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。

PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
Streaming ElfDynLibError
SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

路径超过 max_path_bytes 字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock OpenError

已请求非阻塞模式,但该操作无法立即返回。

std.dynamic_library.ElfDynLib.openPath

函数

第 167 行

fn openPath(io: Io, path: []const u8) !Io.Dir

参数

io: Io
path: []const u8

std.dynamic_library.ElfDynLib.openZ

函数

第 360 行

信任该文件。恶意文件将能够执行任意代码。

pub fn openZ(path_c: [*:0]const u8, LD_LIBRARY_PATH: ?[]const u8) Error!ElfDynLib

参数

path_c: [*:0]const u8
LD_LIBRARY_PATH: ?[]const u8

错误

AccessDenied OpenError

在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。

AntivirusInterference OpenError

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

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

DeviceBusy OpenError
ElfHashTableNotFound ElfDynLibError
ElfStringSectionNotFound ElfDynLibError
ElfSymSectionNotFound ElfDynLibError
FileBusy OpenError

以下三种情况之一:

  • pathname 指向正在执行的可执行映像, 且请求写访问。
  • pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
  • pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
FileLocksUnsupported OpenError
FileNotFound OpenError

以下任一情况:

  • 某个路径分量不存在。
  • 使用了当前工作目录,但该目录已被删除。
  • 已打开目录句柄所关联的路径已被删除。
  • macOS 上,多个进程或线程将 O.EXCL 设为 false,并发争相创建同一文件。
FileTooBig OpenError

文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。

IsDir OpenError

以下任一情况:

  • 路径指向目录,但请求了写权限。
  • 路径指向目录,但 allow_directory 被设为 false。
LockedMemoryLimitExceeded MMapError
MappingAlreadyExists MMapError

使用 FIXED_NOREPLACE 标志,但进程已在给定地址映射内存。

MemoryMappingNotSupported MMapError

指定文件的底层文件系统不支持内存映射。

MissingDynamicLinkingInformation ElfDynLibError
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound OpenError

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice OpenError
NoSpaceLeft OpenError

设备没有空间容纳新文件,无法创建新路径。 仅在提供 CREAT 标志时才可能出现此错误。

NotDir OpenError

路径中用作目录的某个部分实际上不是目录, 或者指定了 DIRECTORY,但路径不是目录。

NotDynamicLibrary ElfDynLibError
NotElfFile ElfDynLibError
OutOfMemory MMapError
PathAlreadyExists OpenError

路径已存在,且提供了 CREAT 和 EXCL 标志。

PermissionDenied MMapError

prot 参数请求 PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。

PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
Streaming ElfDynLibError
SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

路径超过 max_path_bytes 字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock OpenError

已请求非阻塞模式,但该操作无法立即返回。

std.dynamic_library.ElfDynLib.resolveFromName

函数

第 200 行

fn resolveFromName(io: Io, path_or_name: []const u8, LD_LIBRARY_PATH: ?[]const u8) !Io.File

参数

io: Io
path_or_name: []const u8
LD_LIBRARY_PATH: ?[]const u8

std.dynamic_library.ElfDynLib.resolveFromParent

函数

第 189 行

fn resolveFromParent(io: Io, dir_path: []const u8, file_name: []const u8) ?Io.File

参数

io: Io
dir_path: []const u8
file_name: []const u8

std.dynamic_library.ElfDynLib.resolveFromSearchPath

函数

第 179 行

fn resolveFromSearchPath(io: Io, search_path: []const u8, file_name: []const u8, delim: u8) ?Io.File

参数

io: Io
search_path: []const u8
file_name: []const u8
delim: u8

std.dynamic_library.ElfDynLibError

错误集合

第 140 行

单独分离,以避免引用 ElfDynLib,因为其字段类型 在其他目标上可能无效。

错误

AccessDenied OpenError

在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。

AntivirusInterference OpenError

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

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

DeviceBusy OpenError
ElfHashTableNotFound
ElfStringSectionNotFound
ElfSymSectionNotFound
FileBusy OpenError

以下三种情况之一:

  • pathname 指向正在执行的可执行映像, 且请求写访问。
  • pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
  • pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
FileLocksUnsupported OpenError
FileNotFound OpenError

以下任一情况:

  • 某个路径分量不存在。
  • 使用了当前工作目录,但该目录已被删除。
  • 已打开目录句柄所关联的路径已被删除。
  • macOS 上,多个进程或线程将 O.EXCL 设为 false,并发争相创建同一文件。
FileTooBig OpenError

文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。

IsDir OpenError

以下任一情况:

  • 路径指向目录,但请求了写权限。
  • 路径指向目录,但 allow_directory 被设为 false。
LockedMemoryLimitExceeded MMapError
MappingAlreadyExists MMapError

使用 FIXED_NOREPLACE 标志,但进程已在给定地址映射内存。

MemoryMappingNotSupported MMapError

指定文件的底层文件系统不支持内存映射。

MissingDynamicLinkingInformation
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound OpenError

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice OpenError
NoSpaceLeft OpenError

设备没有空间容纳新文件,无法创建新路径。 仅在提供 CREAT 标志时才可能出现此错误。

NotDir OpenError

路径中用作目录的某个部分实际上不是目录, 或者指定了 DIRECTORY,但路径不是目录。

NotDynamicLibrary
NotElfFile
OutOfMemory MMapError
PathAlreadyExists OpenError

路径已存在,且提供了 CREAT 和 EXCL 标志。

PermissionDenied MMapError

prot 参数请求 PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。

PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
Streaming
SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

路径超过 max_path_bytes 字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock OpenError

已请求非阻塞模式,但该操作无法立即返回。

std.dynamic_library.get_DYNAMIC

函数

第 96 行

TODO: 修复外部符号指针的比较,以便无需此辅助函数。

pub fn get_DYNAMIC() ?[*]const elf.Dyn

std.dynamic_library.Io

别名

第 5 行

别名目标 std.Io

std.dynamic_library.LinkMap

容器

第 64 行

字段

addr: usize
name: [*:0]const u8
ld: ?*elf.Dyn
next: ?*LinkMap
prev: ?*LinkMap

std.dynamic_library.linkmap_iterator

函数

第 104 行

pub fn linkmap_iterator() error{InvalidExe}!LinkMap.Iterator

错误

InvalidExe

std.dynamic_library.LinkMap.Iterator

容器

第 71 行

字段

current: ?*LinkMap

std.dynamic_library.LinkMap.Iterator.end

函数

第 74 行

pub fn end(self: *Iterator) bool

参数

self: *Iterator

std.dynamic_library.LinkMap.Iterator.next

函数

第 78 行

pub fn next(self: *Iterator) ?*LinkMap

参数

self: *Iterator

std.dynamic_library.mem

别名

第 6 行

别名目标 std.mem

std.dynamic_library.native_os

常量

第 2 行

std.dynamic_library.posix

别名

第 10 行

别名目标 std.posix

std.dynamic_library.RDebug

容器

第 88 行

字段

version: i32
map: ?*LinkMap
brk: usize
ldbase: usize

std.dynamic_library.std

别名

第 4 行

别名目标 std

std.dynamic_library.testing

别名

第 7 行

别名目标 std.testing

std.dynamic_library.windows

别名

第 9 行

别名目标 std.os.windows

源码

std/dynamic_library.zig

const builtin = @import("builtin");
const native_os = builtin.os.tag;

const std = @import("std.zig");
const Io = std.Io;
const mem = std.mem;
const testing = std.testing;
const elf = std.elf;
const windows = std.os.windows;
const posix = std.posix;

/// 跨平台动态库加载和符号查找。
/// 平台专属功能可通过 `inner` 字段访问。
pub 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,
        .driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos, .freebsd, .netbsd, .openbsd, .dragonfly, .illumos => DlDynLib,
        else => struct {
            const open = @compileError("unsupported platform");
            const openZ = @compileError("unsupported platform");
        },
    };

    inner: InnerType,

    pub const Error = ElfDynLibError || DlDynLibError;

    /// 信任该文件。恶意文件将能够执行任意代码。
    pub fn open(path: []const u8) Error!DynLib {
        if (InnerType == ElfDynLib) {
            return .{ .inner = try InnerType.open(path, null) };
        } else {
            return .{ .inner = try InnerType.open(path) };
        }
    }

    /// 信任该文件。恶意文件将能够执行任意代码。
    pub fn openZ(path_c: [*:0]const u8) Error!DynLib {
        if (InnerType == ElfDynLib) {
            return .{ .inner = try InnerType.openZ(path_c, null) };
        } else {
            return .{ .inner = try InnerType.openZ(path_c) };
        }
    }

    /// 信任该文件。
    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);
    }
};

// 除下方列出的字段外,link_map 结构体没有完整规定,
// 任何 libc 都可自由地在剩余空间存储额外
// 数据。
// 提供迭代器,以便按惯用
// 方式遍历链表。
const LinkMap = extern struct {
    addr: usize,
    name: [*:0]const u8,
    ld: ?*elf.Dyn,
    next: ?*LinkMap,
    prev: ?*LinkMap,

    pub const Iterator = struct {
        current: ?*LinkMap,

        pub fn end(self: *Iterator) bool {
            return self.current == null;
        }

        pub fn next(self: *Iterator) ?*LinkMap {
            if (self.current) |it| {
                self.current = it.next;
                return it;
            }
            return null;
        }
    };
};

const RDebug = extern struct {
    version: i32,
    map: ?*LinkMap,
    brk: usize,
    ldbase: usize,
};

/// TODO: 修复外部符号指针的比较,以便无需此辅助函数。
pub fn get_DYNAMIC() ?[*]const elf.Dyn {
    return @extern([*]const elf.Dyn, .{
        .name = "_DYNAMIC",
        .linkage = .weak,
        .visibility = .hidden,
    });
}

pub fn linkmap_iterator() error{InvalidExe}!LinkMap.Iterator {
    const _DYNAMIC = get_DYNAMIC() orelse {
        // 没有 PT.DYNAMIC 表示这是静态链接的非 PIE 程序。
        return .{ .current = null };
    };

    const link_map_ptr = init: {
        var i: usize = 0;
        while (_DYNAMIC[i].d_tag != elf.DT_NULL) : (i += 1) {
            switch (_DYNAMIC[i].d_tag) {
                elf.DT_DEBUG => {
                    const ptr = @as(?*RDebug, @ptrFromInt(_DYNAMIC[i].d_val));
                    if (ptr) |r_debug| {
                        if (r_debug.version != 1) return error.InvalidExe;
                        break :init r_debug.map;
                    }
                },
                elf.DT_PLTGOT => {
                    const ptr = @as(?[*]usize, @ptrFromInt(_DYNAMIC[i].d_val));
                    if (ptr) |got_table| {
                        // link_map 结构体的地址存储在第二个槽中
                        //
                        break :init @as(?*LinkMap, @ptrFromInt(got_table[1]));
                    }
                },
                else => {},
            }
        }
        return .{ .current = null };
    };

    return .{ .current = link_map_ptr };
}

/// 单独分离,以避免引用 `ElfDynLib`,因为其字段类型
/// 在其他目标上可能无效。
const ElfDynLibError = error{
    FileTooBig,
    NotElfFile,
    NotDynamicLibrary,
    MissingDynamicLinkingInformation,
    ElfStringSectionNotFound,
    ElfSymSectionNotFound,
    ElfHashTableNotFound,
    Canceled,
    Streaming,
} || Io.File.OpenError || posix.MMapError;

pub const ElfDynLib = struct {
    strings: [*:0]u8,
    syms: [*]elf.Sym,
    hash_table: HashTable,
    versym: ?[*]elf.Versym,
    verdef: ?*elf.Verdef,
    memory: []align(std.heap.page_size_min) u8,

    pub const Error = ElfDynLibError;

    const HashTable = union(enum) {
        dt_hash: [*]posix.Elf_Symndx,
        dt_gnu_hash: *elf.gnu_hash.Header,
    };

    fn openPath(io: Io, path: []const u8) !Io.Dir {
        if (path.len == 0) return error.NotDir;
        var parts = std.mem.tokenizeScalar(u8, path, '/');
        var parent = if (path[0] == '/') try Io.Dir.cwd().openDir(io, "/", .{}) else Io.Dir.cwd();
        while (parts.next()) |part| {
            const child = try parent.openDir(io, part, .{});
            parent.close(io);
            parent = child;
        }
        return parent;
    }

    fn resolveFromSearchPath(io: Io, search_path: []const u8, file_name: []const u8, delim: u8) ?Io.File {
        var paths = std.mem.tokenizeScalar(u8, search_path, delim);
        while (paths.next()) |p| {
            var dir = openPath(io, p) catch continue;
            defer dir.close(io);
            return dir.openFile(io, file_name, .{}) catch continue;
        }
        return null;
    }

    fn resolveFromParent(io: Io, dir_path: []const u8, file_name: []const u8) ?Io.File {
        var dir = Io.Dir.cwd().openDir(io, dir_path, .{}) catch return null;
        defer dir.close(io);
        return dir.openFile(io, file_name, .{}) catch null;
    }

    // 实现了通常加载系统库所需的功能。
    // 与 dlopen 的区别:
    // - 不使用调用方二进制的 DT_RPATH 作为搜索路径
    // - 不使用调用方二进制的 DT_RUNPATH 作为搜索路径
    // - 不读取 /etc/ld.so.cache
    fn resolveFromName(io: Io, path_or_name: []const u8, LD_LIBRARY_PATH: ?[]const u8) !Io.File {
        if (std.mem.findScalarPos(u8, path_or_name, 0, '/')) |_| {
            return Io.Dir.cwd().openFile(io, path_or_name, .{});
        }

        // 仅当二进制文件未设置 setuid/setgid 时读取 LD_LIBRARY_PATH。
        if (std.os.linux.geteuid() == std.os.linux.getuid() and
            std.os.linux.getegid() == std.os.linux.getgid())
        {
            if (LD_LIBRARY_PATH) |ld_library_path| {
                if (resolveFromSearchPath(io, ld_library_path, path_or_name, ':')) |file| {
                    return file;
                }
            }
        }

        if (resolveFromParent(io, "/lib", path_or_name)) |file| return file;
        if (resolveFromParent(io, "/lib64", path_or_name)) |file| return file;
        if (resolveFromParent(io, "/usr/lib", path_or_name)) |file| return file;
        if (resolveFromParent(io, "/usr/lib64", path_or_name)) |file| return file;
        return error.FileNotFound;
    }

    /// 信任该文件。恶意文件将能够执行任意代码。
    pub fn open(path: []const u8, LD_LIBRARY_PATH: ?[]const u8) Error!ElfDynLib {
        const io = std.Options.debug_io;

        const file = try resolveFromName(io, path, LD_LIBRARY_PATH);
        defer file.close(io);

        const stat = try file.stat(io);
        const size = std.math.cast(usize, stat.size) orelse return error.FileTooBig;

        const page_size = std.heap.pageSize();

        // 此映射用于读取 ELF 信息。
        // 稍后将针对实际的 LOAD 段创建更多内存映射。
        const file_bytes = try posix.mmap(
            null,
            mem.alignForward(usize, size, page_size),
            .{ .READ = true },
            .{ .TYPE = .PRIVATE },
            file.handle,
            0,
        );
        defer posix.munmap(file_bytes);

        const eh = @as(*elf.Ehdr, @ptrCast(file_bytes.ptr));
        if (!mem.eql(u8, eh.e_ident[0..4], elf.MAGIC)) return error.NotElfFile;
        if (eh.e_type != elf.ET.DYN) return error.NotDynamicLibrary;

        const elf_addr = @intFromPtr(file_bytes.ptr);

        // 遍历程序头条目,以找到动态向量以及虚拟内存总大小。
        //
        var maybe_dynv: ?[*]usize = null;
        var virt_addr_end: usize = 0;
        {
            var i: usize = 0;
            var ph_addr: usize = elf_addr + eh.e_phoff;
            while (i < eh.e_phnum) : ({
                i += 1;
                ph_addr += eh.e_phentsize;
            }) {
                const ph = @as(*elf.ElfN.Phdr, @ptrFromInt(ph_addr));
                switch (ph.type) {
                    .LOAD => virt_addr_end = @max(virt_addr_end, ph.vaddr + ph.memsz),
                    .DYNAMIC => maybe_dynv = @as([*]usize, @ptrFromInt(elf_addr + ph.offset)),
                    else => {},
                }
            }
        }
        const dynv = maybe_dynv orelse return error.MissingDynamicLinkingInformation;

        // 预留整个地址范围(不授予任何权限),以便在下方使用 MAP.FIXED。
        const all_loaded_mem = try posix.mmap(
            null,
            virt_addr_end,
            .{},
            .{ .TYPE = .PRIVATE, .ANONYMOUS = true },
            -1,
            0,
        );
        errdefer posix.munmap(all_loaded_mem);

        const base = @intFromPtr(all_loaded_mem.ptr);

        // 现在再次迭代,实际加载所有程序节。
        {
            var i: usize = 0;
            var ph_addr: usize = elf_addr + eh.e_phoff;
            while (i < eh.e_phnum) : ({
                i += 1;
                ph_addr += eh.e_phentsize;
            }) {
                const ph = @as(*elf.ElfN.Phdr, @ptrFromInt(ph_addr));
                switch (ph.type) {
                    .LOAD => {
                        // VirtAddr 可能未按页对齐;此时 VirtAddr、MemSiz
                        // 之前/之后会额外映射无关内容。
                        const aligned_addr = (base + ph.vaddr) & ~(@as(usize, page_size) - 1);
                        const extra_bytes = (base + ph.vaddr) - aligned_addr;
                        const extended_memsz = mem.alignForward(usize, ph.memsz + extra_bytes, page_size);
                        const ptr = @as([*]align(std.heap.page_size_min) u8, @ptrFromInt(aligned_addr));
                        const prot = elfToProt(ph.flags);
                        _ = try posix.mmap(
                            ptr,
                            extended_memsz,
                            prot,
                            .{ .TYPE = .PRIVATE, .FIXED = true },
                            file.handle,
                            ph.offset - extra_bytes,
                        );
                    },
                    else => {},
                }
            }
        }

        var maybe_strings: ?[*:0]u8 = null;
        var maybe_syms: ?[*]elf.Sym = null;
        var maybe_hashtab: ?[*]posix.Elf_Symndx = null;
        var maybe_gnu_hash: ?*elf.gnu_hash.Header = null;
        var maybe_versym: ?[*]elf.Versym = null;
        var maybe_verdef: ?*elf.Verdef = null;

        {
            var i: usize = 0;
            while (dynv[i] != 0) : (i += 2) {
                const p = base + dynv[i + 1];
                switch (dynv[i]) {
                    elf.DT_STRTAB => maybe_strings = @ptrFromInt(p),
                    elf.DT_SYMTAB => maybe_syms = @ptrFromInt(p),
                    elf.DT_HASH => maybe_hashtab = @ptrFromInt(p),
                    elf.DT_GNU_HASH => maybe_gnu_hash = @ptrFromInt(p),
                    elf.DT_VERSYM => maybe_versym = @ptrFromInt(p),
                    elf.DT_VERDEF => maybe_verdef = @ptrFromInt(p),
                    else => {},
                }
            }
        }

        const hash_table: HashTable = if (maybe_gnu_hash) |gnu_hash|
            .{ .dt_gnu_hash = gnu_hash }
        else if (maybe_hashtab) |hashtab|
            .{ .dt_hash = hashtab }
        else
            return error.ElfHashTableNotFound;

        return .{
            .memory = all_loaded_mem,
            .strings = maybe_strings orelse return error.ElfStringSectionNotFound,
            .syms = maybe_syms orelse return error.ElfSymSectionNotFound,
            .hash_table = hash_table,
            .versym = maybe_versym,
            .verdef = maybe_verdef,
        };
    }

    /// 信任该文件。恶意文件将能够执行任意代码。
    pub fn openZ(path_c: [*:0]const u8, LD_LIBRARY_PATH: ?[]const u8) Error!ElfDynLib {
        return open(mem.sliceTo(path_c, 0), LD_LIBRARY_PATH);
    }

    /// 信任该文件
    pub fn close(self: *ElfDynLib) void {
        posix.munmap(self.memory);
        self.* = undefined;
    }

    pub fn lookup(self: *const ElfDynLib, comptime T: type, name: [:0]const u8) ?T {
        if (self.lookupAddress("", name)) |symbol| {
            return @as(T, @ptrFromInt(symbol));
        } else {
            return null;
        }
    }

    pub const GnuHashSection32 = struct {
        symoffset: u32,
        bloom_shift: u32,
        bloom: []u32,
        buckets: []u32,
        chain: [*]elf.gnu_hash.ChainEntry,

        pub fn fromPtr(header: *elf.gnu_hash.Header) @This() {
            const header_offset = @intFromPtr(header);
            const bloom_offset = header_offset + @sizeOf(elf.gnu_hash.Header);
            const buckets_offset = bloom_offset + header.bloom_size * @sizeOf(u32);
            const chain_offset = buckets_offset + header.nbuckets * @sizeOf(u32);

            const bloom_ptr: [*]u32 = @ptrFromInt(bloom_offset);
            const buckets_ptr: [*]u32 = @ptrFromInt(buckets_offset);
            const chain_ptr: [*]elf.gnu_hash.ChainEntry = @ptrFromInt(chain_offset);

            return .{
                .symoffset = header.symoffset,
                .bloom_shift = header.bloom_shift,
                .bloom = bloom_ptr[0..header.bloom_size],
                .buckets = buckets_ptr[0..header.nbuckets],
                .chain = chain_ptr,
            };
        }
    };

    pub const GnuHashSection64 = struct {
        symoffset: u32,
        bloom_shift: u32,
        bloom: []u64,
        buckets: []u32,
        chain: [*]elf.gnu_hash.ChainEntry,

        pub fn fromPtr(header: *elf.gnu_hash.Header) @This() {
            const header_offset = @intFromPtr(header);
            const bloom_offset = header_offset + @sizeOf(elf.gnu_hash.Header);
            const buckets_offset = bloom_offset + header.bloom_size * @sizeOf(u64);
            const chain_offset = buckets_offset + header.nbuckets * @sizeOf(u32);

            const bloom_ptr: [*]u64 = @ptrFromInt(bloom_offset);
            const buckets_ptr: [*]u32 = @ptrFromInt(buckets_offset);
            const chain_ptr: [*]elf.gnu_hash.ChainEntry = @ptrFromInt(chain_offset);

            return .{
                .symoffset = header.symoffset,
                .bloom_shift = header.bloom_shift,
                .bloom = bloom_ptr[0..header.bloom_size],
                .buckets = buckets_ptr[0..header.nbuckets],
                .chain = chain_ptr,
            };
        }
    };

    /// ElfDynLib 专用
    /// 返回符号的地址
    pub fn lookupAddress(self: *const ElfDynLib, vername: []const u8, name: []const u8) ?usize {
        const maybe_versym = if (self.verdef == null) null else self.versym;

        const OK_TYPES = (1 << elf.STT_NOTYPE | 1 << elf.STT_OBJECT | 1 << elf.STT_FUNC | 1 << elf.STT_COMMON);
        const OK_BINDS = (1 << elf.STB_GLOBAL | 1 << elf.STB_WEAK | 1 << elf.STB_GNU_UNIQUE);

        switch (self.hash_table) {
            .dt_hash => |hashtab| {
                var i: usize = 0;
                while (i < hashtab[1]) : (i += 1) {
                    if (0 == (@as(u32, 1) << @as(u5, @intCast(self.syms[i].st_info & 0xf)) & OK_TYPES)) continue;
                    if (0 == (@as(u32, 1) << @as(u5, @intCast(self.syms[i].st_info >> 4)) & OK_BINDS)) continue;
                    if (0 == self.syms[i].st_shndx) continue;
                    if (!mem.eql(u8, name, mem.sliceTo(self.strings + self.syms[i].st_name, 0))) continue;
                    if (maybe_versym) |versym| {
                        if (!checkver(self.verdef.?, versym[i], vername, self.strings))
                            continue;
                    }
                    return @intFromPtr(self.memory.ptr) + self.syms[i].st_value;
                }
            },
            .dt_gnu_hash => |gnu_hash_header| {
                const GnuHashSection = switch (@bitSizeOf(usize)) {
                    32 => GnuHashSection32,
                    64 => GnuHashSection64,
                    else => |bit_size| @compileError("Unsupported bit size " ++ bit_size),
                };

                const gnu_hash_section: GnuHashSection = .fromPtr(gnu_hash_header);
                const hash = elf.gnu_hash.calculate(name);

                const bloom_index = (hash / @bitSizeOf(usize)) % gnu_hash_header.bloom_size;
                const bloom_val = gnu_hash_section.bloom[bloom_index];

                const bit_index_0 = hash % @bitSizeOf(usize);
                const bit_index_1 = (hash >> @intCast(gnu_hash_header.bloom_shift)) % @bitSizeOf(usize);

                const one: usize = 1;
                const bit_mask: usize = (one << @intCast(bit_index_0)) | (one << @intCast(bit_index_1));

                if (bloom_val & bit_mask != bit_mask) {
                    // 符号不在布隆过滤器中,因此此处一定不存在该符号。
                    return null;
                }

                const bucket_index = hash % gnu_hash_header.nbuckets;
                const chain_index = gnu_hash_section.buckets[bucket_index] - gnu_hash_header.symoffset;

                const chains = gnu_hash_section.chain;
                const hash_as_entry: elf.gnu_hash.ChainEntry = @bitCast(hash);

                var current_index = chain_index;
                var at_end_of_chain = false;
                while (!at_end_of_chain) : (current_index += 1) {
                    const current_entry = chains[current_index];
                    at_end_of_chain = current_entry.end_of_chain;

                    if (current_entry.hash != hash_as_entry.hash) continue;

                    // 检查符号是否匹配
                    const symbol_index = current_index + gnu_hash_header.symoffset;
                    const symbol = self.syms[symbol_index];

                    if (0 == (@as(u32, 1) << @as(u5, @intCast(symbol.st_info & 0xf)) & OK_TYPES)) continue;
                    if (0 == (@as(u32, 1) << @as(u5, @intCast(symbol.st_info >> 4)) & OK_BINDS)) continue;
                    if (0 == symbol.st_shndx) continue;

                    const symbol_name = mem.sliceTo(self.strings + symbol.st_name, 0);
                    if (!mem.eql(u8, name, symbol_name)) {
                        continue;
                    }

                    if (maybe_versym) |versym| {
                        if (!checkver(self.verdef.?, versym[symbol_index], vername, self.strings)) {
                            continue;
                        }
                    }

                    return @intFromPtr(self.memory.ptr) + symbol.st_value;
                }
            },
        }

        return null;
    }

    fn elfToProt(elf_prot: elf.PF) posix.PROT {
        return .{
            .READ = elf_prot.R,
            .WRITE = elf_prot.W,
            .EXEC = elf_prot.X,
        };
    }
};

fn checkver(def_arg: *elf.Verdef, vsym_arg: elf.Versym, vername: []const u8, strings: [*:0]u8) bool {
    var def = def_arg;
    const vsym_index = vsym_arg.VERSION;
    while (true) {
        if (0 == (def.flags & elf.VER_FLG_BASE) and @backingInt(def.ndx) == vsym_index) break;
        if (def.next == 0) return false;
        def = @ptrFromInt(@intFromPtr(def) + def.next);
    }
    const aux: *elf.Verdaux = @ptrFromInt(@intFromPtr(def) + def.aux);
    return mem.eql(u8, vername, mem.sliceTo(strings + aux.name, 0));
}

test "ElfDynLib" {
    if (native_os != .linux) return error.SkipZigTest;
    try testing.expectError(error.FileNotFound, ElfDynLib.open("invalid_so.so", null));
    try testing.expectError(error.FileNotFound, ElfDynLib.openZ("invalid_so.so", null));
}

/// 单独放置以避免引用 `DlDynLib`,因为其字段类型在其他目标上
/// 可能无效。
const DlDynLibError = error{ FileNotFound, NameTooLong };

pub const DlDynLib = struct {
    pub const Error = DlDynLibError;

    handle: *anyopaque,

    pub fn open(path: []const u8) Error!DlDynLib {
        const path_c = try posix.toPosixPath(path);
        return openZ(&path_c);
    }

    pub fn openZ(path_c: [*:0]const u8) Error!DlDynLib {
        return .{
            .handle = std.c.dlopen(path_c, .{ .LAZY = true }) orelse {
                return error.FileNotFound;
            },
        };
    }

    pub fn close(self: *DlDynLib) void {
        switch (posix.errno(std.c.dlclose(self.handle))) {
            .SUCCESS => return,
            else => unreachable,
        }
        self.* = undefined;
    }

    pub fn lookup(self: *DlDynLib, comptime T: type, name: [:0]const u8) ?T {
        // dlsym(及其他 dl 函数)隐式接受一个隐藏参数:栈上的返回地址
        // https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66826
        if (@call(.never_tail, std.c.dlsym, .{ self.handle, name.ptr })) |symbol| {
            return @as(T, @ptrCast(@alignCast(symbol)));
        } else {
            return null;
        }
    }

    /// DlDynLib 专用。
    /// 返回描述最近一次 `lookup` 错误的可读字符串;
    /// 如果初始化后或上次调用 `getError` 后没有发生错误,则返回 `null`。
    pub fn getError() ?[:0]const u8 {
        return mem.span(std.c.dlerror());
    }
};

test "dynamic_library" {
    const libname = switch (native_os) {
        .linux, .freebsd, .openbsd, .illumos => "invalid_so.so",
        .driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos => "invalid_dylib.dylib",
        else => return error.SkipZigTest,
    };

    try testing.expectError(error.FileNotFound, DynLib.open(libname));
    try testing.expectError(error.FileNotFound, DynLib.openZ(libname.ptr));
}