Package tar

import "archive/tar"
Overview
Index
Examples

Overview ▾

包tar实现了对tar存档的访问.

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

示例(最低)

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.

Constants

Header.Typeflag的类型标志.

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

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

type Format 1.10

格式表示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当前不支持稀疏文件.

type Format int

标识各种tar格式的常量.

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:
    //	http://pubs.opengroup.org/onlinepubs/9699919799/utilities/pax.html#tag_20_92_13_06
    FormatUSTAR

    // 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., "GNU.sparse.map").
    //
    // Reference:
    //	http://pubs.opengroup.org/onlinepubs/009695399/utilities/pax.html
    FormatPAX

    // 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:
    //	https://www.gnu.org/software/tar/manual/html_node/Standard.html
    FormatGNU
)

func (Format) String 1.10

func (f Format) String() string

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

为了向前兼容,从Reader中检索Header的用户接下来要以某种方式对其进行突变,然后将其传递回Writer.WriteHeader应该通过创建一个新Header并复制他们想要保留的字段来实现.

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描述目录,则在名称后添加斜杠.

由于os.FileInfo的Name方法仅返回其描述的文件的基本名称,因此可能有必要修改Header.Name以提供文件的完整路径名.

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

NewReader从r创建一个新的Reader读数.

func (*Reader) Next

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

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

io.EOF在输入的末尾返回.

func (*Reader) Read

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

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

如果当前文件稀疏,则标记为孔的区域将以NUL字节的形式读回.

不管Header.Size声明什么,在TypeLink,TypeSymlink,TypeChar,TypeBlock,TypeDir和TypeFifo等特殊类型上调用Read都会返回(0,io.EOF).

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

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

func (*Writer) Close

func (tw *Writer) Close() error

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

func (*Writer) Flush

func (tw *Writer) Flush() error

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

这是不必要的,因为下次调用WriteHeader或Close会隐式清除文件的填充.

func (*Writer) Write

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

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

不管Header.Size声明什么,都对特殊类型(例如TypeLink,TypeSymlink,TypeChar,TypeBlock,TypeDir和TypeFifo)调用Write返回(0,ErrWriteTooLong).

func (*Writer) WriteHeader

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

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

by  ICOPY.SITE