Пакет tar
Обзор
Пакет tar реализует доступ к tar-архивам.
Ленточные архивы (tar) — это формат файлов для хранения последовательности файлов, которые можно читать и записывать потоковым способом. Этот пакет призван поддерживать большинство вариантов формата, в том числе созданных инструментами tar GNU и BSD.
Пример (минимальный)
Код:
// 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()
}
Вывод:
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.
Указатель
Примеры
Файлы пакета
common.go format.go reader.go stat_actime1.go stat_unix.go strconv.go writer.go
Константы
Флаги типов для Header.Typeflag.
const (
// Type '0' indicates a regular file.
TypeReg = '0'
// Deprecated: Use TypeReg instead.
TypeRegA = '\x00'
// 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'
) Переменные
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")
ErrInsecurePath = errors.New("archive/tar: insecure file path")
) тип FileInfoNames 1.23
FileInfoNames расширяет fs.FileInfo. Передача его экземпляра в FileInfoHeader позволяет вызывающему коду избежать зависящего от системы поиска имени, указав непосредственно Uname и Gname.
type FileInfoNames interface {
fs.FileInfo
// Uname should give a user name.
Uname() (string, error)
// Gname should give a group name.
Gname() (string, error)
} тип Format 1.10
Format представляет формат 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
тип Header
Header представляет один заголовок в tar-архиве. Некоторые поля могут быть не заполнены.
Для обеспечения прямой совместимости пользователям, которые получают Header из Reader.Next, изменяют его и затем передают обратно в 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 fs.FileInfo, link string) (*Header, error)
FileInfoHeader создает частично заполненный Header на основе fi. Если fi описывает символическую ссылку, FileInfoHeader записывает link в качестве цели ссылки. Если fi описывает каталог, к имени добавляется косая черта.
Поскольку метод Name интерфейса fs.FileInfo возвращает только базовое имя описываемого файла, может потребоваться изменить Header.Name, чтобы указать полный путь к файлу.
Если fi реализует FileInfoNames, значения Header.Gname и Header.Uname предоставляются методами интерфейса.
func (*Header) FileInfo 1.1
func (h *Header) FileInfo() fs.FileInfo
FileInfo возвращает fs.FileInfo для Header.
тип 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 создает новый Reader, читающий данные из r.
func (*Reader) Next
func (tr *Reader) Next() (*Header, error)
Next переходит к следующей записи в tar-архиве. Header.Size определяет, сколько байтов можно прочитать для следующего файла. Любые оставшиеся данные текущего файла автоматически отбрасываются. В конце архива Next возвращает ошибку io.EOF.
Если Next встречает нелокальное имя файла (согласно определению filepath.IsLocal), а переменная среды GODEBUG содержит `tarinsecurepath=0`, проверяются только имена файлов, но не цели ссылок. Next возвращает заголовок с ошибкой ErrInsecurePath. В будущей версии Go такое поведение может быть включено по умолчанию. Программы, которым нужно принимать нелокальные имена, могут игнорировать ошибку ErrInsecurePath и использовать возвращенный заголовок.
func (*Reader) Read
func (tr *Reader) Read(b []byte) (int, error)
Read читает данные текущего файла в tar-архиве. При достижении конца этого файла возвращается (0, io.EOF); это продолжается до вызова [Next] для перехода к следующему файлу.
Если текущий файл является разреженным, области, помеченные как пропуски, при чтении возвращаются как нулевые байты.
Вызов Read для специальных типов, таких как TypeLink, TypeSymlink, TypeChar, TypeBlock, TypeDir и TypeFifo, возвращает (0, io.EOF) независимо от значения, указанного в Header.Size.
тип Writer
Writer обеспечивает последовательную запись tar-архива. Writer.WriteHeader начинает новый файл с переданным Header, после чего Writer можно использовать как io.Writer для передачи данных этого файла.
type Writer struct {
// contains filtered or unexported fields
}
func NewWriter
func NewWriter(w io.Writer) *Writer
NewWriter создает новый Writer, записывающий данные в w.
func (*Writer) AddFS 1.22
func (tw *Writer) AddFS(fsys fs.FS) error
AddFS добавляет файлы из fs.FS в архив. Он обходит дерево каталогов, начиная с корня файловой системы, и добавляет каждый файл в tar-архив, сохраняя структуру каталогов.
func (*Writer) Close
func (tw *Writer) Close() error
Close закрывает tar-архив, сбрасывая заполняющие данные и записывая завершающую часть. Если текущий файл (из предшествующего вызова Writer.WriteHeader) записан не полностью, возвращается ошибка.
func (*Writer) Flush
func (tw *Writer) Flush() error
Flush завершает запись заполняющих данных блока текущего файла. Перед вызовом Flush текущий файл должен быть записан полностью.
Это необязательно, поскольку следующий вызов Writer.WriteHeader или Writer.Close автоматически запишет заполняющие данные файла.
func (*Writer) Write
func (tw *Writer) Write(b []byte) (int, error)
Write записывает данные в текущий файл tar-архива. Write возвращает ошибку ErrWriteTooLong, если после вызова Writer.WriteHeader записано больше байтов, чем указано в Header.Size.
Вызов Write для специальных типов, таких как TypeLink, TypeSymlink, TypeChar, TypeBlock, TypeDir и TypeFifo, возвращает (0, ErrWriteTooLong) независимо от значения, указанного в Header.Size.
func (*Writer) WriteHeader
func (tw *Writer) WriteHeader(hdr *Header) error
WriteHeader записывает hdr и подготавливает Writer к приему содержимого файла. Header.Size определяет, сколько байтов можно записать для следующего файла. Если текущий файл записан не полностью, возвращается ошибка. Перед записью заголовка этот метод автоматически сбрасывает все необходимые заполняющие данные.
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/archive/tar/
