Пакет zip
Обзор
Пакет zip предоставляет поддержку чтения и записи ZIP-архивов.
Подробнее см. в спецификации ZIP.
Этот пакет не поддерживает разбиение архива на диски.
Примечание о ZIP64:
Для обеспечения обратной совместимости FileHeader содержит поля Size размером 32 и 64 бита. 64-битные поля всегда содержат правильное значение, а для обычных архивов оба поля имеют одинаковое значение. Для файлов, которым требуется формат ZIP64, 32-битные поля будут равны 0xffffffff, и вместо них необходимо использовать 64-битные поля.
Индекс
Примеры
Файлы пакета
reader.go register.go struct.go writer.go
Константы
Методы сжатия.
const (
Store uint16 = 0 // no compression
Deflate uint16 = 8 // DEFLATE compressed
) Переменные
var (
ErrFormat = errors.New("zip: not a valid zip file")
ErrAlgorithm = errors.New("zip: unsupported compression algorithm")
ErrChecksum = errors.New("zip: checksum error")
ErrInsecurePath = errors.New("zip: insecure file path")
) func RegisterCompressor 1.2
func RegisterCompressor(method uint16, comp Compressor)
RegisterCompressor регистрирует пользовательские компрессоры для указанного идентификатора метода. Распространённые методы Store и Deflate встроены.
func RegisterDecompressor 1.2
func RegisterDecompressor(method uint16, dcomp Decompressor)
RegisterDecompressor позволяет использовать пользовательские декомпрессоры для указанного идентификатора метода. Распространённые методы Store и Deflate встроены.
type Compressor 1.2
Compressor возвращает новый записывающий объект для сжатия, который записывает данные в w. Для сброса ожидающих данных в w необходимо вызвать метод Close объекта WriteCloser. Сам Compressor должен быть безопасен для одновременного вызова из нескольких горутин, но каждый возвращаемый записывающий объект будет использоваться только одной горутиной одновременно.
type Compressor func(w io.Writer) (io.WriteCloser, error)
type Decompressor 1.2
Decompressor возвращает новый считывающий объект для распаковки, который читает данные из r. Для освобождения связанных ресурсов необходимо вызвать метод Close объекта io.ReadCloser. Сам Decompressor должен быть безопасен для одновременного вызова из нескольких горутин, но каждый возвращаемый считывающий объект будет использоваться только одной горутиной одновременно.
type Decompressor func(r io.Reader) io.ReadCloser
type File
File — это отдельный файл в ZIP-архиве. Информация о файле содержится во встроенном FileHeader. Доступ к содержимому файла можно получить, вызвав File.Open.
type File struct {
FileHeader
// contains filtered or unexported fields
}
func (*File) DataOffset 1.2
func (f *File) DataOffset() (offset int64, err error)
DataOffset возвращает смещение данных файла, возможно сжатых, относительно начала ZIP-файла.
В большинстве случаев вместо этого следует использовать File.Open, который прозрачно распаковывает данные и проверяет контрольные суммы.
func (*File) Open
func (f *File) Open() (io.ReadCloser, error)
Open возвращает ReadCloser, обеспечивающий доступ к содержимому File. Несколько файлов можно читать одновременно.
func (*File) OpenRaw 1.17
func (f *File) OpenRaw() (io.Reader, error)
OpenRaw возвращает Reader, обеспечивающий доступ к содержимому File без распаковки.
type FileHeader
FileHeader описывает файл в ZIP-архиве. Подробнее см. в спецификации ZIP.
type FileHeader struct {
// Name is the name of the file.
//
// It must be a relative path, not start with a drive letter (such as "C:"),
// and must use forward slashes instead of back slashes. A trailing slash
// indicates that this file is a directory and should have no data.
Name string
// Comment is any arbitrary user-defined string shorter than 64KiB.
Comment string
// NonUTF8 indicates that Name and Comment are not encoded in UTF-8.
//
// By specification, the only other encoding permitted should be CP-437,
// but historically many ZIP readers interpret Name and Comment as whatever
// the system's local character encoding happens to be.
//
// This flag should only be set if the user intends to encode a non-portable
// ZIP file for a specific localized region. Otherwise, the Writer
// automatically sets the ZIP format's UTF-8 flag for valid UTF-8 strings.
NonUTF8 bool // Go 1.10
CreatorVersion uint16
ReaderVersion uint16
Flags uint16
// Method is the compression method. If zero, Store is used.
Method uint16
// Modified is the modified time of the file.
//
// When reading, an extended timestamp is preferred over the legacy MS-DOS
// date field, and the offset between the times is used as the timezone.
// If only the MS-DOS date is present, the timezone is assumed to be UTC.
//
// When writing, an extended timestamp (which is timezone-agnostic) is
// always emitted. The legacy MS-DOS date field is encoded according to the
// location of the Modified time.
Modified time.Time // Go 1.10
// ModifiedTime is an MS-DOS-encoded time.
//
// Deprecated: Use Modified instead.
ModifiedTime uint16
// ModifiedDate is an MS-DOS-encoded date.
//
// Deprecated: Use Modified instead.
ModifiedDate uint16
// CRC32 is the CRC32 checksum of the file content.
CRC32 uint32
// CompressedSize is the compressed size of the file in bytes.
// If either the uncompressed or compressed size of the file
// does not fit in 32 bits, CompressedSize is set to ^uint32(0).
//
// Deprecated: Use CompressedSize64 instead.
CompressedSize uint32
// UncompressedSize is the uncompressed size of the file in bytes.
// If either the uncompressed or compressed size of the file
// does not fit in 32 bits, UncompressedSize is set to ^uint32(0).
//
// Deprecated: Use UncompressedSize64 instead.
UncompressedSize uint32
// CompressedSize64 is the compressed size of the file in bytes.
CompressedSize64 uint64 // Go 1.1
// UncompressedSize64 is the uncompressed size of the file in bytes.
UncompressedSize64 uint64 // Go 1.1
// Extra are the extensible data fields. The writer automatically includes
// the appropriate Zip64 field if necessary, and [Writer.Close] appends the
// Central Directory version of the Zip64 field to Extra.
Extra []byte
ExternalAttrs uint32 // Meaning depends on CreatorVersion
}
func FileInfoHeader
func FileInfoHeader(fi fs.FileInfo) (*FileHeader, error)
FileInfoHeader создаёт частично заполненный FileHeader на основе fs.FileInfo. Поскольку метод Name объекта fs.FileInfo возвращает только базовое имя описываемого файла, может потребоваться изменить поле Name возвращаемого заголовка, чтобы указать полный путь к файлу. Если требуется сжатие, вызывающие стороны должны задать поле FileHeader.Method; по умолчанию оно не задано.
func (*FileHeader) FileInfo
func (h *FileHeader) FileInfo() fs.FileInfo
FileInfo возвращает fs.FileInfo для FileHeader.
func (*FileHeader) ModTime
func (h *FileHeader) ModTime() time.Time
ModTime возвращает время изменения в UTC, используя устаревшие поля [ModifiedDate] и [ModifiedTime].
Устарело: используйте [Modified].
func (*FileHeader) Mode
func (h *FileHeader) Mode() (mode fs.FileMode)
Mode возвращает биты разрешений и режима для FileHeader.
func (*FileHeader) SetModTime
func (h *FileHeader) SetModTime(t time.Time)
SetModTime устанавливает поля [Modified], [ModifiedTime] и [ModifiedDate], задавая указанное время в UTC.
Устарело: используйте [Modified].
func (*FileHeader) SetMode
func (h *FileHeader) SetMode(mode fs.FileMode)
SetMode изменяет биты разрешений и режима для FileHeader.
type ReadCloser
ReadCloser — это Reader, который необходимо закрыть, когда он больше не нужен.
type ReadCloser struct {
Reader
// contains filtered or unexported fields
}
func OpenReader
func OpenReader(name string) (*ReadCloser, error)
OpenReader открывает ZIP-файл, указанный именем, и возвращает ReadCloser.
Если имя какого-либо файла в архиве не является локальным (согласно определению filepath.IsLocal) или содержит обратные косые черты, а переменная окружения GODEBUG содержит `zipinsecurepath=0`, OpenReader возвращает reader с ошибкой ErrInsecurePath. В будущей версии Go это поведение может стать поведением по умолчанию. Программы, которым нужно принимать нелокальные имена, могут игнорировать ошибку ErrInsecurePath и использовать возвращённый reader.
func (*ReadCloser) Close
func (rc *ReadCloser) Close() error
Close закрывает ZIP-файл, делая его непригодным для ввода-вывода.
type Reader
Reader предоставляет доступ к содержимому ZIP-архива.
type Reader struct {
File []*File
Comment string
// contains filtered or unexported fields
}
Пример
Код:
// Open a zip archive for reading.
r, err := zip.OpenReader("testdata/readme.zip")
if err != nil {
log.Fatal(err)
}
defer r.Close()
// Iterate through the files in the archive,
// printing some of their contents.
for _, f := range r.File {
fmt.Printf("Contents of %s:\n", f.Name)
rc, err := f.Open()
if err != nil {
log.Fatal(err)
}
_, err = io.CopyN(os.Stdout, rc, 68)
if err != nil {
log.Fatal(err)
}
rc.Close()
fmt.Println()
}
Вывод:
Contents of README: This is the source code repository for the Go programming language.
func NewReader
func NewReader(r io.ReaderAt, size int64) (*Reader, error)
NewReader возвращает новый Reader, читающий данные из r, размер которого в байтах считается равным указанному значению.
Если имя какого-либо файла в архиве не является локальным (согласно определению filepath.IsLocal) или содержит обратные косые черты, а переменная окружения GODEBUG содержит `zipinsecurepath=0`, NewReader возвращает reader с ошибкой ErrInsecurePath. В будущей версии Go это поведение может стать поведением по умолчанию. Программы, которым нужно принимать нелокальные имена, могут игнорировать ошибку ErrInsecurePath и использовать возвращённый reader.
func (*Reader) Open 1.16
func (r *Reader) Open(name string) (fs.File, error)
Open открывает файл с указанным именем в ZIP-архиве, используя семантику fs.FS.Open: пути всегда разделяются косыми чертами и не содержат начальных / или элементов ../.
func (*Reader) RegisterDecompressor 1.6
func (r *Reader) RegisterDecompressor(method uint16, dcomp Decompressor)
RegisterDecompressor регистрирует или переопределяет пользовательский декомпрессор для определённого идентификатора метода. Если декомпрессор для указанного метода не найден, Reader по умолчанию будет искать декомпрессор на уровне пакета.
type Writer
Writer реализует запись ZIP-файлов.
type Writer struct {
// contains filtered or unexported fields
}
Пример
Код:
// Create a buffer to write our archive to.
buf := new(bytes.Buffer)
// Create a new zip archive.
w := zip.NewWriter(buf)
// Add some files to the archive.
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 licence.\nWrite more examples."},
}
for _, file := range files {
f, err := w.Create(file.Name)
if err != nil {
log.Fatal(err)
}
_, err = f.Write([]byte(file.Body))
if err != nil {
log.Fatal(err)
}
}
// Make sure to check the error on Close.
err := w.Close()
if err != nil {
log.Fatal(err)
}
func NewWriter
func NewWriter(w io.Writer) *Writer
NewWriter возвращает новый Writer, записывающий ZIP-файл в w.
Обратите внимание: точные байты, записываемые в w, не входят в гарантию совместимости Go 1. Вызывающий код, включая тесты, не должен зависеть от точного содержимого записи.
func (*Writer) AddFS 1.22
func (w *Writer) AddFS(fsys fs.FS) error
AddFS добавляет файлы из fs.FS в архив. Метод обходит дерево каталогов, начиная с корня файловой системы, и добавляет каждый файл в ZIP-архив с использованием Deflate, сохраняя структуру каталогов.
func (*Writer) Close
func (w *Writer) Close() error
Close завершает запись ZIP-файла, записывая центральный каталог. Метод не закрывает нижележащий writer.
func (*Writer) Copy 1.17
func (w *Writer) Copy(f *File) error
Copy копирует файл f (полученный из Reader) в w. Метод напрямую копирует исходное представление, минуя распаковку, сжатие и проверку.
func (*Writer) Create
func (w *Writer) Create(name string) (io.Writer, error)
Create добавляет файл в ZIP-файл, используя указанное имя. Метод возвращает Writer, в который следует записать содержимое файла. Содержимое файла будет сжато методом Deflate. Имя должно быть относительным путём: оно не должно начинаться с буквы диска (например, C:) или начальной косой черты; допускаются только прямые косые черты. Чтобы создать каталог вместо файла, добавьте в конец имени косую черту. Повторяющиеся имена не перезаписывают предыдущие записи, а добавляются в ZIP-файл. Содержимое файла необходимо записать в io.Writer до следующего вызова Writer.Create, Writer.CreateHeader или Writer.Close.
func (*Writer) CreateHeader
func (w *Writer) CreateHeader(fh *FileHeader) (io.Writer, error)
CreateHeader добавляет файл в ZIP-архив, используя предоставленный FileHeader с метаданными файла. Writer принимает fh во владение и может изменять его поля. После вызова Writer.CreateHeader вызывающий код не должен изменять fh.
Метод возвращает Writer, в который следует записать содержимое файла. Содержимое файла необходимо записать в io.Writer до следующего вызова Writer.Create, Writer.CreateHeader, Writer.CreateRaw или Writer.Close.
func (*Writer) CreateRaw 1.17
func (w *Writer) CreateRaw(fh *FileHeader) (io.Writer, error)
CreateRaw добавляет файл в ZIP-архив, используя предоставленный FileHeader, и возвращает Writer, в который следует записать содержимое файла. Содержимое файла необходимо записать в io.Writer до следующего вызова Writer.Create, Writer.CreateHeader, Writer.CreateRaw или Writer.Close.
В отличие от Writer.CreateHeader, байты, передаваемые в Writer, не сжимаются.
Аргумент CreateRaw сохраняется в w. Если аргумент является указателем на встроенный FileHeader в File, полученном из Reader, созданного на основе данных в памяти, то w будет ссылаться на всю эту память.
func (*Writer) Flush 1.4
func (w *Writer) Flush() error
Flush сбрасывает все буферизованные данные в нижележащий writer. Обычно вызывать Flush не требуется: достаточно вызвать Close.
func (*Writer) RegisterCompressor 1.6
func (w *Writer) RegisterCompressor(method uint16, comp Compressor)
RegisterCompressor регистрирует или переопределяет пользовательский компрессор для указанного идентификатора метода. Если компрессор для заданного метода не найден, Writer по умолчанию будет искать компрессор на уровне пакета.
Пример
Код:
// Override the default Deflate compressor with a higher compression level.
// Create a buffer to write our archive to.
buf := new(bytes.Buffer)
// Create a new zip archive.
w := zip.NewWriter(buf)
// Register a custom Deflate compressor.
w.RegisterCompressor(zip.Deflate, func(out io.Writer) (io.WriteCloser, error) {
return flate.NewWriter(out, flate.BestCompression)
})
// Proceed to add files to w.
func (*Writer) SetComment 1.10
func (w *Writer) SetComment(comment string) error
SetComment задаёт поле комментария конца центрального каталога. Этот метод можно вызывать только до вызова Writer.Close.
func (*Writer) SetOffset 1.5
func (w *Writer) SetOffset(n int64)
SetOffset задаёт смещение начала данных zip в базовом объекте записи. Этот метод следует использовать, когда данные zip добавляются к существующему файлу, например к исполняемому двоичному файлу. Его необходимо вызвать до записи любых данных.
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/archive/zip/
