跳转到内容

std.tar.Writer

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

第 1 行

字段

underlying_writer: *Io.Writer
prefix: []const u8 = ""

假定所有路径分隔符均使用 /。

std.tar.Writer.assert

别名

第 5 行

别名目标 std.debug.assert

std.tar.Writer.block_size

常量

第 8 行

std.tar.Writer.Error

错误集合

第 23 行

错误

NameTooLong
OctalOverflow
WriteFailed

std.tar.Writer.finishPedantically

函数

第 179 行

规范要求 tar 以两个零块结束,但 “合理的系统在读取归档时,不得假定此类块一定存在”。 因此,Zig 标准库建议不要调用此 函数。

pub fn finishPedantically(w: *Writer) Io.Writer.Error!void

参数

w: *Writer

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.tar.Writer.Header

容器

第 186 行

大小恰好为 512 字节、符合 tar 文件格式的结构体。用于输出 tar 文件;解析时使用 std.tar.Header。

字段

name: [100]u8 = @splat(0)
mode: [7:0]u8 = default_mode.file
uid: [7:0]u8 = @splat(0)
gid: [7:0]u8 = @splat(0)
size: [11:0]u8 = @splat('0')
mtime: [11:0]u8 = @splat('0')
checksum: [7:0]u8 = @splat(' ')
typeflag: FileType = .regular
linkname: [100]u8 = @splat(0)
magic: [6]u8 = .{ 'u', 's', 't', 'a', 'r', 0 }
version: [2]u8 = .{ '0', '0' }
uname: [32]u8 = @splat(0)
gname: [32]u8 = @splat(0)
devmajor: [7:0]u8 = @splat(0)
devminor: [7:0]u8 = @splat(0)
prefix: [155]u8 = @splat(0)
pad: [12]u8 = @splat(0)

std.tar.Writer.Header.default_mode

命名空间

第 222 行

std.tar.Writer.Header.default_mode.dir

常量

第 224 行

std.tar.Writer.Header.default_mode.file

常量

第 223 行

std.tar.Writer.Header.default_mode.other

常量

第 226 行

std.tar.Writer.Header.default_mode.sym_link

常量

第 225 行

std.tar.Writer.Header.FileType

容器

第 214 行

字段

regular = '0'
symbolic_link = '2'
directory = '5'
gnu_long_name = 'L'
gnu_long_link = 'K'

std.tar.Writer.Header.init

函数

第 229 行

pub fn init(typeflag: FileType) Header

参数

typeflag: FileType

std.tar.Writer.Header.octal

函数

第 245 行

fn octal(buf: []u8, value: u64) error{OctalOverflow}!void

参数

buf: []u8
value: u64

错误

OctalOverflow

std.tar.Writer.Header.setLinkname

函数

第 278 行

pub fn setLinkname(w: *Header, link: []const u8) !void

参数

w: *Header
link: []const u8

std.tar.Writer.Header.setMode

函数

第 257 行

pub fn setMode(w: *Header, mode: u32) error{OctalOverflow}!void

参数

w: *Header
mode: u32

错误

OctalOverflow

std.tar.Writer.Header.setMtime

函数

第 262 行

pub fn setMtime(w: *Header, mtime: u64) error{OctalOverflow}!void

参数

w: *Header
mtime: u64

错误

OctalOverflow

std.tar.Writer.Header.setPath

函数

第 283 行

pub fn setPath(w: *Header, prefix: []const u8, sub_path: []const u8) !void

参数

w: *Header
prefix: []const u8
sub_path: []const u8

std.tar.Writer.Header.setSize

函数

第 241 行

pub fn setSize(w: *Header, size: u64) error{OctalOverflow}!void

参数

w: *Header
size: u64

错误

OctalOverflow

std.tar.Writer.Header.updateChecksum

函数

第 266 行

pub fn updateChecksum(w: *Header) !void

参数

w: *Header

std.tar.Writer.Header.write

函数

第 273 行

pub fn write(h: *Header, bw: *Io.Writer) error{ OctalOverflow, WriteFailed }!void

参数

h: *Header
bw: *Io.Writer

错误

OctalOverflow
WriteFailed

std.tar.Writer.Io

别名

第 4 行

别名目标 std.Io

std.tar.Writer.Options

容器

第 12 行

写入文件/目录/链接的选项。留空时,文件模式 使用 0o664,mtime 使用当前时间。

字段

