package tar

import "archive/tar"

Package tar 实现了对 tar 存档的访问。

磁带存档(tar)是一种用于存储文件序列的文件格式,可以以流式方式读取和写入。 本包旨在覆盖该格式的大多数变体,包括由 GNU 和 BSD tar 工具生成的格式。

Example (Minimal)
package main

import (
	"archive/tar"
	"bytes"
	"fmt"
	"io"
	"log"
	"os"
)

func main() {
	// Create and add some files to the archive.
	var buf bytes.Buffer
	tw := tar.NewWriter(&buf)
	var files = []struct {
		Name, Body string
	}{
		{"readme.txt", "This archive contains some text files."},
		{"gopher.txt", "Gopher names:\nGeorge\nGeoffrey\nGonzo"},
		{"todo.txt", "Get animal handling license."},
	}
	for _, file := range files {
		hdr := &tar.Header{
			Name: file.Name,
			Mode: 0600,
			Size: int64(len(file.Body)),
		}
		if err := tw.WriteHeader(hdr); err != nil {
			log.Fatal(err)
		}
		if _, err := tw.Write([]byte(file.Body)); err != nil {
			log.Fatal(err)
		}
	}
	if err := tw.Close(); err != nil {
		log.Fatal(err)
	}

	// Open and iterate through the files in the archive.
	tr := tar.NewReader(&buf)
	for {
		hdr, err := tr.Next()
		if err == io.EOF {
			break // End of archive
		}
		if err != nil {
			log.Fatal(err)
		}
		fmt.Printf("Contents of %s:\n", hdr.Name)
		if _, err := io.Copy(os.Stdout, tr); err != nil {
			log.Fatal(err)
		}
		fmt.Println()
	}

}

Output:

Contents of readme.txt:
This archive contains some text files.
Contents of gopher.txt:
Gopher names:
George
Geoffrey
Gonzo
Contents of todo.txt:
Get animal handling license.

Index

Examples

Constants

const (
	// 类型 '0' 表示普通文件。
	TypeReg = '0'

	// 已弃用:请使用 TypeReg 代替。
	TypeRegA = '\x00'

	// 类型 '1' 到 '6' 是仅头标志,可能没有数据体。
	TypeLink    = '1' // 硬链接
	TypeSymlink = '2' // 符号链接
	TypeChar    = '3' // 字符设备节点
	TypeBlock   = '4' // 块设备节点
	TypeDir     = '5' // 目录
	TypeFifo    = '6' // FIFO 节点

	// 类型 '7' 是保留的。
	TypeCont = '7'

	// 类型 'x' 用于 PAX 格式,存储仅与下一个文件相关的键值记录。
	// 本包透明地处理这些类型。
	TypeXHeader = 'x'

	// 类型 'g' 用于 PAX 格式,存储与所有后续文件相关的键值记录。
	// 本包仅支持解析和组合此类头部,但当前不支持跨文件持久化全局状态。
	TypeXGlobalHeader = 'g'

	// 类型 'S' 表示 GNU 格式中的稀疏文件。
	TypeGNUSparse = 'S'

	// 类型 'L' 和 'K' 用于 GNU 格式的元文件,用于存储下一个文件的路径或链接名。
	// 本包透明地处理这些类型。
	TypeGNULongName = 'L'
	TypeGNULongLink = 'K'
)

Header.Typeflag 的类型标志。

Variables

var (
	ErrHeader          = errors.New("archive/tar: invalid tar header")
	ErrWriteTooLong    = errors.New("archive/tar: write too long")
	ErrFieldTooLong    = errors.New("archive/tar: header field too long")
	ErrWriteAfterClose = errors.New("archive/tar: write after close")
	ErrInsecurePath    = errors.New("archive/tar: insecure file path")
)

Types

type FileInfoNames

type FileInfoNames interface {
	fs.FileInfo
	// Uname 应返回用户名。
	Uname() (string, error)
	// Gname 应返回组名。
	Gname() (string, error)
}

FileInfoNames 扩展了 fs.FileInfo。 将其实例传递给 FileInfoHeader 允许调用者通过直接指定 Uname 和 Gname 来避免系统相关的名称查找。

type Format

type Format int

Format 表示 tar 归档格式。

最初的 tar 格式在 Unix V7 中引入。 此后,出现了多种相互竞争的格式,试图标准化或扩展 V7 格式以克服其局限性。 最常见的格式是 USTAR、PAX 和 GNU 格式, 它们各有自己的优势和局限。

下表列出了每种格式的能力:

                  |  USTAR |       PAX |       GNU
------------------+--------+-----------+----------
Name              |   256B | unlimited | unlimited
Linkname          |   100B | unlimited | unlimited
Size              | uint33 | unlimited |    uint89
Mode              | uint21 |    uint21 |    uint57
Uid/Gid           | uint21 | unlimited |    uint57
Uname/Gname       |    32B | unlimited |       32B
ModTime           | uint33 | unlimited |     int89
AccessTime        |    n/a | unlimited |     int89
ChangeTime        |    n/a | unlimited |     int89
Devmajor/Devminor | uint21 |    uint21 |    uint57
------------------+--------+-----------+----------
string encoding   |  ASCII |     UTF-8 |    binary
sub-second times  |     no |       yes |        no
sparse files      |     no |       yes |       yes

