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 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 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/12783fn 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/12783fn 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/12783fn 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
, returnserror.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
, returnserror.FileTooBig
. Ifsize_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 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 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 WASIfn 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, andfalse
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 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 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 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. `… |