mode: u32 = 0

文件系统权限模式。

mtime: u64 = 0

文件系统修改时间。

std.tar.Writer.repeatString

函数

第 487 行

标记为 inline 以避免不必要的二进制浮点运算,因为参数始终在编译期已知。

inline fn repeatString(comptime n: usize, comptime str: []const u8) []const u8

参数

n: usize
str: []const u8

std.tar.Writer.setPath

函数

第 135 行

将路径写入 POSIX 头;若 name+prefix(100+155 字节) 无法容纳,则写入 GNU 扩展头。

fn setPath(w: *Writer, header: *Header, sub_path: []const u8) Error!void

参数

w: *Writer
header: *Header
sub_path: []const u8

错误

NameTooLong
OctalOverflow
WriteFailed

std.tar.Writer.setRoot

函数

第 31 行

为所有其他 write* 方法的路径设置前缀。 假定 root 中的路径分隔符均为 /。

pub fn setRoot(w: *Writer, root: []const u8) Error!void

参数

w: *Writer
root: []const u8

错误

NameTooLong
OctalOverflow
WriteFailed

std.tar.Writer.std

别名

第 3 行

别名目标 std

std.tar.Writer.testing

别名

第 6 行

别名目标 std.testing

std.tar.Writer.writeDir

函数

第 38 行

pub fn writeDir(w: *Writer, sub_path: []const u8, options: Options) Error!void

参数

w: *Writer
sub_path: []const u8
options: Options

错误

NameTooLong
OctalOverflow
WriteFailed

std.tar.Writer.writeExtendedHeader

函数

第 150 行

写入 gnu 扩展头:gnu_long_name 或 gnu_long_link。

fn writeExtendedHeader(w: *Writer, typeflag: Header.FileType, buffers: []const []const u8) Error!void

参数

w: *Writer
typeflag: Header.FileType
buffers: []const []const u8

错误

NameTooLong
OctalOverflow
WriteFailed

std.tar.Writer.writeFile

函数

第 54 行

pub fn writeFile( w: *Writer, sub_path: []const u8, file_reader: *Io.File.Reader, mtime: u64, ) WriteFileError!void

参数

w: *Writer
sub_path: []const u8

假定所有路径分隔符均使用 /。

file_reader: *Io.File.Reader
mtime: u64

若要符合文件格式要求,应使用自 POSIX 纪元起的 秒数。此处使用零也很合适, 可以提高生成 tar 包的可复现性。

错误

AccessDenied StatError

在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。

Canceled Cancelable

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

EndOfStream FileError

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

NameTooLong Error
OctalOverflow Error
PermissionDenied StatError
ReadFailed FileError

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

Streaming StatError

尝试对非文件流调用 stat。

SystemResources StatError
Unexpected UnexpectedError

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

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

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

Unimplemented FileError

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

WriteFailed FileError

详细诊断信息见 Writer 实现。

std.tar.Writer.writeFileBytes

函数

第 95 行

使用字节缓冲区 content 提供大小和内容,写入文件。

pub fn writeFileBytes( w: *Writer, sub_path: []const u8, content: []const u8, options: Options, ) Error!void

参数

w: *Writer
sub_path: []const u8

假定所有路径分隔符均为 /。

content: []const u8
options: Options

错误

NameTooLong
OctalOverflow
WriteFailed

std.tar.Writer.WriteFileError

错误集合

第 42 行

错误

AccessDenied StatError

在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。

Canceled Cancelable

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

EndOfStream FileError

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

NameTooLong Error
OctalOverflow Error
PermissionDenied StatError
ReadFailed FileError

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

Streaming StatError

尝试对非文件流调用 stat。

SystemResources StatError
Unexpected UnexpectedError

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

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

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

Unimplemented FileError

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

WriteFailed FileError

详细诊断信息见 Writer 实现。

std.tar.Writer.writeFileStream

函数

第 81 行

从 reader 读取文件内容并写入文件。恰好从 reader 读取 size 字节,否则返回 error.EndOfStream。

pub fn writeFileStream( w: *Writer, sub_path: []const u8, size: u64, reader: *Io.Reader, options: Options, ) WriteFileStreamError!void

参数

w: *Writer
sub_path: []const u8

假定所有路径分隔符均使用 /。

size: u64
reader: *Io.Reader
options: Options

错误

EndOfStream StreamError

Reader 指示流结束。此错误不会从 Writer 产生。

