summary refs log tree commit diff
path: root/doc/zlib/inflate.3
blob: 255e0f8471306233d66d427a7003831ffa89aaa9 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
.Dd January 15, 2017
.Dt INFLATE 3
.Os
.
.Sh NAME
.Nm inflate
.Nd deflate decompression
.
.Sh LIBRARY
.Lb libz
.
.Sh SYNOPSIS
.In zlib.h
.Ft int
.Fn inflate "z_streamp strm" "int flush"
.
.Sh DESCRIPTION
.Fn inflate
decompresses as much data as possible,
and stops when the input buffer becomes empty
or the output buffer becomes full.
It may introduce some output latency
(reading input without producing any output)
except when forced to flush.
.
.Pp
The detailed semantics are as follows.
.Fn inflate
performs one or both of the following actions:
.
.Bl -dash
.It
Decompress more input starting at
.Fa next_in
and update
.Fa next_in
and
.Fa avail_in
accordingly.
If not all input can be processed
(because there is not enough room in the output buffer),
then
.Fa next_in
and
.Fa avail_in
are updated accordingly,
and processing will resume at this point
for the next call of
.Fn inflate .
.
.It
Generate more output starting at
.Fa next_out
and update
.Fa next_out
and
.Fa avail_out
accordingly.
.Fn inflate
provides as much output as possible,
until there is no more input data
or no more space in the output buffer
.Po
see below about the
.Fa flush
parameter
.Pc .
.El
.
.Pp
Before the call of
.Fn inflate ,
the application should ensure that
at least one of the actions is possible,
by providing more input
and/or consuming more output,
and updating the
.Fa next_*
and
.Fa avail_*
values accordingly.
If the caller of
.Fn inflate
does not provide both available input
and available output space,
it is possible that there will be no progress made.
The application can consume the uncompressed output
when it wants,
for example when the output buffer is full
.Po
.Fa avail_out
== 0
.Pc ,
or after each call of
.Fn inflate .
If
.Fn inflate
returns
.Dv Z_OK
and with zero
.Fa avail)out ,
it must be called again after making room
in the output buffer
because there might be more output pending.
.
.Pp
The
.Fa flush
parameter of
.Fn inflate
can be
.Dv Z_NO_FLUSH ,
.Dv Z_SYNC_FLUSH ,
.Dv Z_FINISH ,
.Dv Z_BLOCK ,
or
.Dv Z_TREES .
.Dv Z_SYNC_FLUSH
requests that
.Fn inflate
flush as much output as possible
to the output buffer.
.Dv Z_BLOCK
requests that
.Fn inflate
stop if and when it gets to the next deflate block boundary.
When decoding the zlib or gzip format,
this will cause
.Fn inflate
to return immediately after the header
and before the first block.
When doing a raw inflate,
.Fn inflate
will go ahead and process the first block,
and will return when it gets to the end of that block,
or when it runs out of data.
.
.Pp
The
.Dv Z_BLOCK
option assists in appending to
or combining deflate streams.
To assist in this,
on return
.Fn inflate
always sets
.Fa strm->data_type
to the number of unused bits
in the last byte taken from
.Fa strm->next_in ,
plus 64 if
.Fn inflate
is currently decoding the last block in the deflate stream,
plus 128 if
.Fn inflate
returned immediately after decoding an end-of-block code
or decoding the complete header up to
just before the first byte of the deflate stream.
The end-of-block will not be indicated
until all of the uncompressed data
from that block has been written to
.Fa strm->next_out .
The number of unused bits may in general be greater than seven,
except when bit 7 of
.Fa data_type
is set,
in which case the number of unused bits
will be less than eight.
.Fa data_type
is set as noted here every time
.Fn inflate
returns for all flush options,
and so can be used to determine
the amount of currently consumed input in bits.
.
.Pp
The
.Dv Z_TREES
option behaves as
.Dv Z_BLOCK
does,
but it also returns
when the end of each deflate block header is reached,
before any actual data in that block is decoded.
This allows the caller to determine
the length of the deflate block header
for later use in random access
within a deflate block.
256 is added to the value of
.Fa strm->data_type
when
.Fn inflate
returns immediately after reaching
the end of the deflate block header.
.
.Pp
.Fn inflate
should normally be called until it returns
.Dv Z_STREAM_END
or an error.
However if all decompression is to be performed
in a single step
.Po
a single call of
.Fn inflate
.Pc ,
the parameter
.Fa flush
should be set to
.Dv Z_FINISH .
In this case all pending input is processed
and all pending output is flushed;
.Fa avail_out
must be large enough to hold all of
the uncompressed data for the operation to complete.
(The size of the uncompressed data
may have been saved by the compressor for this purpose.)
The use of
.Dv Z_FINISH
is not required to perform inflation in one step.
However it may be used to inform
.Fn inflate
that a faster approach can be used for the single
.Fn inflate
call.
.Dv Z_FINISH also informs
.Fn inflate
to not maintain a sliding window
if the stream completes,
which reduces
.Fn inflate Ap s
memory footprint.
If the stream does not complete,
either because not all of the stream is provided
or not enough output space is provided,
then a sliding window will be allocated and
.Fn inflate
can be called again to continue the operation as if
.Dv Z_NO_FLUSH
had been used.
.
.Pp
In this implementation,
.Fn inflate
always flushes as much output as possible
to the output buffer,
and always uses the faster approach
on the first call.
So the effects of the
.Fa flush
parameter in this implementation
are on the return value of
.Fn inflate
as noted below,
when
.Fn inflate
returns early when
.Dv Z_BLOCK
or
.Dv Z_TREES
is used,
and when
.Fn inflate
avoids the allocation of memory
for a sliding window when
.Dv Z_FINISH
is used.
.
.Pp
If a preset dictionary is needed after this call
.Po
see
.Xr inflateSetDictionary 3
.Pc ,
.Fn inflate
sets
.Fa strm->adler
to the Adler-32 checksum of the dictionary
chosen by the compressor
and returns
.Dv Z_NEED_DICT ;
otherwise it sets
.Fa strm->adler
to the Adler-32 checksum
of all output produced so far
.Po
that is,
.Fa total_out
bytes
.Pc
and returns
.Dv Z_OK ,
.Dv Z_STREAM_END
or an error code
as described in
.Sx RETURN VALUES .
At the end of the stream,
.Fn inflate
checks that its computed Adler-32 checksum
is equal to that saved by the compressor
and returns
.Dv Z_STREAM_END
only if the checksum is correct.
.
.Pp
.Fn inflate
can decompress and check
either zlib-wrapped or gzip-wrapped
deflate data.
The header type is detected automatically,
if requested when initializing with
.Xr inflateInit2 3 .
Any information contained in the gzip header
is not retained unless
.Xr inflateGetHeader 3
is used.
When processing gzip-wrapped deflate data,
.Fa strm->adler32
is set to the CRC-32
of the output produced so far.
The CRC-32 is checked against the gzip trailer,
as is the uncompressed length,
modulo 2^32.
.
.Sh RETURN VALUES
.Fn inflate
returns
.Dv Z_OK
if some progress has been made
(more input processed or more output produced),
.Dv Z_STREAM_END
if the end of the compressed data has been reached
and all uncompressed output has been produced,
.Dv Z_NEED_DICT
if a preset dictionary is needed at this point,
.Dv Z_DATA_ERROR
if the input data was corrupted
.Po
input stream not conforming to the zlib format
or incorrect check value,
in which case
.Fa strm->msg
points to a string with a more specific error
.Pc ,
.Dv Z_STREAM_ERROR
if the stream structure was inconsistent
.Po
for example
.Fa next_in
or
.Fa next_out
was
.Dv Z_NULL ,
or the state was inadvertently written over
by the application
.Pc ,
.Dv Z_MEM_ERROR
if there was not enough memory,
.Dv Z_BUF_ERROR
if no progress was possible
or if there was not enough room
in the output buffer when
.Dv Z_FINISH
is used.
Note that
.Dv Z_BUF_ERROR
is not fatal,
and
.Fn inflate
can be called again with more input
and more output space
to continue decompressing.
If
.Dv Z_DATA_ERROR
is returned,
the application may then call
.Xr inflateSync 3
to look for a good compression block
if a partial recovery of the data
is to be attempted.
.
.Sh SEE ALSO
.Xr deflate 3 ,
.Xr inflateBack 3 ,
.Xr inflateEnd 3 ,
.Xr inflateInit 3 ,
.Xr inflateMark 3 ,
.Xr inflateSync 3
.
.Sh HISTORY
This manual page was converted from
.In zlib.h
to mdoc format by
.An June McEnroe Aq Mt june@causal.agency .
.
.Sh AUTHORS
.An Jean-loup Gailly Aq Mt jloup@gzip.org
.An Mark Adler Aq Mt madler@alumni.caltech.edu