Package tar

import "archive/tar"

Overview ▾


磁带档案(tar)是一种文件格式,用于存储可以以流方式读取和写入的一系列文件. 该软件包旨在涵盖该格式的大多数变体,包括GNU和BSD tar工具产生的那些变体.


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



const (
    // Type '0' indicates a regular file.
    TypeReg  = '0'
    TypeRegA = '\x00' // Deprecated: Use TypeReg instead.

    // Type '1' to '6' are header-only flags and may not have a data body.
    TypeLink    = '1' // Hard link
    TypeSymlink = '2' // Symbolic link
    TypeChar    = '3' // Character device node
    TypeBlock   = '4' // Block device node
    TypeDir     = '5' // Directory
    TypeFifo    = '6' // FIFO node

    // Type '7' is reserved.
    TypeCont = '7'

    // Type 'x' is used by the PAX format to store key-value records that
    // are only relevant to the next file.
    // This package transparently handles these types.
    TypeXHeader = 'x'

    // Type 'g' is used by the PAX format to store key-value records that
    // are relevant to all subsequent files.
    // This package only supports parsing and composing such headers,
    // but does not currently support persisting the global state across files.
    TypeXGlobalHeader = 'g'

    // Type 'S' indicates a sparse file in the GNU format.
    TypeGNUSparse = 'S'

    // Types 'L' and 'K' are used by the GNU format for a meta file
    // used to store the path or link name for the next file.
    // This package transparently handles these types.
    TypeGNULongName = 'L'
    TypeGNULongLink = 'K'


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")

type Format 1.10


原始的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




type Format int


const (

    // FormatUnknown indicates that the format is unknown.
    FormatUnknown Format

    // FormatUSTAR represents the USTAR header format defined in POSIX.1-1988.
    // While this format is compatible with most tar readers,
    // the format has several limitations making it unsuitable for some usages.
    // Most notably, it cannot support sparse files, files larger than 8GiB,
    // filenames larger than 256 characters, and non-ASCII filenames.
    // Reference:

    // FormatPAX represents the PAX header format defined in POSIX.1-2001.
    // PAX extends USTAR by writing a special file with Typeflag TypeXHeader
    // preceding the original header. This file contains a set of key-value
    // records, which are used to overcome USTAR's shortcomings, in addition to
    // providing the ability to have sub-second resolution for timestamps.
    // Some newer formats add their own extensions to PAX by defining their
    // own keys and assigning certain semantic meaning to the associated values.
    // For example, sparse file support in PAX is implemented using keys
    // defined by the GNU manual (e.g., "").
    // Reference:

    // FormatGNU represents the GNU header format.
    // The GNU header format is older than the USTAR and PAX standards and
    // is not compatible with them. The GNU format supports
    // arbitrary file sizes, filenames of arbitrary encoding and length,
    // sparse files, and other features.
    // It is recommended that PAX be chosen over GNU unless the target
    // application can only parse GNU formatted archives.
    // Reference:

func (Format) String 1.10

func (f Format) String() string

标头代表tar归档文件中的单个标头. 某些字段可能未填充.


type Header struct {
    // Typeflag is the type of header entry.
    // The zero value is automatically promoted to either TypeReg or TypeDir
    // depending on the presence of a trailing slash in Name.
    Typeflag byte

    Name     string // Name of file entry
    Linkname string // Target name of link (valid for TypeLink or TypeSymlink)

    Size  int64  // Logical file size in bytes
    Mode  int64  // Permission and mode bits
    Uid   int    // User ID of owner
    Gid   int    // Group ID of owner
    Uname string // User name of owner
    Gname string // Group name of owner

    // If the Format is unspecified, then Writer.WriteHeader rounds ModTime
    // to the nearest second and ignores the AccessTime and ChangeTime fields.
    // To use AccessTime or ChangeTime, specify the Format as PAX or GNU.
    // To use sub-second resolution, specify the Format as PAX.
    ModTime    time.Time // Modification time
    AccessTime time.Time // Access time (requires either PAX or GNU support)
    ChangeTime time.Time // Change time (requires either PAX or GNU support)

    Devmajor int64 // Major device number (valid for TypeChar or TypeBlock)
    Devminor int64 // Minor device number (valid for TypeChar or TypeBlock)

    // Xattrs stores extended attributes as PAX records under the
    // "SCHILY.xattr." namespace.
    // The following are semantically equivalent:
    //  h.Xattrs[key] = value
    //  h.PAXRecords["SCHILY.xattr."+key] = value
    // When Writer.WriteHeader is called, the contents of Xattrs will take
    // precedence over those in PAXRecords.
    // Deprecated: Use PAXRecords instead.
    Xattrs map[string]string // Go 1.3

    // PAXRecords is a map of PAX extended header records.
    // User-defined records should have keys of the following form:
    //	VENDOR.keyword
    // Where VENDOR is some namespace in all uppercase, and keyword may
    // not contain the '=' character (e.g., "GOLANG.pkg.version").
    // The key and value should be non-empty UTF-8 strings.
    // When Writer.WriteHeader is called, PAX records derived from the
    // other fields in Header take precedence over PAXRecords.
    PAXRecords map[string]string // Go 1.10

    // Format specifies the format of the tar header.
    // This is set by Reader.Next as a best-effort guess at the format.
    // Since the Reader liberally reads some non-compliant files,
    // it is possible for this to be FormatUnknown.
    // If the format is unspecified when Writer.WriteHeader is called,
    // then it uses the first format (in the order of USTAR, PAX, GNU)
    // capable of encoding this Header (see Format).
    Format Format // Go 1.10

func FileInfoHeader 1.1

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

FileInfoHeader从fi创建部分填充的Header. 如果fi描述了符号链接,则FileInfoHeader会将链接记录为链接目标. 如果fi描述目录,则在名称后添加斜杠.


func (*Header) FileInfo 1.1

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

FileInfo returns an os.FileInfo for the Header.

type Reader

Reader提供了对tar存档内容的顺序访问. Reader.Next前进到存档中的下一个文件(包括第一个文件),然后Reader可以被视为io.Reader来访问文件的数据.

type Reader struct {
    // contains filtered or unexported fields

func NewReader

func NewReader(r io.Reader) *Reader


func (*Reader) Next

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

下一个前进到tar存档中的下一个条目. Header.Size确定可以为下一个文件读取多少个字节. 当前文件中的所有剩余数据将被自动丢弃.


func (*Reader) Read

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

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



type Writer

Writer提供tar存档的顺序写入. Write.WriteHeader使用提供的Header开始新文件,然后Writer可以被视为io.Writer来提供该文件的数据.

type Writer struct {
    // contains filtered or unexported fields

func NewWriter

func NewWriter(w io.Writer) *Writer


func (*Writer) Close

func (tw *Writer) Close() error

Close通过刷新填充并写入页脚来关闭tar存档. 如果当前文件(从对WriteHeader的先前调用中)未完全写入,则将返回错误.

func (*Writer) Flush

func (tw *Writer) Flush() error

刷新完成当前文件的块填充的写入. 必须先完全写入当前文件,然后才能调用Flush.


func (*Writer) Write

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

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


func (*Writer) WriteHeader

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

WriteHeader写入hdr并准备接受文件的内容. Header.Size确定可以为下一个文件写入多少个字节. 如果当前文件未完全写入,则返回错误. 这将在写入标题之前隐式刷新所有必要的填充.