NameTooLong Error
OctalOverflow Error
ReadFailed StreamError

详细诊断参见 Reader 的实现。

WriteFailed StreamError

详细诊断信息见 Writer 实现。

std.tar.Writer.WriteFileStreamError

错误集合

第 77 行

错误

EndOfStream StreamError

Reader 指示流结束。此错误不会从 Writer 产生。

NameTooLong Error
OctalOverflow Error
ReadFailed StreamError

详细诊断参见 Reader 的实现。

WriteFailed StreamError

详细诊断信息见 Writer 实现。

std.tar.Writer.writeFileTimestamp

函数

第 44 行

pub fn writeFileTimestamp( w: *Writer, sub_path: []const u8, file_reader: *Io.File.Reader, mtime: Io.Timestamp, ) WriteFileError!void

参数

w: *Writer
sub_path: []const u8

假定所有路径分隔符均使用 /。

file_reader: *Io.File.Reader
mtime: Io.Timestamp

错误

AccessDenied StatError

在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。

Canceled Cancelable

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

EndOfStream FileError

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

NameTooLong Error
OctalOverflow Error
PermissionDenied StatError
ReadFailed FileError

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

Streaming StatError

尝试对非文件流调用 stat。

SystemResources StatError
Unexpected UnexpectedError

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

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

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

Unimplemented FileError

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

WriteFailed FileError

详细诊断信息见 Writer 实现。

std.tar.Writer.writeHeader

函数

第 111 行

fn writeHeader( w: *Writer, typeflag: Header.FileType, sub_path: []const u8, link_name: []const u8, size: u64, options: Options, ) Error!void

参数

w: *Writer
typeflag: Header.FileType
sub_path: []const u8
link_name: []const u8
size: u64
options: Options

错误

NameTooLong
OctalOverflow
WriteFailed

std.tar.Writer.writeLink

函数

第 107 行

pub fn writeLink(w: *Writer, sub_path: []const u8, link_name: []const u8, options: Options) Error!void

参数

w: *Writer
sub_path: []const u8
link_name: []const u8
options: Options

错误

NameTooLong
OctalOverflow
WriteFailed

std.tar.Writer.writePadding

函数

第 162 行

fn writePadding(w: *Writer, bytes: usize) Io.Writer.Error!void

参数

w: *Writer
bytes: usize

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.tar.Writer.writePadding64

函数

第 166 行

fn writePadding64(w: *Writer, bytes: u64) Io.Writer.Error!void

参数

w: *Writer
bytes: u64

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.tar.Writer.writePaddingPos

函数

第 170 行

fn writePaddingPos(w: *Writer, pos: usize) Io.Writer.Error!void

参数

w: *Writer
pos: usize

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.tar.Writer.Writer

别名

第 1 行

别名目标 std.tar.Writer

源码

std/tar/Writer.zig

const Writer = @This();

const std = @import("std");
const Io = std.Io;
const assert = std.debug.assert;
const testing = std.testing;

const block_size = @sizeOf(Header);

/// 写入文件/目录/链接的选项。留空时,文件模式
/// 使用 0o664,mtime 使用当前时间。
pub const Options = struct {
    /// 文件系统权限模式。
    mode: u32 = 0,
    /// 文件系统修改时间。
    mtime: u64 = 0,
};

underlying_writer: *Io.Writer,
/// 假定所有路径分隔符均使用 `/`。
prefix: []const u8 = "",

const Error = error{
    WriteFailed,
    OctalOverflow,
    NameTooLong,
};

/// 为所有其他 write* 方法的路径设置前缀。
/// 假定 `root` 中的路径分隔符均为 `/`。
pub fn setRoot(w: *Writer, root: []const u8) Error!void {
    if (root.len > 0)
        try w.writeDir(root, .{});

    w.prefix = root;
}

pub fn writeDir(w: *Writer, sub_path: []const u8, options: Options) Error!void {
    try w.writeHeader(.directory, sub_path, "", 0, options);
}

pub const WriteFileError = Io.Writer.FileError || Error || Io.File.Reader.SizeError;

pub fn writeFileTimestamp(
    w: *Writer,
    /// 假定所有路径分隔符均使用 `/`。
    sub_path: []const u8,
    file_reader: *Io.File.Reader,
    mtime: Io.Timestamp,
) WriteFileError!void {
    return writeFile(w, sub_path, file_reader, @intCast(mtime.toSeconds()));
}

