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

Source line 1

Fields

handle: Handle
flags: Flags

std.Io.File.assert

alias

Source line 9

Alias of std.debug.assert

std.Io.File.Atomic

alias

Source line 30

Alias of std.Io.File.Atomic

std.Io.File.BlockSize

type

Source line 41

std.Io.File.builtin

constant

Source line 3

std.Io.File.close

function

Source line 212

pub fn close(file: File, io: Io) void

Parameters

file: File
io: Io

std.Io.File.closeMany

function

Source line 216

pub fn closeMany(io: Io, files: []const File) void

Parameters

io: Io
files: []const File

std.Io.File.createMemoryMap

function

Source line 745

pub fn createMemoryMap(file: File, io: Io, options: MemoryMap.CreateOptions) MemoryMap.CreateError!MemoryMap

Parameters

file: File
io: Io
options: MemoryMap.CreateOptions

Errors

AccessDenied

One of the following:

  • The File.Kind is not file.
  • The file is not open for reading and read access protections enabled.
  • The file is not open for writing and write access protections enabled.
Canceled Cancelable

Caller has requested the async operation to stop.

InputOutput ReadPositionalError
IsDir ReadPositionalError

Trying to read a directory file descriptor as if it were a file.

LockViolation ReadPositionalError

Unable to read file due to lock. Depending on the Io implementation, reading from a locked file may return this error, or may ignore the lock.

LockedMemoryLimitExceeded
NotOpenForReading ReadPositionalError

File was not opened with read capability.

OutOfMemory Error
PermissionDenied

The prot argument asks for PROT_EXEC but the mapped area belongs to a file on a filesystem that was mounted no-exec.

ProcessFdQuotaExceeded
SystemFdQuotaExceeded
SystemResources ReadPositionalError
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.

Unseekable ReadPositionalError

This file cannot be read positionally.

WouldBlock ReadPositionalError

Non-blocking has been enabled, and reading from the file descriptor would block.

std.Io.File.Dir

alias

Source line 10

Alias of std.Io.Dir

std.Io.File.downgradeLock

function

Source line 660

Assumes the file is already locked in exclusive mode. Atomically modifies the lock to be in shared mode, without releasing it.

pub fn downgradeLock(file: File, io: Io) LockError!void

Parameters

file: File
io: Io

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

FileLocksUnsupported
SystemResources
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.DowngradeLockError

error-set

Source line 656

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

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.enableAnsiEscapeCodes

function

Source line 249

pub fn enableAnsiEscapeCodes(file: File, io: Io) EnableAnsiEscapeCodesError!void

Parameters

file: File
io: Io

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

NotTerminalDevice
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.EnableAnsiEscapeCodesError

error-set

Source line 245

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

NotTerminalDevice
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.File

alias

Source line 1

Alias of std.Io.File

std.Io.File.Flags

container

Source line 15

Fields

nonblocking: bool
  • true:
    • windows: opened with MODE.IO.ASYNCHRONOUS
    • POSIX: O_NONBLOCK is set
  • false:
    • windows: opened with SYNCHRONOUS_ALERT or SYNCHRONOUS_NONALERT, or not a file.
    • POSIX: O_NONBLOCK is unset

std.Io.File.Gid

alias

Source line 40

Alias of std.posix.gid_t

std.Io.File.Handle

alias

Source line 26

Alias of std.posix.fd_t

std.Io.File.hardLink

function

Source line 735

pub fn hardLink( file: File, io: Io, new_dir: Dir, new_sub_path: []const u8, options: HardLinkOptions, ) HardLinkError!void

Parameters

file: File
io: Io
new_dir: Dir
new_sub_path: []const u8
options: HardLinkOptions

Errors

AccessDenied
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
DiskQuota
FileNotFound
HardwareFailure
LinkQuotaExceeded
NameTooLong PathNameError

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

NoSpaceLeft
NotDir
OperationUnsupported

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

PathAlreadyExists
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
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.HardLinkError

error-set

Source line 717

Errors

AccessDenied
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
DiskQuota
FileNotFound
HardwareFailure
LinkQuotaExceeded
NameTooLong PathNameError

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

NoSpaceLeft
NotDir
OperationUnsupported

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

PathAlreadyExists
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
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.HardLinkOptions

container

Source line 713

Fields

follow_symlinks: bool = false

std.Io.File.INode

alias

Source line 37

Alias of std.posix.ino_t

std.Io.File.Io

alias

Source line 8

Alias of std.Io

std.Io.File.is_windows

constant

Source line 5

std.Io.File.isTty

function

Source line 241

Test whether the file refers to a terminal (similar to libc "isatty").

See also:

pub fn isTty(file: File, io: Io) Io.Cancelable!bool

Parameters

file: File
io: Io

Errors

Canceled

Caller has requested the async operation to stop.

std.Io.File.Kind

container

Source line 43

Fields

block_device
character_device
directory
named_pipe
sym_link
file
unix_domain_socket
whiteout
door
event_port
unknown

std.Io.File.length

function

Source line 286

Retrieve the ending byte index of the file.

Sometimes cheaper than stat if only the length is needed.

pub fn length(file: File, io: Io) LengthError!u64

Parameters

file: File
io: Io

Errors

AccessDenied StatError

In WASI, this error may occur when the file descriptor does not hold the required rights to get its filestat information.

Canceled Cancelable

Caller has requested the async operation to stop.

PermissionDenied StatError
Streaming StatError

Attempted to stat a non-file stream.

SystemResources StatError
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.LengthError

alias

Source line 281

Alias of std.Io.File.StatError

std.Io.File.lock

function

Source line 637

Blocks when an incompatible lock is held by another process. A process may hold only one type of lock (shared or exclusive) on a file. When a process terminates in any way, the lock is released.

Assumes the file is unlocked.

pub fn lock(file: File, io: Io, l: Lock) LockError!void

Parameters

file: File
io: Io
l: Lock

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

FileLocksUnsupported
SystemResources
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.Lock

container

Source line 145

Fields

none
shared
exclusive

std.Io.File.LockError

error-set

Source line 627

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

FileLocksUnsupported
SystemResources
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.MemoryMap

alias

Source line 32

Memory intended to remain consistent with file contents.

Alias of std.Io.File.MemoryMap

std.Io.File.MultiReader

alias

Source line 35

Concurrently read from multiple file streams, eliminating risk of deadlocking.

Alias of std.Io.File.MultiReader

std.Io.File.native_os

constant

Source line 4

std.Io.File.NLink

alias

Source line 38

Alias of std.posix.nlink_t

std.Io.File.OpenError

error-set

Source line 151

Errors

AccessDenied

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

AntivirusInterference

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.

DeviceBusy
FileBusy

One of these three things:

  • pathname refers to an executable image which is currently being executed and write access was requested.
  • pathname refers to a file that is currently in use as a swap file, and the O_TRUNC flag was specified.
  • pathname refers to a file that is currently being read by the kernel (e.g., for module/firmware loading), and write access was requested.
FileLocksUnsupported
FileNotFound

Either:

  • One of the path components does not exist.
  • Cwd was used, but cwd has been deleted.
  • The path associated with the open directory handle has been deleted.
  • On macOS, multiple processes or threads raced to create the same file with O.EXCL set to false.
FileTooBig

The file is too large to be opened. This error is unreachable for 64-bit targets, as well as when opening directories.

IsDir

Either:

  • The path refers to a directory and write permissions were requested.
  • The path refers to a directory and allow_directory was set to false.
NameTooLong PathNameError

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

NetworkNotFound

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

NoDevice
NoSpaceLeft

