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
Alias of std.debug.assert
std.Io.File.Atomic.Atomic
alias
Alias of std.Io.File.Atomic
std.Io.File.Atomic.deinit
function
To release all resources, always call deinit, even after a successful
finish.
pub fn deinit(af: *Atomic, io: Io) void
Parameters
std.Io.File.Atomic.Dir
alias
Alias of std.Io.Dir
std.Io.File.Atomic.File
alias
Alias of std.Io.File
std.Io.File.Atomic.InitError
alias
Alias of std.Io.File.OpenError
std.Io.File.Atomic.Io
alias
Alias of std.Io
std.Io.File.Atomic.link
function
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
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,
\\serveror\\server\sharewas 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
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,
\\serveror\\server\sharewas 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
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
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,
\\serveror\\server\sharewas 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
Alias of std.Io.Dir.RenameError
std.Io.File.Atomic.std
alias
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;
}