pub fn writeFile(
    w: *Writer,
    /// 假定所有路径分隔符均使用 `/`。
    sub_path: []const u8,
    file_reader: *Io.File.Reader,
    /// 若要符合文件格式要求,应使用自 POSIX 纪元起的
    /// 秒数。此处使用零也很合适,
    /// 可以提高生成 tar 包的可复现性。
    mtime: u64,
) WriteFileError!void {
    const size = try file_reader.getSize();

    var header: Header = .{};
    try w.setPath(&header, sub_path);
    try header.setSize(size);
    try header.setMtime(mtime);
    try header.updateChecksum();

    try w.underlying_writer.writeAll(@ptrCast((&header)[0..1]));
    _ = try w.underlying_writer.sendFileAll(file_reader, .unlimited);
    try w.writePadding64(size);
}

pub const WriteFileStreamError = Error || Io.Reader.StreamError;

/// 从 `reader` 读取文件内容并写入文件。恰好从 `reader` 读取 `size` 字节,否则返回 `error.EndOfStream`。
///
pub fn writeFileStream(
    w: *Writer,
    /// 假定所有路径分隔符均使用 `/`。
    sub_path: []const u8,
    size: u64,
    reader: *Io.Reader,
    options: Options,
) WriteFileStreamError!void {
    try w.writeHeader(.regular, sub_path, "", size, options);
    try reader.streamExact64(w.underlying_writer, size);
    try w.writePadding64(size);
}

/// 使用字节缓冲区 `content` 提供大小和内容,写入文件。
pub fn writeFileBytes(
    w: *Writer,
    /// 假定所有路径分隔符均为 `/`。
    sub_path: []const u8,
    content: []const u8,
    options: Options,
) Error!void {
    try w.writeHeader(.regular, sub_path, "", content.len, options);
    try w.underlying_writer.writeAll(content);
    try w.writePadding(content.len);
}

pub fn writeLink(w: *Writer, sub_path: []const u8, link_name: []const u8, options: Options) Error!void {
    try w.writeHeader(.symbolic_link, sub_path, link_name, 0, options);
}

fn writeHeader(
    w: *Writer,
    typeflag: Header.FileType,
    sub_path: []const u8,
    link_name: []const u8,
    size: u64,
    options: Options,
) Error!void {
    var header = Header.init(typeflag);
    try w.setPath(&header, sub_path);
    try header.setSize(size);
    try header.setMtime(options.mtime);
    if (options.mode != 0)
        try header.setMode(options.mode);
    if (typeflag == .symbolic_link)
        header.setLinkname(link_name) catch |err| switch (err) {
            error.NameTooLong => try w.writeExtendedHeader(.gnu_long_link, &.{link_name}),
            else => |e| return e,
        };
    try header.write(w.underlying_writer);
}

/// 将路径写入 POSIX 头;若 name+prefix(100+155 字节)
/// 无法容纳,则写入 GNU 扩展头。
fn setPath(w: *Writer, header: *Header, sub_path: []const u8) Error!void {
    header.setPath(w.prefix, sub_path) catch |err| switch (err) {
        error.NameTooLong => {
            // 写入扩展头部
            const buffers: []const []const u8 = if (w.prefix.len == 0)
                &.{sub_path}
            else
                &.{ w.prefix, "/", sub_path };
            try w.writeExtendedHeader(.gnu_long_name, buffers);
        },
        else => |e| return e,
    };
}

/// 写入 gnu 扩展头:gnu_long_name 或 gnu_long_link。
fn writeExtendedHeader(w: *Writer, typeflag: Header.FileType, buffers: []const []const u8) Error!void {
    var len: usize = 0;
    for (buffers) |buf| len += buf.len;

    var header: Header = .init(typeflag);
    try header.setSize(len);
    try header.write(w.underlying_writer);
    for (buffers) |buf|
        try w.underlying_writer.writeAll(buf);
    try w.writePadding(len);
}

fn writePadding(w: *Writer, bytes: usize) Io.Writer.Error!void {
    return writePaddingPos(w, bytes % block_size);
}

fn writePadding64(w: *Writer, bytes: u64) Io.Writer.Error!void {
    return writePaddingPos(w, @intCast(bytes % block_size));
}

fn writePaddingPos(w: *Writer, pos: usize) Io.Writer.Error!void {
    if (pos == 0) return;
    try w.underlying_writer.splatByteAll(0, block_size - pos);
}