A new path cannot be created because the device has no room for the new file. This error is only reachable when the CREAT flag is provided.

NotDir

A component used as a directory in the path was not, in fact, a directory, or DIRECTORY was specified and the path was not a directory.

PathAlreadyExists

The path already exists and the CREAT and EXCL flags were provided.

PermissionDenied
PipeBusy
ProcessFdQuotaExceeded
ReadOnlyFileSystem
SymLinkLoop
SystemFdQuotaExceeded
SystemResources

The path exceeded max_path_bytes bytes. Insufficient kernel memory was available, or the named file is a FIFO and per-user hard limit on memory allocation for pipes has been reached.

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.

WouldBlock

Non-blocking was requested and the operation cannot return immediately.

std.Io.File.Permissions

constant

Source line 332

Cross-platform representation of permissions on a file.

On POSIX systems this corresponds to "mode" and on Windows this corresponds to "attributes".

std.Io.File.Permissions.default_dir

constant

Source line 336

@This()

std.Io.File.Permissions.default_dir

constant

Source line 399

@This()

std.Io.File.Permissions.executable_file

constant

Source line 337

@This()

std.Io.File.Permissions.executable_file

constant

Source line 375

@This()

std.Io.File.Permissions.executable_file

constant

Source line 400

@This()

std.Io.File.Permissions.fromMode

function

Source line 381

pub fn fromMode(mode: std.posix.mode_t) @This()

Parameters

mode: std.posix.mode_t

std.Io.File.Permissions.has_executable_bit

primitive

Source line 338

std.Io.File.Permissions.has_executable_bit

constant

Source line 373

std.Io.File.Permissions.has_executable_bit

primitive

Source line 401

std.Io.File.Permissions.readOnly

function

Source line 346

pub fn readOnly(self: @This()) bool

Parameters

self: @This()

std.Io.File.Permissions.readOnly

function

Source line 386

Returns true if and only if no class has write permissions.

pub fn readOnly(self: @This()) bool

Parameters

self: @This()

std.Io.File.Permissions.setReadOnly

function

Source line 351

pub fn setReadOnly(self: @This(), read_only: bool) @This()

Parameters

self: @This()
read_only: bool

std.Io.File.Permissions.setReadOnly

function

Source line 392

Enables write permission for all classes.

pub fn setReadOnly(self: @This(), read_only: bool) @This()

Parameters

self: @This()
read_only: bool

std.Io.File.Permissions.toAttributes

function

Source line 342

pub fn toAttributes(self: @This()) windows.FILE.ATTRIBUTE

Parameters

self: @This()

std.Io.File.Permissions.toMode

function

Source line 377

pub fn toMode(self: @This()) std.posix.mode_t

Parameters

self: @This()

std.Io.File.Permissions.windows

alias

Source line 340

Alias of std.os.windows

std.Io.File.reader

function

Source line 563

Defaults to positional reading; falls back to streaming.

Positional is more threadsafe, since the global seek position is not affected.

See also:

pub fn reader(file: File, io: Io, buffer: []u8) Reader

Parameters

file: File
io: Io
buffer: []u8

std.Io.File.Reader

alias

Source line 28

Alias of std.Io.File.Reader

std.Io.File.readerStreaming

function

Source line 589

Positional is more threadsafe, since the global seek position is not affected, but when such syscalls are not available, preemptively initializing in streaming mode skips a failed syscall.

See also:

pub fn readerStreaming(file: File, io: Io, buffer: []u8) Reader

Parameters

file: File
io: Io
buffer: []u8

std.Io.File.readPositional

function

Source line 503

Returns 0 on stream end or if buffer has no space available for data.

See also:

pub fn readPositional(file: File, io: Io, buffer: []const []u8, offset: u64) ReadPositionalError!usize

Parameters

file: File
io: Io
buffer: []const []u8
offset: u64

Errors

AccessDenied

In WASI, this error occurs when the file descriptor does not hold the required rights to read from it.

Canceled Cancelable

Caller has requested the async operation to stop.

InputOutput
IsDir

Trying to read a directory file descriptor as if it were a file.

LockViolation

Unable to read file due to lock. Depending on the Io implementation, reading from a locked file may return this error, or may ignore the lock.

NotOpenForReading

File was not opened with read capability.

SystemResources
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.

Unseekable

This file cannot be read positionally.

WouldBlock

Non-blocking has been enabled, and reading from the file descriptor would block.

std.Io.File.readPositionalAll

function

Source line 573

Equivalent to creating a positional reader and reading multiple times to fill buffer.

Returns number of bytes read into buffer. If less than buffer.len, end of file occurred.

See also:

pub fn readPositionalAll(file: File, io: Io, buffer: []u8, offset: u64) ReadPositionalError!usize

Parameters

file: File
io: Io
buffer: []u8
offset: u64

Errors

AccessDenied

In WASI, this error occurs when the file descriptor does not hold the required rights to read from it.

Canceled Cancelable

Caller has requested the async operation to stop.

InputOutput
IsDir

Trying to read a directory file descriptor as if it were a file.

LockViolation

Unable to read file due to lock. Depending on the Io implementation, reading from a locked file may return this error, or may ignore the lock.

NotOpenForReading

File was not opened with read capability.

SystemResources
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.

Unseekable

This file cannot be read positionally.

WouldBlock

Non-blocking has been enabled, and reading from the file descriptor would block.

std.Io.File.ReadPositionalError

error-set

Source line 478

Errors

AccessDenied

In WASI, this error occurs when the file descriptor does not hold the required rights to read from it.

Canceled Cancelable

Caller has requested the async operation to stop.

InputOutput
IsDir

Trying to read a directory file descriptor as if it were a file.

LockViolation

Unable to read file due to lock. Depending on the Io implementation, reading from a locked file may return this error, or may ignore the lock.

NotOpenForReading

File was not opened with read capability.

SystemResources
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.

Unseekable

This file cannot be read positionally.

WouldBlock

Non-blocking has been enabled, and reading from the file descriptor would block.

std.Io.File.readStreaming

function

Source line 471

May return fewer bytes than buffer space available, including 0. End-of-stream is indicated by error.EndOfStream.

See also:

pub fn readStreaming(file: File, io: Io, buffer: []const []u8) ReadStreamingError!usize

Parameters

file: File
io: Io
buffer: []const []u8

Errors

AccessDenied UnendingError

In WASI, this error occurs when the file descriptor does not hold the required rights to read from it.

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionResetByPeer UnendingError
EndOfStream
InputOutput UnendingError
IsDir UnendingError

Trying to read a directory file descriptor as if it were a file.

LockViolation UnendingError

Unable to read file due to lock. Depending on the Io implementation, reading from a locked file may return this error, or may ignore the lock.

NotOpenForReading UnendingError

File was not opened with read capability.

SocketUnconnected UnendingError
SystemResources UnendingError
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.

WouldBlock UnendingError

Non-blocking has been enabled, and reading from the file descriptor would block.

std.Io.File.ReadStreamingError

error-set

Source line 464

Errors

AccessDenied UnendingError

In WASI, this error occurs when the file descriptor does not hold the required rights to read from it.

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionResetByPeer UnendingError
EndOfStream
InputOutput UnendingError
IsDir UnendingError

Trying to read a directory file descriptor as if it were a file.

LockViolation UnendingError

Unable to read file due to lock. Depending on the Io implementation, reading from a locked file may return this error, or may ignore the lock.

NotOpenForReading UnendingError

File was not opened with read capability.

SocketUnconnected UnendingError
SystemResources UnendingError
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.

WouldBlock UnendingError

Non-blocking has been enabled, and reading from the file descriptor would block.

std.Io.File.realPath

