package tar

Import Path
	archive/tar (on go.dev)

Dependency Relation
	imports 18 packages, and imported by 0 packages

Involved Source Files

	  d common.go
		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.

	    format.go
	    reader.go
	    stat_actime1.go
	    stat_unix.go
	    strconv.go
	    writer.go
Code Examples

	_minimal
		package main
		
		import (
			"archive/tar"
			"bytes"
			"fmt"
			"io"
			"log"
			"os"
		)
		
		func main() {
			// Create and add some files to the archive.
			var buf bytes.Buffer
			tw := tar.NewWriter(&buf)
			var files = []struct {
				Name, Body string
			}{
				{"readme.txt", "This archive contains some text files."},
				{"gopher.txt", "Gopher names:\nGeorge\nGeoffrey\nGonzo"},
				{"todo.txt", "Get animal handling license."},
			}
			for _, file := range files {
				hdr := &tar.Header{
					Name: file.Name,
					Mode: 0600,
					Size: int64(len(file.Body)),
				}
				if err := tw.WriteHeader(hdr); err != nil {
					log.Fatal(err)
				}
				if _, err := tw.Write([]byte(file.Body)); err != nil {
					log.Fatal(err)
				}
			}
			if err := tw.Close(); err != nil {
				log.Fatal(err)
			}
		
			// Open and iterate through the files in the archive.
			tr := tar.NewReader(&buf)
			for {
				hdr, err := tr.Next()
				if err == io.EOF {
					break // End of archive
				}
				if err != nil {
					log.Fatal(err)
				}
				fmt.Printf("Contents of %s:\n", hdr.Name)
				if _, err := io.Copy(os.Stdout, tr); err != nil {
					log.Fatal(err)
				}
				fmt.Println()
			}
		
		}


