package tar
import "archive/tar"
Package tar 实现了对 tar 存档的访问。
磁带存档(tar)是一种用于存储文件序列的文件格式,可以以流式方式读取和写入。
本包旨在覆盖该格式的大多数变体,包括由 GNU 和 BSD tar 工具生成的格式。
Output: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()
}
}
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
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 决定下一个文件可以写入多少字节。 如果当前文件未完整写入,则返回错误。 它会在写入头部之前隐式刷出所有必要的填充。