1 // Copyright 2009 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
5 // Package gzip implements reading and writing of gzip format compressed files,
6 // as specified in RFC 1952.
31 // ErrChecksum is returned when reading GZIP data that has an invalid checksum.
32 ErrChecksum
= errors
.New("gzip: invalid checksum")
33 // ErrHeader is returned when reading GZIP data that has an invalid header.
34 ErrHeader
= errors
.New("gzip: invalid header")
37 var le
= binary
.LittleEndian
39 // noEOF converts io.EOF to io.ErrUnexpectedEOF.
40 func noEOF(err error
) error
{
42 return io
.ErrUnexpectedEOF
47 // The gzip file stores a header giving metadata about the compressed file.
48 // That header is exposed as the fields of the Writer and Reader structs.
50 // Strings must be UTF-8 encoded and may only contain Unicode code points
51 // U+0001 through U+00FF, due to limitations of the GZIP file format.
53 Comment
string // comment
54 Extra
[]byte // "extra data"
55 ModTime time
.Time
// modification time
56 Name
string // file name
57 OS
byte // operating system type
60 // A Reader is an io.Reader that can be read to retrieve
61 // uncompressed data from a gzip-format compressed file.
63 // In general, a gzip file can be a concatenation of gzip files,
64 // each with its own header. Reads from the Reader
65 // return the concatenation of the uncompressed data of each.
66 // Only the first header is recorded in the Reader fields.
68 // Gzip files store a length and checksum of the uncompressed data.
69 // The Reader will return a ErrChecksum when Read
70 // reaches the end of the uncompressed data if it does not
71 // have the expected length or checksum. Clients should treat data
72 // returned by Read as tentative until they receive the io.EOF
73 // marking the end of the data.
75 Header
// valid after NewReader or Reader.Reset
77 decompressor io
.ReadCloser
78 digest
uint32 // CRC-32, IEEE polynomial (section 8)
79 size
uint32 // Uncompressed size (section 2.3.1)
85 // NewReader creates a new Reader reading the given reader.
86 // If r does not also implement io.ByteReader,
87 // the decompressor may read more data than necessary from r.
89 // It is the caller's responsibility to call Close on the Reader when done.
91 // The Reader.Header fields will be valid in the Reader returned.
92 func NewReader(r io
.Reader
) (*Reader
, error
) {
94 if err
:= z
.Reset(r
); err
!= nil {
100 // Reset discards the Reader z's state and makes it equivalent to the
101 // result of its original state from NewReader, but reading from r instead.
102 // This permits reusing a Reader rather than allocating a new one.
103 func (z
*Reader
) Reset(r io
.Reader
) error
{
105 decompressor
: z
.decompressor
,
108 if rr
, ok
:= r
.(flate
.Reader
); ok
{
111 z
.r
= bufio
.NewReader(r
)
113 z
.Header
, z
.err
= z
.readHeader()
117 // Multistream controls whether the reader supports multistream files.
119 // If enabled (the default), the Reader expects the input to be a sequence
120 // of individually gzipped data streams, each with its own header and
121 // trailer, ending at EOF. The effect is that the concatenation of a sequence
122 // of gzipped files is treated as equivalent to the gzip of the concatenation
123 // of the sequence. This is standard behavior for gzip readers.
125 // Calling Multistream(false) disables this behavior; disabling the behavior
126 // can be useful when reading file formats that distinguish individual gzip
127 // data streams or mix gzip data streams with other data streams.
128 // In this mode, when the Reader reaches the end of the data stream,
129 // Read returns io.EOF. If the underlying reader implements io.ByteReader,
130 // it will be left positioned just after the gzip stream.
131 // To start the next stream, call z.Reset(r) followed by z.Multistream(false).
132 // If there is no next stream, z.Reset(r) will return io.EOF.
133 func (z
*Reader
) Multistream(ok
bool) {
137 // readString reads a NUL-terminated string from z.r.
138 // It treats the bytes read as being encoded as ISO 8859-1 (Latin-1) and
139 // will output a string encoded using UTF-8.
140 // This method always updates z.digest with the data read.
141 func (z
*Reader
) readString() (string, error
) {
148 z
.buf
[i
], err
= z
.r
.ReadByte()
156 // Digest covers the NUL terminator.
157 z
.digest
= crc32
.Update(z
.digest
, crc32
.IEEETable
, z
.buf
[:i
+1])
159 // Strings are ISO 8859-1, Latin-1 (RFC 1952, section 2.3.1).
161 s
:= make([]rune
, 0, i
)
162 for _
, v
:= range z
.buf
[:i
] {
163 s
= append(s
, rune(v
))
165 return string(s
), nil
167 return string(z
.buf
[:i
]), nil
172 // readHeader reads the GZIP header according to section 2.3.1.
173 // This method does not set z.err.
174 func (z
*Reader
) readHeader() (hdr Header
, err error
) {
175 if _
, err
= io
.ReadFull(z
.r
, z
.buf
[:10]); err
!= nil {
176 // RFC 1952, section 2.2, says the following:
177 // A gzip file consists of a series of "members" (compressed data sets).
179 // Other than this, the specification does not clarify whether a
180 // "series" is defined as "one or more" or "zero or more". To err on the
181 // side of caution, Go interprets this to mean "zero or more".
182 // Thus, it is okay to return io.EOF here.
185 if z
.buf
[0] != gzipID1 || z
.buf
[1] != gzipID2 || z
.buf
[2] != gzipDeflate
{
186 return hdr
, ErrHeader
189 if t
:= int64(le
.Uint32(z
.buf
[4:8])); t
> 0 {
190 // Section 2.3.1, the zero value for MTIME means that the
191 // modified time is not set.
192 hdr
.ModTime
= time
.Unix(t
, 0)
194 // z.buf[8] is XFL and is currently ignored.
196 z
.digest
= crc32
.ChecksumIEEE(z
.buf
[:10])
198 if flg
&flagExtra
!= 0 {
199 if _
, err
= io
.ReadFull(z
.r
, z
.buf
[:2]); err
!= nil {
200 return hdr
, noEOF(err
)
202 z
.digest
= crc32
.Update(z
.digest
, crc32
.IEEETable
, z
.buf
[:2])
203 data
:= make([]byte, le
.Uint16(z
.buf
[:2]))
204 if _
, err
= io
.ReadFull(z
.r
, data
); err
!= nil {
205 return hdr
, noEOF(err
)
207 z
.digest
= crc32
.Update(z
.digest
, crc32
.IEEETable
, data
)
212 if flg
&flagName
!= 0 {
213 if s
, err
= z
.readString(); err
!= nil {
219 if flg
&flagComment
!= 0 {
220 if s
, err
= z
.readString(); err
!= nil {
226 if flg
&flagHdrCrc
!= 0 {
227 if _
, err
= io
.ReadFull(z
.r
, z
.buf
[:2]); err
!= nil {
228 return hdr
, noEOF(err
)
230 digest
:= le
.Uint16(z
.buf
[:2])
231 if digest
!= uint16(z
.digest
) {
232 return hdr
, ErrHeader
237 if z
.decompressor
== nil {
238 z
.decompressor
= flate
.NewReader(z
.r
)
240 z
.decompressor
.(flate
.Resetter
).Reset(z
.r
, nil)
245 // Read implements io.Reader, reading uncompressed bytes from its underlying Reader.
246 func (z
*Reader
) Read(p
[]byte) (n
int, err error
) {
251 n
, z
.err
= z
.decompressor
.Read(p
)
252 z
.digest
= crc32
.Update(z
.digest
, crc32
.IEEETable
, p
[:n
])
255 // In the normal case we return here.
259 // Finished file; check checksum and size.
260 if _
, err
:= io
.ReadFull(z
.r
, z
.buf
[:8]); err
!= nil {
264 digest
:= le
.Uint32(z
.buf
[:4])
265 size
:= le
.Uint32(z
.buf
[4:8])
266 if digest
!= z
.digest || size
!= z
.size
{
270 z
.digest
, z
.size
= 0, 0
272 // File is ok; check if there is another.
276 z
.err
= nil // Remove io.EOF
278 if _
, z
.err
= z
.readHeader(); z
.err
!= nil {
282 // Read from next file, if necessary.
289 // Close closes the Reader. It does not close the underlying io.Reader.
290 // In order for the GZIP checksum to be verified, the reader must be
291 // fully consumed until the io.EOF.
292 func (z
*Reader
) Close() error
{ return z
.decompressor
.Close() }