function

Source line 709

Obtains the canonicalized absolute path name corresponding to an open file handle.

This function has limited platform support, and using it can lead to unnecessary failures and race conditions. It is generally advisable to avoid this function entirely.

pub fn realPath(file: File, io: Io, out_buffer: []u8) RealPathError!usize

Parameters

file: File
io: Io
out_buffer: []u8

Errors

AccessDenied
AntivirusInterference

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.

Canceled Cancelable

Caller has requested the async operation to stop.

DeviceBusy
FileBusy
FileNotFound
FileSystem
FileTooBig
InputOutput
IsDir
NameTooLong

The full file system path could not fit into the provided buffer, or due to its length could not be obtained via realpath functions no matter the buffer size provided.

NetworkNotFound

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

NoDevice
NoSpaceLeft
NotDir
OperationUnsupported

This operating system, file system, or Io implementation does not support realpath operations.

PathAlreadyExists
PermissionDenied
PipeBusy
ProcessFdQuotaExceeded
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
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.

UnrecognizedVolume

On Windows, the volume does not contain a recognized file system. File system drivers might not be loaded, or the volume may be corrupt.

std.Io.File.RealPathError

error-set

Source line 664

Errors

AccessDenied
AntivirusInterference

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.

Canceled Cancelable

Caller has requested the async operation to stop.

DeviceBusy
FileBusy
FileNotFound
FileSystem
FileTooBig
InputOutput
IsDir
NameTooLong

The full file system path could not fit into the provided buffer, or due to its length could not be obtained via realpath functions no matter the buffer size provided.

NetworkNotFound

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

NoDevice
NoSpaceLeft
NotDir
OperationUnsupported

This operating system, file system, or Io implementation does not support realpath operations.

PathAlreadyExists
PermissionDenied
PipeBusy
ProcessFdQuotaExceeded
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
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.

UnrecognizedVolume

On Windows, the volume does not contain a recognized file system. File system drivers might not be loaded, or the volume may be corrupt.

std.Io.File.SeekError

error-set

Source line 548

Errors

AccessDenied

The file descriptor does not hold the required rights to seek on it.

Canceled Cancelable

Caller has requested the async operation to stop.

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.

Unseekable

std.Io.File.setLength

function

Source line 277

Truncates or expands the file, populating any new data with zeroes.

The file offset after this call is left unchanged.

This function operates on an open file handle. There is not an equivalent function in Dir which operates on paths because generally, such functionality will introduce Time-Of-Check, Time-Of-Use (TOCTOU) bugs. In the rare case when those semantics are actually needed, it is reasonable to open the file with the truncate flag.

pub fn setLength(file: File, io: Io, new_length: u64) SetLengthError!void

Parameters

file: File
io: Io
new_length: u64

Errors

AccessDenied
Canceled Cancelable

Caller has requested the async operation to stop.

FileBusy
FileTooBig
InputOutput
NonResizable
PermissionDenied
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.SetLengthError

error-set

Source line 259

Errors

AccessDenied
Canceled Cancelable

Caller has requested the async operation to stop.

FileBusy
FileTooBig
InputOutput
NonResizable
PermissionDenied
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.setOwner

function

Source line 325

Also known as "chown".

The process must have the correct privileges in order to do this successfully. The group may be changed by the owner of the file to any group of which the owner is a member. If the owner or group is specified as null, the ID is not changed.

pub fn setOwner(file: File, io: Io, owner: ?Uid, group: ?Gid) SetOwnerError!void

Parameters

file: File
io: Io
owner: ?Uid
group: ?Gid

Errors

AccessDenied
Canceled Cancelable

Caller has requested the async operation to stop.

FileNotFound
InputOutput
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
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.SetOwnerError

error-set

Source line 309

Errors

AccessDenied
Canceled Cancelable

Caller has requested the async operation to stop.

FileNotFound
InputOutput
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
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.setPermissions

function

Source line 305

Also known as "chmod".

The process must have the correct privileges in order to do this successfully, or must have the effective user ID matching the owner of the file.

pub fn setPermissions(file: File, io: Io, new_permissions: Permissions) SetPermissionsError!void

Parameters

file: File
io: Io
new_permissions: Permissions

Errors

AccessDenied
Canceled Cancelable

Caller has requested the async operation to stop.

FileNotFound
InputOutput
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
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.SetPermissionsError

error-set

Source line 290

Errors

AccessDenied
Canceled Cancelable

Caller has requested the async operation to stop.

FileNotFound
InputOutput
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
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.SetTimestamp

container

Source line 431

Fields

unchanged

Leave the existing timestamp unmodified.

now

Set to current time using Io.Clock.real.

new: Io.Timestamp

Set to provided timestamp using Io.Clock.real.

std.Io.File.SetTimestamp.init

function

Source line 440

Convenience for interacting with Stat, in which null indicates unchanged.

pub fn init(optional: ?Io.Timestamp) SetTimestamp

Parameters

optional: ?Io.Timestamp

std.Io.File.setTimestamps

function

Source line 448

The granularity that ultimately is stored depends on the combination of operating system and file system. When a value as provided that exceeds this range, the value is clamped to the maximum.

pub fn setTimestamps(file: File, io: Io, options: SetTimestampsOptions) SetTimestampsError!void

Parameters

file: File
io: Io
options: SetTimestampsOptions

Errors

AccessDenied

times is NULL, or both nsec values are UTIME_NOW, and either:

  • the effective user ID of the caller does not match the owner of the file, the caller does not have write access to the file, and the caller is not privileged (Linux: does not have either the CAP_FOWNER or the CAP_DAC_OVERRIDE capability); or,
  • the file is marked immutable (see chattr(1)).
Canceled Cancelable

Caller has requested the async operation to stop.

PermissionDenied

The caller attempted to change one or both timestamps to a value other than the current time, or to change one of the timestamps to the current time while leaving the other timestamp unchanged, (i.e., times is not NULL, neither nsec field is UTIME_NOW, and neither nsec field is UTIME_OMIT) and either:

  • the caller's effective user ID does not match the owner of file, and the caller is not privileged (Linux: does not have the CAP_FOWNER capability); or,
  • the file is marked append-only or immutable (see chattr(1)).
ReadOnlyFileSystem
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.SetTimestampsError

error-set

Source line 404

Errors

AccessDenied

times is NULL, or both nsec values are UTIME_NOW, and either:

  • the effective user ID of the caller does not match the owner of the file, the caller does not have write access to the file, and the caller is not privileged (Linux: does not have either the CAP_FOWNER or the CAP_DAC_OVERRIDE capability); or,
  • the file is marked immutable (see chattr(1)).
Canceled Cancelable

Caller has requested the async operation to stop.

PermissionDenied

The caller attempted to change one or both timestamps to a value other than the current time, or to change one of the timestamps to the current time while leaving the other timestamp unchanged, (i.e., times is not NULL, neither nsec field is UTIME_NOW, and neither nsec field is UTIME_OMIT) and either:

  • the caller's effective user ID does not match the owner of file, and the caller is not privileged (Linux: does not have the CAP_FOWNER capability); or,
  • the file is marked append-only or immutable (see chattr(1)).
ReadOnlyFileSystem
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.setTimestampsNow

function

Source line 457

Sets the accessed and modification timestamps of file to the current wall clock time.

The granularity that ultimately is stored depends on the combination of operating system and file system.

pub fn setTimestampsNow(file: File, io: Io) SetTimestampsError!void

Parameters

file: File
io: Io

Errors

AccessDenied

