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.
ConstantsConstants 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.
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.
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").
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.
FormatUnknown indicates that the format is unknown.
Block device node
Character device node
Type '7' is reserved.
Type flags for Header.Typeflag.
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.
Type 'S' indicates a sparse file in the GNU format.
Type '1' to '6' are header-only flags and may not have a data body.
Type '0' indicates a regular file.
Deprecated: Use TypeReg instead.
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.
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.
ErrFieldTooLongGoVar of *error v1.0
ErrHeaderGoVar of *error v1.0
ErrWriteAfterCloseGoVar of *error v1.0
ErrWriteTooLongGoVar of *error v1.0
Functions, Macros, and Special Forms
(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 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.
Go input arguments: (fi os.FileInfo, link string)
Go return type: (*Header, error)
Joker input arguments: [^go.std.os/FileInfo fi, ^String link]
Joker return type: [(ref-to go.std.archive.tar/Header) Error]
NewReader creates a new Reader reading from r.
Go input arguments: (r io.Reader)
Go return type: *Reader
Joker input arguments: [^go.std.io/Reader r]
Joker return type: (ref-to go.std.archive.tar/Reader)
NewWriter creates a new Writer writing to w.
Go input arguments: (w io.Writer)
Go return type: *Writer
Joker input arguments: [^go.std.io/Writer w]
Joker return type: (ref-to go.std.archive.tar/Writer)
*FormatConcrete GoType v1.0
*HeaderConcrete GoType v1.0
FileInfoReceiver for *Header v1.0
FileInfo returns an os.FileInfo for the Header.
*ReaderConcrete GoType v1.0
NextReceiver 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.
*WriterConcrete GoType v1.0
CloseReceiver 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.
FlushReceiver 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.
FormatConcrete GoType 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.
StringReceiver for Format v1.0
HeaderConcrete GoType 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.
ReaderConcrete GoType 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.
WriterConcrete GoType 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.