跳转到内容

std.Io.File.Atomic

标准库Zig 0.17.1官方原文
源码std/Io/File/Atomic.zig

第 1 行

字段

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

别名

第 7 行

别名目标 std.debug.assert

std.Io.File.Atomic.Atomic

别名

第 1 行

别名目标 std.Io.File.Atomic

std.Io.File.Atomic.deinit

函数

第 23 行

要释放所有资源,即使 finish 成功后也必须始终 调用 deinit。

pub fn deinit(af: *Atomic, io: Io) void

参数

af: *Atomic
io: Io

std.Io.File.Atomic.Dir

别名

第 6 行

别名目标 std.Io.Dir

std.Io.File.Atomic.File

别名

第 5 行

别名目标 std.Io.File

std.Io.File.Atomic.InitError

别名

第 19 行

别名目标 std.Io.File.OpenError

std.Io.File.Atomic.Io

别名

第 4 行

别名目标 std.Io

std.Io.File.Atomic.link

函数

第 48 行

以原子方式将文件放置到目标位置;若该处已有内容, 则以 error.PathAlreadyExists 失败。

如果无法使用无名临时文件完成此操作, 则随后另行删除有名临时文件,该删除操作 也可能独立失败。其结果存储在 delete_err 中。

pub fn link(af: *Atomic, io: Io) LinkError!void

参数

af: *Atomic
io: Io

错误

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

错误集合

第 40 行

错误

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

函数

第 77 行

以原子方式将文件实体化到目标位置,替换该位置已有的任意文件。

调用此函数要求将 CreateFileAtomicOptions.replace 设为 true。

Windows 上,此函数会引入一段时间,在此期间,对目标文件的某些文件系统操作会返回 error.AccessDenied,包括本函数使用的重命名操作。

pub fn replace(af: *Atomic, io: Io) ReplaceError!void

参数

af: *Atomic
io: Io

错误

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

别名

第 65 行

别名目标 std.Io.Dir.RenameError

std.Io.File.Atomic.std

别名

第 3 行

别名目标 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;
}