表格的上半部分展示了 Header 字段,其中每种格式报告了 每个字符串字段所允许的最大字节数,以及 用于存储每个数值字段的整数类型 (其中时间戳存储为自 Unix 纪元以来的秒数)。

表格的下半部分展示了每种格式的专门特性, 例如支持的字符串编码、对亚秒级时间戳的支持, 或对稀疏文件的支持。

Writer 当前不支持稀疏文件。

const (

	// FormatUnknown 表示格式未知。
	FormatUnknown Format

	// FormatUSTAR 表示 POSIX.1-1988 中定义的 USTAR 头部格式。
	//
	// 虽然此格式与大多数 tar 读取器兼容,
	// 但该格式有一些局限性,使其不适用于某些用途。
	// 最显著的是,它不支持稀疏文件、大于 8GiB 的文件、
	// 长度超过 256 个字符的文件名,以及非 ASCII 文件名。
	//
	// 参考:
	//	http://pubs.opengroup.org/onlinepubs/9699919799/utilities/pax.html#tag_20_92_13_06
	FormatUSTAR

	// FormatPAX 表示 POSIX.1-2001 中定义的 PAX 头部格式。
	//
	// PAX 通过在原头部之前写入一个 Typeflag 为 TypeXHeader
	// 的特殊文件来扩展 USTAR。该文件包含一组键值
	// 记录,用于克服 USTAR 的缺点,此外还
	// 提供了对时间戳进行亚秒级分辨率处理的能力。
	//
	// 一些较新的格式通过定义各自的
	// 键并赋予关联值特定语义,为 PAX 添加自己的扩展。
	// 例如,PAX 中的稀疏文件支持是通过 GNU 手册
	// 定义的键(例如 "GNU.sparse.map")实现的。
	//
	// 参考:
	//	http://pubs.opengroup.org/onlinepubs/009695399/utilities/pax.html
	FormatPAX

	// FormatGNU 表示 GNU 头部格式。
	//
	// GNU 头部格式比 USTAR 和 PAX 标准更早,且
	// 与它们不兼容。GNU 格式支持
	// 任意文件大小、任意编码和长度的文件名、
	// 稀疏文件以及其他特性。
	//
	// 建议优先选择 PAX 而非 GNU,除非目标
	// 应用程序只能解析 GNU 格式的归档。
	//
	// 参考:
	//	https://www.gnu.org/software/tar/manual/html_node/Standard.html
	FormatGNU
)

用于标识各种 tar 格式的常量。

func (Format) String
func (f Format) String() string
type Header struct {
	// Typeflag 是头部条目的类型。
	// 零值会根据 Name 中是否存在尾部斜杠自动提升为 TypeReg 或 TypeDir。
	Typeflag byte

	Name     string // 文件条目的名称
	Linkname string // 链接的目标名称(对 TypeLink 或 TypeSymlink 有效)

	Size  int64  // 逻辑文件大小(字节)
	Mode  int64  // 权限和模式位
	Uid   int    // 所有者的用户 ID
	Gid   int    // 所有者的组 ID
	Uname string // 所有者的用户名
	Gname string // 所有者的组名

	// 如果 Format 未指定,则 Writer.WriteHeader 会将 ModTime
	// 舍入到最接近的秒,并忽略 AccessTime 和 ChangeTime 字段。
	//
	// 要使用 AccessTime 或 ChangeTime,请将 Format 指定为 PAX 或 GNU。
	// 要使用亚秒级精度,请将 Format 指定为 PAX。
	ModTime    time.Time // 修改时间
	AccessTime time.Time // 访问时间(需要 PAX 或 GNU 支持)
	ChangeTime time.Time // 变更时间(需要 PAX 或 GNU 支持)

	Devmajor int64 // 主设备号(对 TypeChar 或 TypeBlock 有效)
	Devminor int64 // 次设备号(对 TypeChar 或 TypeBlock 有效)

	// Xattrs 在 "SCHILY.xattr." 命名空间下以 PAX 记录存储扩展属性。
	//
	// 以下在语义上是等价的:
	//  h.Xattrs[key] = value
	//  h.PAXRecords["SCHILY.xattr."+key] = value
	//
	// 调用 Writer.WriteHeader 时,Xattrs 的内容将优先于 PAXRecords 中的内容。
	//
	// 已弃用:请使用 PAXRecords 代替。
	Xattrs map[string]string

	// PAXRecords 是 PAX 扩展头部记录的映射。
	//
	// 用户定义的记录应具有以下形式的键:
	//	VENDOR.keyword
	// 其中 VENDOR 是全大写的某个命名空间,keyword 不得包含 '=' 字符(例如 "GOLANG.pkg.version")。
	// 键和值应为非空的 UTF-8 字符串。
	//
	// 调用 Writer.WriteHeader 时,从 Header 的其他字段派生的 PAX 记录优先于 PAXRecords。
	PAXRecords map[string]string

	// Format 指定 tar 头部的格式。
	//
	// 这由 Reader.Next 设置为对格式的最佳猜测。
	// 由于 Reader 宽松地读取一些不兼容的文件,这可能为 FormatUnknown。
	//
	// 如果在调用 Writer.WriteHeader 时未指定格式,
	// 则它使用能够编码此 Header 的第一种格式(按 USTAR、PAX、GNU 的顺序)(参见 Format)。
	Format Format
}

