Fields

handle: Handle,

The OS-specific file descriptor or file handle.

capable_io_mode: io.ModeOverride = io.default_mode,

On some systems, such as Linux, file system file descriptors are incapable of non-blocking I/O. This forces us to perform asynchronous I/O on a dedicated thread, to achieve non-blocking file-system I/O. To do this, File must be aware of whether it is a file system file descriptor, or, more specifically, whether the I/O is always blocking.

intended_io_mode: io.ModeOverride = io.default_mode,

Furthermore, even when std.options.io_mode is async, it is still sometimes desirable to perform blocking I/O, although not by default. For example, when printing a stack trace to stderr. This field tracks both by acting as an overriding I/O mode. When not building in async I/O mode, the type only has the .blocking tag, making it a zero-bit type.

Functions

fn chmod(self: File, new_mode: Mode) ChmodError!void

Changes the mode of the file. The process must have the correct privileges in o…

Changes the mode of the file. 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.

fn chown(self: File, owner: ?Uid, group: ?Gid) ChownError!void

Changes the owner and group of the file. The process must have the correct priv…

Changes the owner and group of the file. 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.

fn close(self: File) void

Upon success, the stream is in an uninitialized state. To continue using it, yo…

Upon success, the stream is in an uninitialized state. To continue using it, you must use the open() function.

fn copyRange(in: File, in_offset: u64, out: File, out_offset: u64, len: u64) CopyRangeError!u64

No documentation provided.

fn copyRangeAll(in: File, in_offset: u64, out: File, out_offset: u64, len: u64) CopyRangeError!u64

Returns the number of bytes copied. If the number read is smaller than `buffer.l…

Returns the number of bytes copied. If the number read is smaller than buffer.len, it means the in file reached the end. Reaching the end of a file is not an error condition.

fn downgradeLock(file: File) LockError!void

Assumes the file is already locked in exclusive mode. Atomically modifies the l…

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

TODO: integrate with async I/O

fn getEndPos(self: File) GetSeekPosError!u64

TODO: integrate with async I/O

fn getPos(self: File) GetSeekPosError!u64

TODO: integrate with async I/O

fn isTty(self: File) bool

Test whether the file refers to a terminal. See also supportsAnsiEscapeCodes.

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

Blocks when an incompatible lock is held by another process. A process may hold…

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.

TODO: integrate with async I/O

fn metadata(self: File) MetadataError!Metadata

No documentation provided.

fn mode(self: File) ModeError!Mode

TODO: integrate with async I/O

fn pread(self: File, buffer: []u8, offset: u64) PReadError!usize

On Windows, this function currently does alter the file pointer. https://github…

On Windows, this function currently does alter the file pointer. https://github.com/ziglang/zig/issues/12783

fn preadAll(self: File, buffer: []u8, offset: u64) PReadError!usize

Returns the number of bytes read. If the number read is smaller than `buffer.len…

Returns the number of bytes read. If the number read is smaller than buffer.len, it means the file reached the end. Reaching the end of a file is not an error condition. On Windows, this function currently does alter the file pointer. https://github.com/ziglang/zig/issues/12783

fn preadv(self: File, iovecs: []const os.iovec, offset: u64) PReadError!usize

See https://github.com/ziglang/zig/issues/7699 On Windows, this function curren…

See https://github.com/ziglang/zig/issues/7699 On Windows, this function currently does alter the file pointer. https://github.com/ziglang/zig/issues/12783

fn preadvAll(self: File, iovecs: []os.iovec, offset: u64) PReadError!usize

Returns the number of bytes read. If the number read is smaller than the total b…

Returns the number of bytes read. If the number read is smaller than the total bytes from all the buffers, it means the file reached the end. Reaching the end of a file is not an error condition. The iovecs parameter is mutable because this function needs to mutate the fields in order to handle partial reads from the underlying OS layer. See https://github.com/ziglang/zig/issues/7699 On Windows, this function currently does alter the file pointer. https://github.com/ziglang/zig/issues/12783

fn pwrite(self: File, bytes: []const u8, offset: u64) PWriteError!usize

On Windows, this function currently does alter the file pointer. https://github…

On Windows, this function currently does alter the file pointer. https://github.com/ziglang/zig/issues/12783

fn pwriteAll(self: File, bytes: []const u8, offset: u64) PWriteError!void

On Windows, this function currently does alter the file pointer. https://github…

On Windows, this function currently does alter the file pointer. https://github.com/ziglang/zig/issues/12783

fn pwritev(self: File, iovecs: []os.iovec_const, offset: u64) PWriteError!usize

See https://github.com/ziglang/zig/issues/7699 On Windows, this function curren…

See https://github.com/ziglang/zig/issues/7699 On Windows, this function currently does alter the file pointer. https://github.com/ziglang/zig/issues/12783

fn pwritevAll(self: File, iovecs: []os.iovec_const, offset: u64) PWriteError!void

The iovecs parameter is mutable because this function needs to mutate the fiel…

The iovecs parameter is mutable because this function needs to mutate the fields in order to handle partial writes from the underlying OS layer. See https://github.com/ziglang/zig/issues/7699 On Windows, this function currently does alter the file pointer. https://github.com/ziglang/zig/issues/12783

fn read(self: File, buffer: []u8) ReadError!usize

No documentation provided.

fn readAll(self: File, buffer: []u8) ReadError!usize