times is NULL, or both nsec values are UTIME_NOW, and either:

  • the effective user ID of the caller does not match the owner of the file, the caller does not have write access to the file, and the caller is not privileged (Linux: does not have either the CAP_FOWNER or the CAP_DAC_OVERRIDE capability); or,
  • the file is marked immutable (see chattr(1)).
Canceled Cancelable

Caller has requested the async operation to stop.

PermissionDenied

The caller attempted to change one or both timestamps to a value other than the current time, or to change one of the timestamps to the current time while leaving the other timestamp unchanged, (i.e., times is not NULL, neither nsec field is UTIME_NOW, and neither nsec field is UTIME_OMIT) and either:

  • the caller's effective user ID does not match the owner of file, and the caller is not privileged (Linux: does not have the CAP_FOWNER capability); or,
  • the file is marked append-only or immutable (see chattr(1)).
ReadOnlyFileSystem
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.SetTimestampsOptions

container

Source line 426

Fields

access_timestamp: SetTimestamp = .unchanged
modify_timestamp: SetTimestamp = .unchanged

std.Io.File.stat

function

Source line 141

Returns Stat containing basic information about the File.

pub fn stat(file: File, io: Io) StatError!Stat

Parameters

file: File
io: Io

Errors

AccessDenied

In WASI, this error may occur when the file descriptor does not hold the required rights to get its filestat information.

Canceled Cancelable

Caller has requested the async operation to stop.

PermissionDenied
Streaming

Attempted to stat a non-file stream.

SystemResources
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.Stat

container

Source line 57

Fields

inode: INode

A number that the system uses to point to the file metadata. This number is not guaranteed to be unique across time, as some file systems may reuse an inode after its file has been deleted. Some systems may change the inode of a file over time.

On Linux, the inode is a structure that stores the metadata, and the inode number is what you see here: the index number of the inode.

The FileIndex on Windows is similar. It is a number for a file that is unique to each filesystem.

nlink: NLink
size: u64
permissions: Permissions
kind: Kind
atime: ?Io.Timestamp

Last access time in nanoseconds, relative to UTC 1970-01-01.

Filesystems generally find this value problematic to keep updated since it turns read-only file system accesses into file system mutations. Some systems report stale values, and some systems explicitly refuse to report this value. The latter case is handled by null.

mtime: Io.Timestamp

Last modification time in nanoseconds, relative to UTC 1970-01-01.

ctime: Io.Timestamp

Last status/metadata change time in nanoseconds, relative to UTC 1970-01-01.

block_size: BlockSize

Smallest chunk length in bytes appropriate for optimal I/O. This will be set to 1 for operating systems or file systems that do not recognize this concept. Not always a power of two.

std.Io.File.StatError

error-set

Source line 130

Errors

AccessDenied

In WASI, this error may occur when the file descriptor does not hold the required rights to get its filestat information.

Canceled Cancelable

Caller has requested the async operation to stop.

PermissionDenied
Streaming

Attempted to stat a non-file stream.

SystemResources
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.std

alias

Source line 7

Alias of std

std.Io.File.stderr

function

Source line 104

pub fn stderr() File

std.Io.File.stdin

function

Source line 117

pub fn stdin() File

std.Io.File.stdout

function

Source line 91

pub fn stdout() File

std.Io.File.supportsAnsiEscapeCodes

function

Source line 255

Test whether ANSI escape codes will be treated as such without attempting to enable support for ANSI escape codes.

pub fn supportsAnsiEscapeCodes(file: File, io: Io) Io.Cancelable!bool

Parameters

file: File
io: Io

Errors

Canceled

Caller has requested the async operation to stop.

std.Io.File.sync

function

Source line 232

Blocks until all pending file contents and metadata modifications for the file have been synchronized with the underlying filesystem.

This does not ensure that metadata for the directory containing the file has also reached disk.

pub fn sync(file: File, io: Io) SyncError!void

Parameters

file: File
io: Io

Errors

AccessDenied
Canceled Cancelable

Caller has requested the async operation to stop.

DiskQuota
InputOutput
NoSpaceLeft
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.SyncError

error-set

Source line 220

Errors

AccessDenied
Canceled Cancelable

Caller has requested the async operation to stop.

DiskQuota
InputOutput
NoSpaceLeft
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.tryLock

function

Source line 652

Attempts to obtain a lock, returning true if the lock is obtained, and false if there was an existing incompatible lock held. A process may hold only one type of lock (shared or exclusive) on a file. When a process terminates in any way, the lock is released.

Assumes the file is unlocked.

pub fn tryLock(file: File, io: Io, l: Lock) LockError!bool

Parameters

file: File
io: Io
l: Lock

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

FileLocksUnsupported
SystemResources
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.Uid

alias

Source line 39

Alias of std.posix.uid_t

std.Io.File.unlock

function

Source line 642

Assumes the file is locked.

pub fn unlock(file: File, io: Io) void

Parameters

file: File
io: Io

std.Io.File.WriteFilePositionalError

error-set

Source line 554

Errors

AccessDenied Error

File descriptor does not hold the required rights to write to it.

BrokenPipe Error

File is an unconnected socket, or closed its read end.

Canceled Cancelable

Caller has requested the async operation to stop.

CorruptedData WriteFileError

Can happen on FreeBSD when using copy_file_range.

DeviceBusy Error
DiskQuota Error
EndOfStream WriteFileError
FileBusy Error
FileTooBig Error
InputOutput Error
LockViolation Error

The process cannot access the file because another process has locked a portion of the file. Windows-only.

NoDevice Error

This error occurs when a device gets disconnected before or mid-flush while it's being written to - errno(6): No such device or address.

NoSpaceLeft Error
NotOpenForWriting Error
PermissionDenied Error
ReadFailed WriteFileError
SystemResources Error

Insufficient kernel memory to read from in_fd.

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.

Unimplemented WriteFileError

Descriptor is not valid or locked, or an mmap(2)-like operation is not available for in_fd.

Unseekable
WouldBlock Error

Non-blocking has been enabled and this operation would block.

std.Io.File.writePositional

function

Source line 537

See also:

pub fn writePositional(file: File, io: Io, buffer: []const []const u8, offset: u64) WritePositionalError!usize

Parameters

file: File
io: Io
buffer: []const []const u8
offset: u64

Errors

AccessDenied

File descriptor does not hold the required rights to write to it.

BrokenPipe

File is an unconnected socket, or closed its read end.

Canceled Cancelable

Caller has requested the async operation to stop.

DeviceBusy
DiskQuota
FileBusy
FileTooBig
InputOutput
LockViolation

The process cannot access the file because another process has locked a portion of the file. Windows-only.

NoDevice

This error occurs when a device gets disconnected before or mid-flush while it's being written to - errno(6): No such device or address.

NoSpaceLeft
NotOpenForWriting

File was not opened with write capability.

PermissionDenied
SystemResources

Insufficient kernel memory to read from in_fd.

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.

Unseekable

This file cannot be written positionally.

WouldBlock

Non-blocking has been enabled and this operation would block.

std.Io.File.writePositionalAll

function

Source line 542

Equivalent to creating a positional writer, writing bytes, and then flushing.

pub fn writePositionalAll(file: File, io: Io, bytes: []const u8, offset: u64) WritePositionalError!void

Parameters

file: File
io: Io
bytes: []const u8
offset: u64

Errors

AccessDenied

File descriptor does not hold the required rights to write to it.

BrokenPipe

File is an unconnected socket, or closed its read end.

Canceled Cancelable

Caller has requested the async operation to stop.

DeviceBusy
DiskQuota
FileBusy
FileTooBig
InputOutput
LockViolation

The process cannot access the file because another process has locked a portion of the file. Windows-only.

NoDevice