Header 表示 tar 存档中的单个头部。 某些字段可能未填充。

为了向前兼容,从 Reader.Next 获取 Header 的用户, 以某种方式修改它,然后将其传回 Writer.WriteHeader 时, 应通过创建一个新的 Header 并复制他们希望保留的字段来实现。

func FileInfoHeader
func FileInfoHeader(fi fs.FileInfo, link string) (*Header, error)

FileInfoHeader 从 fi 创建一个部分填充的 Header。 如果 fi 描述一个符号链接,FileInfoHeader 将 link 记录为链接目标。 如果 fi 描述一个目录,则在名称后附加斜杠。

由于 fs.FileInfo 的 Name 方法仅返回它所描述文件的基本名称, 可能需要修改 Header.Name 以提供文件的完整路径名。

如果 fi 实现了 FileInfoNames,则 Header.Gname 和 Header.Uname 由该接口的方法提供。

func (*Header) FileInfo
func (h *Header) FileInfo() fs.FileInfo

FileInfo 返回 Header 的 fs.FileInfo。

type Reader

type Reader struct {
	// contains filtered or unexported fields
}

Reader 提供对 tar 归档内容的顺序访问。 Reader.Next 前进到归档中的下一个文件(包括第一个), 此后 Reader 可当作 io.Reader 来访问该文件的数据。

func NewReader
func NewReader(r io.Reader) *Reader

NewReader 创建一个从 r 读取的新 Reader。

func (*Reader) Next
func (tr *Reader) Next() (*Header, error)

Next 前进到 tar 归档中的下一个条目。 Header.Size 决定下一个文件可以读取多少字节。 当前文件中任何剩余的数据都会被自动丢弃。 在归档末尾,Next 返回错误 io.EOF。

如果 Next 遇到非本地名称(由 filepath.IsLocal 定义) 且 GODEBUG 环境变量包含 `tarinsecurepath=0`, 则 Next 返回该头部以及一个 ErrInsecurePath 错误。 Go 的未来版本可能会默认引入此行为。 想要接受非本地名称的程序可以忽略 ErrInsecurePath 错误并使用返回的头部。

func (*Reader) Read
func (tr *Reader) Read(b []byte) (int, error)

Read 从 tar 归档中的当前文件读取。 当到达该文件末尾时,它返回 (0, io.EOF), 直到调用 [Next] 前进到下一个文件。

如果当前文件是稀疏的,那么被标记为空洞的区域 会被读回为 NUL 字节。

对特殊类型(如 TypeLink、TypeSymlink、TypeChar、 TypeBlock、TypeDir 和 TypeFifo)调用 Read 会返回 (0, io.EOF), 无论 Header.Size 声称什么。

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer 提供 tar 归档的顺序写入。 Writer.WriteHeader 使用提供的 Header 开始一个新文件, 之后可将 Writer 视为 io.Writer 来提供该文件的数据。

func NewWriter
func NewWriter(w io.Writer) *Writer

NewWriter 创建一个写入 w 的新 Writer。

func (*Writer) AddFS
func (tw *Writer) AddFS(fsys fs.FS) error

AddFS 将 fs.FS 中的文件添加到归档中。 它从文件系统的根开始遍历目录树, 在保持目录结构的同时将每个文件添加到 tar 归档中。

func (*Writer) Close
func (tw *Writer) Close() error

Close 通过刷出填充并写入尾部来关闭 tar 归档。 如果当前文件(来自先前对 Writer.WriteHeader 的调用)未完整写入, 则返回错误。

func (*Writer) Flush
func (tw *Writer) Flush() error

Flush 完成当前文件块填充的写入。 调用 Flush 之前必须已完整写入当前文件。

这一步并非必需,因为下一次调用 Writer.WriteHeader 或 Writer.Close 会隐式刷出文件的填充。

func (*Writer) Write
func (tw *Writer) Write(b []byte) (int, error)

Write 写入 tar 归档中的当前文件。 如果在 Writer.WriteHeader 之后写入超过 Header.Size 字节,则 Write 返回错误 ErrWriteTooLong。

对 TypeLink、TypeSymlink、TypeChar、 TypeBlock、TypeDir 和 TypeFifo 等特殊类型调用 Write 会返回 (0, ErrWriteTooLong),无论 Header.Size 如何声明。

func (*Writer) WriteHeader
func (tw *Writer) WriteHeader(hdr *Header) error

WriteHeader 写入 hdr 并准备接收该文件的内容。 Header.Size 决定下一个文件可以写入多少字节。 如果当前文件未完整写入,则返回错误。 它会在写入头部之前隐式刷出所有必要的填充。