/// 规范要求 tar 以两个零块结束,但
/// “合理的系统在读取归档时,不得假定此类块一定存在”。
/// 因此,Zig 标准库建议不要调用此
/// 函数。
pub fn finishPedantically(w: *Writer) Io.Writer.Error!void {
    try w.underlying_writer.splatByteAll(0, block_size * 2);
}

/// 大小恰好为 512 字节、符合 tar 文件格式的结构体。用于输出 tar 文件;解析时使用 `std.tar.Header`。
///
///
pub const Header = extern struct {
    // 此结构体最初复制自
    // https://github.com/mattnite/tar/blob/main/src/main.zig ,该项目采用 MIT
    // 许可证。
    //
    // name、linkname、magic、uname 和 gname 是以空字符结尾的
    // 字符串。其余所有字段都是以零填充的 ASCII 八进制数。每个
    // 宽度为 w 的数字字段包含 w 减 1 个数字及一个空字符。
    // 参考:https://www.gnu.org/software/tar/manual/html_node/Standard.html
    // POSIX 头部:                                  字节偏移量
    name: [100]u8 = @splat(0), //                               0
    mode: [7:0]u8 = default_mode.file, //                     100
    uid: [7:0]u8 = @splat(0), // 未使用                       108
    gid: [7:0]u8 = @splat(0), // unused                       116
    size: [11:0]u8 = @splat('0'), //                          124
    mtime: [11:0]u8 = @splat('0'), //                         136
    checksum: [7:0]u8 = @splat(' '), //                       148
    typeflag: FileType = .regular, //                         156
    linkname: [100]u8 = @splat(0), //                         157
    magic: [6]u8 = .{ 'u', 's', 't', 'a', 'r', 0 }, //        257
    version: [2]u8 = .{ '0', '0' }, //                        263
    uname: [32]u8 = @splat(0), // unused                      265
    gname: [32]u8 = @splat(0), // 未使用                      297
    devmajor: [7:0]u8 = @splat(0), // 未使用                  329
    devminor: [7:0]u8 = @splat(0), // 未使用                  337
    prefix: [155]u8 = @splat(0), //                           345
    pad: [12]u8 = @splat(0), // unused                        500

    pub const FileType = enum(u8) {
        regular = '0',
        symbolic_link = '2',
        directory = '5',
        gnu_long_name = 'L',
        gnu_long_link = 'K',
    };

    const default_mode = struct {
        const file = [_:0]u8{ '0', '0', '0', '0', '6', '6', '4' }; // 0o664
        const dir = [_:0]u8{ '0', '0', '0', '0', '7', '7', '5' }; // 0o775
        const sym_link = [_:0]u8{ '0', '0', '0', '0', '7', '7', '7' }; // 0o777
        const other = [_:0]u8{ '0', '0', '0', '0', '0', '0', '0' }; // 0o000
    };

    pub fn init(typeflag: FileType) Header {
        return .{
            .typeflag = typeflag,
            .mode = switch (typeflag) {
                .directory => default_mode.dir,
                .symbolic_link => default_mode.sym_link,
                .regular => default_mode.file,
                else => default_mode.other,
            },
        };
    }

    pub fn setSize(w: *Header, size: u64) error{OctalOverflow}!void {
        try octal(&w.size, size);
    }

    fn octal(buf: []u8, value: u64) error{OctalOverflow}!void {
        var remainder: u64 = value;
        var pos: usize = buf.len;
        while (remainder > 0 and pos > 0) {
            pos -= 1;
            const c: u8 = @as(u8, @intCast(remainder % 8)) + '0';
            buf[pos] = c;
            remainder /= 8;
            if (pos == 0 and remainder > 0) return error.OctalOverflow;
        }
    }

    pub fn setMode(w: *Header, mode: u32) error{OctalOverflow}!void {
        try octal(&w.mode, mode);
    }

    // 自协调世界时 1970 年 1 月 1 日 00:00 起的整数秒数。
    pub fn setMtime(w: *Header, mtime: u64) error{OctalOverflow}!void {
        try octal(&w.mtime, mtime);
    }

    pub fn updateChecksum(w: *Header) !void {
        var checksum: usize = ' '; // w.checksum 的其他 7 个字节初始化为 ' '
        for (std.mem.asBytes(w)) |val|
            checksum += val;
        try octal(&w.checksum, checksum);
    }

    pub fn write(h: *Header, bw: *Io.Writer) error{ OctalOverflow, WriteFailed }!void {
        try h.updateChecksum();
        try bw.writeAll(std.mem.asBytes(h));
    }

    pub fn setLinkname(w: *Header, link: []const u8) !void {
        if (link.len > w.linkname.len) return error.NameTooLong;
        @memcpy(w.linkname[0..link.len], link);
    }

    pub fn setPath(w: *Header, prefix: []const u8, sub_path: []const u8) !void {
        const max_prefix = w.prefix.len;
        const max_name = w.name.len;
        const sep = std.fs.path.sep_posix;

        if (prefix.len + sub_path.len > max_name + max_prefix or prefix.len > max_prefix)
            return error.NameTooLong;

        // 两者均能放入名称
        if (prefix.len > 0 and prefix.len + sub_path.len < max_name) {
            @memcpy(w.name[0..prefix.len], prefix);
            w.name[prefix.len] = sep;
            @memcpy(w.name[prefix.len + 1 ..][0..sub_path.len], sub_path);
            return;
        }

        // sub_path 能放入 name。
        // 不存在前缀,或前缀能放入 prefix。
        if (sub_path.len <= max_name) {
            @memcpy(w.name[0..sub_path.len], sub_path);
            @memcpy(w.prefix[0..prefix.len], prefix);
            return;
        }

        if (prefix.len > 0) {
            @memcpy(w.prefix[0..prefix.len], prefix);
            w.prefix[prefix.len] = sep;
        }
        const prefix_pos = if (prefix.len > 0) prefix.len + 1 else 0;

        // 尽可能多地添加到 prefix,必须在 / 处拆分。
        const prefix_remaining = max_prefix - prefix_pos;
        if (std.mem.findLast(u8, sub_path[0..@min(prefix_remaining, sub_path.len)], &.{'/'})) |sep_pos| {
            @memcpy(w.prefix[prefix_pos..][0..sep_pos], sub_path[0..sep_pos]);
            if ((sub_path.len - sep_pos - 1) > max_name) return error.NameTooLong;
            @memcpy(w.name[0..][0 .. sub_path.len - sep_pos - 1], sub_path[sep_pos + 1 ..]);
            return;
        }

        return error.NameTooLong;
    }

    comptime {
        assert(@sizeOf(Header) == 512);
    }

    test "setPath" {
        const cases = [_]struct {
            in: []const []const u8,
            out: []const []const u8,
        }{
            .{
                .in = &.{ "", "123456789" },
                .out = &.{ "", "123456789" },
            },
            // 能放入 name
            .{
                .in = &.{ "prefix", "sub_path" },
                .out = &.{ "", "prefix/sub_path" },
            },
            // 两者不再都能放入名称中
            .{
                .in = &.{ "prefix", repeatString(8, "0123456789/") ++ "basename" },
                .out = &.{ "prefix", repeatString(8, "0123456789/") ++ "basename" },
            },
            // 尽可能多地放入 prefix,其余放入 name
            .{
                .in = &.{ "prefix", repeatString(10, "0123456789/") ++ "basename" },
                .out = &.{ "prefix/" ++ repeatString(9, "0123456789/") ++ "0123456789", "basename" },
            },

            .{
                .in = &.{ "prefix", repeatString(15, "0123456789/") ++ "basename" },
                .out = &.{ "prefix/" ++ repeatString(12, "0123456789/") ++ "0123456789", "0123456789/0123456789/basename" },
            },
            .{
                .in = &.{ "prefix", repeatString(21, "0123456789/") ++ "basename" },
                .out = &.{ "prefix/" ++ repeatString(12, "0123456789/") ++ "0123456789", repeatString(8, "0123456789/") ++ "basename" },
            },
            .{
                .in = &.{ "", repeatString(10, "012345678/") ++ "foo" },
                .out = &.{ repeatString(9, "012345678/") ++ "012345678", "foo" },
            },
        };

        for (cases) |case| {
            var header = Header.init(.regular);
            try header.setPath(case.in[0], case.in[1]);
            try testing.expectEqualStrings(case.out[0], std.mem.sliceTo(&header.prefix, 0));
            try testing.expectEqualStrings(case.out[1], std.mem.sliceTo(&header.name, 0));
        }

        const error_cases = [_]struct {
            in: []const []const u8,
        }{
            // basename 无法放入 name(106 个字符)
            .{ .in = &.{ "zig", "test/cases/compile_errors/regression_test_2980_base_type_u32_is_not_type_checked_properly_when_assigning_a_value_within_a_struct.zig" } },
            // 无法容纳于 255 + sep
            .{ .in = &.{ "prefix", repeatString(22, "0123456789/") ++ "basename" } },
            // 可以容纳,但 sub_path 无法拆分(没有分隔符)
            .{ .in = &.{ "prefix", repeatString(10, "0123456789") ++ "a" } },
            .{ .in = &.{ "prefix", repeatString(14, "0123456789") ++ "basename" } },
        };

        for (error_cases) |case| {
            var header = Header.init(.regular);
            try testing.expectError(
                error.NameTooLong,
                header.setPath(case.in[0], case.in[1]),
            );
        }
    }
};