This error occurs when a device gets disconnected before or mid-flush while it's being written to - errno(6): No such device or address.

NoSpaceLeft
NotOpenForWriting

File was not opened with write capability.

PermissionDenied
SystemResources

Insufficient kernel memory to read from in_fd.

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.

Unseekable

This file cannot be written positionally.

WouldBlock

Non-blocking has been enabled and this operation would block.

std.Io.File.WritePositionalError

error-set

Source line 507

Errors

AccessDenied

File descriptor does not hold the required rights to write to it.

BrokenPipe

File is an unconnected socket, or closed its read end.

Canceled Cancelable

Caller has requested the async operation to stop.

DeviceBusy
DiskQuota
FileBusy
FileTooBig
InputOutput
LockViolation

The process cannot access the file because another process has locked a portion of the file. Windows-only.

NoDevice

This error occurs when a device gets disconnected before or mid-flush while it's being written to - errno(6): No such device or address.

NoSpaceLeft
NotOpenForWriting

File was not opened with write capability.

PermissionDenied
SystemResources

Insufficient kernel memory to read from in_fd.

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.

Unseekable

This file cannot be written positionally.

WouldBlock

Non-blocking has been enabled and this operation would block.

std.Io.File.writer

function

Source line 597

Defaults to positional reading; falls back to streaming.

Positional is more threadsafe, since the global seek position is not affected.

pub fn writer(file: File, io: Io, buffer: []u8) Writer

Parameters

file: File
io: Io
buffer: []u8

std.Io.File.Writer

alias

Source line 29

Alias of std.Io.File.Writer

std.Io.File.writerStreaming

function

Source line 604

Positional is more threadsafe, since the global seek position is not affected, but when such syscalls are not available, preemptively initializing in streaming mode will skip a failed syscall.

pub fn writerStreaming(file: File, io: Io, buffer: []u8) Writer

Parameters

file: File
io: Io
buffer: []u8

std.Io.File.writeStreaming

function

Source line 610

This is a low-level API that calls the Io interface function directly. For a higher level API, see writerStreaming.

pub fn writeStreaming(file: File, io: Io, header: []const u8, data: []const []const u8, splat: usize) Writer.Error!usize

Parameters

file: File
io: Io
header: []const u8
data: []const []const u8
splat: usize

Errors

AccessDenied Error

File descriptor does not hold the required rights to write to it.

BrokenPipe Error

File is an unconnected socket, or closed its read end.

Canceled Cancelable

Caller has requested the async operation to stop.

DeviceBusy Error
DiskQuota Error
FileBusy Error
FileTooBig Error
InputOutput Error
LockViolation Error

The process cannot access the file because another process has locked a portion of the file. Windows-only.

NoDevice Error

This error occurs when a device gets disconnected before or mid-flush while it's being written to - errno(6): No such device or address.

NoSpaceLeft Error
NotOpenForWriting Error
PermissionDenied Error
SystemResources Error

Insufficient kernel memory to read from in_fd.

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.

WouldBlock Error

Non-blocking has been enabled and this operation would block.

std.Io.File.writeStreamingAll

function

Source line 620

Equivalent to creating a streaming writer, writing bytes, and then flushing.

pub fn writeStreamingAll(file: File, io: Io, bytes: []const u8) Writer.Error!void

Parameters

file: File
io: Io
bytes: []const u8

Errors

AccessDenied Error

File descriptor does not hold the required rights to write to it.

BrokenPipe Error

File is an unconnected socket, or closed its read end.

Canceled Cancelable

Caller has requested the async operation to stop.

DeviceBusy Error
DiskQuota Error
FileBusy Error
FileTooBig Error
InputOutput Error
LockViolation Error

The process cannot access the file because another process has locked a portion of the file. Windows-only.

NoDevice Error

This error occurs when a device gets disconnected before or mid-flush while it's being written to - errno(6): No such device or address.

NoSpaceLeft Error
NotOpenForWriting Error
PermissionDenied Error
SystemResources Error

Insufficient kernel memory to read from in_fd.

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.

WouldBlock Error

Non-blocking has been enabled and this operation would block.

Source code

std/Io/File.zig

const File = @This();

const builtin = @import("builtin");
const native_os = builtin.os.tag;
const is_windows = native_os == .windows;

const std = @import("../std.zig");
const Io = std.Io;
const assert = std.debug.assert;
const Dir = std.Io.Dir;

handle: Handle,
flags: Flags,

pub const Flags = struct {
    /// * true:
    ///   - windows: opened with MODE.IO.ASYNCHRONOUS
    ///   - POSIX: O_NONBLOCK is set
    /// * false:
    ///   - windows: opened with SYNCHRONOUS_ALERT or SYNCHRONOUS_NONALERT, or
    ///     not a file.
    ///   - POSIX: O_NONBLOCK is unset
    nonblocking: bool,
};

pub const Handle = std.posix.fd_t;

pub const Reader = @import("File/Reader.zig");
pub const Writer = @import("File/Writer.zig");
pub const Atomic = @import("File/Atomic.zig");
/// Memory intended to remain consistent with file contents.
pub const MemoryMap = @import("File/MemoryMap.zig");
/// Concurrently read from multiple file streams, eliminating risk of
/// deadlocking.
pub const MultiReader = @import("File/MultiReader.zig");

pub const INode = std.posix.ino_t;
pub const NLink = std.posix.nlink_t;
pub const Uid = std.posix.uid_t;
pub const Gid = std.posix.gid_t;
pub const BlockSize = u32;

pub const Kind = enum {
    block_device,
    character_device,
    directory,
    named_pipe,
    sym_link,
    file,
    unix_domain_socket,
    whiteout,
    door,
    event_port,
    unknown,
};

pub const Stat = struct {
    /// A number that the system uses to point to the file metadata. This
    /// number is not guaranteed to be unique across time, as some file
    /// systems may reuse an inode after its file has been deleted. Some
    /// systems may change the inode of a file over time.
    ///
    /// On Linux, the inode is a structure that stores the metadata, and
    /// the inode _number_ is what you see here: the index number of the
    /// inode.
    ///
    /// The FileIndex on Windows is similar. It is a number for a file that
    /// is unique to each filesystem.
    inode: INode,
    nlink: NLink,
    size: u64,
    permissions: Permissions,
    kind: Kind,
    /// Last access time in nanoseconds, relative to UTC 1970-01-01.
    ///
    /// Filesystems generally find this value problematic to keep updated since
    /// it turns read-only file system accesses into file system mutations.
    /// Some systems report stale values, and some systems explicitly refuse to
    /// report this value. The latter case is handled by `null`.
    atime: ?Io.Timestamp,
    /// Last modification time in nanoseconds, relative to UTC 1970-01-01.
    mtime: Io.Timestamp,
    /// Last status/metadata change time in nanoseconds, relative to UTC 1970-01-01.
    ctime: Io.Timestamp,
    /// Smallest chunk length in bytes appropriate for optimal I/O. This will
    /// be set to `1` for operating systems or file systems that do not
    /// recognize this concept. Not always a power of two.
    block_size: BlockSize,
};

pub fn stdout() File {
    return switch (native_os) {
        .windows => .{
            .handle = std.os.windows.peb().ProcessParameters.hStdOutput,
            .flags = .{ .nonblocking = false },
        },
        else => .{
            .handle = std.posix.STDOUT_FILENO,
            .flags = .{ .nonblocking = false },
        },
    };
}

pub fn stderr() File {
    return switch (native_os) {
        .windows => .{
            .handle = std.os.windows.peb().ProcessParameters.hStdError,
            .flags = .{ .nonblocking = false },
        },
        else => .{
            .handle = std.posix.STDERR_FILENO,
            .flags = .{ .nonblocking = false },
        },
    };
}

