跳转到内容

std.Io.File.Writer

标准库Zig 0.17.1官方原文
源码std/Io/File/Writer.zig

第 1 行

字段

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

跟踪文件中的实际定位位置。 要获取逻辑位置,请使用 logicalPos。

write_file_err: ?WriteFileError = null
seek_err: ?SeekError = null
interface: Io.Writer

std.Io.File.Writer.assert

别名

第 8 行

别名目标 std.debug.assert

std.Io.File.Writer.builtin

常量

第 2 行

std.Io.File.Writer.drain

函数

第 89 行

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

参数

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

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.Io.File.Writer.drainPositional

函数

第 98 行

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

参数

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

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.Io.File.Writer.drainStreaming

函数

第 123 行

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

参数

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

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.Io.File.Writer.end

函数

第 237 行

刷新所有已缓冲数据,并设置文件结束位置。

如果不覆盖现有内容,直接调用 interface.flush 即可。

刷新失败时设置 err,以便与其他写入 失败一并处理。

pub fn end(w: *Writer) EndError!void

参数

w: *Writer

错误

AccessDenied SetLengthError
Canceled Cancelable

调用方请求停止异步操作。

FileBusy SetLengthError
FileTooBig SetLengthError
InputOutput SetLengthError
NonResizable SetLengthError
PermissionDenied SetLengthError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WriteFailed Error

详细诊断信息见 Writer 实现。

std.Io.File.Writer.EndError

错误集合

第 228 行

错误

AccessDenied SetLengthError
Canceled Cancelable

调用方请求停止异步操作。

FileBusy SetLengthError
FileTooBig SetLengthError
InputOutput SetLengthError
NonResizable SetLengthError
PermissionDenied SetLengthError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WriteFailed Error

详细诊断信息见 Writer 实现。

std.Io.File.Writer.Error

错误集合

第 23 行

错误

AccessDenied Error

文件描述符没有写入所需的权限。

BrokenPipe Error

文件为未连接的套接字,或其读取端已关闭。

Canceled Cancelable

调用方请求停止异步操作。

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

进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。

NoDevice Error

写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。

NoSpaceLeft Error
NotOpenForWriting Error
PermissionDenied Error
SystemResources Error

内核内存不足,无法从 in_fd 读取。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock Error

已启用非阻塞模式,而此操作将阻塞。

std.Io.File.Writer.File

别名

第 7 行

别名目标 std.Io.File

std.Io.File.Writer.flush

函数

第 257 行

调用 Io.Writer.flush 并返回 底层错误的便捷方法。

pub fn flush(w: *Writer) Error!void

参数

w: *Writer

错误

AccessDenied Error

文件描述符没有写入所需的权限。

BrokenPipe Error

文件为未连接的套接字,或其读取端已关闭。

Canceled Cancelable

调用方请求停止异步操作。

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

进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。

NoDevice Error

写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。

NoSpaceLeft Error
NotOpenForWriting Error
PermissionDenied Error
SystemResources Error

内核内存不足,无法从 in_fd 读取。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock Error

已启用非阻塞模式,而此操作将阻塞。

std.Io.File.Writer.init

函数

第 36 行

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

参数

file: File
io: Io
buffer: []u8

std.Io.File.Writer.initDetect

函数

第 58 行

检测 file 是否为终端,并相应设置模式。

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

参数

file: File
io: Io
buffer: []u8

错误

Canceled

调用方请求停止异步操作。

std.Io.File.Writer.initInterface

函数

第 67 行

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

参数

buffer: []u8

std.Io.File.Writer.initStreaming

函数

第 48 行

定位读取不影响全局查找位置,因此更便于线程安全使用。 但若相应系统调用不可用,则预先初始化为 流式模式可省去一次失败的系统调用。

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

参数

file: File
io: Io
buffer: []u8

std.Io.File.Writer.Io

别名

第 6 行

别名目标 std.Io

std.Io.File.Writer.is_windows

常量

第 3 行

std.Io.File.Writer.logicalPos

函数

第 204 行

pub fn logicalPos(w: *const Writer) u64

参数

w: *const Writer

