字段
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
别名
别名目标 std.debug.assert
std.Io.File.Writer.builtin
常量
std.Io.File.Writer.drain
函数
pub fn drain(io_w: *Io.Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize
参数
错误
- WriteFailed
详细诊断信息见
Writer实现。
std.Io.File.Writer.drainPositional
函数
fn drainPositional(w: *Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize
参数
错误
- WriteFailed
详细诊断信息见
Writer实现。
std.Io.File.Writer.drainStreaming
函数
fn drainStreaming(w: *Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize
参数
错误
- WriteFailed
详细诊断信息见
Writer实现。
std.Io.File.Writer.end
函数
刷新所有已缓冲数据,并设置文件结束位置。
如果不覆盖现有内容,直接调用 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
错误集合
错误
- 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
错误集合
错误
- 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
别名
别名目标 std.Io.File
std.Io.File.Writer.flush
函数
调用 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
函数
pub fn init(file: File, io: Io, buffer: []u8) Writer
参数
std.Io.File.Writer.initDetect
函数
检测 file 是否为终端,并相应设置模式。
pub fn initDetect(file: File, io: Io, buffer: []u8) Io.Cancelable!Writer
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.File.Writer.initInterface
函数
pub fn initInterface(buffer: []u8) Io.Writer
参数
buffer: []u8
std.Io.File.Writer.initStreaming
函数
定位读取不影响全局查找位置,因此更便于线程安全使用。 但若相应系统调用不可用,则预先初始化为 流式模式可省去一次失败的系统调用。
pub fn initStreaming(file: File, io: Io, buffer: []u8) Writer
参数
std.Io.File.Writer.Io
别名
别名目标 std.Io
std.Io.File.Writer.is_windows
常量
std.Io.File.Writer.logicalPos
函数
pub fn logicalPos(w: *const Writer) u64
参数
w: *const Writer
std.Io.File.Writer.Mode
别名
std.Io.File.Writer.moveToReader
函数
pub fn moveToReader(w: *Writer) File.Reader
参数
w: *Writer
std.Io.File.Writer.SeekError
别名
std.Io.File.Writer.seekTo
函数
pub fn seekTo(w: *Writer, offset: u64) (SeekError || Io.Writer.Error)!void
参数
w: *Writer
offset: u64
std.Io.File.Writer.seekToUnbuffered
函数
断言当前没有缓冲数据。
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
函数
pub fn sendFile(io_w: *Io.Writer, file_reader: *Io.File.Reader, limit: Io.Limit) Io.Writer.FileError!usize
参数
错误
- EndOfStream
已到达正在读取的文件末尾。
- ReadFailed
详细诊断信息位于
File.Reader结构体上。- Unimplemented
表示调用方应自行读取文件;被调用方无法 提供更高效的实现。
- WriteFailed
详细诊断信息见
Writer实现。
std.Io.File.Writer.sendFilePositional
函数
fn sendFilePositional(w: *Writer, file_reader: *Io.File.Reader, limit: Io.Limit) Io.Writer.FileError!usize
参数
错误
- EndOfStream
已到达正在读取的文件末尾。
- ReadFailed
详细诊断信息位于
File.Reader结构体上。- Unimplemented
表示调用方应自行读取文件;被调用方无法 提供更高效的实现。
- WriteFailed
详细诊断信息见
Writer实现。
std.Io.File.Writer.sendFileStreaming
函数
fn sendFileStreaming(w: *Writer, file_reader: *Io.File.Reader, limit: Io.Limit) Io.Writer.FileError!usize
参数
错误
- EndOfStream
已到达正在读取的文件末尾。
- ReadFailed
详细诊断信息位于
File.Reader结构体上。- Unimplemented
表示调用方应自行读取文件;被调用方无法 提供更高效的实现。
- WriteFailed
详细诊断信息见
Writer实现。
std.Io.File.Writer.std
别名
别名目标 std
std.Io.File.Writer.WriteFileError
错误集合
错误
- 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
别名
别名目标 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.?,
};
}