Skip to content
Standard libraryZig 0.17.1Official documentation
Sourcestd/Io/File/Atomic.zig

Source line 1

Fields

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

alias

Source line 7

Alias of std.debug.assert

std.Io.File.Atomic.Atomic

alias

Source line 1

Alias of std.Io.File.Atomic

std.Io.File.Atomic.deinit

function

Source line 23

To release all resources, always call deinit, even after a successful finish.

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

Parameters

af: *Atomic
io: Io

std.Io.File.Atomic.Dir

alias

Source line 6

Alias of std.Io.Dir

std.Io.File.Atomic.File

alias

Source line 5

Alias of std.Io.File

std.Io.File.Atomic.InitError

alias

Source line 19

Alias of std.Io.File.OpenError

std.Io.File.Atomic.Io

alias

Source line 4

Alias of std.Io

std.Io.File.Atomic.link

function

Source line 48

Atomically materializes the file into place, failing with error.PathAlreadyExists if something already exists there.

If this operation could not be done with an unnamed temporary file, the named temporary file will be deleted in a following operation, which may independently fail. The result of that operation is stored in delete_err.

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

Parameters

af: *Atomic
io: Io

Errors

AccessDenied RenamePreserveError

In WASI, this error may occur when the file descriptor does not hold the required rights to rename a resource by path relative to it.

On Windows, this error may be returned instead of PathAlreadyExists when renaming a directory over an existing directory.

On Darwin, this error may be returned when a component of either pathname refers to a "dataless" directory that requires materialization, and the I/O policy of the current thread or process disallows dataless directory materialization.

AntivirusInterference RenameError

On Windows, antivirus software is enabled by default. It can be disabled, but Windows Update sometimes ignores the user's preference and re-enables it. When enabled, antivirus software on Windows intercepts file system operations and makes them significantly slower in addition to possibly failing with this error code.

BadPathName PathNameError

File system cannot encode the requested file name bytes. Could be due to invalid WTF-8 on Windows, invalid UTF-8 on WASI, invalid characters on Windows, etc. Filesystem and operating specific.

Canceled Cancelable

Caller has requested the async operation to stop.

CrossDevice HardLinkError
DirNotEmpty RenameError

Attempted to replace a nonempty directory.

DiskQuota HardLinkError
FileBusy RenameError

The file attempted to be moved or replaced is a running executable.

FileNotFound HardLinkError
HardwareFailure HardLinkError
IsDir RenameError
LinkQuotaExceeded HardLinkError
NameTooLong PathNameError

Returned when an insufficient buffer is provided that cannot fit the path name.

NetworkNotFound RenameError

On Windows, \\server or \\server\share was not found.

NoDevice RenameError
NoSpaceLeft HardLinkError
NotDir HardLinkError
OperationUnsupported HardLinkError

Either the OS or the filesystem does not support hard links.

PathAlreadyExists HardLinkError
PermissionDenied HardLinkError
PipeBusy RenameError
ReadOnlyFileSystem HardLinkError
SymLinkLoop HardLinkError
SystemResources HardLinkError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.File.Atomic.LinkError

error-set

Source line 40

Errors

AccessDenied RenamePreserveError

In WASI, this error may occur when the file descriptor does not hold the required rights to rename a resource by path relative to it.

On Windows, this error may be returned instead of PathAlreadyExists when renaming a directory over an existing directory.

On Darwin, this error may be returned when a component of either pathname refers to a "dataless" directory that requires materialization, and the I/O policy of the current thread or process disallows dataless directory materialization.

AntivirusInterference RenameError

On Windows, antivirus software is enabled by default. It can be disabled, but Windows Update sometimes ignores the user's preference and re-enables it. When enabled, antivirus software on Windows intercepts file system operations and makes them significantly slower in addition to possibly failing with this error code.

BadPathName PathNameError

