Пакет tar
Обзор
Пакет tar реализует доступ к архивам tar.
Архивы на магнитной ленте (tar) — это формат файлов для хранения последовательности файлов, которые можно читать и записывать потоковым способом. Этот пакет предназначен для охвата большинства вариаций формата, включая те, которые созданы инструментами GNU и BSD tar.
Пример (Минимальный)
Код:
// 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
) Функция (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
}
Функция 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 предоставляются методами интерфейса.
Функция (*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
}
Функция NewReader
func NewReader(r io.Reader) *Reader
NewReader создаёт новый Reader, читающий из r.
Функция (*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 и использовать возвращённый заголовок.
Функция (*Reader) Read
func (tr *Reader) Read(b []byte) (int, error)
Read считывает данные из текущего файла в архиве tar. Он возвращает (0, io.EOF), когда достигает конца этого файла, до тех пор, пока не будет вызван [Next] для перехода к следующему файлу.
Если текущий файл разреженный, области, помеченные как пустые, читаются как NUL-байты.
Вызов 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
}
Функция NewWriter
func NewWriter(w io.Writer) *Writer
NewWriter создаёт новый Writer, записывающий в w.
Функция (*Writer) AddFS 1.22
func (tw *Writer) AddFS(fsys fs.FS) error
AddFS добавляет файлы из fs.FS в архив. Он обходит древовидную структуру каталогов, начиная с корня файловой системы, добавляя каждый файл в архив tar, сохраняя структуру каталогов.
Функция (*Writer) Close
func (tw *Writer) Close() error
Close закрывает архив tar, очищая заполнители и записывая подпись. Если текущий файл (из предыдущего вызова Writer.WriteHeader) не записан полностью, возвращается ошибка.
Функция (*Writer) Flush
func (tw *Writer) Flush() error
Flush завершает запись заполнителей текущего блока файла. Текущий файл должен быть записан полностью перед вызовом Flush.
Это необязательно, так как следующий вызов Writer.WriteHeader или Writer.Close неявно очистит заполнители файла.
Функция (*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].
Функция (*Writer) WriteHeader
func (tw *Writer) WriteHeader(hdr *Header) error
WriteHeader записывает hdr и подготавливает приём содержимого файла. Header.Size определяет, сколько байтов можно записать для следующего файла. Если текущий файл не записан полностью, возвращается ошибка. Это неявно очищает необходимые заполнители перед записью заголовка.
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/archive/tar/