test {
    _ = Header;
}

test "write files" {
    const files = [_]struct {
        path: []const u8,
        content: []const u8,
    }{
        .{ .path = "foo", .content = "bar" },
        .{ .path = repeatString(10, "a12345678/") ++ "foo", .content = repeatString(511, "a") },
        .{ .path = repeatString(24, "b12345678/") ++ "foo", .content = repeatString(512, "b") },
        .{ .path = repeatString(25, "c12345678/") ++ "foo", .content = repeatString(513, "c") },
        .{ .path = repeatString(51, "d12345678/") ++ "foo", .content = repeatString(1025, "d") },
        .{ .path = repeatString(11, "e123456789"), .content = "e" },
    };

    var file_name_buffer: [std.fs.max_path_bytes]u8 = undefined;
    var link_name_buffer: [std.fs.max_path_bytes]u8 = undefined;

    // 带根节点
    {
        const root = "root";

        var output: Io.Writer.Allocating = .init(testing.allocator);
        var w: Writer = .{ .underlying_writer = &output.writer };
        defer output.deinit();
        try w.setRoot(root);
        for (files) |file|
            try w.writeFileBytes(file.path, file.content, .{});

        var input: Io.Reader = .fixed(output.written());
        var it: std.tar.Iterator = .init(&input, .{
            .file_name_buffer = &file_name_buffer,
            .link_name_buffer = &link_name_buffer,
        });

        // 首个条目为带前缀的目录
        {
            const actual = (try it.next()).?;
            try testing.expectEqualStrings(root, actual.name);
            try testing.expectEqual(std.tar.FileKind.directory, actual.kind);
        }

        var i: usize = 0;
        while (try it.next()) |actual| {
            defer i += 1;
            const expected = files[i];
            try testing.expectEqualStrings(root, actual.name[0..root.len]);
            try testing.expectEqual('/', actual.name[root.len..][0]);
            try testing.expectEqualStrings(expected.path, actual.name[root.len + 1 ..]);

            var content: Io.Writer.Allocating = .init(testing.allocator);
            defer content.deinit();
            try it.streamRemaining(actual, &content.writer);
            try testing.expectEqualSlices(u8, expected.content, content.written());
        }
    }
    // 不包含根
    {
        var output: Io.Writer.Allocating = .init(testing.allocator);
        var w: Writer = .{ .underlying_writer = &output.writer };
        defer output.deinit();
        for (files) |file| {
            var content: Io.Reader = .fixed(file.content);
            try w.writeFileStream(file.path, file.content.len, &content, .{});
        }

        var input: Io.Reader = .fixed(output.written());
        var it: std.tar.Iterator = .init(&input, .{
            .file_name_buffer = &file_name_buffer,
            .link_name_buffer = &link_name_buffer,
        });

        var i: usize = 0;
        while (try it.next()) |actual| {
            defer i += 1;
            const expected = files[i];
            try testing.expectEqualStrings(expected.path, actual.name);

            var content: Io.Writer.Allocating = .init(testing.allocator);
            defer content.deinit();
            try it.streamRemaining(actual, &content.writer);
            try testing.expectEqualSlices(u8, expected.content, content.written());
        }
        try w.finishPedantically();
    }
}

/// 标记为 `inline` 以避免不必要的二进制浮点运算,因为参数始终在编译期已知。
inline fn repeatString(comptime n: usize, comptime str: []const u8) []const u8 {
    const buf: [n][str.len]u8 = @splat(str[0..str.len].*);
    return @ptrCast(&buf);
}