pub fn stdin() File {
    return switch (native_os) {
        .windows => .{
            .handle = std.os.windows.peb().ProcessParameters.hStdInput,
            .flags = .{ .nonblocking = false },
        },
        else => .{
            .handle = std.posix.STDIN_FILENO,
            .flags = .{ .nonblocking = false },
        },
    };
}

pub const StatError = error{
    SystemResources,
    /// In WASI, this error may occur when the file descriptor does
    /// not hold the required rights to get its filestat information.
    AccessDenied,
    PermissionDenied,
    /// Attempted to stat a non-file stream.
    Streaming,
} || Io.Cancelable || Io.UnexpectedError;

/// Returns `Stat` containing basic information about the `File`.
pub fn stat(file: File, io: Io) StatError!Stat {
    return io.vtable.fileStat(io.userdata, file);
}

pub const Lock = enum {
    none,
    shared,
    exclusive,
};

pub const OpenError = error{
    PipeBusy,
    NoDevice,
    /// On Windows, `\\server` or `\\server\share` was not found.
    NetworkNotFound,
    /// 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.
    AntivirusInterference,
    /// In WASI, this error may occur when the file descriptor does
    /// not hold the required rights to open a new resource relative to it.
    AccessDenied,
    PermissionDenied,
    SymLinkLoop,
    ProcessFdQuotaExceeded,
    SystemFdQuotaExceeded,
    /// Either:
    /// * One of the path components does not exist.
    /// * Cwd was used, but cwd has been deleted.
    /// * The path associated with the open directory handle has been deleted.
    /// * On macOS, multiple processes or threads raced to create the same file
    ///   with `O.EXCL` set to `false`.
    FileNotFound,
    /// The path exceeded `max_path_bytes` bytes.
    /// Insufficient kernel memory was available, or
    /// the named file is a FIFO and per-user hard limit on
    /// memory allocation for pipes has been reached.
    SystemResources,
    /// The file is too large to be opened. This error is unreachable
    /// for 64-bit targets, as well as when opening directories.
    FileTooBig,
    /// Either:
    /// * The path refers to a directory and write permissions were requested.
    /// * The path refers to a directory and `allow_directory` was set to false.
    IsDir,
    /// A new path cannot be created because the device has no room for the new file.
    /// This error is only reachable when the `CREAT` flag is provided.
    NoSpaceLeft,
    /// A component used as a directory in the path was not, in fact, a directory, or
    /// `DIRECTORY` was specified and the path was not a directory.
    NotDir,
    /// The path already exists and the `CREAT` and `EXCL` flags were provided.
    PathAlreadyExists,
    ReadOnlyFileSystem,
    DeviceBusy,
    FileLocksUnsupported,
    /// One of these three things:
    /// * pathname  refers to an executable image which is currently being
    ///   executed and write access was requested.
    /// * pathname refers to a file that is currently in  use  as  a  swap
    ///   file, and the O_TRUNC flag was specified.
    /// * pathname  refers  to  a file that is currently being read by the
    ///   kernel (e.g., for module/firmware loading), and write access was
    ///   requested.
    FileBusy,
    /// Non-blocking was requested and the operation cannot return immediately.
    WouldBlock,
} || Dir.PathNameError || Io.Cancelable || Io.UnexpectedError;

pub fn close(file: File, io: Io) void {
    return io.vtable.fileClose(io.userdata, (&file)[0..1]);
}

pub fn closeMany(io: Io, files: []const File) void {
    return io.vtable.fileClose(io.userdata, files);
}

pub const SyncError = error{
    InputOutput,
    NoSpaceLeft,
    DiskQuota,
    AccessDenied,
} || Io.Cancelable || Io.UnexpectedError;

/// Blocks until all pending file contents and metadata modifications for the
/// file have been synchronized with the underlying filesystem.
///
/// This does not ensure that metadata for the directory containing the file
/// has also reached disk.
pub fn sync(file: File, io: Io) SyncError!void {
    return io.vtable.fileSync(io.userdata, file);
}

/// Test whether the file refers to a terminal (similar to libc "isatty").
///
/// See also:
/// * `enableAnsiEscapeCodes`
/// * `supportsAnsiEscapeCodes`.
pub fn isTty(file: File, io: Io) Io.Cancelable!bool {
    return io.vtable.fileIsTty(io.userdata, file);
}

pub const EnableAnsiEscapeCodesError = error{
    NotTerminalDevice,
} || Io.Cancelable || Io.UnexpectedError;

pub fn enableAnsiEscapeCodes(file: File, io: Io) EnableAnsiEscapeCodesError!void {
    return io.vtable.fileEnableAnsiEscapeCodes(io.userdata, file);
}

/// Test whether ANSI escape codes will be treated as such without
/// attempting to enable support for ANSI escape codes.
pub fn supportsAnsiEscapeCodes(file: File, io: Io) Io.Cancelable!bool {
    return io.vtable.fileSupportsAnsiEscapeCodes(io.userdata, file);
}

pub const SetLengthError = error{
    FileTooBig,
    InputOutput,
    FileBusy,
    AccessDenied,
    PermissionDenied,
    NonResizable,
} || Io.Cancelable || Io.UnexpectedError;

/// Truncates or expands the file, populating any new data with zeroes.
///
/// The file offset after this call is left unchanged.
///
/// This function operates on an open file handle. There is not an equivalent
/// function in `Dir` which operates on paths because generally, such
/// functionality will introduce Time-Of-Check, Time-Of-Use (TOCTOU) bugs. In
/// the rare case when those semantics are actually needed, it is reasonable to
/// open the file with the truncate flag.
pub fn setLength(file: File, io: Io, new_length: u64) SetLengthError!void {
    return io.vtable.fileSetLength(io.userdata, file, new_length);
}

pub const LengthError = StatError;

/// Retrieve the ending byte index of the file.
///
/// Sometimes cheaper than `stat` if only the length is needed.
pub fn length(file: File, io: Io) LengthError!u64 {
    return io.vtable.fileLength(io.userdata, file);
}

pub const SetPermissionsError = error{
    AccessDenied,
    PermissionDenied,
    InputOutput,
    SymLinkLoop,
    FileNotFound,
    SystemResources,
    ReadOnlyFileSystem,
} || Io.Cancelable || Io.UnexpectedError;

/// Also known as "chmod".
///
/// The process must have the correct privileges in order to do this
/// successfully, or must have the effective user ID matching the owner of the
/// file.
pub fn setPermissions(file: File, io: Io, new_permissions: Permissions) SetPermissionsError!void {
    return io.vtable.fileSetPermissions(io.userdata, file, new_permissions);
}

pub const SetOwnerError = error{
    AccessDenied,
    PermissionDenied,
    InputOutput,
    SymLinkLoop,
    FileNotFound,
    SystemResources,
    ReadOnlyFileSystem,
} || Io.Cancelable || Io.UnexpectedError;

/// Also known as "chown".
///
/// The process must have the correct privileges in order to do this
/// successfully. The group may be changed by the owner of the file to any
/// group of which the owner is a member. If the owner or group is specified as
/// `null`, the ID is not changed.
pub fn setOwner(file: File, io: Io, owner: ?Uid, group: ?Gid) SetOwnerError!void {
    return io.vtable.fileSetOwner(io.userdata, file, owner, group);
}

