Fields
io: Io
file: File
err: ?Error = null
mode: Mode = .positional
pos: u64 = 0Tracks the true seek position in the file. To obtain the logical position,
use logicalPos.
write_file_err: ?WriteFileError = null
seek_err: ?SeekError = null
interface: Io.Writer
std.Io.File.Writer.assert
alias
Alias of std.debug.assert
std.Io.File.Writer.builtin
constant
std.Io.File.Writer.drain
function
pub fn drain(io_w: *Io.Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize
Parameters
Errors
- WriteFailed
See the
Writerimplementation for detailed diagnostics.
std.Io.File.Writer.drainPositional
function
fn drainPositional(w: *Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize
Parameters
Errors
- WriteFailed
See the
Writerimplementation for detailed diagnostics.
std.Io.File.Writer.drainStreaming
function
fn drainStreaming(w: *Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize
Parameters
Errors
- WriteFailed
See the
Writerimplementation for detailed diagnostics.
std.Io.File.Writer.end
function
Flushes any buffered data and sets the end position of the file.
If not overwriting existing contents, then calling interface.flush
directly is sufficient.
Flush failure is handled by setting err so that it can be handled
along with other write failures.
pub fn end(w: *Writer) EndError!void
Parameters
w: *Writer
Errors
- AccessDenied SetLengthError
- Canceled Cancelable
Caller has requested the async operation to stop.
- FileBusy SetLengthError
- FileTooBig SetLengthError
- InputOutput SetLengthError
- NonResizable SetLengthError
- PermissionDenied SetLengthError
- 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.
- WriteFailed Error
See the
Writerimplementation for detailed diagnostics.
std.Io.File.Writer.EndError
error-set
Errors
- AccessDenied SetLengthError
- Canceled Cancelable
Caller has requested the async operation to stop.
- FileBusy SetLengthError
- FileTooBig SetLengthError
- InputOutput SetLengthError
- NonResizable SetLengthError
- PermissionDenied SetLengthError
- 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.
- WriteFailed Error
See the
Writerimplementation for detailed diagnostics.
std.Io.File.Writer.Error
error-set
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.Writer.File
alias
Alias of std.Io.File
std.Io.File.Writer.flush
function
Convenience method for calling Io.Writer.flush and returning the
underlying error.
pub fn flush(w: *Writer) Error!void
Parameters
w: *Writer
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.Writer.init
function
pub fn init(file: File, io: Io, buffer: []u8) Writer
Parameters
std.Io.File.Writer.initDetect
function
Detects if file is terminal and sets the mode accordingly.
pub fn initDetect(file: File, io: Io, buffer: []u8) Io.Cancelable!Writer
Parameters
Errors
- Canceled
Caller has requested the async operation to stop.
std.Io.File.Writer.initInterface
function
pub fn initInterface(buffer: []u8) Io.Writer
Parameters
buffer: []u8
std.Io.File.Writer.initStreaming
function
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 initStreaming(file: File, io: Io, buffer: []u8) Writer
Parameters
std.Io.File.Writer.Io
alias
Alias of std.Io
std.Io.File.Writer.is_windows
constant
std.Io.File.Writer.logicalPos
function
pub fn logicalPos(w: *const Writer) u64
Parameters
w: *const Writer
std.Io.File.Writer.Mode
alias
Alias of std.Io.File.Reader.Mode
std.Io.File.Writer.moveToReader
function
pub fn moveToReader(w: *Writer) File.Reader
Parameters
w: *Writer
std.Io.File.Writer.SeekError
alias
Alias of std.Io.File.SeekError
std.Io.File.Writer.seekTo
function
pub fn seekTo(w: *Writer, offset: u64) (SeekError || Io.Writer.Error)!void
Parameters
w: *Writer
offset: u64
std.Io.File.Writer.seekToUnbuffered
function
Asserts that no data is currently buffered.
pub fn seekToUnbuffered(w: *Writer, offset: u64) SeekError!void
Parameters
w: *Writer
offset: u64
Errors
- AccessDenied SeekError
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 SeekError
std.Io.File.Writer.sendFile
function
pub fn sendFile(io_w: *Io.Writer, file_reader: *Io.File.Reader, limit: Io.Limit) Io.Writer.FileError!usize
Parameters
Errors
- EndOfStream
Reached the end of the file being read.
- ReadFailed
Detailed diagnostics are found on the
File.Readerstruct.- Unimplemented
Indicates the caller should do its own file reading; the callee cannot offer a more efficient implementation.
- WriteFailed
See the
Writerimplementation for detailed diagnostics.
std.Io.File.Writer.sendFilePositional
function
fn sendFilePositional(w: *Writer, file_reader: *Io.File.Reader, limit: Io.Limit) Io.Writer.FileError!usize
Parameters
Errors
- EndOfStream
Reached the end of the file being read.
- ReadFailed
Detailed diagnostics are found on the
File.Readerstruct.- Unimplemented
Indicates the caller should do its own file reading; the callee cannot offer a more efficient implementation.
- WriteFailed
See the
Writerimplementation for detailed diagnostics.
std.Io.File.Writer.sendFileStreaming
function
fn sendFileStreaming(w: *Writer, file_reader: *Io.File.Reader, limit: Io.Limit) Io.Writer.FileError!usize
Parameters
Errors
- EndOfStream
Reached the end of the file being read.
- ReadFailed
Detailed diagnostics are found on the
File.Readerstruct.- Unimplemented
Indicates the caller should do its own file reading; the callee cannot offer a more efficient implementation.
- WriteFailed
See the
Writerimplementation for detailed diagnostics.
std.Io.File.Writer.std
alias
Alias of std
std.Io.File.Writer.WriteFileError
error-set
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
Can happen on FreeBSD when using copy_file_range.
- DeviceBusy Error
- DiskQuota Error
- EndOfStream
- 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
- 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
Descriptor is not valid or locked, or an mmap(2)-like operation is not available for in_fd.
- WouldBlock Error
Non-blocking has been enabled and this operation would block.
std.Io.File.Writer.Writer
alias
Alias of std.Io.File.Writer
Source code
std/Io/File/Writer.zig
const Writer = @This();
const builtin = @import("builtin");
const is_windows = builtin.os.tag == .windows;
const std = @import("../../std.zig");
const Io = std.Io;
const File = std.Io.File;
const assert = std.debug.assert;
io: Io,
file: File,
err: ?Error = null,
mode: Mode = .positional,
/// Tracks the true seek position in the file. To obtain the logical position,
/// use `logicalPos`.
pos: u64 = 0,
write_file_err: ?WriteFileError = null,
seek_err: ?SeekError = null,
interface: Io.Writer,
pub const Mode = File.Reader.Mode;
pub const Error = Io.Operation.FileWriteStreaming.Error || Io.Cancelable;
pub const WriteFileError = Error || error{
/// Descriptor is not valid or locked, or an mmap(2)-like operation is not available for in_fd.
Unimplemented,
/// Can happen on FreeBSD when using copy_file_range.
CorruptedData,
EndOfStream,
ReadFailed,
};
pub const SeekError = Io.File.SeekError;
pub fn init(file: File, io: Io, buffer: []u8) Writer {
return .{
.io = io,
.file = file,
.interface = initInterface(buffer),
.mode = .positional,
};
}
/// 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 initStreaming(file: File, io: Io, buffer: []u8) Writer {
return .{
.io = io,
.file = file,
.interface = initInterface(buffer),
.mode = .streaming,
};
}
/// Detects if `file` is terminal and sets the mode accordingly.
pub fn initDetect(file: File, io: Io, buffer: []u8) Io.Cancelable!Writer {
return .{
.io = io,
.file = file,
.interface = initInterface(buffer),
.mode = try .detect(io, file, true, .positional),
};
}
pub fn initInterface(buffer: []u8) Io.Writer {
return .{
.vtable = &.{
.drain = drain,
.sendFile = sendFile,
},
.buffer = buffer,
};
}
pub fn moveToReader(w: *Writer) File.Reader {
defer w.* = undefined;
return .{
.io = w.io,
.file = w.file,
.mode = w.mode,
.pos = w.pos,
.interface = File.Reader.initInterface(w.interface.buffer),
.seek_err = w.seek_err,
};
}
pub fn drain(io_w: *Io.Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize {
const w: *Writer = @alignCast(@fieldParentPtr("interface", io_w));
switch (w.mode) {
.positional, .positional_simple => return drainPositional(w, data, splat),
.streaming, .streaming_simple => return drainStreaming(w, data, splat),
.failure => return error.WriteFailed,
}
}
fn drainPositional(w: *Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize {
const io = w.io;
const header = w.interface.buffered();
const n = io.vtable.fileWritePositional(io.userdata, w.file, header, data, splat, w.pos) catch |err| switch (err) {
error.Unseekable => {
w.mode = w.mode.toStreaming();
const pos = w.pos;
if (pos != 0) {
w.pos = 0;
w.seekTo(@intCast(pos)) catch {
w.mode = .failure;
return error.WriteFailed;
};
}
return 0;
},
else => |e| {
w.err = e;
return error.WriteFailed;
},
};
w.pos += n;
return w.interface.consume(n);
}
fn drainStreaming(w: *Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize {
const io = w.io;
const header = w.interface.buffered();
const n = w.file.writeStreaming(io, header, data, splat) catch |err| {
w.err = err;
return error.WriteFailed;
};
w.pos += n;
return w.interface.consume(n);
}
pub fn sendFile(io_w: *Io.Writer, file_reader: *Io.File.Reader, limit: Io.Limit) Io.Writer.FileError!usize {
const w: *Writer = @alignCast(@fieldParentPtr("interface", io_w));
switch (w.mode) {
.positional => return sendFilePositional(w, file_reader, limit),
.positional_simple => return error.Unimplemented,
.streaming => return sendFileStreaming(w, file_reader, limit),
.streaming_simple => return error.Unimplemented,
.failure => return error.WriteFailed,
}
}
fn sendFilePositional(w: *Writer, file_reader: *Io.File.Reader, limit: Io.Limit) Io.Writer.FileError!usize {
const io = w.io;
const header = w.interface.buffered();
const n = io.vtable.fileWriteFilePositional(io.userdata, w.file, header, file_reader, limit, w.pos) catch |err| switch (err) {
error.Unseekable => {
w.mode = w.mode.toStreaming();
const pos = w.pos;
if (pos != 0) {
w.pos = 0;
w.seekTo(@intCast(pos)) catch {
w.mode = .failure;
return error.WriteFailed;
};
}
return 0;
},
error.Canceled => {
w.err = error.Canceled;
return error.WriteFailed;
},
error.EndOfStream,
error.Unimplemented,
error.ReadFailed,
=> |e| return e,
else => |e| {
w.write_file_err = e;
return error.WriteFailed;
},
};
w.pos += n;
return w.interface.consume(n);
}
fn sendFileStreaming(w: *Writer, file_reader: *Io.File.Reader, limit: Io.Limit) Io.Writer.FileError!usize {
const io = w.io;
const header = w.interface.buffered();
const n = io.vtable.fileWriteFileStreaming(io.userdata, w.file, header, file_reader, limit) catch |err| switch (err) {
error.Canceled => {
w.err = error.Canceled;
return error.WriteFailed;
},
error.EndOfStream,
error.Unimplemented,
error.ReadFailed,
=> |e| return e,
else => |e| {
w.write_file_err = e;
return error.WriteFailed;
},
};
w.pos += n;
return w.interface.consume(n);
}
pub fn seekTo(w: *Writer, offset: u64) (SeekError || Io.Writer.Error)!void {
try w.interface.flush();
try seekToUnbuffered(w, offset);
}
pub fn logicalPos(w: *const Writer) u64 {
return w.pos + w.interface.end;
}
/// Asserts that no data is currently buffered.
pub fn seekToUnbuffered(w: *Writer, offset: u64) SeekError!void {
assert(w.interface.buffered().len == 0);
const io = w.io;
switch (w.mode) {
.positional, .positional_simple => {
w.pos = offset;
},
.streaming, .streaming_simple => {
if (w.seek_err) |err| return err;
io.vtable.fileSeekTo(io.userdata, w.file, offset) catch |err| {
w.seek_err = err;
return err;
};
w.pos = offset;
},
.failure => return w.seek_err.?,
}
}
pub const EndError = File.SetLengthError || Io.Writer.Error;
/// Flushes any buffered data and sets the end position of the file.
///
/// If not overwriting existing contents, then calling `interface.flush`
/// directly is sufficient.
///
/// Flush failure is handled by setting `err` so that it can be handled
/// along with other write failures.
pub fn end(w: *Writer) EndError!void {
const io = w.io;
try w.interface.flush();
switch (w.mode) {
.positional,
.positional_simple,
=> w.file.setLength(io, w.pos) catch |err| switch (err) {
error.NonResizable => return,
else => |e| return e,
},
.streaming,
.streaming_simple,
.failure,
=> {},
}
}
/// Convenience method for calling `Io.Writer.flush` and returning the
/// underlying error.
pub fn flush(w: *Writer) Error!void {
w.interface.flush() catch |err| switch (err) {
error.WriteFailed => return w.err.?,
};
}
test "failing io fails to flush in positional mode" {
var buffer: [128]u8 = undefined;
var file_writer: File.Writer = .init(.stdout(), .failing, &buffer);
try file_writer.interface.writeAll("hello");
try std.testing.expectError(error.WriteFailed, file_writer.interface.flush());
}