std.Io.File.Writer.Mode

别名

第 21 行

别名目标 std.Io.File.Reader.Mode

std.Io.File.Writer.moveToReader

函数

第 77 行

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

参数

w: *Writer

std.Io.File.Writer.SeekError

别名

第 34 行

别名目标 std.Io.File.SeekError

std.Io.File.Writer.seekTo

函数

第 199 行

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

参数

w: *Writer
offset: u64

std.Io.File.Writer.seekToUnbuffered

函数

第 209 行

断言当前没有缓冲数据。

pub fn seekToUnbuffered(w: *Writer, offset: u64) SeekError!void

参数

w: *Writer
offset: u64

错误

AccessDenied SeekError

文件描述符不具备执行定位所需的权限。

Canceled Cancelable

调用方请求停止异步操作。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable SeekError

std.Io.File.Writer.sendFile

函数

第 134 行

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

参数

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

错误

EndOfStream

已到达正在读取的文件末尾。

ReadFailed

详细诊断信息位于 File.Reader 结构体上。

Unimplemented

表示调用方应自行读取文件;被调用方无法 提供更高效的实现。

WriteFailed

详细诊断信息见 Writer 实现。

std.Io.File.Writer.sendFilePositional

函数

第 145 行

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

参数

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

错误

EndOfStream

已到达正在读取的文件末尾。

ReadFailed

详细诊断信息位于 File.Reader 结构体上。

Unimplemented

表示调用方应自行读取文件;被调用方无法 提供更高效的实现。

WriteFailed

详细诊断信息见 Writer 实现。

std.Io.File.Writer.sendFileStreaming

函数

第 178 行

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

参数

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

错误

EndOfStream

已到达正在读取的文件末尾。

ReadFailed

详细诊断信息位于 File.Reader 结构体上。

Unimplemented

表示调用方应自行读取文件;被调用方无法 提供更高效的实现。

WriteFailed

详细诊断信息见 Writer 实现。

std.Io.File.Writer.std

别名

第 5 行

别名目标 std

std.Io.File.Writer.WriteFileError

错误集合

第 25 行

错误

AccessDenied Error

文件描述符没有写入所需的权限。

BrokenPipe Error

文件为未连接的套接字,或其读取端已关闭。

Canceled Cancelable

调用方请求停止异步操作。

CorruptedData

在 FreeBSD 上使用 copy_file_range 时可能发生。

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

进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。

NoDevice Error

写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。

NoSpaceLeft Error
NotOpenForWriting Error
PermissionDenied Error
ReadFailed
SystemResources Error

内核内存不足,无法从 in_fd 读取。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unimplemented

描述符无效或已锁定,或 in_fd 不支持类似 mmap(2) 的操作。

WouldBlock Error

已启用非阻塞模式,而此操作将阻塞。

std.Io.File.Writer.Writer

别名

第 1 行

别名目标 std.Io.File.Writer

源码

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,
/// 跟踪文件中的实际定位位置。
/// 要获取逻辑位置,请使用 `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{
    /// 描述符无效或已锁定,或 in_fd 不支持类似 mmap(2) 的操作。
    Unimplemented,
    /// 在 FreeBSD 上使用 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,
    };
}

/// 定位读取不影响全局查找位置,因此更便于线程安全使用。
/// 但若相应系统调用不可用,则预先初始化为
/// 流式模式可省去一次失败的系统调用。
pub fn initStreaming(file: File, io: Io, buffer: []u8) Writer {
    return .{
        .io = io,
        .file = file,
        .interface = initInterface(buffer),
        .mode = .streaming,
    };
}

/// 检测 `file` 是否为终端,并相应设置模式。
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;
}

/// 断言当前没有缓冲数据。
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;

/// 刷新所有已缓冲数据,并设置文件结束位置。
///
/// 如果不覆盖现有内容,直接调用 `interface.flush`
/// 即可。
///
/// 刷新失败时设置 `err`,以便与其他写入
/// 失败一并处理。
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,
        => {},
    }
}

/// 调用 `Io.Writer.flush` 并返回
/// 底层错误的便捷方法。
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());
}