/// Cross-platform representation of permissions on a file.
///
/// On POSIX systems this corresponds to "mode" and on Windows this corresponds to "attributes".
pub const Permissions = std.Options.FilePermissions orelse if (is_windows) enum(std.os.windows.DWORD) {
    default_file = 0,
    _,

    pub const default_dir: @This() = .default_file;
    pub const executable_file: @This() = .default_file;
    pub const has_executable_bit = false;

    const windows = std.os.windows;

    pub fn toAttributes(self: @This()) windows.FILE.ATTRIBUTE {
        return @bitCast(@backingInt(self));
    }

    pub fn readOnly(self: @This()) bool {
        const attributes = toAttributes(self);
        return attributes & windows.FILE_ATTRIBUTE_READONLY != 0;
    }

    pub fn setReadOnly(self: @This(), read_only: bool) @This() {
        const attributes = toAttributes(self);
        return @fromBackingInt(@intCast(if (read_only)
            attributes | windows.FILE_ATTRIBUTE_READONLY
        else
            attributes & ~@as(windows.DWORD, windows.FILE_ATTRIBUTE_READONLY)));
    }
} else if (std.posix.mode_t != u0) enum(std.posix.mode_t) {
    /// This is the default mode given to POSIX operating systems for creating
    /// files. `0o666` is "-rw-rw-rw-" which is counter-intuitive at first,
    /// since most people would expect "-rw-r--r--", for example, when using
    /// the `touch` command, which would correspond to `0o644`. However, POSIX
    /// libc implementations use `0o666` inside `fopen` and then rely on the
    /// process-scoped "umask" setting to adjust this number for file creation.
    default_file = 0o666,
    /// This is the default mode given to POSIX operating systems for creating
    /// directories. `0o777` is "-rwxrwxrwx" which is counter-intuitive at first,
    /// since most people would expect "-rwxr-xr-x", for example, when using
    /// the `touch` command, which would correspond to `0o755`.
    default_dir = 0o777,
    _,

    pub const has_executable_bit = native_os != .wasi;

    pub const executable_file: @This() = .default_dir;

    pub fn toMode(self: @This()) std.posix.mode_t {
        return @backingInt(self);
    }

    pub fn fromMode(mode: std.posix.mode_t) @This() {
        return @fromBackingInt(@intCast(mode));
    }

    /// Returns `true` if and only if no class has write permissions.
    pub fn readOnly(self: @This()) bool {
        const mode = toMode(self);
        return mode & 0o222 == 0;
    }

    /// Enables write permission for all classes.
    pub fn setReadOnly(self: @This(), read_only: bool) @This() {
        const mode = toMode(self);
        const o222 = @as(std.posix.mode_t, 0o222);
        return @fromBackingInt(@intCast(if (read_only) mode & ~o222 else mode | o222));
    }
} else enum(u0) {
    default_file = 0,
    pub const default_dir: @This() = .default_file;
    pub const executable_file: @This() = .default_file;
    pub const has_executable_bit = false;
};

pub const SetTimestampsError = error{
    /// times is NULL, or both nsec values are UTIME_NOW, and either:
    /// *  the effective user ID of the caller does not match the  owner
    ///    of  the  file,  the  caller does not have write access to the
    ///    file, and the caller is not privileged (Linux: does not  have
    ///    either  the  CAP_FOWNER  or the CAP_DAC_OVERRIDE capability);
    ///    or,
    /// *  the file is marked immutable (see chattr(1)).
    AccessDenied,
    /// The caller attempted to change one or both timestamps to a value
    /// other than the current time, or to change one of the  timestamps
    /// to the current time while leaving the other timestamp unchanged,
    /// (i.e., times is not NULL, neither nsec  field  is  UTIME_NOW,
    /// and neither nsec field is UTIME_OMIT) and either:
    /// *  the  caller's  effective  user ID does not match the owner of
    ///    file, and the caller is not privileged (Linux: does not  have
    ///    the CAP_FOWNER capability); or,
    /// *  the file is marked append-only or immutable (see chattr(1)).
    PermissionDenied,
    ReadOnlyFileSystem,
} || Io.Cancelable || Io.UnexpectedError;

pub const SetTimestampsOptions = struct {
    access_timestamp: SetTimestamp = .unchanged,
    modify_timestamp: SetTimestamp = .unchanged,
};

pub const SetTimestamp = union(enum) {
    /// Leave the existing timestamp unmodified.
    unchanged,
    /// Set to current time using `Io.Clock.real`.
    now,
    /// Set to provided timestamp using `Io.Clock.real`.
    new: Io.Timestamp,

    /// Convenience for interacting with `Stat`, in which `null` indicates `unchanged`.
    pub fn init(optional: ?Io.Timestamp) SetTimestamp {
        return if (optional) |t| .{ .new = t } else .unchanged;
    }
};

/// The granularity that ultimately is stored depends on the combination of
/// operating system and file system. When a value as provided that exceeds
/// this range, the value is clamped to the maximum.
pub fn setTimestamps(file: File, io: Io, options: SetTimestampsOptions) SetTimestampsError!void {
    return io.vtable.fileSetTimestamps(io.userdata, file, options);
}

/// Sets the accessed and modification timestamps of `file` to the current wall
/// clock time.
///
/// The granularity that ultimately is stored depends on the combination of
/// operating system and file system.
pub fn setTimestampsNow(file: File, io: Io) SetTimestampsError!void {
    return io.vtable.fileSetTimestamps(io.userdata, file, .{
        .access_timestamp = .now,
        .modify_timestamp = .now,
    });
}

pub const ReadStreamingError = error{EndOfStream} || Reader.Error;

/// May return fewer bytes than buffer space available, including 0.
/// End-of-stream is indicated by `error.EndOfStream`.
///
/// See also:
/// * `reader`
pub fn readStreaming(file: File, io: Io, buffer: []const []u8) ReadStreamingError!usize {
    return (try io.operate(.{ .file_read_streaming = .{
        .file = file,
        .data = buffer,
    } })).file_read_streaming;
}

pub const ReadPositionalError = error{
    InputOutput,
    SystemResources,
    /// Trying to read a directory file descriptor as if it were a file.
    IsDir,
    /// Non-blocking has been enabled, and reading from the file descriptor
    /// would block.
    WouldBlock,
    /// In WASI, this error occurs when the file descriptor does
    /// not hold the required rights to read from it.
    AccessDenied,
    /// Unable to read file due to lock. Depending on the `Io` implementation,
    /// reading from a locked file may return this error, or may ignore the
    /// lock.
    LockViolation,
    /// This file cannot be read positionally.
    Unseekable,
    /// File was not opened with read capability.
    NotOpenForReading,
} || Io.Cancelable || Io.UnexpectedError;

/// Returns 0 on stream end or if `buffer` has no space available for data.
///
/// See also:
/// * `reader`
pub fn readPositional(file: File, io: Io, buffer: []const []u8, offset: u64) ReadPositionalError!usize {
    return io.vtable.fileReadPositional(io.userdata, file, buffer, offset);
}

pub const WritePositionalError = error{
    DiskQuota,
    FileTooBig,
    InputOutput,
    NoSpaceLeft,
    DeviceBusy,
    /// File descriptor does not hold the required rights to write to it.
    AccessDenied,
    PermissionDenied,
    /// File is an unconnected socket, or closed its read end.
    BrokenPipe,
    /// Insufficient kernel memory to read from in_fd.
    SystemResources,
    /// The process cannot access the file because another process has locked
    /// a portion of the file. Windows-only.
    LockViolation,
    /// Non-blocking has been enabled and this operation would block.
    WouldBlock,
    /// This error occurs when a device gets disconnected before or mid-flush
    /// while it's being written to - errno(6): No such device or address.
    NoDevice,
    FileBusy,
    /// This file cannot be written positionally.
    Unseekable,
    /// File was not opened with write capability.
    NotOpenForWriting,
} || Io.Cancelable || Io.UnexpectedError;

