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

Source line 1

Fields

io: Io
file: File
err: ?Error = null
mode: Mode = .positional
pos: u64 = 0

Tracks 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

Source line 8

Alias of std.debug.assert

std.Io.File.Writer.builtin

constant

Source line 2

std.Io.File.Writer.drain

function

Source line 89

pub fn drain(io_w: *Io.Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize

Parameters

io_w: *Io.Writer
data: []const []const u8
splat: usize

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.Io.File.Writer.drainPositional

function

Source line 98

fn drainPositional(w: *Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize

Parameters

w: *Writer
data: []const []const u8
splat: usize

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.Io.File.Writer.drainStreaming

function

Source line 123

fn drainStreaming(w: *Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize

Parameters

w: *Writer
data: []const []const u8
splat: usize

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.Io.File.Writer.end

function

Source line 237

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 Writer implementation for detailed diagnostics.

std.Io.File.Writer.EndError

error-set

Source line 228

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 Writer implementation for detailed diagnostics.

std.Io.File.Writer.Error

error-set

Source line 23

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

Source line 7

Alias of std.Io.File

std.Io.File.Writer.flush

function

Source line 257

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

Source line 36

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

Parameters

file: File
io: Io
buffer: []u8

std.Io.File.Writer.initDetect

function

Source line 58

Detects if file is terminal and sets the mode accordingly.

pub fn initDetect(file: File, io: Io, buffer: []u8) Io.Cancelable!Writer

Parameters

file: File
io: Io
buffer: []u8

Errors

Canceled

Caller has requested the async operation to stop.

std.Io.File.Writer.initInterface

function

Source line 67

pub fn initInterface(buffer: []u8) Io.Writer

Parameters

buffer: []u8

std.Io.File.Writer.initStreaming

function

Source line 48

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

file: File
io: Io
buffer: []u8

std.Io.File.Writer.Io

alias

Source line 6

Alias of std.Io

std.Io.File.Writer.is_windows

constant

Source line 3

std.Io.File.Writer.logicalPos

function

Source line 204

pub fn logicalPos(w: *const Writer) u64

Parameters

w: *const Writer

std.Io.File.Writer.Mode

alias

Source line 21

Alias of std.Io.File.Reader.Mode

std.Io.File.Writer.moveToReader

function

Source line 77

pub fn moveToReader(w: *Writer) File.Reader

Parameters

w: *Writer

std.Io.File.Writer.SeekError

alias

Source line 34

Alias of std.Io.File.SeekError

std.Io.File.Writer.seekTo

function

Source line 199

pub fn seekTo(w: *Writer, offset: u64) (SeekError || Io.Writer.Error)!void

Parameters

w: *Writer
offset: u64

std.Io.File.Writer.seekToUnbuffered

function

Source line 209

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

Source line 134

pub fn sendFile(io_w: *Io.Writer, file_reader: *Io.File.Reader, limit: Io.Limit) Io.Writer.FileError!usize

Parameters

io_w: *Io.Writer
file_reader: *Io.File.Reader
limit: Io.Limit

Errors

EndOfStream

Reached the end of the file being read.

ReadFailed

Detailed diagnostics are found on the File.Reader struct.

Unimplemented

Indicates the caller should do its own file reading; the callee cannot offer a more efficient implementation.

WriteFailed

See the Writer implementation for detailed diagnostics.

std.Io.File.Writer.sendFilePositional

function

Source line 145

fn sendFilePositional(w: *Writer, file_reader: *Io.File.Reader, limit: Io.Limit) Io.Writer.FileError!usize

Parameters

w: *Writer
file_reader: *Io.File.Reader
limit: Io.Limit

Errors

EndOfStream

Reached the end of the file being read.

ReadFailed

Detailed diagnostics are found on the File.Reader struct.

Unimplemented

Indicates the caller should do its own file reading; the callee cannot offer a more efficient implementation.

WriteFailed

See the Writer implementation for detailed diagnostics.

std.Io.File.Writer.sendFileStreaming

function

Source line 178

fn sendFileStreaming(w: *Writer, file_reader: *Io.File.Reader, limit: Io.Limit) Io.Writer.FileError!usize

Parameters

w: *Writer
file_reader: *Io.File.Reader
limit: Io.Limit

Errors

EndOfStream

Reached the end of the file being read.

ReadFailed

Detailed diagnostics are found on the File.Reader struct.

Unimplemented

Indicates the caller should do its own file reading; the callee cannot offer a more efficient implementation.

WriteFailed

See the Writer implementation for detailed diagnostics.

std.Io.File.Writer.std

alias

Source line 5

Alias of std

std.Io.File.Writer.WriteFileError

error-set

Source line 25

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

Source line 1

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.?,
    };
}