Returns the number of bytes read. If the number read is smaller than `buffer.len…

Returns the number of bytes read. If the number read is smaller than buffer.len, it means the file reached the end. Reaching the end of a file is not an error condition.

fn readToEndAlloc(self: File, allocator: mem.Allocator, max_bytes: usize) ![]u8

Reads all the bytes from the current position to the end of the file. On succes…

Reads all the bytes from the current position to the end of the file. On success, caller owns returned buffer. If the file is larger than max_bytes, returns error.FileTooBig.

fn readToEndAllocOptions(self: File, allocator: mem.Allocator, max_bytes: usize, size_hint: ?usize, comptime alignment: u29, comptime optional_sentinel: ?u8) !if (optional_sentinel) |s| [:s]align(alignment) u8 else []align(alignment) u8

Reads all the bytes from the current position to the end of the file. On succes…

Reads all the bytes from the current position to the end of the file. On success, caller owns returned buffer. If the file is larger than max_bytes, returns error.FileTooBig. If size_hint is specified the initial buffer size is calculated using that value, otherwise an arbitrary value is used instead. Allows specifying alignment and a sentinel value.

fn reader(file: File) Reader

No documentation provided.

fn readv(self: File, iovecs: []const os.iovec) ReadError!usize

See https://github.com/ziglang/zig/issues/7699

fn readvAll(self: File, iovecs: []os.iovec) ReadError!usize

Returns the number of bytes read. If the number read is smaller than the total b…

Returns the number of bytes read. If the number read is smaller than the total bytes from all the buffers, it means the file reached the end. Reaching the end of a file is not an error condition.

The iovecs parameter is mutable because:

  • This function needs to mutate the fields in order to handle partial reads from the underlying OS layer.
  • The OS layer expects pointer addresses to be inside the application’s address space even if the length is zero. Meanwhile, in Zig, slices may have undefined pointer addresses when the length is zero. So this function modifies the iov_base fields when the length is zero.

Related open issue: https://github.com/ziglang/zig/issues/7699

fn seekBy(self: File, offset: i64) SeekError!void

Repositions read/write file offset relative to the current offset. TODO: integr…

Repositions read/write file offset relative to the current offset. TODO: integrate with async I/O

fn seekFromEnd(self: File, offset: i64) SeekError!void

Repositions read/write file offset relative to the end. TODO: integrate with as…

Repositions read/write file offset relative to the end. TODO: integrate with async I/O

fn seekTo(self: File, offset: u64) SeekError!void

Repositions read/write file offset relative to the beginning. TODO: integrate w…

Repositions read/write file offset relative to the beginning. TODO: integrate with async I/O

fn seekableStream(file: File) SeekableStream

No documentation provided.

fn setEndPos(self: File, length: u64) SetEndPosError!void

Shrinks or expands the file. The file offset after this call is left unchanged.

fn setPermissions(self: File, permissions: Permissions) SetPermissionsError!void

Sets permissions according to the provided Permissions struct. This method is…

Sets permissions according to the provided Permissions struct. This method is NOT available on WASI

fn stat(self: File) StatError!Stat

TODO: integrate with async I/O

fn supportsAnsiEscapeCodes(self: File) bool

Test whether ANSI escape codes will be treated as such.

fn sync(self: File) SyncError!void

Blocks until all pending file contents and metadata modifications for the file …

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

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

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

Attempts to obtain a lock, returning true if the lock is obtained, and `false…

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.

TODO: integrate with async I/O

fn unlock(file: File) void

Assumes the file is locked.

fn updateTimes(self: File, atime: i128, mtime: i128) UpdateTimesError!void

The underlying file system may have a different granularity than nanoseconds, a…

The underlying file system may have a different granularity than nanoseconds, and therefore this function cannot guarantee any precision will be stored. Further, the maximum value is limited by the system ABI. When a value is provided that exceeds this range, the value is clamped to the maximum. TODO: integrate with async I/O

fn write(self: File, bytes: []const u8) WriteError!usize

No documentation provided.

fn writeAll(self: File, bytes: []const u8) WriteError!void

No documentation provided.

fn writeFileAll(self: File, in_file: File, args: WriteFileOptions) WriteFileError!void

No documentation provided.

fn writeFileAllUnseekable(self: File, in_file: File, args: WriteFileOptions) WriteFileError!void

Does not try seeking in either of the File parameters. See writeFileAll as an…

Does not try seeking in either of the File parameters. See writeFileAll as an alternative to calling this.

fn writer(file: File) Writer

No documentation provided.

fn writev(self: File, iovecs: []const os.iovec_const) WriteError!usize

See https://github.com/ziglang/zig/issues/7699 See equivalent function: `std.ne…

See https://github.com/ziglang/zig/issues/7699 See equivalent function: std.net.Stream.writev.

fn writevAll(self: File, iovecs: []os.iovec_const) WriteError!void

The iovecs parameter is mutable because:

  • This function needs to mutate the …

The iovecs parameter is mutable because:

  • This function needs to mutate the fields in order to handle partial writes from the underlying OS layer.
  • The OS layer expects pointer addresses to be inside the application’s address space even if the length is zero. Meanwhile, in Zig, slices may have undefined pointer addresses when the length is zero. So this function modifies the iov_base fields when the length is zero. See https://github.com/ziglang/zig/issues/7699 See equivalent function: std.net.Stream.writevAll.

Values

ChmodError
type
ChownError
type
CopyRangeError
type
GetSeekPosError
type
Gid
undefined
Handle
undefined
INode
undefined
LockError
type
MetadataError
type
Mode
undefined
ModeError
type
OpenError
type
PReadError
type
PWriteError
type
ReadError
type
Reader
undefined
SeekError
type
SeekableStream
undefined
SetEndPosError
type
SetPermissionsError
type
StatError
type
SyncError
type
Uid
undefined
UpdateTimesError
type
WriteError
type
WriteFileError
type
Writer
undefined
default_mode
type

This is the default mode given to POSIX operating systems for creating files. `…