/// See also:
/// * `writer`
pub fn writePositional(file: File, io: Io, buffer: []const []const u8, offset: u64) WritePositionalError!usize {
    return io.vtable.fileWritePositional(io.userdata, file, &.{}, buffer, 1, offset);
}

/// Equivalent to creating a positional writer, writing `bytes`, and then flushing.
pub fn writePositionalAll(file: File, io: Io, bytes: []const u8, offset: u64) WritePositionalError!void {
    var index: usize = 0;
    while (index < bytes.len)
        index += try io.vtable.fileWritePositional(io.userdata, file, &.{}, &.{bytes[index..]}, 1, offset + index);
}

pub const SeekError = error{
    Unseekable,
    /// The file descriptor does not hold the required rights to seek on it.
    AccessDenied,
} || Io.Cancelable || Io.UnexpectedError;

pub const WriteFilePositionalError = Writer.WriteFileError || error{Unseekable};

/// Defaults to positional reading; falls back to streaming.
///
/// Positional is more threadsafe, since the global seek position is not
/// affected.
///
/// See also:
/// * `readerStreaming`
pub fn reader(file: File, io: Io, buffer: []u8) Reader {
    return .init(file, io, buffer);
}

/// Equivalent to creating a positional reader and reading multiple times to fill `buffer`.
///
/// Returns number of bytes read into `buffer`. If less than `buffer.len`, end of file occurred.
///
/// See also:
/// * `reader`
pub fn readPositionalAll(file: File, io: Io, buffer: []u8, offset: u64) ReadPositionalError!usize {
    var index: usize = 0;
    while (index != buffer.len) {
        const amt = try file.readPositional(io, &.{buffer[index..]}, offset + index);
        if (amt == 0) break;
        index += amt;
    }
    return index;
}

/// Positional is more threadsafe, since the global seek position is not
/// affected, but when such syscalls are not available, preemptively
/// initializing in streaming mode skips a failed syscall.
///
/// See also:
/// * `reader`
pub fn readerStreaming(file: File, io: Io, buffer: []u8) Reader {
    return .initStreaming(file, io, buffer);
}

/// Defaults to positional reading; falls back to streaming.
///
/// Positional is more threadsafe, since the global seek position is not
/// affected.
pub fn writer(file: File, io: Io, buffer: []u8) Writer {
    return .init(file, io, buffer);
}

/// Positional is more threadsafe, since the global seek position is not
/// affected, but when such syscalls are not available, preemptively
/// initializing in streaming mode will skip a failed syscall.
pub fn writerStreaming(file: File, io: Io, buffer: []u8) Writer {
    return .initStreaming(file, io, buffer);
}

/// This is a low-level API that calls the `Io` interface function directly.
/// For a higher level API, see `writerStreaming`.
pub fn writeStreaming(file: File, io: Io, header: []const u8, data: []const []const u8, splat: usize) Writer.Error!usize {
    return (try io.operate(.{ .file_write_streaming = .{
        .file = file,
        .header = header,
        .data = data,
        .splat = splat,
    } })).file_write_streaming;
}

/// Equivalent to creating a streaming writer, writing `bytes`, and then flushing.
pub fn writeStreamingAll(file: File, io: Io, bytes: []const u8) Writer.Error!void {
    var index: usize = 0;
    while (index < bytes.len) {
        index += try writeStreaming(file, io, &.{}, &.{bytes[index..]}, 1);
    }
}

pub const LockError = error{
    SystemResources,
    FileLocksUnsupported,
} || Io.Cancelable || Io.UnexpectedError;

/// Blocks when an incompatible lock is held by another process. A process may
/// hold only one type of lock (shared or exclusive) on a file. When a process
/// terminates in any way, the lock is released.
///
/// Assumes the file is unlocked.
pub fn lock(file: File, io: Io, l: Lock) LockError!void {
    return io.vtable.fileLock(io.userdata, file, l);
}

/// Assumes the file is locked.
pub fn unlock(file: File, io: Io) void {
    return io.vtable.fileUnlock(io.userdata, file);
}

/// Attempts to obtain a lock, returning `true` if the lock is obtained, and
/// `false` if there was an existing incompatible lock held. A process may hold
/// only one type of lock (shared or exclusive) on a file. When a process
/// terminates in any way, the lock is released.
///
/// Assumes the file is unlocked.
pub fn tryLock(file: File, io: Io, l: Lock) LockError!bool {
    return io.vtable.fileTryLock(io.userdata, file, l);
}

pub const DowngradeLockError = Io.Cancelable || Io.UnexpectedError;

/// Assumes the file is already locked in exclusive mode.
/// Atomically modifies the lock to be in shared mode, without releasing it.
pub fn downgradeLock(file: File, io: Io) LockError!void {
    return io.vtable.fileDowngradeLock(io.userdata, file);
}

pub const RealPathError = error{
    /// This operating system, file system, or `Io` implementation does not
    /// support realpath operations.
    OperationUnsupported,
    /// The full file system path could not fit into the provided buffer, or
    /// due to its length could not be obtained via realpath functions no
    /// matter the buffer size provided.
    NameTooLong,
    FileNotFound,
    AccessDenied,
    PermissionDenied,
    NotDir,
    SymLinkLoop,
    InputOutput,
    FileTooBig,
    IsDir,
    ProcessFdQuotaExceeded,
    SystemFdQuotaExceeded,
    NoDevice,
    SystemResources,
    NoSpaceLeft,
    FileSystem,
    DeviceBusy,
    FileBusy,
    PipeBusy,
    /// On Windows, `\\server` or `\\server\share` was not found.
    NetworkNotFound,
    PathAlreadyExists,
    /// 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.
    AntivirusInterference,
    /// On Windows, the volume does not contain a recognized file system. File
    /// system drivers might not be loaded, or the volume may be corrupt.
    UnrecognizedVolume,
} || Io.Cancelable || Io.UnexpectedError;

/// Obtains the canonicalized absolute path name corresponding to an open file
/// handle.
///
/// This function has limited platform support, and using it can lead to
/// unnecessary failures and race conditions. It is generally advisable to
/// avoid this function entirely.
pub fn realPath(file: File, io: Io, out_buffer: []u8) RealPathError!usize {
    return io.vtable.fileRealPath(io.userdata, file, out_buffer);
}

pub const HardLinkOptions = struct {
    follow_symlinks: bool = false,
};

pub const HardLinkError = error{
    AccessDenied,
    PermissionDenied,
    DiskQuota,
    PathAlreadyExists,
    HardwareFailure,
    /// Either the OS or the filesystem does not support hard links.
    OperationUnsupported,
    SymLinkLoop,
    LinkQuotaExceeded,
    FileNotFound,
    SystemResources,
    NoSpaceLeft,
    ReadOnlyFileSystem,
    CrossDevice,
    NotDir,
} || Io.Cancelable || Dir.PathNameError || Io.UnexpectedError;

pub fn hardLink(
    file: File,
    io: Io,
    new_dir: Dir,
    new_sub_path: []const u8,
    options: HardLinkOptions,
) HardLinkError!void {
    return io.vtable.fileHardLink(io.userdata, file, new_dir, new_sub_path, options);
}

pub fn createMemoryMap(file: File, io: Io, options: MemoryMap.CreateOptions) MemoryMap.CreateError!MemoryMap {
    return .create(io, file, options);
}

test {
    _ = Reader;
    _ = Writer;
    _ = Atomic;
    _ = MemoryMap;
}