Package-Level Type Names (total 5)

	/* sort by: alphabet | popularity */
	 type FileInfoNames (interface)
		FileInfoNames extends [fs.FileInfo].
		Passing an instance of this to [FileInfoHeader] permits the caller
		to avoid a system-dependent name lookup by specifying the Uname and Gname directly.

		Methods (total 8)
			( FileInfoNames) Gname() (string, error)
				Gname should give a group name.

			( FileInfoNames) IsDir() bool
				// abbreviation for Mode().IsDir()

			( FileInfoNames) ModTime() time.Time
				// modification time

			( FileInfoNames) Mode() fs.FileMode
				// file mode bits

			( FileInfoNames) Name() string
				// base name of the file

			( FileInfoNames) Size() int64
				// length in bytes for regular files; system-dependent for others

			( FileInfoNames) Sys() any
				// underlying data source (can return nil)

			( FileInfoNames) Uname() (string, error)
				Uname should give a user name.

		Implements (at least one exported)
			 FileInfoNames : io/fs.FileInfo

	 type Format int (basic type)
		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.

		Methods (only one)
			( Format) String() string
		Implements (at least 2)
			 Format : expvar.Var
			 Format : fmt.Stringer
		As Types Of (total 4)
			const FormatGNU
			const FormatPAX
			const FormatUnknown
			const FormatUSTAR

	 type Header (struct)
		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.

		Fields (total 17)
			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)

			Format Format
				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).

			Gid int
				// Group ID of owner

			Gname string
				// Group name of owner

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

			ModTime time.Time
				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.
				// Modification time

			Mode int64
				// Permission and mode bits

			Name string
				// Name of file entry

			PAXRecords map[string]string
				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.

			Size int64
				// Logical file size in bytes

			Typeflag byte
				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.

			Uid int
				// User ID of owner

			Uname string
				// User name of owner

			Xattrs map[string]string
				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.

		Methods (only one)
			(*Header) FileInfo() fs.FileInfo
				FileInfo returns an fs.FileInfo for the Header.

		As Outputs Of (at least 2)
			func FileInfoHeader(fi fs.FileInfo, link string) (*Header, error)
			func (*Reader).Next() (*Header, error)
		As Inputs Of (at least one exported)
			func (*Writer).WriteHeader(hdr *Header) error

	 type Reader (struct)
		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.

		Methods (total 2)
			(*Reader) Next() (*Header, error)
				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.
				At the end of the archive, Next returns the error io.EOF.
				
				If Next encounters a non-local name (as defined by [filepath.IsLocal])
				and the GODEBUG environment variable contains `tarinsecurepath=0`,
				Next returns the header with an [ErrInsecurePath] error.
				A future version of Go may introduce this behavior by default.
				Programs that want to accept non-local names can ignore
				the [ErrInsecurePath] error and use the returned header.

			(*Reader) Read(b []byte) (int, error)
				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.

		Implements (at least one exported)
			*Reader : io.Reader
		As Outputs Of (at least one exported)
			func NewReader(r io.Reader) *Reader

	 type Writer (struct)
		Writer provides sequential writing of a tar archive.
		[Writer.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.

		Methods (total 5)
			(*Writer) AddFS(fsys fs.FS) error
				AddFS adds the files from fs.FS to the archive.
				It walks the directory tree starting at the root of the filesystem
				adding each file to the tar archive while maintaining the directory structure.

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

			(*Writer) Flush() error
				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 [Writer.WriteHeader] or [Writer.Close]
				will implicitly flush out the file's padding.

			(*Writer) Write(b []byte) (int, error)
				Write writes to the current file in the tar archive.
				Write returns the error [ErrWriteTooLong] if more than
				Header.Size bytes are written after [Writer.WriteHeader].
				
				Calling Write on special types like [TypeLink], [TypeSymlink], [TypeChar],
				[TypeBlock], [TypeDir], and [TypeFifo] returns (0, [ErrWriteTooLong]) regardless
				of what the [Header.Size] claims.

			(*Writer) WriteHeader(hdr *Header) error
				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.

		Implements (at least 4)
			*Writer : internal/bisect.Writer
			*Writer : io.Closer
			*Writer : io.WriteCloser
			*Writer : io.Writer
		As Outputs Of (at least one exported)
			func NewWriter(w io.Writer) *Writer


Package-Level Functions (total 3)

	 func FileInfoHeader(fi fs.FileInfo, link string) (*Header, error)
		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.
		
		If fi implements [FileInfoNames]
		Header.Gname and Header.Uname
		are provided by the methods of the interface.

	 func NewReader(r io.Reader) *Reader
		NewReader creates a new [Reader] reading from r.

	 func NewWriter(w io.Writer) *Writer
		NewWriter creates a new Writer writing to w.


Package-Level Variables (total 5)

	  var ErrFieldTooLong error
	  var ErrHeader error
	  var ErrInsecurePath error
	  var ErrWriteAfterClose error
	  var ErrWriteTooLong error
Package-Level Constants (total 18)

	const FormatGNU Format = 8
		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

	const FormatPAX Format = 4
		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

	const FormatUnknown Format = 0
		FormatUnknown indicates that the format is unknown.

	const FormatUSTAR Format = 2
		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

	const TypeBlock = 52 // Block device node
		Type flags for Header.Typeflag.

	const TypeChar = 51 // Character device node
		Type flags for Header.Typeflag.

	const TypeCont = 55
		Type '7' is reserved.

	const TypeDir = 53 // Directory
		Type flags for Header.Typeflag.

	const TypeFifo = 54 // FIFO node
		Type flags for Header.Typeflag.

	const TypeGNULongLink = 75
		Type flags for Header.Typeflag.

	const TypeGNULongName = 76
		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.

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

	const TypeLink = 49 // Hard link
		Type '1' to '6' are header-only flags and may not have a data body.

	const TypeReg = 48
		Type '0' indicates a regular file.

	const TypeRegA = 0
		Deprecated: Use TypeReg instead.

	const TypeSymlink = 50 // Symbolic link
		Type flags for Header.Typeflag.

	const TypeXGlobalHeader = 103
		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.

	const TypeXHeader = 120
		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.

The pages are generated with Golds v0.7.0-preview. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.