Overview

Package tar implements access to tar archives.

Tape archives (tar) are a file format for storing a sequence of files that can
be read and written in a streaming manner. This package aims to cover most
variations of the format, including those produced by GNU and BSD tar tools.


Example:

Index

Package files

format.go stat_actime1.go strconv.go 

  1. const (
  2.     // Type '0' indicates a regular file.
  3.     TypeReg  = '0'
  4.     TypeRegA = '\x00' // For legacy support; use TypeReg instead
  5.  
  6.     // Type '1' to '6' are header-only flags and may not have a data body.
  7.     TypeLink    = '1' // Hard link
  8.     TypeSymlink = '2' // Symbolic link
  9.     TypeChar    = '3' // Character device node
  10.     TypeBlock   = '4' // Block device node
  11.     TypeDir     = '5' // Directory
  12.     TypeFifo    = '6' // FIFO node
  13.  
  14.     // Type '7' is reserved.
  15.     TypeCont = '7'
  16.  
  17.     // Type 'x' is used by the PAX format to store key-value records that
  18.     // are only relevant to the next file.
  19.     // This package transparently handles these types.
  20.     TypeXHeader = 'x'
  21.  
  22.     // Type 'g' is used by the PAX format to store key-value records that
  23.     // are relevant to all subsequent files.
  24.     // This package only supports parsing and composing such headers,
  25.     // but does not currently support persisting the global state across files.
  26.     TypeXGlobalHeader = 'g'
  27.  
  28.     // Type 'S' indicates a sparse file in the GNU format.
  29.     TypeGNUSparse = 'S'
  30.  
  31.     // Types 'L' and 'K' are used by the GNU format for a meta file
  32.     // used to store the path or link name for the next file.
  33.     // This package transparently handles these types.
  34.     TypeGNULongName = 'L'
  35.     TypeGNULongLink = 'K'
  36. )

Type flags for Header.Typeflag.

Variables

  1. var (
  2.     ErrHeader          = errors.("archive/tar: invalid tar header")
  3.     ErrWriteTooLong    = errors.("archive/tar: write too long")
  4.     ErrFieldTooLong    = errors.("archive/tar: header field too long")
  5.     ErrWriteAfterClose = errors.("archive/tar: write after close")
  6. )

type Format

  1. type Format int

Format represents the tar archive format.

The original tar format was introduced in Unix V7. Since then, there have been
multiple competing formats attempting to standardize or extend the V7 format to
overcome its limitations. The most common formats are the USTAR, PAX, and GNU
formats, each with their own advantages and limitations.

The following table captures the capabilities of each format:

  1.                   |  USTAR |       PAX |       GNU
  2. Name              |   256B | unlimited | unlimited
  3. Linkname          |   100B | unlimited | unlimited
  5. Mode              | uint21 |    uint21 |    uint57
  6. Uid/Gid           | uint21 | unlimited |    uint57
  7. Uname/Gname       |    32B | unlimited |       32B
  8. ModTime           | uint33 | unlimited |     int89
  10. ChangeTime        |    n/a | unlimited |     int89
  11. Devmajor/Devminor | uint21 |    uint21 |    uint57
  12. ------------------+--------+-----------+----------
  13. string encoding   |  ASCII |     UTF-8 |    binary
  15. sparse files      |     no |       yes |       yes

The table’s upper portion shows the Header fields, where each format reports the
maximum number of bytes allowed for each string field and the integer type used
to store each numeric field (where timestamps are stored as the number of
seconds since the Unix epoch).

The table’s lower portion shows specialized features of each format, such as
supported string encodings, support for sub-second timestamps, or support for
sparse files.

The Writer currently provides no support for sparse files.

  1. const (
  2.  
  3.     // FormatUnknown indicates that the format is unknown.
  4.     FormatUnknown 
  5.  
  6.     // FormatUSTAR represents the USTAR header format defined in POSIX.1-1988.
  7.     //
  8.     // While this format is compatible with most tar readers,
  9.     // the format has several limitations making it unsuitable for some usages.
  10.     // Most notably, it cannot support sparse files, files larger than 8GiB,
  11.     // filenames larger than 256 characters, and non-ASCII filenames.
  12.     //
  13.     // Reference:
  14.     //    http://pubs.opengroup.org/onlinepubs/9699919799/utilities/pax.html#tag_20_92_13_06
  15.     FormatUSTAR
  16.  
  17.     // FormatPAX represents the PAX header format defined in POSIX.1-2001.
  18.     //
  19.     // PAX extends USTAR by writing a special file with Typeflag TypeXHeader
  20.     // preceding the original header. This file contains a set of key-value
  21.     // records, which are used to overcome USTAR's shortcomings, in addition to
  22.     // providing the ability to have sub-second resolution for timestamps.
  23.     //
  24.     // Some newer formats add their own extensions to PAX by defining their
  25.     // own keys and assigning certain semantic meaning to the associated values.
  26.     // For example, sparse file support in PAX is implemented using keys
  27.     // defined by the GNU manual (e.g., "GNU.sparse.map").
  28.     //
  29.     // Reference:
  30.     //    http://pubs.opengroup.org/onlinepubs/009695399/utilities/pax.html
  31.     FormatPAX
  32.  
  33.     // FormatGNU represents the GNU header format.
  34.     //
  35.     // The GNU header format is older than the USTAR and PAX standards and
  36.     // is not compatible with them. The GNU format supports
  37.     // arbitrary file sizes, filenames of arbitrary encoding and length,
  38.     // sparse files, and other features.
  39.     //
  40.     // It is recommended that PAX be chosen over GNU unless the target
  41.     // application can only parse GNU formatted archives.
  42.     //
  43.     // Reference:
  44.     //    http://www.gnu.org/software/tar/manual/html_node/Standard.html
  45.     FormatGNU
  46. )

