字段
handle: Handle
Dirrootbuiltinnative_osstdIoFileassertAllocatorHandlepathmax_path_bytesmax_name_bytesEntrycwdReaderIteratoriterateiterateAssumeFirstIterationSelectiveWalkerwalkSelectivelyWalkerwalkPathNameErrorAccessErrorAccessOptionsaccessaccessAbsoluteOpenErrorOpenOptionsopenDiropenDirAbsoluteclosecloseManyOpenFileOptionsopenFileopenFileAbsoluteCreateFileOptionscreateFilecreateFileAbsoluteWriteFileOptionsWriteFileErrorwriteFilePrevStatusUpdateFileErrorupdateFileReadFileErrorreadFileCreateDirErrorcreateDircreateDirAbsoluteCreateDirPathErrorcreateDirPathCreatePathStatuscreateDirPathStatusCreateDirPathOpenErrorCreateDirPathOpenOptionscreateDirPathOpenStatStatErrorstatStatFileErrorStatFileOptionsstatFileRealPathErrorrealPathRealPathFileErrorrealPathFileRealPathFileAllocErrorrealPathFileAllocrealPathFileAbsoluterealPathFileAbsoluteAllocDeleteFileErrordeleteFiledeleteFileAbsoluteDeleteDirErrordeleteDirdeleteDirAbsoluteRenameErrorrenamerenameAbsoluteRenamePreserveErrorrenamePreserveHardLinkOptionsHardLinkErrorhardLinkSymLinkFlagsSymLinkErrorsymLinksymLinkAbsolutesymLinkAtomicReadLinkErrorreadLinkreadLinkAbsoluteReadFileAllocErrorreadFileAllocreadFileAllocOptionsDeleteTreeErrordeleteTreedeleteTreeMinStackSizedeleteTreeMinStackSizeWithKindHintdeleteTreeOpenInitialSubpathCopyFileOptionsCopyFileErrorcopyFilecopyFileAbsoluteCreateFileAtomicOptionsCreateFileAtomicErrorcreateFileAtomicSetPermissionsErrorPermissionssetPermissionsSetFilePermissionsErrorSetFilePermissionsOptionssetFilePermissionsSetOwnerErrorsetOwnerSetFileOwnerErrorSetFileOwnerOptionssetFileOwnerSetTimestampsErrorSetTimestampsOptionssetTimestampsSetTimestampsNowOptionssetTimestampsNow
std.Io.Dir.access
函数
测试对 sub_path 的访问。
Windows 上,sub_path 应编码为 WTF-8。
WASI 上,sub_path 应编码为有效 UTF-8。
其他平台上,sub_path 是不规定编码的不透明字节序列。
使用此函数时,请注意检查时间与使用时间之间的竞态。 例如,不要先检查文件是否存在再打开它, 而应直接打开并处理文件不存在的错误。
pub fn access(dir: Dir, io: Io, sub_path: []const u8, options: AccessOptions) AccessError!void
参数
错误
- AccessDenied
文件不允许请求的
AccessOptions,或路径前缀中的 某个目录不允许搜索。- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileNotFound
- InputOutput
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- PermissionDenied
请求了写入权限,但文件不可变。
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.accessAbsolute
函数
pub fn accessAbsolute(io: Io, absolute_path: []const u8, options: AccessOptions) AccessError!void
参数
错误
- AccessDenied
文件不允许请求的
AccessOptions,或路径前缀中的 某个目录不允许搜索。- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileNotFound
- InputOutput
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- PermissionDenied
请求了写入权限,但文件不可变。
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.AccessError
错误集合
错误
- AccessDenied
文件不允许请求的
AccessOptions,或路径前缀中的 某个目录不允许搜索。- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileNotFound
- InputOutput
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- PermissionDenied
请求了写入权限,但文件不可变。
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.AccessOptions
容器
字段
follow_symlinks: bool = true
read: bool = false
write: bool = false
execute: bool = false
std.Io.Dir.Allocator
别名
别名目标 std.mem.Allocator
std.Io.Dir.assert
别名
别名目标 std.debug.assert
std.Io.Dir.builtin
常量
std.Io.Dir.close
函数
pub fn close(dir: Dir, io: Io) void
参数
std.Io.Dir.closeMany
函数
pub fn closeMany(io: Io, dirs: []const Dir) void
参数
std.Io.Dir.copyFile
函数
在 dest_path 原子创建新文件,该路径位于 dest_dir 内,
内容与 source_path 相同,该源路径位于 source_dir 内。
是否覆盖已有文件由 options 决定。
Linux 上,在 https://patchwork.kernel.org/patch/9636735/ 合入 并广泛可用之前,断电或应用 终止可能使临时文件残留在 dest_path 所在的同一目录中。
Windows 上,两条路径均应采用 WTF-8 编码。WASI 上,两条路径均应采用 有效的 UTF-8 编码。其他平台上,两条路径均为 不指定编码的不透明字节序列。
pub fn copyFile( source_dir: Dir, source_path: []const u8, dest_dir: Dir, dest_path: []const u8, io: Io, options: CopyFileOptions, ) CopyFileError!void
参数
source_dir: Dir
source_path: []const u8
dest_dir: Dir
dest_path: []const u8
io: Io
options: CopyFileOptions
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- BrokenPipe Error
文件为未连接的套接字,或其读取端已关闭。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer UnendingError
- CrossDevice RenameError
- DeviceBusy OpenError
- DirNotEmpty RenameError
试图替换非空目录。
- DiskQuota RenameError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- HardwareFailure RenameError
- InputOutput UnendingError
- InvalidFileName
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LinkQuotaExceeded RenameError
- LockViolation UnendingError
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice Error
写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- NotOpenForReading UnendingError
打开文件时未授予读取能力。
- NotOpenForWriting Error
- OperationUnsupported HardLinkError
操作系统或文件系统不支持硬链接。
- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied OpenError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem OpenError
- SocketUnconnected UnendingError
- Streaming StatError
尝试对非文件流调用 stat。
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Dir.copyFileAbsolute
函数
与 copyFile 相同,但断言 source_path 和 dest_path 均为绝对路径。
Windows 上,两个路径都应采用 WTF-8 编码。 WASI 上,两个路径都应采用有效 UTF-8 编码。 其他平台上,两个路径都是不透明的字节序列,没有特定编码。
pub fn copyFileAbsolute( source_path: []const u8, dest_path: []const u8, io: Io, options: CopyFileOptions, ) !void
参数
用法示例
test copyFileAbsolute {}
std.Io.Dir.CopyFileError
错误集合
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- BrokenPipe Error
文件为未连接的套接字,或其读取端已关闭。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer UnendingError
- CrossDevice RenameError
- DeviceBusy OpenError
- DirNotEmpty RenameError
试图替换非空目录。
- DiskQuota RenameError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- HardwareFailure RenameError
- InputOutput UnendingError
- InvalidFileName
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LinkQuotaExceeded RenameError
- LockViolation UnendingError
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice Error
写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- NotOpenForReading UnendingError
打开文件时未授予读取能力。
- NotOpenForWriting Error
- OperationUnsupported HardLinkError
操作系统或文件系统不支持硬链接。
- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied OpenError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem OpenError
- SocketUnconnected UnendingError
- Streaming StatError
尝试对非文件流调用 stat。
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Dir.CopyFileOptions
容器
字段
permissions: ?File.Permissions = null此项为 null 时,从源文件复制权限。
make_path: bool = false
replace: bool = true
std.Io.Dir.createDir
函数
使用相对或绝对路径创建单个目录。
- Windows 上,
sub_path应采用 WTF-8 编码。 - WASI 上,
sub_path应采用有效的 UTF-8 编码。 - 其他平台上,
sub_path是不指定编码的不透明字节序列。
相关函数:
pub fn createDir(dir: Dir, io: Io, sub_path: []const u8, permissions: Permissions) CreateDirError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DiskQuota
- FileNotFound
- LinkQuotaExceeded
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- PathAlreadyExists
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.createDirAbsolute
函数
根据绝对路径创建新目录。
断言路径为绝对路径。若需要同时处理
绝对和相对路径,参见 createDir。
Windows 上,absolute_path 应编码为 WTF-8。
WASI 上,absolute_path 应编码为有效 UTF-8。
其他平台上,absolute_path 是不规定编码的不透明字节序列。
pub fn createDirAbsolute(io: Io, absolute_path: []const u8, permissions: Permissions) CreateDirError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DiskQuota
- FileNotFound
- LinkQuotaExceeded
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- PathAlreadyExists
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
用法示例
test createDirAbsolute {}
std.Io.Dir.CreateDirError
错误集合
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DiskQuota
- FileNotFound
- LinkQuotaExceeded
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- PathAlreadyExists
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.createDirPath
函数
按需使用默认权限创建父目录,确保
sub_path 作为目录存在。
若路径已存在且是目录,则成功返回。
此函数不一定是原子操作。若返回错误,文件系统 可能已被修改。
路径为空时返回 error.BadPathName,因为空路径
无法创建。
Windows 上,sub_path 应采用 WTF-8 编码。
WASI 上,sub_path 应采用有效的 UTF-8 编码。
其他平台上,sub_path 是不指定编码的不透明字节序列。
包含 .. 分量的路径按平台采用不同的处理方式:
- Windows 上,在将路径传给 NtCreateFile 之前解析
..,因此 对于类似 "first/../second" 的sub_path,会先解析为 "second",只创建./second目录。 - 其他平台上,
..在将路径传给mkdirat之前不会解析, 因此类似 "first/../second" 的sub_path会同时创建./first和./second目录。
另请参见:
pub fn createDirPath(dir: Dir, io: Io, sub_path: []const u8) CreateDirPathError!void
参数
错误
- AccessDenied CreateDirError
在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- DiskQuota CreateDirError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LinkQuotaExceeded CreateDirError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound CreateDirError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice CreateDirError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied CreateDirError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem CreateDirError
- Streaming StatError
尝试对非文件流调用 stat。
- SymLinkLoop CreateDirError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Dir.CreateDirPathError
错误集合
错误
- AccessDenied CreateDirError
在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- DiskQuota CreateDirError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LinkQuotaExceeded CreateDirError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound CreateDirError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice CreateDirError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied CreateDirError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem CreateDirError
- Streaming StatError
尝试对非文件流调用 stat。
- SymLinkLoop CreateDirError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Dir.createDirPathOpen
函数
执行等同于先调用 createDirPath、再调用 openDir 的操作,尽可能原子执行。
取消此操作时,文件系统可能处于部分修改状态。
Windows 上,sub_path 应采用 WTF-8 编码。
WASI 上,sub_path 应采用有效 UTF-8 编码。
其他平台上,sub_path 是不透明的字节序列,没有特定编码。
pub fn createDirPathOpen(dir: Dir, io: Io, sub_path: []const u8, options: CreateDirPathOpenOptions) CreateDirPathOpenError!Dir
参数
错误
- AccessDenied CreateDirError
在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- DiskQuota CreateDirError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LinkQuotaExceeded CreateDirError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound CreateDirError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice CreateDirError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied CreateDirError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem CreateDirError
- Streaming StatError
尝试对非文件流调用 stat。
- SymLinkLoop CreateDirError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Dir.CreateDirPathOpenError
错误集合
错误
- AccessDenied CreateDirError
在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- DiskQuota CreateDirError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LinkQuotaExceeded CreateDirError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound CreateDirError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice CreateDirError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied CreateDirError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem CreateDirError
- Streaming StatError
尝试对非文件流调用 stat。
- SymLinkLoop CreateDirError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Dir.CreateDirPathOpenOptions
容器
字段
open_options: OpenOptions = .{}
permissions: Permissions = .default_dir
std.Io.Dir.createDirPathStatus
函数
与 createDirPath 相同,但返回路径原本已存在,还是
已成功创建。
pub fn createDirPathStatus(dir: Dir, io: Io, sub_path: []const u8, permissions: Permissions) CreateDirPathError!CreatePathStatus
参数
错误
- AccessDenied CreateDirError
在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- DiskQuota CreateDirError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LinkQuotaExceeded CreateDirError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound CreateDirError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice CreateDirError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied CreateDirError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem CreateDirError
- Streaming StatError
尝试对非文件流调用 stat。
- SymLinkLoop CreateDirError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Dir.createFile
函数
以写入权限创建、打开或覆盖文件。
会分配资源,需通过 File.close 释放。
Windows 上,sub_path 应编码为 WTF-8。
WASI 上,sub_path 应编码为有效 UTF-8。
其他平台上,sub_path 是不规定编码的不透明字节序列。
pub fn createFile(dir: Dir, io: Io, sub_path: []const u8, flags: CreateFileOptions) File.OpenError!File
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported
- FileNotFound
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Dir.createFileAbsolute
函数
pub fn createFileAbsolute(io: Io, absolute_path: []const u8, flags: CreateFileOptions) File.OpenError!File
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported
- FileNotFound
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Dir.createFileAtomic
函数
创建一个未命名的临时文件,之后可将其原子地实体化为 sub_path。
在该文件完成实体化之前,sub_path 必须保持有效。
返回的 File.Atomic 提供 API,可在底层操作系统不直接支持时模拟此行为。
- 在 Windows 上,
sub_path应采用 WTF-8 编码。 - 在 WASI 上,
sub_path应采用有效的 UTF-8 编码。 - 在其他平台上,
sub_path是不限定编码的不透明字节序列。
pub fn createFileAtomic( dir: Dir, io: Io, sub_path: []const u8, options: CreateFileAtomicOptions, ) CreateFileAtomicError!File.Atomic
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
尝试创建的文件是正在运行的可执行文件。
- FileNotFound
以下情况之一:
- 某个路径分量不存在。
- 使用了 Cwd,但当前工作目录已被删除。
- 与已打开目录句柄关联的路径已被删除。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
设备没有空间容纳新文件,无法创建新路径。
- NotDir
路径中作为目录使用的某个组成部分实际上不是目录。
- PermissionDenied
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
可用内核内存不足。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
std.Io.Dir.CreateFileAtomicError
错误集合
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
尝试创建的文件是正在运行的可执行文件。
- FileNotFound
以下情况之一:
- 某个路径分量不存在。
- 使用了 Cwd,但当前工作目录已被删除。
- 与已打开目录句柄关联的路径已被删除。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
设备没有空间容纳新文件,无法创建新路径。
- NotDir
路径中作为目录使用的某个组成部分实际上不是目录。
- PermissionDenied
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
可用内核内存不足。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
std.Io.Dir.CreateFileAtomicOptions
容器
字段
permissions: File.Permissions = .default_file
make_path: bool = false
replace: bool = false指示无名文件最终将通过 File.Atomic.link
还是 File.Atomic.replace 创建。
如果此值不正确,会在
File.Atomic.replace 中导致断言失败。
std.Io.Dir.CreateFileOptions
容器
字段
read: bool = false是否创建具有读取访问权限的文件。
truncate: bool = true若文件已存在且是普通文件,并且访问 模式允许写入,则将其截断为长度 0。
exclusive: bool = false确保此次打开操作创建文件,否则
返回 error.PathAlreadyExists。
lock: File.Lock = .none打开文件并获取建议锁,以协调其他同时访问 该文件的进程。独占锁会阻止其他 进程获取锁。共享锁会阻止其他 进程获取独占锁,但不会阻止 其他进程获取各自的共享锁。
除 Linux 上极少数特定情况外,此锁均为建议锁[1]。 也就是说,不遵守锁 API 的进程即使面对已加锁文件, 仍然可以访问文件。
以下操作系统在打开文件的同时 原子地获取锁:
- Darwin
- DragonFlyBSD
- FreeBSD
- Haiku
- NetBSD
- OpenBSD 以下操作系统在打开文件后, 通过单独的系统调用获取锁:
- Linux
- Windows
[1]: https://www.kernel.org/doc/Documentation/filesystems/mandatory-locking.txt
lock_nonblocking: bool = false设置返回前是否等待文件加锁。若为 true,
则返回 error.WouldBlock;否则等待,直至文件
可供继续操作(原文条件如此)。
permissions: Permissions = .default_file
resolve_beneath: bool = false如果操作系统支持,尝试解析会越出此目录的路径时,
将改为返回 error.AccessDenied。
若不支持,则忽略此选项。
std.Io.Dir.CreatePathStatus
容器
字段
existed
created
std.Io.Dir.cwd
函数
返回当前工作目录的句柄。
该句柄不以迭代能力打开,对结果进行迭代属于非法行为。
关闭返回的 Dir 属于受检查的非法行为。
在 POSIX 目标上,此函数可在编译期调用。
可通过 std.Options.cwd 覆盖此函数。
pub fn cwd() Dir
std.Io.Dir.deleteDir
函数
如果目录非空,则返回 error.DirNotEmpty。
递归删除目录,参见 deleteTree。
Windows 上,sub_path 应编码为 WTF-8。
WASI 上,sub_path 应编码为有效 UTF-8。
其他平台上,sub_path 是不规定编码的不透明字节序列。
pub fn deleteDir(dir: Dir, io: Io, sub_path: []const u8) DeleteDirError!void
参数
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DirNotEmpty
- FileBusy
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.deleteDirAbsolute
函数
与 deleteDir 相同,但路径为绝对路径。
Windows 上,dir_path 应采用 WTF-8 编码。
WASI 上,dir_path 应采用有效 UTF-8 编码。
其他平台上,dir_path 是不透明的字节序列,没有特定编码。
pub fn deleteDirAbsolute(io: Io, absolute_path: []const u8) DeleteDirError!void
参数
io: Io
absolute_path: []const u8
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DirNotEmpty
- FileBusy
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.DeleteDirError
错误集合
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DirNotEmpty
- FileBusy
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.deleteFile
函数
根据已打开的目录句柄删除文件名,并可能删除其引用的文件。
Windows 上,sub_path 应编码为 WTF-8。
WASI 上,sub_path 应编码为有效 UTF-8。
其他平台上,sub_path 是不规定编码的不透明字节序列。
断言路径参数不含空字节。
pub fn deleteFile(dir: Dir, io: Io, sub_path: []const u8) DeleteFileError!void
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有通过相对于它的路径 解除资源链接所需的权限,可能发生此错误。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileNotFound
- FileSystem
- IsDir
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.deleteFileAbsolute
函数
pub fn deleteFileAbsolute(io: Io, absolute_path: []const u8) DeleteFileError!void
参数
io: Io
absolute_path: []const u8
错误
- AccessDenied
在 WASI 中,若文件描述符不具有通过相对于它的路径 解除资源链接所需的权限,可能发生此错误。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileNotFound
- FileSystem
- IsDir
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
用法示例
test deleteFileAbsolute {}
std.Io.Dir.DeleteFileError
错误集合
错误
- AccessDenied
在 WASI 中,若文件描述符不具有通过相对于它的路径 解除资源链接所需的权限,可能发生此错误。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileNotFound
- FileSystem
- IsDir
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.deleteTree
函数
不论 sub_path 描述的是符号链接、文件还是目录,此函数
都会将其删除。若因目录非空而无法删除,
则先递归删除其条目,再次尝试。
此操作在多数文件系统上不是原子操作。
Windows 上,sub_path 应采用 WTF-8 编码。
WASI 上,sub_path 应采用有效的 UTF-8 编码。
其他平台上,sub_path 是不指定编码的不透明字节序列。
pub fn deleteTree(dir: Dir, io: Io, sub_path: []const u8) DeleteTreeError!void
参数
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileSystem
- FileTooBig
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NotDir
某个路径分量不是目录。 若
sub_path不包含路径分隔符,则此错误不可达。- PermissionDenied
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.deleteTree.closeAll
函数
fn closeAll(inner_io: Io, items: []@This()) void
参数
inner_io: Io
items: []@This()
std.Io.Dir.DeleteTreeError
错误集合
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileSystem
- FileTooBig
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NotDir
某个路径分量不是目录。 若
sub_path不包含路径分隔符,则此错误不可达。- PermissionDenied
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.deleteTreeMinStackSize
函数
类似 deleteTree,但每次只保持一个 Iterator 活跃,以最小化函数栈大小。
比 deleteTree 慢,但使用更少栈空间。
Windows 上,sub_path 应采用 WTF-8 编码。
WASI 上,sub_path 应采用有效的 UTF-8 编码。
其他平台上,sub_path 是不指定编码的不透明字节序列。
pub fn deleteTreeMinStackSize(dir: Dir, io: Io, sub_path: []const u8) DeleteTreeError!void
参数
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileSystem
- FileTooBig
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NotDir
某个路径分量不是目录。 若
sub_path不包含路径分隔符,则此错误不可达。- PermissionDenied
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.deleteTreeMinStackSizeWithKindHint
函数
fn deleteTreeMinStackSizeWithKindHint(parent: Dir, io: Io, sub_path: []const u8, kind_hint: File.Kind) DeleteTreeError!void
参数
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileSystem
- FileTooBig
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NotDir
某个路径分量不是目录。 若
sub_path不包含路径分隔符,则此错误不可达。- PermissionDenied
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.deleteTreeOpenInitialSubpath
函数
删除成功时返回 null。
fn deleteTreeOpenInitialSubpath(dir: Dir, io: Io, sub_path: []const u8, kind_hint: File.Kind) !?Dir
参数
std.Io.Dir.Dir
别名
别名目标 std.Io.Dir
std.Io.Dir.Entry
容器
字段
std.Io.Dir.File
别名
别名目标 std.Io.File
std.Io.Dir.Handle
别名
别名目标 std.posix.fd_t
std.Io.Dir.hardLink
函数
pub fn hardLink( old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, io: Io, options: HardLinkOptions, ) HardLinkError!void
参数
old_dir: Dir
old_sub_path: []const u8
new_dir: Dir
new_sub_path: []const u8
io: Io
options: HardLinkOptions
错误
- AccessDenied HardLinkError
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice HardLinkError
- DiskQuota HardLinkError
- FileNotFound HardLinkError
- HardwareFailure HardLinkError
- LinkQuotaExceeded HardLinkError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NoSpaceLeft HardLinkError
- NotDir HardLinkError
- OperationUnsupported HardLinkError
操作系统或文件系统不支持硬链接。
- PathAlreadyExists HardLinkError
- PermissionDenied HardLinkError
- ReadOnlyFileSystem HardLinkError
- SymLinkLoop HardLinkError
- SystemResources HardLinkError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.HardLinkError
别名
std.Io.Dir.HardLinkOptions
别名
std.Io.Dir.Io
别名
别名目标 std.Io
std.Io.Dir.iterate
函数
pub fn iterate(dir: Dir) Iterator
参数
dir: Dir
std.Io.Dir.iterateAssumeFirstIteration
函数
pub fn iterateAssumeFirstIteration(dir: Dir) Iterator
参数
dir: Dir
std.Io.Dir.Iterator
容器
此 API 优先考虑便利性,而非性能:
字段
reader: Reader
reader_buffer: [reader_buffer_len]u8 align(@alignOf(usize))
std.Io.Dir.Iterator.Error
别名
std.Io.Dir.Iterator.init
函数
pub fn init(dir: Dir, reader_state: Reader.State) Iterator
参数
std.Io.Dir.Iterator.next
函数
pub fn next(it: *Iterator, io: Io) Error!?Entry
参数
错误
- AccessDenied Error
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied Error
- SystemResources Error
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.Iterator.reader_buffer_len
常量
std.Io.Dir.max_name_bytes
常量
表示平台常见文件系统支持的 []u8 文件名分量
的最大大小。文件系统操作返回的文件名分量
通常可容纳于此长度的 u8 数组中,但
此假设可能不适用于每种配置,具体取决于平台。
字节数不包括空哨兵字节。
Windows 上的 []u8 文件名分量编码为 WTF-8。
WASI 上的文件名分量编码为有效 UTF-8。
其他平台上的 []u8 分量是不规定编码的不透明字节序列。
std.Io.Dir.max_path_bytes
常量
操作系统接受的文件路径最大长度。
路径,包括文件系统操作返回的路径,都可能超过此长度,但这样的路径无法再成功传入其他文件系统操作。不过,假定文件系统操作返回的所有单独路径分量都能放入此长度的 u8 数组。
字节数包含空终止哨兵字节所需的空间。
- Windows 上,
[]u8文件路径采用 WTF-8 编码。 - WASI 上,
[]u8文件路径采用有效 UTF-8 编码。 - 其他平台上,
[]u8文件路径是不透明的字节序列,没有特定编码。
std.Io.Dir.native_os
常量
std.Io.Dir.openDir
函数
打开给定路径的目录。目录是系统资源,
会保持打开,直到对返回结果调用 close。
只有将 iterate 选项设为 true,才能迭代该目录。
Windows 上,sub_path 应采用 WTF-8 编码。
WASI 上,sub_path 应采用有效的 UTF-8 编码。
其他平台上,sub_path 是不指定编码的不透明字节序列。
pub fn openDir(dir: Dir, io: Io, sub_path: []const u8, options: OpenOptions) OpenError!Dir
参数
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NotDir
- PermissionDenied
- ProcessFdQuotaExceeded
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.openDirAbsolute
函数
pub fn openDirAbsolute(io: Io, absolute_path: []const u8, options: OpenOptions) OpenError!Dir
参数
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NotDir
- PermissionDenied
- ProcessFdQuotaExceeded
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.OpenError
错误集合
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NotDir
- PermissionDenied
- ProcessFdQuotaExceeded
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.openFile
函数
打开文件以读取或写入,不尝试创建新文件。
创建新文件,参见 createFile。
会分配资源,需通过 File.close 释放。
Windows 上,sub_path 应编码为 WTF-8。
WASI 上,sub_path 应编码为有效 UTF-8。
其他平台上,sub_path 是不规定编码的不透明字节序列。
pub fn openFile(dir: Dir, io: Io, sub_path: []const u8, options: OpenFileOptions) File.OpenError!File
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported
- FileNotFound
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Dir.openFileAbsolute
函数
pub fn openFileAbsolute(io: Io, absolute_path: []const u8, options: OpenFileOptions) File.OpenError!File
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported
- FileNotFound
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Dir.OpenFileOptions
容器
字段
mode: Mode = .read_only
allow_directory: bool = true决定打开指向目录的路径时的行为。
若设为 true,可以打开目录,但某些情况下仍可能返回 error.IsDir,例如尝试以写权限打开目录。
若设为 false,打开目录时始终返回 error.IsDir。
设为 false 时:
- Windows 上无需额外系统调用。
- 其他操作系统上需要额外执行一次
fstat系统调用。
path_only: bool = false
lock: File.Lock = .none打开文件并获取建议锁,以协调其他同时访问 该文件的进程。独占锁会阻止其他 进程获取锁。共享锁会阻止其他 进程获取独占锁,但不会阻止 其他进程获取各自的共享锁。
除 Linux 上极少数特定情况外,此锁均为建议锁[1]。 也就是说,不遵守锁 API 的进程即使面对已加锁文件, 仍然可以访问文件。
以下操作系统在打开文件的同时 原子地获取锁:
- Darwin
- DragonFlyBSD
- FreeBSD
- Haiku
- NetBSD
- OpenBSD 以下操作系统在打开文件后, 通过单独的系统调用获取锁:
- Linux
- Windows
[1]: https://www.kernel.org/doc/Documentation/filesystems/mandatory-locking.txt
lock_nonblocking: bool = false设置返回前是否等待文件加锁。若为 true,
则返回 error.WouldBlock;否则等待,直至文件
可供继续操作(原文条件如此)。
allow_ctty: bool = false设置此项,以允许打开的文件自动成为 当前进程的控制 TTY。
follow_symlinks: bool = true
resolve_beneath: bool = false如果操作系统支持,尝试解析会越出此目录的路径时,
将改为返回 error.AccessDenied。
若不支持,则忽略此选项。
std.Io.Dir.OpenFileOptions.isRead
函数
pub fn isRead(self: OpenFileOptions) bool
参数
self: OpenFileOptions
std.Io.Dir.OpenFileOptions.isWrite
函数
pub fn isWrite(self: OpenFileOptions) bool
参数
self: OpenFileOptions
std.Io.Dir.OpenFileOptions.Mode
容器
字段
read_only
write_only
read_write
std.Io.Dir.OpenOptions
容器
字段
std.Io.Dir.path
别名
别名目标 std.fs.path
std.Io.Dir.PathNameError
错误集合
错误
- BadPathName
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- NameTooLong
提供的缓冲区过小, 无法容纳路径名时返回。
std.Io.Dir.Permissions
别名
std.Io.Dir.PrevStatus
容器
字段
stale
fresh
std.Io.Dir.Reader
容器
字段
std.Io.Dir.Reader.Error
错误集合
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.Reader.init
函数
断言 buffer 长度至少为 min_buffer_len。
pub fn init(dir: Dir, buffer: []align(@alignOf(usize)) u8) Reader
参数
dir: Dir
buffer: []align(@alignOf(usize)) u8
std.Io.Dir.Reader.min_buffer_len
常量
使所有实现均能正常工作的 buffer 长度。
std.Io.Dir.Reader.next
函数
下次调用 read 或 next 时,Entry.name 失效。
pub fn next(r: *Reader, io: Io) Error!?Entry
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.Reader.read
函数
下次调用 read 或 next 时,
所有 Entry.name 均失效。
pub fn read(r: *Reader, io: Io, buffer: []Entry) Error!usize
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.Reader.reset
函数
pub fn reset(r: *Reader) void
参数
r: *Reader
std.Io.Dir.Reader.State
容器
字段
std.Io.Dir.readFile
函数
使用预先分配的缓冲区读取全部文件内容。
返回切片与 buffer 具有相同指针。若长度等于 buffer.len,
则情况存在歧义:既可能表示已读取整个文件,且
恰好填满缓冲区;也可能表示缓冲区不足以容纳
整个文件。
- Windows 上,
file_path应采用 WTF-8 编码。 - WASI 上,
file_path应采用有效的 UTF-8 编码。 - 其他平台上,
file_path是不指定编码的不透明字节序列。
pub fn readFile(dir: Dir, io: Io, file_path: []const u8, buffer: []u8) ReadFileError![]u8
参数
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer UnendingError
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- InputOutput UnendingError
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LockViolation UnendingError
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice OpenError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- NotOpenForReading UnendingError
打开文件时未授予读取能力。
- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied OpenError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem OpenError
- SocketUnconnected UnendingError
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Dir.readFileAlloc
函数
读取指定文件的全部字节。成功时,调用者拥有返回的缓冲区。
若已知文件大小,更好的方式是初始化 File.Reader。
若无法获取文件大小,则返回错误。若实际中可能遇到这种情况,更好的方式是初始化 File.Reader,它可无缝处理该情况。
pub fn readFileAlloc( dir: Dir, io: Io, sub_path: []const u8, gpa: Allocator, limit: Io.Limit, ) ReadFileAllocError![]u8
参数
dir: Dir
io: Io
sub_path: []const u8在 Windows 上,应编码为 WTF-8。 在 WASI 上,应编码为有效的 UTF-8。 在其他平台上,为不规定编码的不透明字节序列。
gpa: Allocator用于分配结果。
limit: Io.Limit如果达到或超过此值,则改为返回 error.StreamTooLong。
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer UnendingError
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- InputOutput UnendingError
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LockViolation UnendingError
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice OpenError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- NotOpenForReading UnendingError
打开文件时未授予读取能力。
- OutOfMemory Error
- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied OpenError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem OpenError
- SocketUnconnected UnendingError
- StreamTooLong
文件大小达到或超过提供的限制。
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Dir.ReadFileAllocError
错误集合
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer UnendingError
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- InputOutput UnendingError
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LockViolation UnendingError
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice OpenError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- NotOpenForReading UnendingError
打开文件时未授予读取能力。
- OutOfMemory Error
- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied OpenError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem OpenError
- SocketUnconnected UnendingError
- StreamTooLong
文件大小达到或超过提供的限制。
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Dir.readFileAllocOptions
函数
读取指定文件的所有字节。成功时,返回缓冲区的 所有权归调用者。
若文件大小已知,更好的选择是初始化一个
File.Reader。
pub fn readFileAllocOptions( dir: Dir, io: Io, sub_path: []const u8, gpa: Allocator, limit: Io.Limit, comptime alignment: std.mem.Alignment, comptime sentinel: ?u8, ) ReadFileAllocError!(if (sentinel) |s| [:s]align(alignment.toByteUnits()) u8 else []align(alignment.toByteUnits()) u8)
参数
dir: Dir
io: Io
sub_path: []const u8在 Windows 上,应编码为 WTF-8。 在 WASI 上,应编码为有效的 UTF-8。 在其他平台上,为不规定编码的不透明字节序列。
gpa: Allocator用于分配结果。
limit: Io.Limit如果达到或超过此值,则改为返回 error.StreamTooLong。
alignment: std.mem.Alignment
sentinel: ?u8
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer UnendingError
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- InputOutput UnendingError
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LockViolation UnendingError
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice OpenError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- NotOpenForReading UnendingError
打开文件时未授予读取能力。
- OutOfMemory Error
- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied OpenError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem OpenError
- SocketUnconnected UnendingError
- StreamTooLong
文件大小达到或超过提供的限制。
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Dir.ReadFileError
错误集合
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer UnendingError
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- InputOutput UnendingError
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LockViolation UnendingError
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice OpenError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- NotOpenForReading UnendingError
打开文件时未授予读取能力。
- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied OpenError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem OpenError
- SocketUnconnected UnendingError
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Dir.readLink
函数
获取符号链接的目标。
返回 buffer 中已填充的字节数。
断言路径参数不含空字节。
Windows 上,sub_path 应采用 WTF-8 编码。
WASI 上,sub_path 应采用有效 UTF-8 编码。
其他平台上,sub_path 是不透明的字节序列,没有特定编码。
pub fn readLink(dir: Dir, io: Io, sub_path: []const u8, buffer: []u8) ReadLinkError!usize
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于该描述符读取符号链接值所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
尝试打开的文件是正在运行的可执行文件。
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- NotLink
- PermissionDenied
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnsupportedReparsePointType
仅限 Windows。如果打开的重解析点类型不受支持, 可能发生此错误。
std.Io.Dir.readLinkAbsolute
函数
与 readLink 相同,但断言路径为绝对路径。
Windows 上,path 应采用 WTF-8 编码。
WASI 上,path 应采用有效的 UTF-8 编码。
其他平台上,path 是不指定编码的不透明字节序列。
pub fn readLinkAbsolute(io: Io, absolute_path: []const u8, buffer: []u8) ReadLinkError!usize
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于该描述符读取符号链接值所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
尝试打开的文件是正在运行的可执行文件。
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- NotLink
- PermissionDenied
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnsupportedReparsePointType
仅限 Windows。如果打开的重解析点类型不受支持, 可能发生此错误。
std.Io.Dir.ReadLinkError
错误集合
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于该描述符读取符号链接值所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
尝试打开的文件是正在运行的可执行文件。
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- NotLink
- PermissionDenied
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnsupportedReparsePointType
仅限 Windows。如果打开的重解析点类型不受支持, 可能发生此错误。
std.Io.Dir.realPath
函数
获取 dir 的规范化绝对路径名。
此函数的平台支持有限,使用它可能导致不必要的失败和竞态条件。 通常建议完全避免使用此函数。
pub fn realPath(dir: Dir, io: Io, out_buffer: []u8) RealPathError!usize
参数
错误
- AccessDenied RealPathError
- AntivirusInterference RealPathError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy RealPathError
- FileBusy RealPathError
- FileNotFound RealPathError
- FileSystem RealPathError
- FileTooBig RealPathError
- InputOutput RealPathError
- IsDir RealPathError
- NameTooLong RealPathError
完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。
- NetworkNotFound RealPathError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RealPathError
- NoSpaceLeft RealPathError
- NotDir RealPathError
- OperationUnsupported RealPathError
此操作系统、文件系统或
Io实现 不支持 realpath 操作。- PathAlreadyExists RealPathError
- PermissionDenied RealPathError
- PipeBusy RealPathError
- ProcessFdQuotaExceeded RealPathError
- SymLinkLoop RealPathError
- SystemFdQuotaExceeded RealPathError
- SystemResources RealPathError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume RealPathError
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.Dir.RealPathError
别名
std.Io.Dir.realPathFile
函数
取得 sub_path 相对于此 Dir 的规范化绝对路径名。
如果 sub_path 为绝对路径,则忽略此 Dir 句柄,
取得 sub_path 参数的规范化绝对路径名。
此函数的平台支持有限,使用它可能导致 不必要的失败和竞态。通常建议 完全避免使用此函数。
另请参见:
pub fn realPathFile(dir: Dir, io: Io, sub_path: []const u8, out_buffer: []u8) RealPathFileError!usize
参数
错误
- AccessDenied RealPathError
- AntivirusInterference RealPathError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy RealPathError
- FileBusy RealPathError
- FileNotFound RealPathError
- FileSystem RealPathError
- FileTooBig RealPathError
- InputOutput RealPathError
- IsDir RealPathError
- NameTooLong RealPathError
完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。
- NetworkNotFound RealPathError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RealPathError
- NoSpaceLeft RealPathError
- NotDir RealPathError
- OperationUnsupported RealPathError
此操作系统、文件系统或
Io实现 不支持 realpath 操作。- PathAlreadyExists RealPathError
- PermissionDenied RealPathError
- PipeBusy RealPathError
- ProcessFdQuotaExceeded RealPathError
- SymLinkLoop RealPathError
- SystemFdQuotaExceeded RealPathError
- SystemResources RealPathError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume RealPathError
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.Dir.realPathFileAbsolute
函数
pub fn realPathFileAbsolute(io: Io, absolute_path: []const u8, out_buffer: []u8) RealPathFileError!usize
参数
错误
- AccessDenied RealPathError
- AntivirusInterference RealPathError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy RealPathError
- FileBusy RealPathError
- FileNotFound RealPathError
- FileSystem RealPathError
- FileTooBig RealPathError
- InputOutput RealPathError
- IsDir RealPathError
- NameTooLong RealPathError
完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。
- NetworkNotFound RealPathError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RealPathError
- NoSpaceLeft RealPathError
- NotDir RealPathError
- OperationUnsupported RealPathError
此操作系统、文件系统或
Io实现 不支持 realpath 操作。- PathAlreadyExists RealPathError
- PermissionDenied RealPathError
- PipeBusy RealPathError
- ProcessFdQuotaExceeded RealPathError
- SymLinkLoop RealPathError
- SystemFdQuotaExceeded RealPathError
- SystemResources RealPathError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume RealPathError
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.Dir.realPathFileAbsoluteAlloc
函数
pub fn realPathFileAbsoluteAlloc(io: Io, absolute_path: []const u8, allocator: Allocator) RealPathFileAllocError![:0]u8
参数
错误
- AccessDenied RealPathError
- AntivirusInterference RealPathError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy RealPathError
- FileBusy RealPathError
- FileNotFound RealPathError
- FileSystem RealPathError
- FileTooBig RealPathError
- InputOutput RealPathError
- IsDir RealPathError
- NameTooLong RealPathError
完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。
- NetworkNotFound RealPathError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RealPathError
- NoSpaceLeft RealPathError
- NotDir RealPathError
- OperationUnsupported RealPathError
此操作系统、文件系统或
Io实现 不支持 realpath 操作。- OutOfMemory Error
- PathAlreadyExists RealPathError
- PermissionDenied RealPathError
- PipeBusy RealPathError
- ProcessFdQuotaExceeded RealPathError
- SymLinkLoop RealPathError
- SystemFdQuotaExceeded RealPathError
- SystemResources RealPathError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume RealPathError
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.Dir.realPathFileAlloc
函数
pub fn realPathFileAlloc(dir: Dir, io: Io, sub_path: []const u8, allocator: Allocator) RealPathFileAllocError![:0]u8
参数
错误
- AccessDenied RealPathError
- AntivirusInterference RealPathError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy RealPathError
- FileBusy RealPathError
- FileNotFound RealPathError
- FileSystem RealPathError
- FileTooBig RealPathError
- InputOutput RealPathError
- IsDir RealPathError
- NameTooLong RealPathError
完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。
- NetworkNotFound RealPathError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RealPathError
- NoSpaceLeft RealPathError
- NotDir RealPathError
- OperationUnsupported RealPathError
此操作系统、文件系统或
Io实现 不支持 realpath 操作。- OutOfMemory Error
- PathAlreadyExists RealPathError
- PermissionDenied RealPathError
- PipeBusy RealPathError
- ProcessFdQuotaExceeded RealPathError
- SymLinkLoop RealPathError
- SystemFdQuotaExceeded RealPathError
- SystemResources RealPathError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume RealPathError
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.Dir.RealPathFileAllocError
错误集合
错误
- AccessDenied RealPathError
- AntivirusInterference RealPathError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy RealPathError
- FileBusy RealPathError
- FileNotFound RealPathError
- FileSystem RealPathError
- FileTooBig RealPathError
- InputOutput RealPathError
- IsDir RealPathError
- NameTooLong RealPathError
完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。
- NetworkNotFound RealPathError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RealPathError
- NoSpaceLeft RealPathError
- NotDir RealPathError
- OperationUnsupported RealPathError
此操作系统、文件系统或
Io实现 不支持 realpath 操作。- OutOfMemory Error
- PathAlreadyExists RealPathError
- PermissionDenied RealPathError
- PipeBusy RealPathError
- ProcessFdQuotaExceeded RealPathError
- SymLinkLoop RealPathError
- SystemFdQuotaExceeded RealPathError
- SystemResources RealPathError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume RealPathError
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.Dir.RealPathFileError
错误集合
错误
- AccessDenied RealPathError
- AntivirusInterference RealPathError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy RealPathError
- FileBusy RealPathError
- FileNotFound RealPathError
- FileSystem RealPathError
- FileTooBig RealPathError
- InputOutput RealPathError
- IsDir RealPathError
- NameTooLong RealPathError
完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。
- NetworkNotFound RealPathError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RealPathError
- NoSpaceLeft RealPathError
- NotDir RealPathError
- OperationUnsupported RealPathError
此操作系统、文件系统或
Io实现 不支持 realpath 操作。- PathAlreadyExists RealPathError
- PermissionDenied RealPathError
- PipeBusy RealPathError
- ProcessFdQuotaExceeded RealPathError
- SymLinkLoop RealPathError
- SystemFdQuotaExceeded RealPathError
- SystemResources RealPathError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume RealPathError
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.Dir.rename
函数
更改文件或目录的名称或位置。
如果 new_sub_path 已存在,则将其替换。
将文件重命名以覆盖已有目录,或将目录重命名以覆盖已有
文件,都会失败并返回 error.IsDir 或 error.NotDir。
- Windows 上,两个路径均应编码为 WTF-8。
- WASI 上,两个路径均应编码为有效 UTF-8。
- 其他平台上,两个路径均是不规定编码的不透明字节序列。
pub fn rename( old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, io: Io, ) RenameError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 按路径重命名资源所需的权限时,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice
- DirNotEmpty
试图替换非空目录。
- DiskQuota
- FileBusy
尝试移动或替换的文件是正在运行的可执行文件。
- FileNotFound
- HardwareFailure
- IsDir
- LinkQuotaExceeded
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- PermissionDenied
- PipeBusy
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.renameAbsolute
函数
pub fn renameAbsolute(old_path: []const u8, new_path: []const u8, io: Io) RenameError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 按路径重命名资源所需的权限时,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice
- DirNotEmpty
试图替换非空目录。
- DiskQuota
- FileBusy
尝试移动或替换的文件是正在运行的可执行文件。
- FileNotFound
- HardwareFailure
- IsDir
- LinkQuotaExceeded
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- PermissionDenied
- PipeBusy
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.RenameError
错误集合
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 按路径重命名资源所需的权限时,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice
- DirNotEmpty
试图替换非空目录。
- DiskQuota
- FileBusy
尝试移动或替换的文件是正在运行的可执行文件。
- FileNotFound
- HardwareFailure
- IsDir
- LinkQuotaExceeded
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- PermissionDenied
- PipeBusy
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.renamePreserve
函数
更改文件或目录的名称或位置。
如果 new_sub_path 已存在,将返回 error.PathAlreadyExists。
若操作系统支持,整个操作将以原子方式完成。否则,将回退为先创建硬链接再取消链接;这对 new_sub_path 是原子的,但存在清理 old_sub_path 可能失败的时间窗口。虽然该操作具有较好的可移植性,但严格来说,在某些环境下该回退方案也可能不受支持,此时返回 error.OperationUnsupported。
- 在 Windows 上,两个路径都应采用 WTF-8 编码。
- 在 WASI 上,两个路径都应采用有效的 UTF-8 编码。
- 在其他平台上,两个路径都是不限定编码的不透明字节序列。
pub fn renamePreserve( old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, io: Io, ) RenamePreserveError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具有 按相对于该描述符的路径重命名资源所需的权限时,可能发生此错误。
在 Windows 上,将目录重命名并覆盖已有目录时, 可能返回此错误,而不是 PathAlreadyExists。
在 Darwin 上,如果任一路径中的分量指向需要实体化的 “无数据”目录,而当前线程或进程的 I/O 策略不允许无数据目录实体化,则可能返回此错误。
- AntivirusInterference RenameError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice RenameError
- DirNotEmpty RenameError
试图替换非空目录。
- DiskQuota RenameError
- FileBusy RenameError
尝试移动或替换的文件是正在运行的可执行文件。
- FileNotFound RenameError
- HardwareFailure RenameError
- IsDir RenameError
- LinkQuotaExceeded RenameError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound RenameError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RenameError
- NoSpaceLeft RenameError
- NotDir RenameError
- OperationUnsupported
操作系统或文件系统不支持原子地执行不替换目标的重命名。
- PathAlreadyExists
- PermissionDenied RenameError
- PipeBusy RenameError
- ReadOnlyFileSystem RenameError
- SymLinkLoop RenameError
- SystemResources RenameError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.RenamePreserveError
错误集合
错误
- AccessDenied
在 WASI 中,当文件描述符不具有 按相对于该描述符的路径重命名资源所需的权限时,可能发生此错误。
在 Windows 上,将目录重命名并覆盖已有目录时, 可能返回此错误,而不是 PathAlreadyExists。
在 Darwin 上,如果任一路径中的分量指向需要实体化的 “无数据”目录,而当前线程或进程的 I/O 策略不允许无数据目录实体化,则可能返回此错误。
- AntivirusInterference RenameError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice RenameError
- DirNotEmpty RenameError
试图替换非空目录。
- DiskQuota RenameError
- FileBusy RenameError
尝试移动或替换的文件是正在运行的可执行文件。
- FileNotFound RenameError
- HardwareFailure RenameError
- IsDir RenameError
- LinkQuotaExceeded RenameError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound RenameError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RenameError
- NoSpaceLeft RenameError
- NotDir RenameError
- OperationUnsupported
操作系统或文件系统不支持原子地执行不替换目标的重命名。
- PathAlreadyExists
- PermissionDenied RenameError
- PipeBusy RenameError
- ReadOnlyFileSystem RenameError
- SymLinkLoop RenameError
- SystemResources RenameError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.root
常量
std.Io.Dir.SelectiveWalker
容器
字段
std.Io.Dir.SelectiveWalker.deinit
函数
pub fn deinit(self: *SelectiveWalker) void
参数
self: *SelectiveWalker
std.Io.Dir.SelectiveWalker.enter
函数
进入目录,继续向下一层遍历。
pub fn enter(self: *SelectiveWalker, io: Io, entry: Walker.Entry) !void
参数
std.Io.Dir.SelectiveWalker.Error
错误集合
错误
- AccessDenied Error
- Canceled Cancelable
调用方请求停止异步操作。
- OutOfMemory Error
- PermissionDenied Error
- SystemResources Error
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.SelectiveWalker.leave
函数
离开当前目录,继续向上一级遍历。
若当前条目是目录条目,并在 leave 之前调用了
enter,则“当前目录”指向该条目。
pub fn leave(self: *SelectiveWalker, io: Io) void
参数
self: *SelectiveWalker
io: Io
std.Io.Dir.SelectiveWalker.next
函数
每次调用此函数后,以及调用 deinit() 时, 此函数先前返回的内存均会失效。若要保留 对路径的引用,必须进行拷贝。
pub fn next(self: *SelectiveWalker, io: Io) Error!?Walker.Entry
参数
self: *SelectiveWalker
io: Io
错误
- AccessDenied Error
- Canceled Cancelable
调用方请求停止异步操作。
- OutOfMemory Error
- PermissionDenied Error
- SystemResources Error
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.SelectiveWalker.StackItem
容器
字段
iter: Iterator
dirname_len: usize
std.Io.Dir.setFileOwner
函数
也称为 "fchownat"。
pub fn setFileOwner( dir: Dir, io: Io, sub_path: []const u8, owner: ?File.Uid, group: ?File.Gid, options: SetFileOwnerOptions, ) SetFileOwnerError!void
参数
错误
- AccessDenied SetOwnerError
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound SetOwnerError
- InputOutput SetOwnerError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- PermissionDenied SetOwnerError
- ReadOnlyFileSystem SetOwnerError
- SymLinkLoop SetOwnerError
- SystemResources SetOwnerError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.SetFileOwnerError
错误集合
错误
- AccessDenied SetOwnerError
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound SetOwnerError
- InputOutput SetOwnerError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- PermissionDenied SetOwnerError
- ReadOnlyFileSystem SetOwnerError
- SymLinkLoop SetOwnerError
- SystemResources SetOwnerError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.SetFileOwnerOptions
容器
字段
follow_symlinks: bool = true
std.Io.Dir.setFilePermissions
函数
也称为 "fchmodat"。
pub fn setFilePermissions( dir: Dir, io: Io, sub_path: []const u8, new_permissions: File.Permissions, options: SetFilePermissionsOptions, ) SetFilePermissionsError!void
参数
dir: Dir
io: Io
sub_path: []const u8
new_permissions: File.Permissions
options: SetFilePermissionsOptions
错误
- AccessDenied SetPermissionsError
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound SetPermissionsError
- InputOutput SetPermissionsError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- OperationUnsupported
SetFilePermissionsOptions.follow_symlinks被设为 false,但文件系统或操作系统不允许。- PermissionDenied SetPermissionsError
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem SetPermissionsError
- SymLinkLoop SetPermissionsError
- SystemFdQuotaExceeded
- SystemResources SetPermissionsError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.SetFilePermissionsError
错误集合
错误
- AccessDenied SetPermissionsError
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound SetPermissionsError
- InputOutput SetPermissionsError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- OperationUnsupported
SetFilePermissionsOptions.follow_symlinks被设为 false,但文件系统或操作系统不允许。- PermissionDenied SetPermissionsError
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem SetPermissionsError
- SymLinkLoop SetPermissionsError
- SystemFdQuotaExceeded
- SystemResources SetPermissionsError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.SetFilePermissionsOptions
容器
字段
follow_symlinks: bool = true
std.Io.Dir.setOwner
函数
也称为“chown”。
进程必须具有正确权限才能成功执行。目录所有者可以将所属组改为自身属于的任意组。此外,目录必须在打开时将 OpenOptions.iterate 设为 true。
若所有者或所属组指定为 null,则对应标识不变。
pub fn setOwner(dir: Dir, io: Io, owner: ?File.Uid, group: ?File.Gid) SetOwnerError!void
参数
错误
- AccessDenied SetOwnerError
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound SetOwnerError
- InputOutput SetOwnerError
- PermissionDenied SetOwnerError
- ReadOnlyFileSystem SetOwnerError
- SymLinkLoop SetOwnerError
- SystemResources SetOwnerError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.SetOwnerError
别名
std.Io.Dir.setPermissions
函数
也称为 chmod。
进程必须具有适当特权,才能成功执行,
或者有效用户标识符必须与目录
所有者匹配。此外,目录必须在打开时
将 OpenOptions.iterate 设为 true。
pub fn setPermissions(dir: Dir, io: Io, new_permissions: File.Permissions) SetPermissionsError!void
参数
错误
- AccessDenied SetPermissionsError
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound SetPermissionsError
- InputOutput SetPermissionsError
- PermissionDenied SetPermissionsError
- ReadOnlyFileSystem SetPermissionsError
- SymLinkLoop SetPermissionsError
- SystemResources SetPermissionsError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.SetPermissionsError
别名
std.Io.Dir.setTimestamps
函数
最终存储的时间粒度取决于操作系统 与文件系统的组合。若提供的值超出此范围, 则将其限制为最大值。
pub fn setTimestamps( dir: Dir, io: Io, sub_path: []const u8, options: SetTimestampsOptions, ) SetTimestampsError!void
参数
错误
- AccessDenied SetTimestampsError
times 为 NULL,或两个 nsec 值均为 UTIME_NOW,且满足以下之一:
- 调用方的有效用户标识符与文件 所有者不匹配,调用方不具有该文件的 写入权限,且调用方不具有特权;Linux 上即不具备 CAP_FOWNER 或 CAP_DAC_OVERRIDE 任一能力; 或者,
- 文件被标记为不可变,参见 chattr(1)。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- PermissionDenied SetTimestampsError
调用方尝试将一个或两个时间戳设置为当前时间 以外的值,或将一个时间戳 设为当前时间而保持另一个不变, 即 times 非 NULL,两个 nsec 字段均非 UTIME_NOW, 且两个 nsec 字段均非 UTIME_OMIT,同时满足以下任一条件:
- 调用方的有效用户 ID 不等于文件 所有者,且调用方无特权;Linux 上 指不具备 CAP_FOWNER 能力。
- 文件被标记为仅追加或不可变,参见 chattr(1)。
- ReadOnlyFileSystem SetTimestampsError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.SetTimestampsError
错误集合
错误
- AccessDenied SetTimestampsError
times 为 NULL,或两个 nsec 值均为 UTIME_NOW,且满足以下之一:
- 调用方的有效用户标识符与文件 所有者不匹配,调用方不具有该文件的 写入权限,且调用方不具有特权;Linux 上即不具备 CAP_FOWNER 或 CAP_DAC_OVERRIDE 任一能力; 或者,
- 文件被标记为不可变,参见 chattr(1)。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- PermissionDenied SetTimestampsError
调用方尝试将一个或两个时间戳设置为当前时间 以外的值,或将一个时间戳 设为当前时间而保持另一个不变, 即 times 非 NULL,两个 nsec 字段均非 UTIME_NOW, 且两个 nsec 字段均非 UTIME_OMIT,同时满足以下任一条件:
- 调用方的有效用户 ID 不等于文件 所有者,且调用方无特权;Linux 上 指不具备 CAP_FOWNER 能力。
- 文件被标记为仅追加或不可变,参见 chattr(1)。
- ReadOnlyFileSystem SetTimestampsError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.setTimestampsNow
函数
将所提供路径的访问时间戳及修改时间戳 设置为当前墙上时钟时间。
最终存储的时间粒度取决于 操作系统与文件系统的组合。
pub fn setTimestampsNow( dir: Dir, io: Io, sub_path: []const u8, options: SetTimestampsNowOptions, ) SetTimestampsError!void
参数
错误
- AccessDenied SetTimestampsError
times 为 NULL,或两个 nsec 值均为 UTIME_NOW,且满足以下之一:
- 调用方的有效用户标识符与文件 所有者不匹配,调用方不具有该文件的 写入权限,且调用方不具有特权;Linux 上即不具备 CAP_FOWNER 或 CAP_DAC_OVERRIDE 任一能力; 或者,
- 文件被标记为不可变,参见 chattr(1)。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- PermissionDenied SetTimestampsError
调用方尝试将一个或两个时间戳设置为当前时间 以外的值,或将一个时间戳 设为当前时间而保持另一个不变, 即 times 非 NULL,两个 nsec 字段均非 UTIME_NOW, 且两个 nsec 字段均非 UTIME_OMIT,同时满足以下任一条件:
- 调用方的有效用户 ID 不等于文件 所有者,且调用方无特权;Linux 上 指不具备 CAP_FOWNER 能力。
- 文件被标记为仅追加或不可变,参见 chattr(1)。
- ReadOnlyFileSystem SetTimestampsError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.SetTimestampsNowOptions
容器
字段
follow_symlinks: bool = true
std.Io.Dir.SetTimestampsOptions
容器
字段
follow_symlinks: bool = true
access_timestamp: File.SetTimestamp = .unchanged
modify_timestamp: File.SetTimestamp = .unchanged
std.Io.Dir.stat
函数
pub fn stat(dir: Dir, io: Io) StatError!Stat
参数
错误
- AccessDenied StatError
在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied StatError
- Streaming StatError
尝试对非文件流调用 stat。
- SystemResources StatError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.Stat
别名
别名目标 std.Io.File.Stat
std.Io.Dir.StatError
别名
std.Io.Dir.statFile
函数
返回目录内某个文件的元数据。
Windows 上需要三次系统调用。其他操作系统上 只需一次。
会跟随符号链接。
sub_path 可以是绝对路径,此时忽略 self。
- Windows 上,
sub_path应编码为 WTF-8。 - WASI 上,
sub_path应编码为有效 UTF-8。 - 其他平台上,
sub_path是不规定编码的不透明字节序列。
pub fn statFile(dir: Dir, io: Io, sub_path: []const u8, options: StatFileOptions) StatFileError!Stat
参数
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice OpenError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied OpenError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem OpenError
- Streaming StatError
尝试对非文件流调用 stat。
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Dir.StatFileError
错误集合
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice OpenError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied OpenError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem OpenError
- Streaming StatError
尝试对非文件流调用 stat。
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Dir.StatFileOptions
容器
字段
follow_symlinks: bool = true
std.Io.Dir.std
别名
别名目标 std
std.Io.Dir.symLink
函数
创建名为 sym_link_path、内容为字符串 target_path 的符号链接。
符号链接也称软链接,既可指向已有文件,也可指向不存在的 文件;后者称为悬空链接。
若 sym_link_path 已存在,不会覆盖。
Windows 上,两条路径均应采用 WTF-8 编码。 WASI 上,两条路径均应采用有效的 UTF-8 编码。 其他平台上,两条路径均为不指定编码的不透明字节序列。
pub fn symLink( dir: Dir, io: Io, target_path: []const u8, sym_link_path: []const u8, flags: SymLinkFlags, ) SymLinkError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 创建新符号链接所需的权限时,可能发生此错误。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DiskQuota
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoSpaceLeft
- NotDir
- PathAlreadyExists
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.symLinkAbsolute
函数
pub fn symLinkAbsolute( io: Io, target_path: []const u8, sym_link_path: []const u8, flags: SymLinkFlags, ) SymLinkError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 创建新符号链接所需的权限时,可能发生此错误。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DiskQuota
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoSpaceLeft
- NotDir
- PathAlreadyExists
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.symLinkAtomic
函数
与 symLink 相同,但会持续尝试创建符号链接,直到
成功或遇到 error.PathAlreadyExists 之外的错误。
- Windows 上,两条路径均应采用 WTF-8 编码。
- WASI 上,两条路径均应采用有效的 UTF-8 编码。
- 其他平台上,两条路径均为不指定编码的不透明字节序列。
pub fn symLinkAtomic( dir: Dir, io: Io, target_path: []const u8, sym_link_path: []const u8, flags: SymLinkFlags, ) !void
参数
std.Io.Dir.SymLinkError
错误集合
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 创建新符号链接所需的权限时,可能发生此错误。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DiskQuota
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoSpaceLeft
- NotDir
- PathAlreadyExists
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Dir.SymLinkFlags
容器
与 symLink、symLinkAtomic 和 symLinkAbsolute 配合使用,
指定符号链接指向文件还是目录。除 Windows 外,所有宿主
均忽略此值;在 Windows 上,创建指向不同
资源类型的符号链接需要不同标志。默认假定 symLinkAbsolute
指向文件。
字段
is_directory: bool = false
std.Io.Dir.updateFile
函数
检查 source_path 和 dest_path 的文件大小、mtime 和权限。若
均相同,则不执行任何操作。否则将 source_path 原子复制到
dest_path,并按需创建父目录层级。
目标文件继承源文件的 mtime、atime 和权限,
因此下次调用 updateFile 时无需再次复制。
返回更新前文件的状态。
- Windows 上,两条路径均应采用 WTF-8 编码。
- WASI 上,两条路径均应采用有效的 UTF-8 编码。
- 其他平台上,两条路径均为不指定编码的不透明字节序列。
pub fn updateFile( source_dir: Dir, io: Io, source_path: []const u8, dest_dir: Dir, dest_path: []const u8, options: CopyFileOptions, ) !PrevStatus
参数
source_dir: Dir
io: Io
source_path: []const u8
dest_dir: Dir
dest_path: []const u8若此路径中的目录不存在,则创建它们。
options: CopyFileOptions
std.Io.Dir.UpdateFileError
别名
std.Io.Dir.walk
函数
递归遍历目录。
打开 dir 时必须将 OpenOptions.iterate 设为 true。
Walker.deinit 释放已分配的内存和目录句柄。
返回文件系统条目的顺序未定义。
遍历后不会关闭 dir。
另见:
pub fn walk(dir: Dir, allocator: Allocator) Allocator.Error!Walker
参数
错误
- OutOfMemory
std.Io.Dir.Walker
容器
字段
inner: SelectiveWalker
std.Io.Dir.Walker.deinit
函数
pub fn deinit(self: *Walker) void
参数
self: *Walker
std.Io.Dir.Walker.Entry
容器
字段
std.Io.Dir.Walker.Entry.depth
函数
返回条目相对于初始目录的深度。 初始目录的直接子项返回 1,直接子目录内的条目返回 2, 依此类推。
pub fn depth(self: Walker.Entry) usize
参数
std.Io.Dir.Walker.leave
函数
离开当前目录,继续在上一级遍历。 若当前条目是目录条目,则“当前目录” 指与当前条目对应的目录。
pub fn leave(self: *Walker, io: Io) void
参数
std.Io.Dir.Walker.next
函数
每次调用此函数后,以及调用 deinit() 时, 此函数先前返回的内存均会失效。若要保留 对路径的引用,必须进行拷贝。
pub fn next(self: *Walker, io: Io) !?Walker.Entry
参数
std.Io.Dir.walkSelectively
函数
递归遍历目录,但要求用户对每个目录条目显式选择是否递归进入。
打开 dir 时,必须将 OpenOptions.iterate 设为 true。
Walker.deinit 释放已分配内存与目录句柄。
返回文件系统条目的顺序未定义。
遍历后不会关闭 dir。
另见 walk。
pub fn walkSelectively(dir: Dir, allocator: Allocator) !SelectiveWalker
参数
std.Io.Dir.writeFile
函数
使用提供的文件创建标志,将内容写入文件系统。
pub fn writeFile(dir: Dir, io: Io, options: WriteFileOptions) WriteFileError!void
参数
错误
- AccessDenied Error
文件描述符没有写入所需的权限。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- BrokenPipe Error
文件为未连接的套接字,或其读取端已关闭。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy Error
- DiskQuota Error
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- InputOutput Error
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LockViolation Error
进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice Error
写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- NotOpenForWriting Error
- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied Error
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem OpenError
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources Error
内核内存不足,无法从 in_fd 读取。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock Error
已启用非阻塞模式,而此操作将阻塞。
std.Io.Dir.WriteFileError
错误集合
错误
- AccessDenied Error
文件描述符没有写入所需的权限。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- BrokenPipe Error
文件为未连接的套接字,或其读取端已关闭。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy Error
- DiskQuota Error
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- InputOutput Error
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LockViolation Error
进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice Error
写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- NotOpenForWriting Error
- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied Error
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem OpenError
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources Error
内核内存不足,无法从 in_fd 读取。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock Error
已启用非阻塞模式,而此操作将阻塞。
std.Io.Dir.WriteFileOptions
容器
字段
sub_path: []const u8Windows 上,sub_path 应编码为 WTF-8。
WASI 上,sub_path 应编码为有效 UTF-8。
其他平台上,sub_path 是不规定编码的不透明字节序列。
data: []const u8
flags: CreateFileOptions = .{}
源码
std/Io/Dir.zig
const Dir = @This();
const root = @import("root");
const builtin = @import("builtin");
const native_os = builtin.os.tag;
const std = @import("../std.zig");
const Io = std.Io;
const File = Io.File;
const assert = std.debug.assert;
const Allocator = std.mem.Allocator;
handle: Handle,
pub const Handle = std.posix.fd_t;
pub const path = std.fs.path;
/// 操作系统接受的文件路径最大长度。
///
/// 路径,包括文件系统操作返回的路径,都可能超过此长度,但这样的路径无法再成功传入其他文件系统操作。不过,假定文件系统操作返回的所有单独路径分量都能放入此长度的 `u8` 数组。
///
/// 字节数包含空终止哨兵字节所需的空间。
///
/// * Windows 上,`[]u8` 文件路径采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// * WASI 上,`[]u8` 文件路径采用有效 UTF-8 编码。
/// * 其他平台上,`[]u8` 文件路径是不透明的字节序列,没有特定编码。
///
///
///
///
///
pub const max_path_bytes = switch (native_os) {
.linux, .driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos, .freebsd, .openbsd, .netbsd, .dragonfly, .haiku, .illumos, .plan9, .emscripten, .wasi, .serenity => std.posix.PATH_MAX,
// 每个 WTF-16LE 码元最多可扩展为 3 个 WTF-8 字节。
// 若需要 4 个 WTF-8 字节,则 WTF-16LE 中必然有一个代理项
// 对,因此按 3 个字节计算,且会有冗余计数。
// 末尾的空字符额外占 1 个字节。
.windows => std.os.windows.PATH_MAX_WIDE * 3 + 1,
else => if (@hasDecl(root, "os") and @hasDecl(root.os, "PATH_MAX"))
root.os.PATH_MAX
else
@compileError("PATH_MAX not implemented for " ++ @tagName(native_os)),
};
/// 表示平台常见文件系统支持的 `[]u8` 文件名分量
/// 的最大大小。文件系统操作返回的文件名分量
/// 通常可容纳于此长度的 `u8` 数组中,但
/// 此假设可能不适用于每种配置,具体取决于平台。
/// 字节数不包括空哨兵字节。
/// Windows 上的 `[]u8` 文件名分量编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// WASI 上的文件名分量编码为有效 UTF-8。
/// 其他平台上的 `[]u8` 分量是不规定编码的不透明字节序列。
pub const max_name_bytes = switch (native_os) {
.linux, .driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos, .freebsd, .openbsd, .netbsd, .dragonfly, .illumos, .serenity, .psp => std.posix.NAME_MAX,
// Haiku 的 NAME_MAX 包含空终止符,因此减去一。
.haiku => std.posix.NAME_MAX - 1,
// 每个 WTF-16LE 字符最多展开为 3 个 WTF-8 字节。
// 若需要 4 个 WTF-8 字节,则 WTF-16LE 中会存在代理对,
// 按每个码元 3 字节计数时已将其多计入。
.windows => std.os.windows.NAME_MAX * 3,
// 对于 WASI,MAX_NAME 取决于宿主操作系统,因此必须
// 不小于最大的 max_name_bytes(Windows),才能适用于任意宿主操作系统。
// TODO: 确定此方法是否合理。
.wasi => std.os.windows.NAME_MAX * 3,
else => if (@hasDecl(root, "os") and @hasDecl(root.os, "NAME_MAX"))
root.os.NAME_MAX
else
@compileError("NAME_MAX not implemented for " ++ @tagName(native_os)),
};
pub const Entry = struct {
name: []const u8,
kind: File.Kind,
inode: File.INode,
};
/// 返回当前工作目录的句柄。
///
/// 该句柄不以迭代能力打开,对结果进行迭代属于非法行为。
///
/// 关闭返回的 `Dir` 属于受检查的非法行为。
///
/// 在 POSIX 目标上,此函数可在编译期调用。
///
/// 可通过 `std.Options.cwd` 覆盖此函数。
///
pub fn cwd() Dir {
const cwdFn = std.Options.cwd orelse return switch (native_os) {
.windows => .{ .handle = std.os.windows.peb().ProcessParameters.CurrentDirectory.Handle },
.wasi => .{ .handle = 3 }, // 预期第一个预打开目录是当前工作目录。
else => .{ .handle = std.posix.AT.FDCWD },
};
return cwdFn();
}
pub const Reader = struct {
dir: Dir,
state: State,
/// 存储 I/O 实现专用数据。
buffer: []align(@alignOf(usize)) u8,
/// `buffer` 中下一条目的索引。
index: usize,
/// 填充 `buffer` 的位置。
end: usize,
/// 使所有实现均能正常工作的 `buffer` 长度。
pub const min_buffer_len = switch (native_os) {
.linux => std.mem.alignForward(usize, @sizeOf(std.os.linux.dirent64), 8) +
std.mem.alignForward(usize, max_name_bytes, 8),
.windows => len: {
const max_info_len = @sizeOf(std.os.windows.FILE_BOTH_DIR_INFORMATION) + std.os.windows.NAME_MAX * 2;
const info_align = @alignOf(std.os.windows.FILE_BOTH_DIR_INFORMATION);
const reserved_len = std.mem.alignForward(usize, max_name_bytes, info_align) - max_info_len;
break :len std.mem.alignForward(usize, reserved_len, info_align) + max_info_len;
},
.wasi => @sizeOf(std.os.wasi.dirent_t) +
std.mem.alignForward(usize, max_name_bytes, @alignOf(std.os.wasi.dirent_t)),
.openbsd => std.c.S.BLKSIZE,
else => if (builtin.link_libc) @sizeOf(std.c.dirent) else std.mem.alignForward(usize, max_name_bytes, @alignOf(usize)),
};
pub const State = enum {
/// 表示下一次调用 `read` 应回退并重新开始目录列表。
///
reset,
reading,
finished,
};
pub const Error = error{
AccessDenied,
PermissionDenied,
SystemResources,
} || Io.UnexpectedError || Io.Cancelable;
/// 断言 `buffer` 长度至少为 `min_buffer_len`。
pub fn init(dir: Dir, buffer: []align(@alignOf(usize)) u8) Reader {
assert(buffer.len >= min_buffer_len);
return .{
.dir = dir,
.state = .reset,
.index = 0,
.end = 0,
.buffer = buffer,
};
}
/// 下次调用 `read` 或 `next` 时,
/// 所有 `Entry.name` 均失效。
pub fn read(r: *Reader, io: Io, buffer: []Entry) Error!usize {
return io.vtable.dirRead(io.userdata, r, buffer);
}
/// 下次调用 `read` 或 `next` 时,`Entry.name` 失效。
pub fn next(r: *Reader, io: Io) Error!?Entry {
var buffer: [1]Entry = undefined;
while (true) {
const n = try read(r, io, &buffer);
if (n == 1) return buffer[0];
if (r.state == .finished) return null;
}
}
pub fn reset(r: *Reader) void {
r.state = .reset;
r.index = 0;
r.end = 0;
}
};
/// 此 API 优先考虑便利性,而非性能:
/// * 自行选择缓冲区大小,不允许用户提供。
/// * 每次仅请求一个 `Entry`,来源为 `Io` 实现,
/// 而非批量操作,从而使其可移动。
///
/// 不过,它仍会尽量减少系统调用开销。
/// 更底层的抽象参见 `Reader`,更高层的抽象
/// 参见 `Walker`。
pub const Iterator = struct {
reader: Reader,
reader_buffer: [reader_buffer_len]u8 align(@alignOf(usize)),
pub const reader_buffer_len = 2048;
comptime {
assert(reader_buffer_len >= Reader.min_buffer_len);
}
pub const Error = Reader.Error;
pub fn init(dir: Dir, reader_state: Reader.State) Iterator {
return .{
.reader = .{
.dir = dir,
.state = reader_state,
.index = 0,
.end = 0,
.buffer = undefined,
},
.reader_buffer = undefined,
};
}
pub fn next(it: *Iterator, io: Io) Error!?Entry {
it.reader.buffer = &it.reader_buffer;
return it.reader.next(io);
}
};
pub fn iterate(dir: Dir) Iterator {
return .init(dir, .reset);
}
/// 类似 `iterate`,但不会在首次迭代前重置目录游标。
/// 仅应在已知 `Dir` 的游标尚未被修改时使用,
/// 例如该目录刚刚打开。
pub fn iterateAssumeFirstIteration(dir: Dir) Iterator {
return .init(dir, .reading);
}
pub const SelectiveWalker = struct {
stack: std.ArrayList(StackItem),
name_buffer: std.ArrayList(u8),
allocator: Allocator,
pub const Error = Iterator.Error || Allocator.Error;
const StackItem = struct {
iter: Iterator,
dirname_len: usize,
};
/// 每次调用此函数后,以及调用 deinit() 时,
/// 此函数先前返回的内存均会失效。若要保留
/// 对路径的引用,必须进行拷贝。
pub fn next(self: *SelectiveWalker, io: Io) Error!?Walker.Entry {
while (self.stack.items.len > 0) {
const top = &self.stack.items[self.stack.items.len - 1];
var dirname_len = top.dirname_len;
if (top.iter.next(io) catch |err| {
// 如果发生错误,我们希望用户仍可选择继续
// 遍历,因此必须从栈中弹出发生错误的目录。
// 否则,后续所有 `next` 调用
// 很可能都会因相同错误而失败。
var item = self.stack.pop().?;
if (self.stack.items.len != 0) {
item.iter.reader.dir.close(io);
}
return err;
}) |entry| {
self.name_buffer.shrinkRetainingCapacity(dirname_len);
if (self.name_buffer.items.len != 0) {
try self.name_buffer.append(self.allocator, path.sep);
dirname_len += 1;
}
try self.name_buffer.ensureUnusedCapacity(self.allocator, entry.name.len + 1);
self.name_buffer.appendSliceAssumeCapacity(entry.name);
self.name_buffer.appendAssumeCapacity(0);
const walker_entry: Walker.Entry = .{
.dir = top.iter.reader.dir,
.basename = self.name_buffer.items[dirname_len .. self.name_buffer.items.len - 1 :0],
.path = self.name_buffer.items[0 .. self.name_buffer.items.len - 1 :0],
.kind = entry.kind,
};
return walker_entry;
} else {
var item = self.stack.pop().?;
if (self.stack.items.len != 0) {
item.iter.reader.dir.close(io);
}
}
}
return null;
}
/// 进入目录,继续向下一层遍历。
pub fn enter(self: *SelectiveWalker, io: Io, entry: Walker.Entry) !void {
if (entry.kind != .directory) {
@branchHint(.cold);
return;
}
var new_dir = entry.dir.openDir(io, entry.basename, .{ .iterate = true }) catch |err| {
switch (err) {
error.NameTooLong => unreachable,
else => |e| return e,
}
};
errdefer new_dir.close(io);
try self.stack.append(self.allocator, .{
.iter = new_dir.iterateAssumeFirstIteration(),
.dirname_len = self.name_buffer.items.len - 1,
});
}
pub fn deinit(self: *SelectiveWalker) void {
self.name_buffer.deinit(self.allocator);
self.stack.deinit(self.allocator);
}
/// 离开当前目录,继续向上一级遍历。
/// 若当前条目是目录条目,并在 `leave` 之前调用了
/// `enter`,则“当前目录”指向该条目。
pub fn leave(self: *SelectiveWalker, io: Io) void {
var item = self.stack.pop().?;
if (self.stack.items.len != 0) {
@branchHint(.likely);
item.iter.reader.dir.close(io);
}
}
};
/// 递归遍历目录,但要求用户对每个目录条目显式选择是否递归进入。
///
/// 打开 `dir` 时,必须将 `OpenOptions.iterate` 设为 `true`。
///
/// `Walker.deinit` 释放已分配内存与目录句柄。
///
/// 返回文件系统条目的顺序未定义。
///
/// 遍历后不会关闭 `dir`。
///
/// 另见 `walk`。
///
pub fn walkSelectively(dir: Dir, allocator: Allocator) !SelectiveWalker {
var stack: std.ArrayList(SelectiveWalker.StackItem) = .empty;
try stack.append(allocator, .{
.iter = dir.iterate(),
.dirname_len = 0,
});
return .{
.stack = stack,
.name_buffer = .empty,
.allocator = allocator,
};
}
pub const Walker = struct {
inner: SelectiveWalker,
pub const Entry = struct {
/// 所属目录。可直接操作 `basename`
/// 而非 `path`,从而避免深层嵌套路径出现 `error.NameTooLong`。
/// 目录保持打开,直到调用 `next` 或 `deinit`。
dir: Dir,
basename: [:0]const u8,
path: [:0]const u8,
kind: File.Kind,
/// 返回条目相对于初始目录的深度。
/// 初始目录的直接子项返回 1,直接子目录内的条目返回 2,
/// 依此类推。
pub fn depth(self: Walker.Entry) usize {
return std.mem.countScalar(u8, self.path, path.sep) + 1;
}
};
/// 每次调用此函数后,以及调用 deinit() 时,
/// 此函数先前返回的内存均会失效。若要保留
/// 对路径的引用,必须进行拷贝。
pub fn next(self: *Walker, io: Io) !?Walker.Entry {
const entry = try self.inner.next(io);
if (entry != null and entry.?.kind == .directory) {
try self.inner.enter(io, entry.?);
}
return entry;
}
pub fn deinit(self: *Walker) void {
self.inner.deinit();
}
/// 离开当前目录,继续在上一级遍历。
/// 若当前条目是目录条目,则“当前目录”
/// 指与当前条目对应的目录。
pub fn leave(self: *Walker, io: Io) void {
self.inner.leave(io);
}
};
/// 递归遍历目录。
///
/// 打开 `dir` 时必须将 `OpenOptions.iterate` 设为 `true`。
///
/// `Walker.deinit` 释放已分配的内存和目录句柄。
///
/// 返回文件系统条目的顺序未定义。
///
/// 遍历后不会关闭 `dir`。
///
/// 另见:
/// * `walkSelectively`
pub fn walk(dir: Dir, allocator: Allocator) Allocator.Error!Walker {
return .{ .inner = try walkSelectively(dir, allocator) };
}
pub const PathNameError = error{
/// 提供的缓冲区过小,
/// 无法容纳路径名时返回。
NameTooLong,
/// 文件系统无法编码请求的文件名字节。
/// 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、
/// Windows 上的无效字符等,具体取决于文件系统与操作系统。
BadPathName,
};
pub const AccessError = error{
/// 文件不允许请求的 `AccessOptions`,或路径前缀中的
/// 某个目录不允许搜索。
AccessDenied,
/// 请求了写入权限,但文件不可变。
PermissionDenied,
FileNotFound,
InputOutput,
SystemResources,
FileBusy,
SymLinkLoop,
ReadOnlyFileSystem,
} || PathNameError || Io.Cancelable || Io.UnexpectedError;
pub const AccessOptions = packed struct {
follow_symlinks: bool = true,
read: bool = false,
write: bool = false,
execute: bool = false,
};
/// 测试对 `sub_path` 的访问。
///
/// Windows 上,`sub_path` 应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// WASI 上,`sub_path` 应编码为有效 UTF-8。
/// 其他平台上,`sub_path` 是不规定编码的不透明字节序列。
///
/// 使用此函数时,请注意检查时间与使用时间之间的竞态。
/// 例如,不要先检查文件是否存在再打开它,
/// 而应直接打开并处理文件不存在的错误。
pub fn access(dir: Dir, io: Io, sub_path: []const u8, options: AccessOptions) AccessError!void {
return io.vtable.dirAccess(io.userdata, dir, sub_path, options);
}
pub fn accessAbsolute(io: Io, absolute_path: []const u8, options: AccessOptions) AccessError!void {
assert(path.isAbsolute(absolute_path));
return access(.cwd(), io, absolute_path, options);
}
pub const OpenError = error{
FileNotFound,
NotDir,
AccessDenied,
PermissionDenied,
SymLinkLoop,
ProcessFdQuotaExceeded,
SystemFdQuotaExceeded,
NoDevice,
SystemResources,
/// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
NetworkNotFound,
} || PathNameError || Io.Cancelable || Io.UnexpectedError;
pub const OpenOptions = struct {
/// `true` 表示打开的目录可用作基于已打开目录句柄
/// 进行操作的函数的 `Dir` 参数。若为 `false`,
/// 则此类操作属于非法行为。
access_sub_paths: bool = true,
/// `true` 表示可扫描打开的目录,获取其文件和子目录
/// 作为结果,即可以调用 `iterate` 函数。
iterate: bool = false,
/// `false` 表示不解引用符号链接。
follow_symlinks: bool = true,
};
/// 打开给定路径的目录。目录是系统资源,
/// 会保持打开,直到对返回结果调用 `close`。
///
/// 只有将 `iterate` 选项设为 `true`,才能迭代该目录。
///
/// Windows 上,`sub_path` 应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// WASI 上,`sub_path` 应采用有效的 UTF-8 编码。
/// 其他平台上,`sub_path` 是不指定编码的不透明字节序列。
pub fn openDir(dir: Dir, io: Io, sub_path: []const u8, options: OpenOptions) OpenError!Dir {
return io.vtable.dirOpenDir(io.userdata, dir, sub_path, options);
}
pub fn openDirAbsolute(io: Io, absolute_path: []const u8, options: OpenOptions) OpenError!Dir {
assert(path.isAbsolute(absolute_path));
return openDir(.cwd(), io, absolute_path, options);
}
pub fn close(dir: Dir, io: Io) void {
return io.vtable.dirClose(io.userdata, (&dir)[0..1]);
}
pub fn closeMany(io: Io, dirs: []const Dir) void {
return io.vtable.dirClose(io.userdata, dirs);
}
pub const OpenFileOptions = struct {
mode: Mode = .read_only,
/// 决定打开指向目录的路径时的行为。
///
/// 若设为 true,可以打开目录,但某些情况下仍可能返回 `error.IsDir`,例如尝试以写权限打开目录。
///
/// 若设为 false,打开目录时始终返回 `error.IsDir`。
///
/// 设为 false 时:
/// * Windows 上无需额外系统调用。
/// * 其他操作系统上需要额外执行一次 `fstat` 系统调用。
///
///
///
allow_directory: bool = true,
/// 表示此已打开文件仅打算用于部分操作:
/// * `close`
/// * `stat`
/// 在 Linux 和 FreeBSD 上,对应 `std.posix.O.PATH`。
///
path_only: bool = false,
/// 打开文件并获取建议锁,以协调其他同时访问
/// 该文件的进程。独占锁会阻止其他
/// 进程获取锁。共享锁会阻止其他
/// 进程获取独占锁,但不会阻止
/// 其他进程获取各自的共享锁。
///
/// 除 Linux 上极少数特定情况外,此锁均为建议锁[1]。
/// 也就是说,不遵守锁 API 的进程即使面对已加锁文件,
/// 仍然可以访问文件。
///
/// 以下操作系统在打开文件的同时
/// 原子地获取锁:
/// * Darwin
/// * DragonFlyBSD
/// * FreeBSD
/// * Haiku
/// * NetBSD
/// * OpenBSD
/// 以下操作系统在打开文件后,
/// 通过单独的系统调用获取锁:
/// * Linux
/// * Windows
///
/// [1]: https://www.kernel.org/doc/Documentation/filesystems/mandatory-locking.txt
lock: File.Lock = .none,
/// 设置返回前是否等待文件加锁。若为 true,
/// 则返回 `error.WouldBlock`;否则等待,直至文件
/// 可供继续操作(原文条件如此)。
lock_nonblocking: bool = false,
/// 设置此项,以允许打开的文件自动成为
/// 当前进程的控制 TTY。
allow_ctty: bool = false,
follow_symlinks: bool = true,
/// 如果操作系统支持,尝试解析会越出此目录的路径时,
/// 将改为返回 `error.AccessDenied`。
/// 若不支持,则忽略此选项。
resolve_beneath: bool = false,
pub const Mode = enum { read_only, write_only, read_write };
pub fn isRead(self: OpenFileOptions) bool {
return self.mode != .write_only;
}
pub fn isWrite(self: OpenFileOptions) bool {
return self.mode != .read_only;
}
};
/// 打开文件以读取或写入,不尝试创建新文件。
///
/// 创建新文件,参见 `createFile`。
///
/// 会分配资源,需通过 `File.close` 释放。
///
/// Windows 上,`sub_path` 应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// WASI 上,`sub_path` 应编码为有效 UTF-8。
/// 其他平台上,`sub_path` 是不规定编码的不透明字节序列。
pub fn openFile(dir: Dir, io: Io, sub_path: []const u8, options: OpenFileOptions) File.OpenError!File {
return io.vtable.dirOpenFile(io.userdata, dir, sub_path, options);
}
pub fn openFileAbsolute(io: Io, absolute_path: []const u8, options: OpenFileOptions) File.OpenError!File {
assert(path.isAbsolute(absolute_path));
return openFile(.cwd(), io, absolute_path, options);
}
pub const CreateFileOptions = struct {
/// 是否创建具有读取访问权限的文件。
read: bool = false,
/// 若文件已存在且是普通文件,并且访问
/// 模式允许写入,则将其截断为长度 0。
truncate: bool = true,
/// 确保此次打开操作创建文件,否则
/// 返回 `error.PathAlreadyExists`。
exclusive: bool = false,
/// 打开文件并获取建议锁,以协调其他同时访问
/// 该文件的进程。独占锁会阻止其他
/// 进程获取锁。共享锁会阻止其他
/// 进程获取独占锁,但不会阻止
/// 其他进程获取各自的共享锁。
///
/// 除 Linux 上极少数特定情况外,此锁均为建议锁[1]。
/// 也就是说,不遵守锁 API 的进程即使面对已加锁文件,
/// 仍然可以访问文件。
///
/// 以下操作系统在打开文件的同时
/// 原子地获取锁:
/// * Darwin
/// * DragonFlyBSD
/// * FreeBSD
/// * Haiku
/// * NetBSD
/// * OpenBSD
/// 以下操作系统在打开文件后,
/// 通过单独的系统调用获取锁:
/// * Linux
/// * Windows
///
/// [1]: https://www.kernel.org/doc/Documentation/filesystems/mandatory-locking.txt
lock: File.Lock = .none,
/// 设置返回前是否等待文件加锁。若为 true,
/// 则返回 `error.WouldBlock`;否则等待,直至文件
/// 可供继续操作(原文条件如此)。
lock_nonblocking: bool = false,
permissions: Permissions = .default_file,
/// 如果操作系统支持,尝试解析会越出此目录的路径时,
/// 将改为返回 `error.AccessDenied`。
/// 若不支持,则忽略此选项。
resolve_beneath: bool = false,
};
/// 以写入权限创建、打开或覆盖文件。
///
/// 会分配资源,需通过 `File.close` 释放。
///
/// Windows 上,`sub_path` 应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// WASI 上,`sub_path` 应编码为有效 UTF-8。
/// 其他平台上,`sub_path` 是不规定编码的不透明字节序列。
pub fn createFile(dir: Dir, io: Io, sub_path: []const u8, flags: CreateFileOptions) File.OpenError!File {
return io.vtable.dirCreateFile(io.userdata, dir, sub_path, flags);
}
pub fn createFileAbsolute(io: Io, absolute_path: []const u8, flags: CreateFileOptions) File.OpenError!File {
return createFile(.cwd(), io, absolute_path, flags);
}
pub const WriteFileOptions = struct {
/// Windows 上,`sub_path` 应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// WASI 上,`sub_path` 应编码为有效 UTF-8。
/// 其他平台上,`sub_path` 是不规定编码的不透明字节序列。
sub_path: []const u8,
data: []const u8,
flags: CreateFileOptions = .{},
};
pub const WriteFileError = File.Writer.Error || File.OpenError;
/// 使用提供的文件创建标志,将内容写入文件系统。
pub fn writeFile(dir: Dir, io: Io, options: WriteFileOptions) WriteFileError!void {
var file = try dir.createFile(io, options.sub_path, options.flags);
defer file.close(io);
try file.writeStreamingAll(io, options.data);
}
pub const PrevStatus = enum {
stale,
fresh,
};
pub const UpdateFileError = File.OpenError;
/// 检查 `source_path` 和 `dest_path` 的文件大小、mtime 和权限。若
/// 均相同,则不执行任何操作。否则将 `source_path` 原子复制到
/// `dest_path`,并按需创建父目录层级。
/// 目标文件继承源文件的 mtime、atime 和权限,
/// 因此下次调用 `updateFile` 时无需再次复制。
///
/// 返回更新前文件的状态。
///
/// * Windows 上,两条路径均应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// * WASI 上,两条路径均应采用有效的 UTF-8 编码。
/// * 其他平台上,两条路径均为不指定编码的不透明字节序列。
pub fn updateFile(
source_dir: Dir,
io: Io,
source_path: []const u8,
dest_dir: Dir,
/// 若此路径中的目录不存在,则创建它们。
dest_path: []const u8,
options: CopyFileOptions,
) !PrevStatus {
var src_file = try source_dir.openFile(io, source_path, .{});
defer src_file.close(io);
const src_stat = try src_file.stat(io);
const actual_permissions = options.permissions orelse src_stat.permissions;
check_dest_stat: {
const dest_stat = blk: {
var dest_file = dest_dir.openFile(io, dest_path, .{}) catch |err| switch (err) {
error.FileNotFound => break :check_dest_stat,
else => |e| return e,
};
defer dest_file.close(io);
break :blk try dest_file.stat(io);
};
if (src_stat.size == dest_stat.size and
src_stat.mtime.nanoseconds == dest_stat.mtime.nanoseconds and
actual_permissions == dest_stat.permissions)
{
return .fresh;
}
}
var atomic_file = try dest_dir.createFileAtomic(io, dest_path, .{
.permissions = actual_permissions,
.make_path = true,
.replace = true,
});
defer atomic_file.deinit(io);
var buffer: [1024]u8 = undefined; // 仅当无法直接在 fd 之间传输时使用。
var file_writer = atomic_file.file.writer(io, &buffer);
var src_reader: File.Reader = .initSize(src_file, io, &.{}, src_stat.size);
const dest_writer = &file_writer.interface;
_ = dest_writer.sendFileAll(&src_reader, .unlimited) catch |err| switch (err) {
error.ReadFailed => return src_reader.err.?,
error.WriteFailed => return file_writer.err.?,
};
try file_writer.flush();
try file_writer.file.setTimestamps(io, .{
.access_timestamp = .init(src_stat.atime),
.modify_timestamp = .init(src_stat.mtime),
});
try atomic_file.replace(io);
return .stale;
}
pub const ReadFileError = File.OpenError || File.Reader.Error;
/// 使用预先分配的缓冲区读取全部文件内容。
///
/// 返回切片与 `buffer` 具有相同指针。若长度等于 `buffer.len`,
/// 则情况存在歧义:既可能表示已读取整个文件,且
/// 恰好填满缓冲区;也可能表示缓冲区不足以容纳
/// 整个文件。
///
/// * Windows 上,`file_path` 应采用 [WTF-8](https://simonsapin.github.io/wtf-8/) 编码。
/// * WASI 上,`file_path` 应采用有效的 UTF-8 编码。
/// * 其他平台上,`file_path` 是不指定编码的不透明字节序列。
pub fn readFile(dir: Dir, io: Io, file_path: []const u8, buffer: []u8) ReadFileError![]u8 {
var file = try dir.openFile(io, file_path, .{
// 在 Windows 上可以利用这一点,因为不会增加系统调用,
// 从而在打开时而非读取时获得 error.IsDir。
.allow_directory = if (native_os == .windows) false else true,
});
defer file.close(io);
var reader = file.reader(io, &.{});
const n = reader.interface.readSliceShort(buffer) catch |err| switch (err) {
error.ReadFailed => return reader.err.?,
};
return buffer[0..n];
}
pub const CreateDirError = error{
/// 在 WASI 中,当文件描述符不具备相对于自身
/// 创建新目录所需的权限时,可能发生此错误。
AccessDenied,
PermissionDenied,
DiskQuota,
PathAlreadyExists,
SymLinkLoop,
LinkQuotaExceeded,
FileNotFound,
SystemResources,
NoSpaceLeft,
NotDir,
ReadOnlyFileSystem,
NoDevice,
/// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
NetworkNotFound,
} || PathNameError || Io.Cancelable || Io.UnexpectedError;
/// 使用相对或绝对路径创建单个目录。
///
/// * Windows 上,`sub_path` 应采用 [WTF-8](https://simonsapin.github.io/wtf-8/) 编码。
/// * WASI 上,`sub_path` 应采用有效的 UTF-8 编码。
/// * 其他平台上,`sub_path` 是不指定编码的不透明字节序列。
///
/// 相关函数:
/// * `createDirPath`
/// * `createDirAbsolute`
pub fn createDir(dir: Dir, io: Io, sub_path: []const u8, permissions: Permissions) CreateDirError!void {
return io.vtable.dirCreateDir(io.userdata, dir, sub_path, permissions);
}
/// 根据绝对路径创建新目录。
///
/// 断言路径为绝对路径。若需要同时处理
/// 绝对和相对路径,参见 `createDir`。
///
/// Windows 上,`absolute_path` 应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// WASI 上,`absolute_path` 应编码为有效 UTF-8。
/// 其他平台上,`absolute_path` 是不规定编码的不透明字节序列。
pub fn createDirAbsolute(io: Io, absolute_path: []const u8, permissions: Permissions) CreateDirError!void {
assert(path.isAbsolute(absolute_path));
return createDir(.cwd(), io, absolute_path, permissions);
}
test createDirAbsolute {}
pub const CreateDirPathError = CreateDirError || StatFileError;
/// 按需使用默认权限创建父目录,确保
/// `sub_path` 作为目录存在。
///
/// 若路径已存在且是目录,则成功返回。
///
/// 此函数不一定是原子操作。若返回错误,文件系统
/// 可能已被修改。
///
/// 路径为空时返回 `error.BadPathName`,因为空路径
/// 无法创建。
///
/// Windows 上,`sub_path` 应采用 [WTF-8](https://simonsapin.github.io/wtf-8/) 编码。
/// WASI 上,`sub_path` 应采用有效的 UTF-8 编码。
/// 其他平台上,`sub_path` 是不指定编码的不透明字节序列。
///
/// 包含 `..` 分量的路径按平台采用不同的处理方式:
/// - Windows 上,在将路径传给 NtCreateFile 之前解析 `..`,因此
/// 对于类似 "first/../second" 的 `sub_path`,会先解析为 "second",只创建
/// `./second` 目录。
/// - 其他平台上,`..` 在将路径传给 `mkdirat` 之前不会解析,
/// 因此类似 "first/../second" 的 `sub_path` 会同时创建 `./first`
/// 和 `./second` 目录。
///
/// 另请参见:
/// * `createDirPathStatus`
pub fn createDirPath(dir: Dir, io: Io, sub_path: []const u8) CreateDirPathError!void {
_ = try io.vtable.dirCreateDirPath(io.userdata, dir, sub_path, .default_dir);
}
pub const CreatePathStatus = enum { existed, created };
/// 与 `createDirPath` 相同,但返回路径原本已存在,还是
/// 已成功创建。
pub fn createDirPathStatus(dir: Dir, io: Io, sub_path: []const u8, permissions: Permissions) CreateDirPathError!CreatePathStatus {
return io.vtable.dirCreateDirPath(io.userdata, dir, sub_path, permissions);
}
pub const CreateDirPathOpenError = CreateDirError || OpenError || StatFileError;
pub const CreateDirPathOpenOptions = struct {
open_options: OpenOptions = .{},
permissions: Permissions = .default_dir,
};
/// 执行等同于先调用 `createDirPath`、再调用 `openDir` 的操作,尽可能原子执行。
///
/// 取消此操作时,文件系统可能处于部分修改状态。
///
/// Windows 上,`sub_path` 应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// WASI 上,`sub_path` 应采用有效 UTF-8 编码。
/// 其他平台上,`sub_path` 是不透明的字节序列,没有特定编码。
///
pub fn createDirPathOpen(dir: Dir, io: Io, sub_path: []const u8, options: CreateDirPathOpenOptions) CreateDirPathOpenError!Dir {
return io.vtable.dirCreateDirPathOpen(io.userdata, dir, sub_path, options.permissions, options.open_options);
}
pub const Stat = File.Stat;
pub const StatError = File.StatError;
pub fn stat(dir: Dir, io: Io) StatError!Stat {
return io.vtable.dirStat(io.userdata, dir);
}
pub const StatFileError = File.OpenError || File.StatError;
pub const StatFileOptions = struct {
follow_symlinks: bool = true,
};
/// 返回目录内某个文件的元数据。
///
/// Windows 上需要三次系统调用。其他操作系统上
/// 只需一次。
///
/// 会跟随符号链接。
///
/// `sub_path` 可以是绝对路径,此时忽略 `self`。
///
/// * Windows 上,`sub_path` 应编码为 [WTF-8](https://simonsapin.github.io/wtf-8/)。
/// * WASI 上,`sub_path` 应编码为有效 UTF-8。
/// * 其他平台上,`sub_path` 是不规定编码的不透明字节序列。
pub fn statFile(dir: Dir, io: Io, sub_path: []const u8, options: StatFileOptions) StatFileError!Stat {
return io.vtable.dirStatFile(io.userdata, dir, sub_path, options);
}
pub const RealPathError = File.RealPathError;
/// 获取 `dir` 的规范化绝对路径名。
///
/// 此函数的平台支持有限,使用它可能导致不必要的失败和竞态条件。
/// 通常建议完全避免使用此函数。
///
pub fn realPath(dir: Dir, io: Io, out_buffer: []u8) RealPathError!usize {
return io.vtable.dirRealPath(io.userdata, dir, out_buffer);
}
pub const RealPathFileError = RealPathError || PathNameError;
/// 取得 `sub_path` 相对于此 `Dir` 的规范化绝对路径名。
/// 如果 `sub_path` 为绝对路径,则忽略此 `Dir` 句柄,
/// 取得 `sub_path` 参数的规范化绝对路径名。
///
/// 此函数的平台支持有限,使用它可能导致
/// 不必要的失败和竞态。通常建议
/// 完全避免使用此函数。
///
/// 另请参见:
/// * `realPathFileAlloc`。
/// * `realPathFileAbsolute`。
pub fn realPathFile(dir: Dir, io: Io, sub_path: []const u8, out_buffer: []u8) RealPathFileError!usize {
return io.vtable.dirRealPathFile(io.userdata, dir, sub_path, out_buffer);
}
pub const RealPathFileAllocError = RealPathFileError || Allocator.Error;
/// 与 `realPathFile` 相同,但会分配结果。
///
/// 此函数的平台支持有限,使用它可能导致
/// 不必要的失败和竞态。通常建议
/// 完全避免使用此函数。
///
/// 另请参见:
/// * `realPathFile`。
/// * `realPathFileAbsolute`。
pub fn realPathFileAlloc(dir: Dir, io: Io, sub_path: []const u8, allocator: Allocator) RealPathFileAllocError![:0]u8 {
var buffer: [max_path_bytes]u8 = undefined;
const n = try realPathFile(dir, io, sub_path, &buffer);
return allocator.dupeSentinel(u8, buffer[0..n], 0);
}
/// 与 `realPathFile` 相同,但断言 `absolute_path` 为绝对
/// 路径。
///
/// 此函数的平台支持有限,使用它可能导致
/// 不必要的失败和竞态。通常建议
/// 完全避免使用此函数。
///
/// 另请参见:
/// * `realPathFile`。
/// * `realPathFileAlloc`。
pub fn realPathFileAbsolute(io: Io, absolute_path: []const u8, out_buffer: []u8) RealPathFileError!usize {
assert(path.isAbsolute(absolute_path));
return io.vtable.dirRealPathFile(io.userdata, .cwd(), absolute_path, out_buffer);
}
/// 与 `realPathFileAbsolute` 相同,但会分配结果。
///
/// 此函数的平台支持有限,使用它可能导致
/// 不必要的失败和竞态。通常建议
/// 完全避免使用此函数。
///
/// 另请参见:
/// * `realPathFileAbsolute`。
/// * `realPathFile`。
pub fn realPathFileAbsoluteAlloc(io: Io, absolute_path: []const u8, allocator: Allocator) RealPathFileAllocError![:0]u8 {
var buffer: [max_path_bytes]u8 = undefined;
const n = try realPathFileAbsolute(io, absolute_path, &buffer);
return allocator.dupeSentinel(u8, buffer[0..n], 0);
}
pub const DeleteFileError = error{
FileNotFound,
/// 在 WASI 中,若文件描述符不具有通过相对于它的路径
/// 解除资源链接所需的权限,可能发生此错误。
AccessDenied,
PermissionDenied,
FileBusy,
FileSystem,
IsDir,
SymLinkLoop,
NotDir,
SystemResources,
ReadOnlyFileSystem,
/// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
NetworkNotFound,
} || PathNameError || Io.Cancelable || Io.UnexpectedError;
/// 根据已打开的目录句柄删除文件名,并可能删除其引用的文件。
///
/// Windows 上,`sub_path` 应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// WASI 上,`sub_path` 应编码为有效 UTF-8。
/// 其他平台上,`sub_path` 是不规定编码的不透明字节序列。
///
/// 断言路径参数不含空字节。
pub fn deleteFile(dir: Dir, io: Io, sub_path: []const u8) DeleteFileError!void {
return io.vtable.dirDeleteFile(io.userdata, dir, sub_path);
}
pub fn deleteFileAbsolute(io: Io, absolute_path: []const u8) DeleteFileError!void {
assert(path.isAbsolute(absolute_path));
return deleteFile(.cwd(), io, absolute_path);
}
test deleteFileAbsolute {}
pub const DeleteDirError = error{
DirNotEmpty,
FileNotFound,
AccessDenied,
PermissionDenied,
FileBusy,
FileSystem,
SymLinkLoop,
NotDir,
SystemResources,
ReadOnlyFileSystem,
/// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
NetworkNotFound,
} || PathNameError || Io.Cancelable || Io.UnexpectedError;
/// 如果目录非空,则返回 `error.DirNotEmpty`。
///
/// 递归删除目录,参见 `deleteTree`。
///
/// Windows 上,`sub_path` 应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// WASI 上,`sub_path` 应编码为有效 UTF-8。
/// 其他平台上,`sub_path` 是不规定编码的不透明字节序列。
pub fn deleteDir(dir: Dir, io: Io, sub_path: []const u8) DeleteDirError!void {
return io.vtable.dirDeleteDir(io.userdata, dir, sub_path);
}
/// 与 `deleteDir` 相同,但路径为绝对路径。
///
/// Windows 上,`dir_path` 应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// WASI 上,`dir_path` 应采用有效 UTF-8 编码。
/// 其他平台上,`dir_path` 是不透明的字节序列,没有特定编码。
pub fn deleteDirAbsolute(io: Io, absolute_path: []const u8) DeleteDirError!void {
assert(path.isAbsolute(absolute_path));
return deleteDir(.cwd(), io, absolute_path);
}
pub const RenameError = error{
/// 在 WASI 中,当文件描述符不具备相对于自身
/// 按路径重命名资源所需的权限时,可能发生此错误。
AccessDenied,
/// 试图替换非空目录。
DirNotEmpty,
PermissionDenied,
/// 尝试移动或替换的文件是正在运行的可执行文件。
FileBusy,
DiskQuota,
IsDir,
SymLinkLoop,
LinkQuotaExceeded,
FileNotFound,
NotDir,
SystemResources,
NoSpaceLeft,
ReadOnlyFileSystem,
CrossDevice,
NoDevice,
PipeBusy,
/// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
NetworkNotFound,
/// Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。
/// 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
///
///
///
AntivirusInterference,
HardwareFailure,
} || PathNameError || Io.Cancelable || Io.UnexpectedError;
/// 更改文件或目录的名称或位置。
///
/// 如果 `new_sub_path` 已存在,则将其替换。
///
/// 将文件重命名以覆盖已有目录,或将目录重命名以覆盖已有
/// 文件,都会失败并返回 `error.IsDir` 或 `error.NotDir`。
///
/// * Windows 上,两个路径均应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// * WASI 上,两个路径均应编码为有效 UTF-8。
/// * 其他平台上,两个路径均是不规定编码的不透明字节序列。
pub fn rename(
old_dir: Dir,
old_sub_path: []const u8,
new_dir: Dir,
new_sub_path: []const u8,
io: Io,
) RenameError!void {
return io.vtable.dirRename(io.userdata, old_dir, old_sub_path, new_dir, new_sub_path);
}
pub fn renameAbsolute(old_path: []const u8, new_path: []const u8, io: Io) RenameError!void {
assert(path.isAbsolute(old_path));
assert(path.isAbsolute(new_path));
const my_cwd = cwd();
return io.vtable.dirRename(io.userdata, my_cwd, old_path, my_cwd, new_path);
}
pub const RenamePreserveError = error{
/// 在 WASI 中,当文件描述符不具有
/// 按相对于该描述符的路径重命名资源所需的权限时,可能发生此错误。
///
/// 在 Windows 上,将目录重命名并覆盖已有目录时,
/// 可能返回此错误,而不是 PathAlreadyExists。
///
/// 在 Darwin 上,如果任一路径中的分量指向需要实体化的
/// “无数据”目录,而当前线程或进程的 I/O
/// 策略不允许无数据目录实体化,则可能返回此错误。
AccessDenied,
PathAlreadyExists,
/// 操作系统或文件系统不支持原子地执行不替换目标的重命名。
OperationUnsupported,
} || RenameError;
/// 更改文件或目录的名称或位置。
///
/// 如果 `new_sub_path` 已存在,将返回 `error.PathAlreadyExists`。
///
/// 若操作系统支持,整个操作将以原子方式完成。否则,将回退为先创建硬链接再取消链接;这对 `new_sub_path` 是原子的,但存在清理 old_sub_path 可能失败的时间窗口。虽然该操作具有较好的可移植性,但严格来说,在某些环境下该回退方案也可能不受支持,此时返回 `error.OperationUnsupported`。
///
/// * 在 Windows 上,两个路径都应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// * 在 WASI 上,两个路径都应采用有效的 UTF-8 编码。
/// * 在其他平台上,两个路径都是不限定编码的不透明字节序列。
///
///
///
///
pub fn renamePreserve(
old_dir: Dir,
old_sub_path: []const u8,
new_dir: Dir,
new_sub_path: []const u8,
io: Io,
) RenamePreserveError!void {
return io.vtable.dirRenamePreserve(io.userdata, old_dir, old_sub_path, new_dir, new_sub_path);
}
pub const HardLinkOptions = File.HardLinkOptions;
pub const HardLinkError = File.HardLinkError;
pub fn hardLink(
old_dir: Dir,
old_sub_path: []const u8,
new_dir: Dir,
new_sub_path: []const u8,
io: Io,
options: HardLinkOptions,
) HardLinkError!void {
return io.vtable.dirHardLink(io.userdata, old_dir, old_sub_path, new_dir, new_sub_path, options);
}
/// 与 `symLink`、`symLinkAtomic` 和 `symLinkAbsolute` 配合使用,
/// 指定符号链接指向文件还是目录。除 Windows 外,所有宿主
/// 均忽略此值;在 Windows 上,创建指向不同
/// 资源类型的符号链接需要不同标志。默认假定 `symLinkAbsolute`
/// 指向文件。
pub const SymLinkFlags = struct {
is_directory: bool = false,
};
pub const SymLinkError = error{
/// 在 WASI 中,当文件描述符不具备相对于自身
/// 创建新符号链接所需的权限时,可能发生此错误。
AccessDenied,
PermissionDenied,
DiskQuota,
PathAlreadyExists,
FileSystem,
SymLinkLoop,
FileNotFound,
SystemResources,
NoSpaceLeft,
/// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
NetworkNotFound,
ReadOnlyFileSystem,
NotDir,
} || PathNameError || Io.Cancelable || Io.UnexpectedError;
/// 创建名为 `sym_link_path`、内容为字符串 `target_path` 的符号链接。
///
/// 符号链接也称软链接,既可指向已有文件,也可指向不存在的
/// 文件;后者称为悬空链接。
///
/// 若 `sym_link_path` 已存在,不会覆盖。
///
/// Windows 上,两条路径均应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// WASI 上,两条路径均应采用有效的 UTF-8 编码。
/// 其他平台上,两条路径均为不指定编码的不透明字节序列。
pub fn symLink(
dir: Dir,
io: Io,
target_path: []const u8,
sym_link_path: []const u8,
flags: SymLinkFlags,
) SymLinkError!void {
return io.vtable.dirSymLink(io.userdata, dir, target_path, sym_link_path, flags);
}
pub fn symLinkAbsolute(
io: Io,
target_path: []const u8,
sym_link_path: []const u8,
flags: SymLinkFlags,
) SymLinkError!void {
assert(path.isAbsolute(target_path));
assert(path.isAbsolute(sym_link_path));
return symLink(.cwd(), io, target_path, sym_link_path, flags);
}
/// 与 `symLink` 相同,但会持续尝试创建符号链接,直到
/// 成功或遇到 `error.PathAlreadyExists` 之外的错误。
///
/// * Windows 上,两条路径均应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// * WASI 上,两条路径均应采用有效的 UTF-8 编码。
/// * 其他平台上,两条路径均为不指定编码的不透明字节序列。
pub fn symLinkAtomic(
dir: Dir,
io: Io,
target_path: []const u8,
sym_link_path: []const u8,
flags: SymLinkFlags,
) !void {
if (dir.symLink(io, target_path, sym_link_path, flags)) {
return;
} else |err| switch (err) {
error.PathAlreadyExists => {},
else => |e| return e,
}
const dirname = path.dirname(sym_link_path) orelse ".";
const rand_len = @sizeOf(u64) * 2;
const temp_path_len = dirname.len + 1 + rand_len;
var temp_path_buf: [max_path_bytes]u8 = undefined;
if (temp_path_len > temp_path_buf.len) return error.NameTooLong;
@memcpy(temp_path_buf[0..dirname.len], dirname);
temp_path_buf[dirname.len] = path.sep;
const temp_path = temp_path_buf[0..temp_path_len];
var random_integer: u64 = undefined;
while (true) {
io.random(@ptrCast(&random_integer));
temp_path[dirname.len + 1 ..][0..rand_len].* = std.fmt.hex(random_integer);
if (dir.symLink(io, target_path, temp_path, flags)) {
return dir.rename(temp_path, dir, sym_link_path, io);
} else |err| switch (err) {
error.PathAlreadyExists => continue,
else => |e| return e,
}
}
}
pub const ReadLinkError = error{
/// 在 WASI 中,若文件描述符不具有相对于该描述符读取符号链接值所需的权限,可能发生此错误。
///
AccessDenied,
PermissionDenied,
FileSystem,
SymLinkLoop,
FileNotFound,
SystemResources,
NotLink,
NotDir,
/// 仅限 Windows。如果打开的重解析点类型不受支持,
/// 可能发生此错误。
UnsupportedReparsePointType,
/// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
NetworkNotFound,
/// Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。
/// 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
///
///
///
AntivirusInterference,
/// 尝试打开的文件是正在运行的可执行文件。
FileBusy,
} || PathNameError || Io.Cancelable || Io.UnexpectedError;
/// 获取符号链接的目标。
///
/// 返回 `buffer` 中已填充的字节数。
///
/// 断言路径参数不含空字节。
///
/// Windows 上,`sub_path` 应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// WASI 上,`sub_path` 应采用有效 UTF-8 编码。
/// 其他平台上,`sub_path` 是不透明的字节序列,没有特定编码。
pub fn readLink(dir: Dir, io: Io, sub_path: []const u8, buffer: []u8) ReadLinkError!usize {
return io.vtable.dirReadLink(io.userdata, dir, sub_path, buffer);
}
/// 与 `readLink` 相同,但断言路径为绝对路径。
///
/// Windows 上,`path` 应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// WASI 上,`path` 应采用有效的 UTF-8 编码。
/// 其他平台上,`path` 是不指定编码的不透明字节序列。
pub fn readLinkAbsolute(io: Io, absolute_path: []const u8, buffer: []u8) ReadLinkError!usize {
assert(path.isAbsolute(absolute_path));
return io.vtable.dirReadLink(io.userdata, .cwd(), absolute_path, buffer);
}
pub const ReadFileAllocError = File.OpenError || File.Reader.Error || Allocator.Error || error{
/// 文件大小达到或超过提供的限制。
StreamTooLong,
};
/// 读取指定文件的全部字节。成功时,调用者拥有返回的缓冲区。
///
/// 若已知文件大小,更好的方式是初始化 `File.Reader`。
///
/// 若无法获取文件大小,则返回错误。若实际中可能遇到这种情况,更好的方式是初始化 `File.Reader`,它可无缝处理该情况。
///
///
///
///
pub fn readFileAlloc(
dir: Dir,
io: Io,
/// 在 Windows 上,应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// 在 WASI 上,应编码为有效的 UTF-8。
/// 在其他平台上,为不规定编码的不透明字节序列。
sub_path: []const u8,
/// 用于分配结果。
gpa: Allocator,
/// 如果达到或超过此值,则改为返回 `error.StreamTooLong`。
limit: Io.Limit,
) ReadFileAllocError![]u8 {
return readFileAllocOptions(dir, io, sub_path, gpa, limit, .of(u8), null);
}
/// 读取指定文件的所有字节。成功时,返回缓冲区的
/// 所有权归调用者。
///
/// 若文件大小已知,更好的选择是初始化一个
/// `File.Reader`。
pub fn readFileAllocOptions(
dir: Dir,
io: Io,
/// 在 Windows 上,应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// 在 WASI 上,应编码为有效的 UTF-8。
/// 在其他平台上,为不规定编码的不透明字节序列。
sub_path: []const u8,
/// 用于分配结果。
gpa: Allocator,
/// 如果达到或超过此值,则改为返回 `error.StreamTooLong`。
limit: Io.Limit,
comptime alignment: std.mem.Alignment,
comptime sentinel: ?u8,
) ReadFileAllocError!(if (sentinel) |s| [:s]align(alignment.toByteUnits()) u8 else []align(alignment.toByteUnits()) u8) {
var file = try dir.openFile(io, sub_path, .{
// 在 Windows 上可以利用这一点,因为不会增加系统调用,
// 从而在打开时而非读取时获得 error.IsDir。
.allow_directory = if (native_os == .windows) false else true,
});
defer file.close(io);
var file_reader = file.reader(io, &.{});
return file_reader.interface.allocRemainingAlignedSentinel(gpa, limit, alignment, sentinel) catch |err| switch (err) {
error.ReadFailed => return file_reader.err.?,
error.OutOfMemory, error.StreamTooLong => |e| return e,
};
}
pub const DeleteTreeError = error{
AccessDenied,
PermissionDenied,
FileTooBig,
SymLinkLoop,
ProcessFdQuotaExceeded,
SystemFdQuotaExceeded,
NoDevice,
SystemResources,
ReadOnlyFileSystem,
FileSystem,
FileBusy,
/// 某个路径分量不是目录。
/// 若 `sub_path` 不包含路径分隔符,则此错误不可达。
NotDir,
/// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
NetworkNotFound,
} || PathNameError || Io.Cancelable || Io.UnexpectedError;
/// 不论 `sub_path` 描述的是符号链接、文件还是目录,此函数
/// 都会将其删除。若因目录非空而无法删除,
/// 则先递归删除其条目,再次尝试。
///
/// 此操作在多数文件系统上不是原子操作。
///
/// Windows 上,`sub_path` 应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// WASI 上,`sub_path` 应采用有效的 UTF-8 编码。
/// 其他平台上,`sub_path` 是不指定编码的不透明字节序列。
pub fn deleteTree(dir: Dir, io: Io, sub_path: []const u8) DeleteTreeError!void {
var initial_iterable_dir = (try dir.deleteTreeOpenInitialSubpath(io, sub_path, .file)) orelse return;
const StackItem = struct {
name: []const u8,
parent_dir: Dir,
iter: Iterator,
fn closeAll(inner_io: Io, items: []@This()) void {
for (items) |*item| item.iter.reader.dir.close(inner_io);
}
};
var stack_buffer: [16]StackItem = undefined;
var stack = std.ArrayList(StackItem).initBuffer(&stack_buffer);
defer StackItem.closeAll(io, stack.items);
stack.appendAssumeCapacity(.{
.name = sub_path,
.parent_dir = dir,
.iter = initial_iterable_dir.iterateAssumeFirstIteration(),
});
process_stack: while (stack.items.len != 0) {
var top = &stack.items[stack.items.len - 1];
while (try top.iter.next(io)) |entry| {
var treat_as_dir = entry.kind == .directory;
handle_entry: while (true) {
if (treat_as_dir) {
if (stack.unusedCapacitySlice().len >= 1) {
var iterable_dir = top.iter.reader.dir.openDir(io, entry.name, .{
.follow_symlinks = false,
.iterate = true,
}) catch |err| switch (err) {
error.NotDir => {
treat_as_dir = false;
continue :handle_entry;
},
error.FileNotFound => {
// 没有问题,原本就打算移除此目录。
break :handle_entry;
},
error.AccessDenied,
error.PermissionDenied,
error.SymLinkLoop,
error.ProcessFdQuotaExceeded,
error.NameTooLong,
error.SystemFdQuotaExceeded,
error.NoDevice,
error.SystemResources,
error.Unexpected,
error.BadPathName,
error.NetworkNotFound,
error.Canceled,
=> |e| return e,
};
stack.appendAssumeCapacity(.{
.name = entry.name,
.parent_dir = top.iter.reader.dir,
.iter = iterable_dir.iterateAssumeFirstIteration(),
});
continue :process_stack;
} else {
try top.iter.reader.dir.deleteTreeMinStackSizeWithKindHint(io, entry.name, entry.kind);
break :handle_entry;
}
} else {
if (top.iter.reader.dir.deleteFile(io, entry.name)) {
break :handle_entry;
} else |err| switch (err) {
error.FileNotFound => break :handle_entry,
// 不可能发生,因为未传入任何路径分隔符。
error.NotDir => unreachable,
error.IsDir => {
treat_as_dir = true;
continue :handle_entry;
},
error.AccessDenied,
error.PermissionDenied,
error.SymLinkLoop,
error.NameTooLong,
error.SystemResources,
error.ReadOnlyFileSystem,
error.FileSystem,
error.FileBusy,
error.BadPathName,
error.NetworkNotFound,
error.Canceled,
error.Unexpected,
=> |e| return e,
}
}
}
}
// 在 Windows 上,关闭目录句柄前无法删除目录,
// 因此先关闭句柄,再尝试删除。
top.iter.reader.dir.close(io);
// 为避免出错时清理栈导致目录被关闭两次,
// 保存相关部分,并从栈中弹出该值。
//
const parent_dir = top.parent_dir;
const name = top.name;
stack.items.len -= 1;
var need_to_retry: bool = false;
parent_dir.deleteDir(io, name) catch |err| switch (err) {
error.FileNotFound => {},
error.DirNotEmpty => need_to_retry = true,
else => |e| return e,
};
if (need_to_retry) {
// 由于已关闭先前迭代器使用的句柄,
// 需要重新打开目录并重新创建迭代器。
var iterable_dir = iterable_dir: {
var treat_as_dir = true;
handle_entry: while (true) {
if (treat_as_dir) {
break :iterable_dir parent_dir.openDir(io, name, .{
.follow_symlinks = false,
.iterate = true,
}) catch |err| switch (err) {
error.NotDir => {
treat_as_dir = false;
continue :handle_entry;
},
error.FileNotFound => {
// 没有问题,原本就打算移除此目录。
continue :process_stack;
},
error.AccessDenied,
error.PermissionDenied,
error.SymLinkLoop,
error.ProcessFdQuotaExceeded,
error.NameTooLong,
error.SystemFdQuotaExceeded,
error.NoDevice,
error.SystemResources,
error.Unexpected,
error.BadPathName,
error.NetworkNotFound,
error.Canceled,
=> |e| return e,
};
} else {
if (parent_dir.deleteFile(io, name)) {
continue :process_stack;
} else |err| switch (err) {
error.FileNotFound => continue :process_stack,
// 不可能发生,因为未传入任何路径分隔符。
error.NotDir => unreachable,
error.IsDir => {
treat_as_dir = true;
continue :handle_entry;
},
error.AccessDenied,
error.PermissionDenied,
error.SymLinkLoop,
error.NameTooLong,
error.SystemResources,
error.ReadOnlyFileSystem,
error.FileSystem,
error.FileBusy,
error.BadPathName,
error.NetworkNotFound,
error.Canceled,
error.Unexpected,
=> |e| return e,
}
}
}
};
// 已知栈有空间,因为只是重新放入
// 刚弹出的 StackItem。
stack.appendAssumeCapacity(.{
.name = name,
.parent_dir = parent_dir,
.iter = iterable_dir.iterateAssumeFirstIteration(),
});
continue :process_stack;
}
}
}
/// 类似 `deleteTree`,但每次只保持一个 `Iterator` 活跃,以最小化函数栈大小。
/// 比 `deleteTree` 慢,但使用更少栈空间。
/// Windows 上,`sub_path` 应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// WASI 上,`sub_path` 应采用有效的 UTF-8 编码。
/// 其他平台上,`sub_path` 是不指定编码的不透明字节序列。
pub fn deleteTreeMinStackSize(dir: Dir, io: Io, sub_path: []const u8) DeleteTreeError!void {
return dir.deleteTreeMinStackSizeWithKindHint(io, sub_path, .file);
}
fn deleteTreeMinStackSizeWithKindHint(parent: Dir, io: Io, sub_path: []const u8, kind_hint: File.Kind) DeleteTreeError!void {
start_over: while (true) {
var dir = (try parent.deleteTreeOpenInitialSubpath(io, sub_path, kind_hint)) orelse return;
var cleanup_dir_parent: ?Dir = null;
defer if (cleanup_dir_parent) |*d| d.close(io);
var cleanup_dir = true;
defer if (cleanup_dir) dir.close(io);
// 使用 max_path_bytes 是合理的,因为 dir_name_buf
// 只会存储文件系统返回的单个
// 路径分量。
var dir_name_buf: [max_path_bytes]u8 = undefined;
var dir_name: []const u8 = sub_path;
// 此处必须避免递归,才能保证此函数使用 O(1) 内存。
// 逐个处理条目:若不是目录,则删除;若是目录,
// 则打开该目录,并关闭原目录。重复此过程,随后重新开始整个操作。
scan_dir: while (true) {
var dir_it = dir.iterateAssumeFirstIteration();
dir_it: while (try dir_it.next(io)) |entry| {
var treat_as_dir = entry.kind == .directory;
handle_entry: while (true) {
if (treat_as_dir) {
const new_dir = dir.openDir(io, entry.name, .{
.follow_symlinks = false,
.iterate = true,
}) catch |err| switch (err) {
error.NotDir => {
treat_as_dir = false;
continue :handle_entry;
},
error.FileNotFound => {
// 没有问题,原本就打算移除此目录。
continue :dir_it;
},
error.AccessDenied,
error.PermissionDenied,
error.SymLinkLoop,
error.ProcessFdQuotaExceeded,
error.NameTooLong,
error.SystemFdQuotaExceeded,
error.NoDevice,
error.SystemResources,
error.Unexpected,
error.BadPathName,
error.NetworkNotFound,
error.Canceled,
=> |e| return e,
};
if (cleanup_dir_parent) |*d| d.close(io);
cleanup_dir_parent = dir;
dir = new_dir;
const result = dir_name_buf[0..entry.name.len];
@memcpy(result, entry.name);
dir_name = result;
continue :scan_dir;
} else {
if (dir.deleteFile(io, entry.name)) {
continue :dir_it;
} else |err| switch (err) {
error.FileNotFound => continue :dir_it,
// 不可能发生,因为未传入任何路径分隔符。
error.NotDir => unreachable,
error.IsDir => {
treat_as_dir = true;
continue :handle_entry;
},
error.AccessDenied,
error.PermissionDenied,
error.SymLinkLoop,
error.NameTooLong,
error.SystemResources,
error.ReadOnlyFileSystem,
error.FileSystem,
error.FileBusy,
error.BadPathName,
error.NetworkNotFound,
error.Canceled,
error.Unexpected,
=> |e| return e,
}
}
}
}
// 已到达目录条目末尾,表示成功删除了全部条目。
// 接下来删除目录本身。
dir.close(io);
cleanup_dir = false;
if (cleanup_dir_parent) |d| {
d.deleteDir(io, dir_name) catch |err| switch (err) {
// 这两种情况都可能因文件系统竞态条件发生。
error.FileNotFound, error.DirNotEmpty => continue :start_over,
else => |e| return e,
};
continue :start_over;
} else {
parent.deleteDir(io, sub_path) catch |err| switch (err) {
error.FileNotFound => return,
error.DirNotEmpty => continue :start_over,
else => |e| return e,
};
return;
}
}
}
}
/// 删除成功时返回 null。
fn deleteTreeOpenInitialSubpath(dir: Dir, io: Io, sub_path: []const u8, kind_hint: File.Kind) !?Dir {
return iterable_dir: {
// 默认按文件处理
var treat_as_dir = kind_hint == .directory;
handle_entry: while (true) {
if (treat_as_dir) {
break :iterable_dir dir.openDir(io, sub_path, .{
.follow_symlinks = false,
.iterate = true,
}) catch |err| switch (err) {
error.NotDir => {
treat_as_dir = false;
continue :handle_entry;
},
error.FileNotFound => {
// 没有问题,原本就打算移除此目录。
return null;
},
error.AccessDenied,
error.PermissionDenied,
error.SymLinkLoop,
error.ProcessFdQuotaExceeded,
error.NameTooLong,
error.SystemFdQuotaExceeded,
error.NoDevice,
error.SystemResources,
error.Unexpected,
error.BadPathName,
error.NetworkNotFound,
error.Canceled,
=> |e| return e,
};
} else {
if (dir.deleteFile(io, sub_path)) {
return null;
} else |err| switch (err) {
error.FileNotFound => return null,
error.IsDir => {
treat_as_dir = true;
continue :handle_entry;
},
error.AccessDenied,
error.PermissionDenied,
error.SymLinkLoop,
error.NameTooLong,
error.SystemResources,
error.ReadOnlyFileSystem,
error.NotDir,
error.FileSystem,
error.FileBusy,
error.BadPathName,
error.NetworkNotFound,
error.Canceled,
error.Unexpected,
=> |e| return e,
}
}
}
};
}
pub const CopyFileOptions = struct {
/// 此项为 `null` 时,从源文件复制权限。
permissions: ?File.Permissions = null,
make_path: bool = false,
replace: bool = true,
};
pub const CopyFileError = File.OpenError || File.StatError ||
CreateFileAtomicError || File.Atomic.ReplaceError || File.Atomic.LinkError ||
File.Reader.Error || File.Writer.Error || error{InvalidFileName};
/// 在 `dest_path` 原子创建新文件,该路径位于 `dest_dir` 内,
/// 内容与 `source_path` 相同,该源路径位于 `source_dir` 内。
///
/// 是否覆盖已有文件由 `options` 决定。
///
/// Linux 上,在 https://patchwork.kernel.org/patch/9636735/ 合入
/// 并广泛可用之前,断电或应用
/// 终止可能使临时文件残留在
/// dest_path 所在的同一目录中。
///
/// Windows 上,两条路径均应采用
/// [WTF-8](https://wtf-8.codeberg.page/) 编码。WASI 上,两条路径均应采用
/// 有效的 UTF-8 编码。其他平台上,两条路径均为
/// 不指定编码的不透明字节序列。
pub fn copyFile(
source_dir: Dir,
source_path: []const u8,
dest_dir: Dir,
dest_path: []const u8,
io: Io,
options: CopyFileOptions,
) CopyFileError!void {
const file = try source_dir.openFile(io, source_path, .{});
var file_reader: File.Reader = .init(file, io, &.{});
defer file_reader.file.close(io);
const permissions = options.permissions orelse blk: {
const st = try file_reader.file.stat(io);
file_reader.size = st.size;
break :blk st.permissions;
};
var atomic_file = try dest_dir.createFileAtomic(io, dest_path, .{
.permissions = permissions,
.make_path = options.make_path,
.replace = options.replace,
});
defer atomic_file.deinit(io);
var buffer: [1024]u8 = undefined; // 仅当无法直接在 fd 之间传输时使用。
var file_writer = atomic_file.file.writer(io, &buffer);
_ = file_writer.interface.sendFileAll(&file_reader, .unlimited) catch |err| switch (err) {
error.ReadFailed => return file_reader.err.?,
error.WriteFailed => return file_writer.err.?,
};
try file_writer.flush();
switch (options.replace) {
true => try atomic_file.replace(io),
false => try atomic_file.link(io),
}
}
/// 与 `copyFile` 相同,但断言 `source_path` 和 `dest_path` 均为绝对路径。
///
/// Windows 上,两个路径都应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// WASI 上,两个路径都应采用有效 UTF-8 编码。
/// 其他平台上,两个路径都是不透明的字节序列,没有特定编码。
///
pub fn copyFileAbsolute(
source_path: []const u8,
dest_path: []const u8,
io: Io,
options: CopyFileOptions,
) !void {
assert(path.isAbsolute(source_path));
assert(path.isAbsolute(dest_path));
const my_cwd = cwd();
return copyFile(my_cwd, source_path, my_cwd, dest_path, io, options);
}
test copyFileAbsolute {}
pub const CreateFileAtomicOptions = struct {
permissions: File.Permissions = .default_file,
make_path: bool = false,
/// 指示无名文件最终将通过 `File.Atomic.link`
/// 还是 `File.Atomic.replace` 创建。
///
/// 如果此值不正确,会在
/// `File.Atomic.replace` 中导致断言失败。
replace: bool = false,
};
pub const CreateFileAtomicError = error{
NoDevice,
/// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
NetworkNotFound,
/// Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。
/// 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
///
///
///
AntivirusInterference,
/// 在 WASI 中,若文件描述符不具有相对于它
/// 打开新资源所需的权限,可能发生此错误。
AccessDenied,
PermissionDenied,
SymLinkLoop,
ProcessFdQuotaExceeded,
SystemFdQuotaExceeded,
/// 以下情况之一:
/// * 某个路径分量不存在。
/// * 使用了 Cwd,但当前工作目录已被删除。
/// * 与已打开目录句柄关联的路径已被删除。
FileNotFound,
/// 可用内核内存不足。
SystemResources,
/// 设备没有空间容纳新文件,无法创建新路径。
NoSpaceLeft,
/// 路径中作为目录使用的某个组成部分实际上不是目录。
NotDir,
WouldBlock,
ReadOnlyFileSystem,
/// 尝试创建的文件是正在运行的可执行文件。
FileBusy,
} || Io.Dir.PathNameError || Io.Cancelable || Io.UnexpectedError;
/// 创建一个未命名的临时文件,之后可将其原子地实体化为 `sub_path`。
/// 在该文件完成实体化之前,`sub_path` 必须保持有效。
///
/// 返回的 `File.Atomic` 提供 API,可在底层操作系统不直接支持时模拟此行为。
///
/// * 在 Windows 上,`sub_path` 应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// * 在 WASI 上,`sub_path` 应采用有效的 UTF-8 编码。
/// * 在其他平台上,`sub_path` 是不限定编码的不透明字节序列。
///
///
pub fn createFileAtomic(
dir: Dir,
io: Io,
sub_path: []const u8,
options: CreateFileAtomicOptions,
) CreateFileAtomicError!File.Atomic {
return io.vtable.dirCreateFileAtomic(io.userdata, dir, sub_path, options);
}
pub const SetPermissionsError = File.SetPermissionsError;
pub const Permissions = File.Permissions;
/// 也称为 chmod。
///
/// 进程必须具有适当特权,才能成功执行,
/// 或者有效用户标识符必须与目录
/// 所有者匹配。此外,目录必须在打开时
/// 将 `OpenOptions.iterate` 设为 `true`。
pub fn setPermissions(dir: Dir, io: Io, new_permissions: File.Permissions) SetPermissionsError!void {
return io.vtable.dirSetPermissions(io.userdata, dir, new_permissions);
}
pub const SetFilePermissionsError = PathNameError || SetPermissionsError || error{
ProcessFdQuotaExceeded,
SystemFdQuotaExceeded,
/// `SetFilePermissionsOptions.follow_symlinks` 被设为 false,但文件系统或操作系统不允许。
///
OperationUnsupported,
};
pub const SetFilePermissionsOptions = struct {
follow_symlinks: bool = true,
};
/// 也称为 "fchmodat"。
pub fn setFilePermissions(
dir: Dir,
io: Io,
sub_path: []const u8,
new_permissions: File.Permissions,
options: SetFilePermissionsOptions,
) SetFilePermissionsError!void {
return io.vtable.dirSetFilePermissions(io.userdata, dir, sub_path, new_permissions, options);
}
pub const SetOwnerError = File.SetOwnerError;
/// 也称为“chown”。
///
/// 进程必须具有正确权限才能成功执行。目录所有者可以将所属组改为自身属于的任意组。此外,目录必须在打开时将 `OpenOptions.iterate` 设为 `true`。
/// 若所有者或所属组指定为 `null`,则对应标识不变。
///
///
///
pub fn setOwner(dir: Dir, io: Io, owner: ?File.Uid, group: ?File.Gid) SetOwnerError!void {
return io.vtable.dirSetOwner(io.userdata, dir, owner, group);
}
pub const SetFileOwnerError = PathNameError || SetOwnerError;
pub const SetFileOwnerOptions = struct {
follow_symlinks: bool = true,
};
/// 也称为 "fchownat"。
pub fn setFileOwner(
dir: Dir,
io: Io,
sub_path: []const u8,
owner: ?File.Uid,
group: ?File.Gid,
options: SetFileOwnerOptions,
) SetFileOwnerError!void {
return io.vtable.dirSetFileOwner(io.userdata, dir, sub_path, owner, group, options);
}
pub const SetTimestampsError = File.SetTimestampsError || PathNameError;
pub const SetTimestampsOptions = struct {
follow_symlinks: bool = true,
access_timestamp: File.SetTimestamp = .unchanged,
modify_timestamp: File.SetTimestamp = .unchanged,
};
/// 最终存储的时间粒度取决于操作系统
/// 与文件系统的组合。若提供的值超出此范围,
/// 则将其限制为最大值。
pub fn setTimestamps(
dir: Dir,
io: Io,
sub_path: []const u8,
options: SetTimestampsOptions,
) SetTimestampsError!void {
return io.vtable.dirSetTimestamps(io.userdata, dir, sub_path, options);
}
pub const SetTimestampsNowOptions = struct {
follow_symlinks: bool = true,
};
/// 将所提供路径的访问时间戳及修改时间戳
/// 设置为当前墙上时钟时间。
///
/// 最终存储的时间粒度取决于
/// 操作系统与文件系统的组合。
pub fn setTimestampsNow(
dir: Dir,
io: Io,
sub_path: []const u8,
options: SetTimestampsNowOptions,
) SetTimestampsError!void {
return io.vtable.dirSetTimestamps(io.userdata, dir, sub_path, .{
.follow_symlinks = options.follow_symlinks,
.access_timestamp = .now,
.modify_timestamp = .now,
});
}
test {
_ = &setFileOwner;
_ = &setTimestampsNow;
}