Namespace: go.std.archive.tar

v1.0

Contents

• Summary
• Index
• Constants
• Variables
• Functions, Macros, and Special Forms
• Types

Summary

Provides a low-level interface to the archive/tar package.

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.

Index

• *Format
• *Header
• *Reader
• *Writer
• ErrFieldTooLong
• ErrHeader
• ErrWriteAfterClose
• ErrWriteTooLong
• FileInfoHeader
• Format
• FormatGNU
• FormatPAX
• FormatUSTAR
• FormatUnknown
• Header
• NewReader
• NewWriter
• Reader
• TypeBlock
• TypeChar
• TypeCont
• TypeDir
• TypeFifo
• TypeGNULongLink
• TypeGNULongName
• TypeGNUSparse
• TypeLink
• TypeReg
• TypeRegA
• TypeSymlink
• TypeXGlobalHeader
• TypeXHeader
• Writer
• arrayOfFormat
• arrayOfHeader
• arrayOfReader
• arrayOfWriter

Legend

Constant Variable Function Macro Special form Type GoVar Receiver/Method

Constants

Constants are variables with :const true in their metadata. Joker currently does not recognize them as special; as such, it allows redefining them or their values.

• TypeBlock

  Char v1.0

  Block device node
  

• TypeChar

  Char v1.0

  Character device node
  

• TypeCont

  Char v1.0

  Type '7' is reserved.
  

• TypeDir

  Char v1.0

  Directory
  

• TypeFifo

  Char v1.0

  FIFO node
  

• TypeGNULongLink

  Char v1.0

  Type flags for Header.Typeflag.
  

• TypeGNULongName

  Char v1.0

  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.
  

• TypeGNUSparse

  Char v1.0

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

• TypeLink

  Char v1.0

  Type '1' to '6' are header-only flags and may not have a data body.
  

• TypeReg

  Char v1.0

  Type '0' indicates a regular file.
  

• TypeRegA

  Char v1.0

  Deprecated: Use TypeReg instead.
  

• TypeSymlink

  Char v1.0

  Symbolic link
  

• TypeXGlobalHeader

  Char v1.0

  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.
  

• TypeXHeader

  Char v1.0

  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.
  

Variables

• ErrFieldTooLong

  Var v1.0

• ErrHeader

  Var v1.0

• ErrWriteAfterClose

  Var v1.0

• ErrWriteTooLong

  Var v1.0

• FormatGNU

  GoObject v1.0

  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
  

• FormatPAX

  GoObject v1.0

  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
  

• FormatUSTAR

  GoObject v1.0

  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
  

• FormatUnknown

  GoObject v1.0

  FormatUnknown indicates that the format is unknown.
  

Functions, Macros, and Special Forms

• FileInfoHeader

  Function v1.0

  (FileInfoHeader fi link)
  

  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 fs.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.
  
  Go input arguments: (fi io/fs.FileInfo, link string)
  
  Go returns: (*Header, error)
  
  Joker input arguments: [^go.std.io.fs/FileInfo fi, ^String link]
  
  Joker returns: [^*Header, ^Error]

• NewReader

  Function v1.0

  (NewReader r)
  

  NewReader creates a new Reader reading from r.
  
  Go input arguments: (r io.Reader)
  
  Go returns: *Reader
  
  Joker input arguments: [^go.std.io/Reader r]
  
  Joker returns: ^*Reader

• NewWriter

  Function v1.0

  (NewWriter w)
  

  NewWriter creates a new Writer writing to w.
  
  Go input arguments: (w io.Writer)
  
  Go returns: *Writer
  
  Joker input arguments: [^go.std.io/Writer w]
  
  Joker returns: ^*Writer

Types

• *Format

  Concrete Type v1.0

  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:
  
  | 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
  
  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.
  

• *Header

  Concrete Type v1.0

  A Header represents a single header in a tar archive.
  Some fields may not be populated.
  
  For forward compatibility, users that retrieve a Header from Reader.Next,
  mutate it in some ways, and then pass it back to Writer.WriteHeader
  should do so by creating a new Header and copying the fields
  that they are interested in preserving.
  

• FileInfo

  Receiver for *Header v1.0

  ([])
  

  FileInfo returns an fs.FileInfo for the Header.
  

• *Reader

  Concrete Type v1.0

  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.
  

• Next

  Receiver for *Reader v1.0

  ([])
  

  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.
  

• Read

  Receiver for *Reader v1.0

  ([b])
  

  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.
  
  If the current file is sparse, then the regions marked as a hole
  are read back as NUL-bytes.
  
  Calling Read on special types like TypeLink, TypeSymlink, TypeChar,
  TypeBlock, TypeDir, and TypeFifo returns (0, io.EOF) regardless of what
  the Header.Size claims.
  

• *Writer

  Concrete Type v1.0

  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.
  

• Close

  Receiver for *Writer v1.0

  ([])
  

  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.
  

• Flush

  Receiver for *Writer v1.0

  ([])
  

  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.
  

• Write

  Receiver for *Writer v1.0

  ([b])
  

  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.
  

• WriteHeader

  Receiver for *Writer v1.0

  ([hdr])
  

  WriteHeader writes hdr and prepares to accept the file's contents.
  The Header.Size determines how many bytes can be written for the next file.
  If the current file is not fully written, then this returns an error.
  This implicitly flushes any padding necessary before writing the header.
  

• Format

  Concrete Type v1.0

  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:
  
  | 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
  
  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.
  

• String

  Receiver for Format v1.0

  ([])
  

• Header

  Concrete Type v1.0

  A Header represents a single header in a tar archive.
  Some fields may not be populated.
  
  For forward compatibility, users that retrieve a Header from Reader.Next,
  mutate it in some ways, and then pass it back to Writer.WriteHeader
  should do so by creating a new Header and copying the fields
  that they are interested in preserving.
  

• Reader

  Concrete Type v1.0

  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.
  

• Writer

  Concrete Type v1.0

  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.
  

• arrayOfFormat

  Concrete Type v1.0

  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:
  
  | 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
  
  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.
  

• arrayOfHeader

  Concrete Type v1.0

  A Header represents a single header in a tar archive.
  Some fields may not be populated.
  
  For forward compatibility, users that retrieve a Header from Reader.Next,
  mutate it in some ways, and then pass it back to Writer.WriteHeader
  should do so by creating a new Header and copying the fields
  that they are interested in preserving.
  

• arrayOfReader

  Concrete Type v1.0

  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.
  

• arrayOfWriter

  Concrete Type v1.0

  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.