字段
file: File
file_basename_hex: u64
file_open: bool
file_exists: bool
dir: Dir
close_dir_on_deinit: bool
dest_sub_path: []const u8
std.Io.File.Atomic.assert
别名
别名目标 std.debug.assert
std.Io.File.Atomic.Atomic
别名
别名目标 std.Io.File.Atomic
std.Io.File.Atomic.deinit
函数
要释放所有资源,即使 finish 成功后也必须始终
调用 deinit。
pub fn deinit(af: *Atomic, io: Io) void
参数
std.Io.File.Atomic.Dir
别名
别名目标 std.Io.Dir
std.Io.File.Atomic.File
别名
别名目标 std.Io.File
std.Io.File.Atomic.InitError
别名
std.Io.File.Atomic.Io
别名
别名目标 std.Io
std.Io.File.Atomic.link
函数
以原子方式将文件放置到目标位置;若该处已有内容,
则以 error.PathAlreadyExists 失败。
如果无法使用无名临时文件完成此操作,
则随后另行删除有名临时文件,该删除操作
也可能独立失败。其结果存储在 delete_err 中。
pub fn link(af: *Atomic, io: Io) LinkError!void
参数
错误
- AccessDenied RenamePreserveError
在 WASI 中,当文件描述符不具有 按相对于该描述符的路径重命名资源所需的权限时,可能发生此错误。
在 Windows 上,将目录重命名并覆盖已有目录时, 可能返回此错误,而不是 PathAlreadyExists。
在 Darwin 上,如果任一路径中的分量指向需要实体化的 “无数据”目录,而当前线程或进程的 I/O 策略不允许无数据目录实体化,则可能返回此错误。
- AntivirusInterference RenameError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice HardLinkError
- DirNotEmpty RenameError
试图替换非空目录。
- DiskQuota HardLinkError
- FileBusy RenameError
尝试移动或替换的文件是正在运行的可执行文件。
- FileNotFound HardLinkError
- HardwareFailure HardLinkError
- IsDir RenameError
- LinkQuotaExceeded HardLinkError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound RenameError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RenameError
- NoSpaceLeft HardLinkError
- NotDir HardLinkError
- OperationUnsupported HardLinkError
操作系统或文件系统不支持硬链接。
- PathAlreadyExists HardLinkError
- PermissionDenied HardLinkError
- PipeBusy RenameError
- ReadOnlyFileSystem HardLinkError
- SymLinkLoop HardLinkError
- SystemResources HardLinkError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.Atomic.LinkError
错误集合
错误
- AccessDenied RenamePreserveError
在 WASI 中,当文件描述符不具有 按相对于该描述符的路径重命名资源所需的权限时,可能发生此错误。
在 Windows 上,将目录重命名并覆盖已有目录时, 可能返回此错误,而不是 PathAlreadyExists。
在 Darwin 上,如果任一路径中的分量指向需要实体化的 “无数据”目录,而当前线程或进程的 I/O 策略不允许无数据目录实体化,则可能返回此错误。
- AntivirusInterference RenameError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice HardLinkError
- DirNotEmpty RenameError
试图替换非空目录。
- DiskQuota HardLinkError
- FileBusy RenameError
尝试移动或替换的文件是正在运行的可执行文件。
- FileNotFound HardLinkError
- HardwareFailure HardLinkError
- IsDir RenameError
- LinkQuotaExceeded HardLinkError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound RenameError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RenameError
- NoSpaceLeft HardLinkError
- NotDir HardLinkError
- OperationUnsupported HardLinkError
操作系统或文件系统不支持硬链接。
- PathAlreadyExists HardLinkError
- PermissionDenied HardLinkError
- PipeBusy RenameError
- ReadOnlyFileSystem HardLinkError
- SymLinkLoop HardLinkError
- SystemResources HardLinkError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.Atomic.replace
函数
以原子方式将文件实体化到目标位置,替换该位置已有的任意文件。
调用此函数要求将 CreateFileAtomicOptions.replace 设为 true。
Windows 上,此函数会引入一段时间,在此期间,对目标文件的某些文件系统操作会返回 error.AccessDenied,包括本函数使用的重命名操作。
pub fn replace(af: *Atomic, io: Io) ReplaceError!void
参数
错误
- AccessDenied RenameError
在 WASI 中,当文件描述符不具备相对于自身 按路径重命名资源所需的权限时,可能发生此错误。
- 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
- PermissionDenied RenameError
- PipeBusy RenameError
- ReadOnlyFileSystem RenameError
- SymLinkLoop RenameError
- SystemResources RenameError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.Atomic.ReplaceError
别名
std.Io.File.Atomic.std
别名
别名目标 std
源码
std/Io/File/Atomic.zig
const Atomic = @This();
const std = @import("../../std.zig");
const Io = std.Io;
const File = std.Io.File;
const Dir = std.Io.Dir;
const assert = std.debug.assert;
file: File,
file_basename_hex: u64,
file_open: bool,
file_exists: bool,
dir: Dir,
close_dir_on_deinit: bool,
dest_sub_path: []const u8,
pub const InitError = File.OpenError;
/// 要释放所有资源,即使 `finish` 成功后也必须始终
/// 调用 `deinit`。
pub fn deinit(af: *Atomic, io: Io) void {
if (af.file_open) {
af.file.close(io);
af.file_open = false;
}
if (af.file_exists) {
const tmp_sub_path = std.fmt.hex(af.file_basename_hex);
af.dir.deleteFile(io, &tmp_sub_path) catch {};
af.file_exists = false;
}
if (af.close_dir_on_deinit) {
af.dir.close(io);
af.close_dir_on_deinit = false;
}
af.* = undefined;
}
pub const LinkError = File.HardLinkError || Dir.RenamePreserveError;
/// 以原子方式将文件放置到目标位置;若该处已有内容,
/// 则以 `error.PathAlreadyExists` 失败。
///
/// 如果无法使用无名临时文件完成此操作,
/// 则随后另行删除有名临时文件,该删除操作
/// 也可能独立失败。其结果存储在 `delete_err` 中。
pub fn link(af: *Atomic, io: Io) LinkError!void {
if (af.file_exists) {
if (af.file_open) {
af.file.close(io);
af.file_open = false;
}
const tmp_sub_path = std.fmt.hex(af.file_basename_hex);
try af.dir.renamePreserve(&tmp_sub_path, af.dir, af.dest_sub_path, io);
af.file_exists = false;
} else {
assert(af.file_open);
try af.file.hardLink(io, af.dir, af.dest_sub_path, .{});
af.file.close(io);
af.file_open = false;
}
}
pub const ReplaceError = Dir.RenameError;
/// 以原子方式将文件实体化到目标位置,替换该位置已有的任意文件。
///
/// 调用此函数要求将 `CreateFileAtomicOptions.replace` 设为 `true`。
///
/// Windows 上,此函数会引入一段时间,在此期间,对目标文件的某些文件系统操作会返回 `error.AccessDenied`,包括本函数使用的重命名操作。
///
///
///
///
///
pub fn replace(af: *Atomic, io: Io) ReplaceError!void {
assert(af.file_exists); // `CreateFileAtomicOptions.replace` 的值错误。
if (af.file_open) {
af.file.close(io);
af.file_open = false;
}
const tmp_sub_path = std.fmt.hex(af.file_basename_hex);
try af.dir.rename(&tmp_sub_path, af.dir, af.dest_sub_path, io);
af.file_exists = false;
}