File system cannot encode the requested file name bytes. Could be due to invalid WTF-8 on Windows, invalid UTF-8 on WASI, invalid characters on Windows, etc. Filesystem and operating specific.

Canceled Cancelable

Caller has requested the async operation to stop.

CrossDevice HardLinkError
DirNotEmpty RenameError

Attempted to replace a nonempty directory.

DiskQuota HardLinkError
FileBusy RenameError

The file attempted to be moved or replaced is a running executable.

FileNotFound HardLinkError
HardwareFailure HardLinkError
IsDir RenameError
LinkQuotaExceeded HardLinkError
NameTooLong PathNameError

Returned when an insufficient buffer is provided that cannot fit the path name.

NetworkNotFound RenameError

On Windows, \\server or \\server\share was not found.

NoDevice RenameError
NoSpaceLeft HardLinkError
NotDir HardLinkError
OperationUnsupported HardLinkError

Either the OS or the filesystem does not support hard links.

PathAlreadyExists HardLinkError
PermissionDenied HardLinkError
PipeBusy RenameError
ReadOnlyFileSystem HardLinkError
SymLinkLoop HardLinkError
SystemResources HardLinkError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.File.Atomic.replace

function

Source line 77

Atomically materializes the file into place, replacing any file that already exists there.

Calling this function requires setting CreateFileAtomicOptions.replace to true.

On Windows, this function introduces a period of time where some file system operations on the destination file will result in error.AccessDenied, including rename operations (such as the one used in this function).

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

Parameters

af: *Atomic
io: Io

Errors

AccessDenied RenameError

In WASI, this error may occur when the file descriptor does not hold the required rights to rename a resource by path relative to it.

AntivirusInterference RenameError

On Windows, antivirus software is enabled by default. It can be disabled, but Windows Update sometimes ignores the user's preference and re-enables it. When enabled, antivirus software on Windows intercepts file system operations and makes them significantly slower in addition to possibly failing with this error code.

BadPathName PathNameError

File system cannot encode the requested file name bytes. Could be due to invalid WTF-8 on Windows, invalid UTF-8 on WASI, invalid characters on Windows, etc. Filesystem and operating specific.

Canceled Cancelable

Caller has requested the async operation to stop.

CrossDevice RenameError
DirNotEmpty RenameError

Attempted to replace a nonempty directory.

DiskQuota RenameError
FileBusy RenameError

The file attempted to be moved or replaced is a running executable.

FileNotFound RenameError
HardwareFailure RenameError
IsDir RenameError
LinkQuotaExceeded RenameError
NameTooLong PathNameError

Returned when an insufficient buffer is provided that cannot fit the path name.

NetworkNotFound RenameError

On Windows, \\server or \\server\share was not found.

NoDevice RenameError
NoSpaceLeft RenameError
NotDir RenameError
PermissionDenied RenameError
PipeBusy RenameError
ReadOnlyFileSystem RenameError
SymLinkLoop RenameError
SystemResources RenameError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.File.Atomic.ReplaceError

alias

Source line 65

Alias of std.Io.Dir.RenameError

std.Io.File.Atomic.std

alias

Source line 3

Alias of std

Source code

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;

/// To release all resources, always call `deinit`, even after a successful
/// `finish`.
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;

/// Atomically materializes the file into place, failing with
/// `error.PathAlreadyExists` if something already exists there.
///
/// If this operation could not be done with an unnamed temporary file, the
/// named temporary file will be deleted in a following operation, which may
/// independently fail. The result of that operation is stored in `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;

/// Atomically materializes the file into place, replacing any file that
/// already exists there.
///
/// Calling this function requires setting `CreateFileAtomicOptions.replace` to
/// `true`.
///
/// On Windows, this function introduces a period of time where some file
/// system operations on the destination file will result in
/// `error.AccessDenied`, including rename operations (such as the one used in
/// this function).
pub fn replace(af: *Atomic, io: Io) ReplaceError!void {
    assert(af.file_exists); // Wrong value for `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;
}