summary refs log tree commit diff
path: root/doc/zlib/inflateBack.3
blob: 59d5f8cbd31ecbab1493cc29c0d2ab9a3fbbab8a (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
.Dd January 15, 2017
.Dt INFLATEBACK 3
.Os
.
.Sh NAME
.Nm inflateBack
.Nd inflate call-back interface
.
.Sh LIBRARY
.Lb libz
.
.Sh SYNOPSIS
.In zlib.h
.
.Ft typedef unsigned
.Fo (*in_func)
.Fa "void FAR *"
.Fa "z_const unsigned char FAR * FAR *"
.Fc
.
.Ft typedef int
.Fo (*out_func)
.Fa "void FAR *"
.Fa "unsigned char FAR *"
.Fa "unsigned"
.Fc
.
.Ft int
.Fo inflateBack
.Fa "z_streamp strm"
.Fa "in_func in"
.Fa "void FAR *in_desc"
.Fa "out_func out"
.Fa "void FAR *out_desc"
.Fc
.
.Sh DESCRIPTION
.Fn inflateBack
does a raw inflate
with a single call
using a call-back interface
for input and output.
This is potentially more efficient than
.Xr inflate 3
for file I/O applications,
in that it avoids copying between the output
and the sliding window
by simply making the window itself the output buffer.
.Xr inflate 3
can be faster on modern CPUs
when used with large buffers.
.Fn inflateBack
trusts the application to not change
the output buffer passed by the output function,
at least until
.Fn inflateBack
returns.
.
.Pp
.Xr inflateBackInit 3
must be called first
to allocate the internal state
and to initialize the state
with the user-provided window buffer.
.Fn inflateBack
may then be used multiple times
to inflate a complete,
raw deflate stream
with each call.
.Xr inflateBackEnd 3
is then called to free the allocated state.
.
.Pp
A raw deflate stream
is one with no zlib or gzip header or trailer.
This routine would normally be used
in a utility that reads zip or gzip files
and write out uncompressed files.
The utility would decode the header
and process the trailer on its own,
hence this routine expects only
the raw deflate stream to decompress.
This is different from the default behaviour of
.Xr inflate 3 ,
which expects a zlib header and trailer
around the deflate stream.
.
.Pp
.Fn inflateBack
uses two subroutines
supplied by the caller
that are then called by
.Fn inflateBack
for input and output.
.Fn inflateBack
calls those routines
until it reads a complete deflate stream
and writes out all of the uncompressed data,
or until it encounters an error.
The function's parameters and return types
are defined above in the
.Vt in_func
and
.Vt out_func
typedefs.
.Fn inflateBack
will call
.Fn in in_desc &buf
which should return
the number of bytes of provided input,
and a pointer to that input in
.Fa buf .
If there is no input available,
.Fn in
must return zero \(em
.Fa buf
is ignored in that case \(em
and
.Fn inflateBack
will return a buffer error.
.Fn inflateBack
will call
.Fn out out_desc buf len
to write the uncompressed data
.Fa buf[0..len-1] .
.Fn out
should return zero on success,
or non-zero on failure.
If
.Fn out
returns non-zero,
.Fn inflateBack
will return with an error.
Neither
.Fn in
nor
.Fn out
are permitted to change
the contents of the window provided to
.Xr inflateBackInit 3 ,
which is also the buffer that
.Fn out
uses to write from.
The length written by
.Fn out
will be at most the window size.
Any non-zero amount of input
may be provided by
.Fn in .
.
.Pp
For convenience,
.Fn inflateBack
can be provided input on the first call
by setting
.Fa strm->next_in
and
.Fa strm->avail_in .
If that input is exhausted,
then
.Fn in
will be called.
Therefore
.Fa strm->next_in
must be initialized before calling
.Fn inflateBack .
If
.Fa strm->next_in
is
.Dv Z_NULL ,
then
.Fn in
will be called immediately for input.
If
.Fa strm->next_in
is not
.Dv Z_NULL ,
then
.Fa strm->avail_in
must also be initialized,
and then if
.Fa strm->avail_in
is not zero,
input will initially be taken from
.Fa "strm->next_in[0 .. strm->avail_in - 1]" .
.
.Pp
The
.Fa in_desc
and
.Fa out_desc
parameters of
.Fn inflateBack
is passed as the first parameter of
.Fn in
and
.Fn out
respectively when they are called.
These descriptors can be optionally used
to pass any information that the caller-supplied
.Fn in
and
.Fn out
functions need to do their job.
.
.Sh RETURN VALUES
On return,
.Fn inflateBack
will set
.Fa strm->next_in
and
.Fa strm->avail_in
to pass back any unused input
that was provided by the last
.Fn in
call.
The return values of
.Fn inflateBack
can be
.Dv Z_STREAM_END
on success,
.Dv Z_BUF_ERROR
if
.Fn in
or
.Fn out
returned an error,
.Dv Z_DATA_ERROR
if there was a format error
in the deflate stream
.Po
in which case
.Fa strm->msg
is set to indicate the nature of the error
.Pc ,
or
.Dv Z_STREAM_ERROR
if the stream was not properly initialized.
In the case of
.Dv Z_BUF_ERROR ,
an input or output error can be distinguished using
.Fa strm->next_in
which will be
.Dv Z_NULL
only if
.Fn in
returned an error.
If
.Fa strm->next_in
is not
.Dv Z_NULL ,
then the
.Dv Z_BUF_ERROR
was due to
.Fn out
returning non-zero.
.Po
.Fn in
will always be called before
.Fn out ,
so
.Fa strm->next_in
is assured to be defined if
.Fa out
returns non-zero.
.Pc \&
Note that
.Fn inflateBack
cannot return
.Dv Z_OK .
.
.Sh SEE ALSO
.Xr inflate 3 ,
.Xr inflateBackEnd 3 ,
.Xr inflateBackInit 3
.
.Sh HISTORY
This manual page was converted from
.In zlib.h
to mdoc format by
.An C. 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