Constants to identify various tar formats.

func (Format) String

  1. type Header struct {
  2.     Typeflag byte // Type of header entry (should be TypeReg for most files)
  3.  
  4.     Name      // Name of file entry
  5.     Linkname string // Target name of link (valid for TypeLink or TypeSymlink)
  6.  
  7.     Mode    // Permission and mode bits
  8.     Uid   int    // User ID of owner
  9.     Gid       // Group ID of owner
  10.     Uname string // User name of owner
  11.     Gname  // Group name of owner
  12.  
  13.     // If the Format is unspecified, then Writer.WriteHeader rounds ModTime
  14.     // to the nearest second and ignores the AccessTime and ChangeTime fields.
  15.     //
  16.     // To use AccessTime or ChangeTime, specify the Format as PAX or GNU.
  17.     // To use sub-second resolution, specify the Format as PAX.
  18.     ModTime    time. // Modification time
  19.     AccessTime time. // Access time (requires either PAX or GNU support)
  20.     ChangeTime time. // Change time (requires either PAX or GNU support)
  21.  
  22.     Devmajor int64 // Major device number (valid for TypeChar or TypeBlock)
  23.     Devminor  // Minor device number (valid for TypeChar or TypeBlock)
  24.  
  25.     // Xattrs stores extended attributes as PAX records under the
  26.     // "SCHILY.xattr." namespace.
  27.     //
  28.     // The following are semantically equivalent:
  29.     //  h.Xattrs[key] = value
  30.     //  h.PAXRecords["SCHILY.xattr."+key] = value
  31.     //
  32.     // When Writer.WriteHeader is called, the contents of Xattrs will take
  33.     // precedence over those in PAXRecords.
  34.     //
  35.     // Deprecated: Use PAXRecords instead.
  36.     Xattrs map[string]
  37.  
  38.     // PAXRecords is a map of PAX extended header records.
  39.     //
  40.     // User-defined records should have keys of the following form:
  41.     //    VENDOR.keyword
  42.     // Where VENDOR is some namespace in all uppercase, and keyword may
  43.     // not contain the '=' character (e.g., "GOLANG.pkg.version").
  44.     // The key and value should be non-empty UTF-8 strings.
  45.     //
  46.     // When Writer.WriteHeader is called, PAX records derived from the
  47.     // the other fields in Header take precedence over PAXRecords.
  48.     PAXRecords map[string]
  49.  
  50.     // Format specifies the format of the tar header.
  51.     //
  52.     // This is set by Reader.Next as a best-effort guess at the format.
  53.     // Since the Reader liberally reads some non-compliant files,
  54.     // it is possible for this to be FormatUnknown.
  55.     //
  56.     // If the format is unspecified when Writer.WriteHeader is called,
  57.     // then it uses the first format (in the order of USTAR, PAX, GNU)
  58.     // capable of encoding this Header (see Format).
  59.     Format Format
  60. }

A Header represents a single header in a tar archive. Some fields may not be
populated.

func 

  1. func FileInfoHeader(fi .FileInfo, link ) (*Header, )

FileInfoHeader creates a partially-populated Header from fi. If fi describes a
symlink, FileInfoHeader records link as the link target. If fi describes a
directory, a slash is appended to the name.

Since os.FileInfo’s Name method only returns the base name of the file it
describes, it may be necessary to modify Header.Name to provide the full path
name of the file.

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

FileInfo returns an os.FileInfo for the Header.

type 

  1. type Reader struct {
  2.     // contains filtered or unexported fields
  3. }

Reader provides sequential access to the contents of a tar archive. Reader.Next
advances to the next file in the archive (including the first), and then Reader
can be treated as an io.Reader to access the file’s data.

func 

  1. func NewReader(r .Reader) *

NewReader creates a new Reader reading from r.

func (*Reader) Next

Next advances to the next entry in the tar archive. The Header.Size determines
how many bytes can be read for the next file. Any remaining data in the current
file is automatically discarded.

io.EOF is returned at the end of the input.

func (*Reader) Read

  1. func (tr *Reader) Read(b []) (int, )

Read reads from the current file in the tar archive. It returns (0, io.EOF) when
it reaches the end of that file, until Next is called to advance to the next
file.

Calling Read on special types like TypeLink, TypeSymlink, TypeChar, TypeBlock,
TypeDir, and TypeFifo returns (0, io.EOF) regardless of what the Header.Size
claims.

type Writer

  1. type Writer struct {
  2.     // contains filtered or unexported fields
  3. }

Writer provides sequential writing of a tar archive. Write.WriteHeader begins a
new file with the provided Header, and then Writer can be treated as an
io.Writer to supply that file’s data.

  1. func NewWriter(w io.) *Writer

NewWriter creates a new Writer writing to w.

func (*Writer) 

  1. func (tw *) Close() error

Close closes the tar archive by flushing the padding, and writing the footer. If
the current file (from a prior call to WriteHeader) is not fully written, then
this returns an error.

func (*Writer)

    Flush finishes writing the current file’s block padding. The current file must
    be fully written before Flush can be called.

    This is unnecessary as the next call to WriteHeader or Close will implicitly
    flush out the file’s padding.

    func (*Writer)

    Write writes to the current file in the tar archive. Write returns the error
    ErrWriteTooLong if more than Header.Size bytes are written after WriteHeader.

    Calling Write on special types like TypeLink, TypeSymlink, TypeChar, TypeBlock,
    TypeDir, and TypeFifo returns (0, ErrWriteTooLong) regardless of what the
    Header.Size claims.

    1. func (tw *) WriteHeader(hdr *Header)