| blob | fccdf56d79e19e7b7968fd2402e1cc5e434bd8b8 |
1 .\" $NetBSD: zlib.3,v 1.10 2014/03/18 18:20:38 riastradh Exp $
2 .\" $OpenBSD: zlib.3,v 1.1 2003/09/25 09:12:09 jmc Exp $
3 .\"
4 .\" Copyright (C) 1995-2002 Jean-loup Gailly and Mark Adler
5 .\"
6 .\" This software is provided 'as-is', without any express or implied
7 .\" warranty. In no event will the authors be held liable for any damages
8 .\" arising from the use of this software.
9 .\"
10 .\" Permission is granted to anyone to use this software for any purpose,
11 .\" including commercial applications, and to alter it and redistribute it
12 .\" freely, subject to the following restrictions:
13 .\"
14 .\" The origin of this software must not be misrepresented; you must not
15 .\" claim that you wrote the original software. If you use this software
16 .\" in a product, an acknowledgment in the product documentation would be
17 .\" appreciated but is not required.
18 .\" Altered source versions must be plainly marked as such, and must not be
19 .\" misrepresented as being the original software.
20 .\" This notice may not be removed or altered from any source distribution.
21 .\"
22 .\" Converted to mdoc format for the OpenBSD project
23 .\" by Jason McIntyre <jmc@openbsd.org>
24 .\"
25 .Dd May 1, 2004
26 .Dt ZLIB 3
27 .Os
28 .Sh NAME
29 .Nm zlib
30 .Nd general purpose compression library
31 .Sh SYNOPSIS
32 .In zlib.h
33 .Ss Basic functions
34 .Ft const char *
35 .Fn zlibVersion "void"
36 .Ft int
37 .Fn deflateInit "z_streamp strm" "int level"
38 .Ft int
39 .Fn deflate "z_streamp strm" "int flush"
40 .Ft int
41 .Fn deflateEnd "z_streamp strm"
42 .Ft int
43 .Fn inflateInit "z_streamp strm"
44 .Ft int
45 .Fn inflate "z_streamp strm" "int flush"
46 .Ft int
47 .Fn inflateEnd "z_streamp strm"
48 .Ss Advanced functions
49 .Ft int
50 .Fn deflateInit2 "z_streamp strm" "int level" "int method" \
51 "int windowBits" "int memLevel" "int strategy"
52 .Ft int
53 .Fn deflateSetDictionary "z_streamp strm" "const Bytef *dictionary" \
54 "uInt dictLength"
55 .Ft int
56 .Fn deflateCopy "z_streamp dest" "z_streamp source"
57 .Ft int
58 .Fn deflateReset "z_streamp strm"
59 .Ft int
60 .Fn deflateParams "z_streamp strm" "int level" "int strategy"
61 .Ft int
62 .Fn inflateInit2 "z_streamp strm" "int windowBits"
63 .Ft int
64 .Fn inflateSetDictionary "z_streamp strm" "const Bytef *dictionary" "uInt dictLength"
65 .Ft int
66 .Fn inflateSync "z_streamp strm"
67 .Ft int
68 .Fn inflateReset "z_streamp strm"
69 .Ss Utility functions
70 .Fd typedef voidp gzFile ;
71 .Pp
72 .Ft int
73 .Fn compress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen"
74 .Ft int
75 .Fn compress2 "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" "int level"
76 .Ft int
77 .Fn uncompress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen"
78 .Ft gzFile
79 .Fn gzopen "const char *path" "const char *mode"
80 .Ft gzFile
81 .Fn gzdopen "int fd" "const char *mode"
82 .Ft int
83 .Fn gzsetparams "gzFile file" "int level" "int strategy"
84 .Ft int
85 .Fn gzread "gzFile file" "voidp buf" "unsigned len"
86 .Ft int
87 .Fn gzwrite "gzFile file" "const voidp buf" "unsigned len"
88 .Ft int
89 .Fn gzprintf "gzFile file" "const char *format" "..."
90 .Ft int
91 .Fn gzputs "gzFile file" "const char *s"
92 .Ft char *
93 .Fn gzgets "gzFile file" "char *buf" "int len"
94 .Ft int
95 .Fn gzputc "gzFile file" "int c"
96 .Ft int
97 .Fn gzgetc "gzFile file"
98 .Ft int
99 .Fn gzflush "gzFile file" "int flush"
100 .Ft z_off_t
101 .Fn gzseek "gzFile file" "z_off_t offset" "int whence"
102 .Ft int
103 .Fn gzrewind "gzFile file"
104 .Ft z_off_t
105 .Fn gztell "gzFile file"
106 .Ft int
107 .Fn gzeof "gzFile file"
108 .Ft int
109 .Fn gzclose "gzFile file"
110 .Ft const char *
111 .Fn gzerror "gzFile file" "int *errnum"
112 .Ss Checksum functions
113 .Ft uLong
114 .Fn adler32 "uLong adler" "const Bytef *buf" "uInt len"
115 .Ft uLong
116 .Fn crc32 "uLong crc" "const Bytef *buf" "uInt len"
117 .Sh DESCRIPTION
118 This manual page describes the
119 .Nm
120 general purpose compression library, version 1.1.4.
121 .Pp
122 The
123 .Nm
124 compression library provides in-memory compression and decompression functions,
125 including integrity checks of the uncompressed data.
126 This version of the library supports only one compression method
127 .Pq deflation
128 but other algorithms will be added later and will have the same
129 stream interface.
130 .Pp
131 Compression can be done in a single step if the buffers are large enough
132 .Pq for example if an input file is mmap'ed ,
133 or can be done by repeated calls of the compression function.
134 In the latter case, the application must provide more input
135 and/or consume the output
136 .Pq providing more output space
137 before each call.
138 .Pp
139 The library also supports reading and writing files in
140 .Xr gzip 1
141 .Pq .gz
142 format with an interface similar to that of
143 .Xr stdio 3 .
144 .Pp
145 The library does not install any signal handler.
146 The decoder checks the consistency of the compressed data,
147 so the library should never crash even in case of corrupted input.
148 .Pp
149 The functions within the library are divided into the following sections:
150 .Pp
151 .Bl -dash -offset indent -compact
152 .It
153 Basic functions
154 .It
155 Advanced functions
156 .It
157 Utility functions
158 .It
159 Checksum functions
160 .El
161 .Sh BASIC FUNCTIONS
162 .Bl -tag -width Ds
163 .It Fa const char * Fn zlibVersion "void" ;
164 .Pp
165 The application can compare
166 .Fn zlibVersion
167 and
168 .Dv ZLIB_VERSION
169 for consistency.
170 If the first character differs, the library code actually used is
171 not compatible with the
172 .In zlib.h
173 header file used by the application.
174 This check is automatically made by
175 .Fn deflateInit
176 and
177 .Fn inflateInit .
178 .It Fa int Fn deflateInit "z_streamp strm" "int level" ;
179 .Pp
180 The
181 .Fn deflateInit
182 function initializes the internal stream state for compression.
183 The fields
184 .Fa zalloc ,
185 .Fa zfree ,
186 and
187 .Fa opaque
188 must be initialized before by the caller.
189 If
190 .Fa zalloc
191 and
192 .Fa zfree
193 are set to
194 .Dv Z_NULL ,
195 .Fn deflateInit
196 updates them to use default allocation functions.
197 .Pp
198 The compression level must be
199 .Dv Z_DEFAULT_COMPRESSION ,
200 or between 0 and 9:
201 1 gives best speed, 9 gives best compression, 0 gives no compression at all
202 (the input data is simply copied a block at a time).
203 .Pp
204 .Dv Z_DEFAULT_COMPRESSION
205 requests a default compromise between speed and compression
206 .Pq currently equivalent to level 6 .
207 .Pp
208 .Fn deflateInit
209 returns
210 .Dv Z_OK
211 if successful,
212 .Dv Z_MEM_ERROR
213 if there was not enough memory,
214 .Dv Z_STREAM_ERROR
215 if level is not a valid compression level,
216 .Dv Z_VERSION_ERROR
217 if the
218 .Nm
219 library version
220 .Pq zlib_version
221 is incompatible with the version assumed by the caller
222 .Pq ZLIB_VERSION .
223 .Fa msg
224 is set to null if there is no error message.
225 .Fn deflateInit
226 does not perform any compression: this will be done by
227 .Fn deflate .
228 .It Fa int Fn deflate "z_streamp strm" "int flush" ;
229 .Pp
230 .Fn deflate
231 compresses as much data as possible, and stops when the input
232 buffer becomes empty or the output buffer becomes full.
233 It may introduce some output latency
234 .Pq reading input without producing any output
235 except when forced to flush.
236 .Pp
237 The detailed semantics are as follows.
238 .Fn deflate
239 performs one or both of the following actions:
240 .Pp
241 Compress more input starting at
242 .Fa next_in
243 and update
244 .Fa next_in
245 and
246 .Fa avail_in
247 accordingly.
248 If not all input can be processed
249 (because there is not enough room in the output buffer),
250 .Fa next_in
251 and
252 .Fa avail_in
253 are updated and processing will resume at this point for the next call to
254 .Fn deflate .
255 .Pp
256 Provide more output starting at
257 .Fa next_out
258 and update
259 .Fa next_out
260 and
261 .Fa avail_out
262 accordingly.
263 This action is forced if the parameter
264 .Fa flush
265 is non-zero.
266 Forcing
267 .Fa flush
268 frequently degrades the compression ratio,
269 so this parameter should be set only when necessary
270 .Pq in interactive applications .
271 Some output may be provided even if
272 .Fa flush
273 is not set.
274 .Pp
275 Before the call to
276 .Fn deflate ,
277 the application should ensure that at least
278 one of the actions is possible, by providing more input and/or consuming
279 more output, and updating
280 .Fa avail_in
281 or
282 .Fa avail_out
283 accordingly;
284 .Fa avail_out
285 should never be zero before the call.
286 The application can consume the compressed output when it wants,
287 for example when the output buffer is full
288 .Pq avail_out == 0 ,
289 or after each call to
290 .Fn deflate .
291 If
292 .Fn deflate
293 returns
294 .Dv Z_OK
295 and with zero
296 .Fa avail_out ,
297 it must be called again after making room in the
298 output buffer because there might be more output pending.
299 .Pp
300 If the parameter
301 .Fa flush
302 is set to
303 .Dv Z_SYNC_FLUSH ,
304 all pending output is flushed to the output buffer and the output
305 is aligned on a byte boundary, so that the decompressor can get all
306 input data available so far.
307 (In particular,
308 .Fa avail_in
309 is zero after the call if enough output space
310 has been provided before the call.)
311 Flushing may degrade compression for some compression algorithms
312 and so it should be used only when necessary.
313 .Pp
314 If
315 .Fa flush
316 is set to
317 .Dv Z_FULL_FLUSH ,
318 all output is flushed as with
319 .Dv Z_SYNC_FLUSH ,
320 and the compression state is reset so that decompression can restart from this
321 point if previous compressed data has been damaged or if random access
322 is desired.
323 Using
324 .Dv Z_FULL_FLUSH
325 too often can seriously degrade the compression.
326 .Pp
327 If
328 .Fn deflate
329 returns with avail_out == 0, this function must be called again
330 with the same value of the flush parameter and more output space
331 (updated
332 .Fa avail_out ) ,
333 until the flush is complete
334 .Pf ( Fn deflate
335 returns with non-zero
336 .Fa avail_out ) .
337 .Pp
338 If the parameter
339 .Fa flush
340 is set to
341 .Dv Z_FINISH ,
342 pending input is processed, pending output is flushed and
343 .Fn deflate
344 returns with
345 .Dv Z_STREAM_END
346 if there was enough output space; if
347 .Fn deflate
348 returns with
349 .Dv Z_OK ,
350 this function must be called again with
351 .Dv Z_FINISH
352 and more output space
353 (updated
354 .Fa avail_out
355 but no more input data, until it returns with
356 .Dv Z_STREAM_END
357 or an error.
358 After
359 .Fn deflate
360 has returned
361 .Dv Z_STREAM_END ,
362 the only possible operations on the stream are
363 .Fn deflateReset
364 or
365 .Fn deflateEnd .
366 .Pp
367 .Dv Z_FINISH
368 can be used immediately after
369 .Fn deflateInit
370 if all the compression is to be done in a single step.
371 In this case,
372 .Fa avail_out
373 must be at least 0.1% larger than
374 .Fa avail_in
375 plus 12 bytes.
376 If
377 .Fn deflate
378 does not return
379 .Dv Z_STREAM_END ,
380 then it must be called again as described above.
381 .Pp
382 .Fn deflate
383 sets strm-\*[Gt]adler to the Adler-32 checksum of all input read so far
384 (that is,
385 .Fa total_in
386 bytes).
387 .Pp
388 .Fn deflate
389 may update
390 .Fa data_type
391 if it can make a good guess about the input data type
392 .Pq Z_ASCII or Z_BINARY .
393 If in doubt, the data is considered binary.
394 This field is only for information purposes and does not affect
395 the compression algorithm in any manner.
396 .Pp
397 .Fn deflate
398 returns
399 .Dv Z_OK
400 if some progress has been made
401 .Pq more input processed or more output produced ,
402 .Dv Z_STREAM_END
403 if all input has been consumed and all output has been produced
404 (only when
405 .Fa flush
406 is set to
407 .Dv Z_FINISH ) ,
408 .Dv Z_STREAM_ERROR
409 if the stream state was inconsistent
410 (for example, if
411 .Fa next_in
412 or
413 .Fa next_out
414 was
415 .Dv NULL ) ,
416 .Dv Z_BUF_ERROR
417 if no progress is possible
418 (for example,
419 .Fa avail_in
420 or
421 .Fa avail_out
422 was zero).
423 .It Fa int Fn deflateEnd "z_streamp strm" ;
424 .Pp
425 All dynamically allocated data structures for this stream are freed.
426 This function discards any unprocessed input and does not flush any
427 pending output.
428 .Pp
429 .Fn deflateEnd
430 returns
431 .Dv Z_OK
432 if successful,
433 .Dv Z_STREAM_ERROR
434 if the stream state was inconsistent,
435 .Dv Z_DATA_ERROR
436 if the stream was freed prematurely
437 .Pq some input or output was discarded .
438 In the error case,
439 .Fa msg
440 may be set but then points to a static string
441 .Pq which must not be deallocated .
442 .It Fa int Fn inflateInit "z_streamp strm" ;
443 The
444 .Fn inflateInit
445 function initializes the internal stream state for decompression.
446 The fields
447 .Fa next_in ,
448 .Fa avail_in ,
449 .Fa zalloc ,
450 .Fa zfree ,
451 and
452 .Fa opaque
453 must be initialized before by the caller.
454 If
455 .Fa next_in
456 is not
457 .Dv Z_NULL
458 and
459 .Fa avail_in
460 is large enough
461 .Pq the exact value depends on the compression method ,
462 .Fn inflateInit
463 determines the compression method from the
464 .Nm
465 header and allocates all data structures accordingly;
466 otherwise the allocation will be deferred to the first call to
467 .Fn inflate .
468 If
469 .Fa zalloc
470 and
471 .Fa zfree
472 are set to
473 .Dv Z_NULL ,
474 .Fn inflateInit
475 updates them to use default allocation functions.
476 .Pp
477 .Fn inflateInit
478 returns
479 .Dv Z_OK
480 if successful,
481 .Dv Z_MEM_ERROR
482 if there was not enough memory,
483 .Dv Z_VERSION_ERROR
484 if the
485 .Nm
486 library version is incompatible with the version assumed by the caller.
487 .Fa msg
488 is set to null if there is no error message.
489 .Fn inflateInit
490 does not perform any decompression apart from reading the
491 .Nm
492 header if present: this will be done by
493 .Fn inflate .
494 (So
495 .Fa next_in
496 and
497 .Fa avail_in
498 may be modified,
499 but
500 .Fa next_out
501 and
502 .Fa avail_out
503 are unchanged.)
504 .It Fa int Fn inflate "z_streamp strm" "int flush" ;
505 .Fn inflate
506 decompresses as much data as possible, and stops when the input
507 buffer becomes empty or the output buffer becomes full.
508 It may introduce some output latency
509 .Pq reading input without producing any output
510 except when forced to flush.
511 .Pp
512 The detailed semantics are as follows.
513 .Fn inflate
514 performs one or both of the following actions:
515 .Pp
516 Decompress more input starting at
517 .Fa next_in
518 and update
519 .Fa next_in
520 and
521 .Fa avail_in
522 accordingly.
523 If not all input can be processed
524 (because there is not enough room in the output buffer),
525 .Fa next_in
526 is updated and processing will resume at this point for the next call to
527 .Fn inflate .
528 .Pp
529 Provide more output starting at
530 .Fa next_out
531 and update
532 .Fa next_out
533 and
534 .Fa avail_out
535 accordingly.
536 .Fn inflate
537 provides as much output as possible,
538 until there is no more input data or no more space in the output buffer
539 .Pq see below about the flush parameter .
540 .Pp
541 Before the call to
542 .Fn inflate ,
543 the application should ensure that at least one of the actions is possible,
544 by providing more input and/or consuming more output,
545 and updating the next_* and avail_* values accordingly.
546 The application can consume the uncompressed output when it wants,
547 for example when the output buffer is full (avail_out == 0),
548 or after each call to
549 .Fn inflate .
550 If
551 .Fn inflate
552 returns
553 .Dv Z_OK
554 and with zero
555 .Fa avail_out ,
556 it must be called again after making room
557 in the output buffer because there might be more output pending.
558 .Pp
559 If the parameter
560 .Fa flush
561 is set to
562 .Dv Z_SYNC_FLUSH ,
563 .Fn inflate
564 flushes as much output as possible to the output buffer.
565 The flushing behavior of
566 .Fn inflate
567 is not specified for values of the flush parameter other than
568 .Dv Z_SYNC_FLUSH
569 and
570 .Dv Z_FINISH ,
571 but the current implementation actually flushes as much output
572 as possible anyway.
573 .Pp
574 .Fn inflate
575 should normally be called until it returns
576 .Dv Z_STREAM_END
577 or an error.
578 However if all decompression is to be performed in a single step
579 .Pq a single call to inflate ,
580 the parameter
581 .Fa flush
582 should be set to
583 .Dv Z_FINISH .
584 In this case all pending input is processed and all pending output is flushed;
585 .Fa avail_out
586 must be large enough to hold all the uncompressed data.
587 (The size of the uncompressed data may have been saved
588 by the compressor for this purpose.)
589 The next operation on this stream must be
590 .Fn inflateEnd
591 to deallocate the decompression state.
592 The use of
593 .Dv Z_FINISH
594 is never required, but can be used to inform
595 .Fn inflate
596 that a faster routine may be used for the single
597 .Fn inflate
598 call.
599 .Pp
600 If a preset dictionary is needed at this point (see
601 .Fn inflateSetDictionary
602 below),
603 .Fn inflate
604 sets strm-\*[Gt]adler to the Adler-32 checksum of the dictionary
605 chosen by the compressor and returns
606 .Dv Z_NEED_DICT ;
607 otherwise it sets strm-\*[Gt]adler to the Adler-32 checksum of all output produced
608 so far
609 (that is,
610 .Fa total_out
611 bytes)
612 and returns
613 .Dv Z_OK ,
614 .Dv Z_STREAM_END ,
615 or an error code as described below.
616 At the end of the stream,
617 .Fn inflate
618 checks that its computed Adler-32 checksum is equal to that saved by the
619 compressor and returns
620 .Dv Z_STREAM_END
621 only if the checksum is correct.
622 .Pp
623 .Fn inflate
624 returns
625 .Dv Z_OK
626 if some progress has been made
627 .Pq more input processed or more output produced ,
628 .Dv Z_STREAM_END
629 if the end of the compressed data has been reached and all uncompressed output
630 has been produced,
631 .Dv Z_NEED_DICT
632 if a preset dictionary is needed at this point,
633 .Dv Z_DATA_ERROR
634 if the input data was corrupted (input stream not conforming to the
635 .Nm
636 format or incorrect Adler-32 checksum),
637 .Dv Z_STREAM_ERROR
638 if the stream structure was inconsistent
639 (for example, if
640 .Fa next_in
641 or
642 .Fa next_out
643 was
644 .Dv NULL ) ,
645 .Dv Z_MEM_ERROR
646 if there was not enough memory,
647 .Dv Z_BUF_ERROR
648 if no progress is possible or if there was not enough room in the output buffer
649 when
650 .Dv Z_FINISH
651 is used.
652 In the
653 .Dv Z_DATA_ERROR
654 case, the application may then call
655 .Fn inflateSync
656 to look for a good compression block.
657 .It Fa int Fn inflateEnd "z_streamp strm" ;
658 All dynamically allocated data structures for this stream are freed.
659 This function discards any unprocessed input and does not flush any
660 pending output.
661 .Pp
662 .Fn inflateEnd
663 returns
664 .Dv Z_OK
665 if successful, or
666 .Dv Z_STREAM_ERROR
667 if the stream state was inconsistent.
668 In the error case,
669 .Fa msg
670 may be set but then points to a static string
671 .Pq which must not be deallocated .
672 .El
673 .Sh ADVANCED FUNCTIONS
674 The following functions are needed only in some special applications.
675 .Bl -tag -width Ds
676 .It Fa int Fn deflateInit2 "z_streamp strm" "int level" "int method" \
677 "int windowBits" "int memLevel" "int strategy" ;
678 .Pp
679 This is another version of
680 .Fn deflateInit
681 with more compression options.
682 The fields
683 .Fa next_in ,
684 .Fa zalloc ,
685 .Fa zfree ,
686 and
687 .Fa opaque
688 must be initialized before by the caller.
689 .Pp
690 The
691 .Fa method
692 parameter is the compression method.
693 It must be
694 .Dv Z_DEFLATED
695 in this version of the library.
696 .Pp
697 The
698 .Fa windowBits
699 parameter is the base two logarithm of the window size
700 .Pq the size of the history buffer .
701 It should be in the range 8..15 for this version of the library.
702 Larger values of this parameter result in better compression
703 at the expense of memory usage.
704 The default value is 15 if
705 .Fn deflateInit
706 is used instead.
707 .Pp
708 The
709 .Fa memLevel
710 parameter specifies how much memory should be allocated
711 for the internal compression state.
712 memLevel=1 uses minimum memory but is slow and reduces compression ratio;
713 memLevel=9 uses maximum memory for optimal speed.
714 The default value is 8.
715 See
716 .In zconf.h
717 for total memory usage as a function of
718 .Fa windowBits
719 and
720 .Fa memLevel .
721 .Pp
722 The
723 .Fa strategy
724 parameter is used to tune the compression algorithm.
725 Use the value
726 .Dv Z_DEFAULT_STRATEGY
727 for normal data;
728 .Dv Z_FILTERED
729 for data produced by a filter
730 .Pq or predictor ;
731 or
732 .Dv Z_HUFFMAN_ONLY
733 to force Huffman encoding only
734 .Pq no string match .
735 Filtered data consists mostly of small values with a
736 somewhat random distribution.
737 In this case, the compression algorithm is tuned to compress them better.
738 The effect of
739 .Dv Z_FILTERED
740 is to force more Huffman coding and less string matching;
741 it is somewhat intermediate between
742 .Dv Z_DEFAULT
743 and
744 .Dv Z_HUFFMAN_ONLY .
745 The
746 .Fa strategy
747 parameter only affects the compression ratio but not the correctness of the
748 compressed output, even if it is not set appropriately.
749 .Pp
750 .Fn deflateInit2
751 returns
752 .Dv Z_OK
753 if successful,
754 .Dv Z_MEM_ERROR
755 if there was not enough memory,
756 .Dv Z_STREAM_ERROR
757 if a parameter is invalid
758 .Pq such as an invalid method .
759 .Fa msg
760 is set to null if there is no error message.
761 .Fn deflateInit2
762 does not perform any compression: this will be done by
763 .Fn deflate .
764 .It Fa int Fn deflateSetDictionary "z_streamp strm" \
765 "const Bytef *dictionary" "uInt dictLength" ;
766 .Pp
767 Initializes the compression dictionary from the given byte sequence
768 without producing any compressed output.
769 This function must be called immediately after
770 .Fn deflateInit ,
771 .Fn deflateInit2 ,
772 or
773 .Fn deflateReset ,
774 before any call to
775 .Fn deflate .
776 The compressor and decompressor must use exactly the same dictionary
777 (see
778 .Fn inflateSetDictionary ) .
779 .Pp
780 The dictionary should consist of strings
781 .Pq byte sequences
782 that are likely to be encountered later in the data to be compressed,
783 with the most commonly used strings preferably put towards
784 the end of the dictionary.
785 Using a dictionary is most useful when the data to be compressed is short
786 and can be predicted with good accuracy;
787 the data can then be compressed better than with the default empty dictionary.
788 .Pp
789 Depending on the size of the compression data structures selected by
790 .Fn deflateInit
791 or
792 .Fn deflateInit2 ,
793 a part of the dictionary may in effect be discarded,
794 for example if the dictionary is larger than the window size in
795 .Fn deflate
796 or
797 .Fn deflate2 .
798 Thus the strings most likely to be useful should be
799 put at the end of the dictionary, not at the front.
800 .Pp
801 Upon return of this function, strm-\*[Gt]adler is set to the Adler-32 value
802 of the dictionary; the decompressor may later use this value to determine
803 which dictionary has been used by the compressor.
804 (The Adler-32 value applies to the whole dictionary even if only a subset
805 of the dictionary is actually used by the compressor.)
806 .Pp
807 .Fn deflateSetDictionary
808 returns
809 .Dv Z_OK
810 if successful,
811 or
812 .Dv Z_STREAM_ERROR
813 if a parameter is invalid
814 .Pq such as NULL dictionary
815 or the stream state is inconsistent
816 (for example if
817 .Fn deflate
818 has already been called for this stream or if the compression method is bsort).
819 .Fn deflateSetDictionary
820 does not perform any compression: this will be done by
821 .Fn deflate .
822 .It Fa int Fn deflateCopy "z_streamp dest" "z_streamp source" ;
823 .Pp
824 The
825 .Fn deflateCopy
826 function sets the destination stream as a complete copy of the source stream.
827 .Pp
828 This function can be useful when several compression strategies will be
829 tried, for example when there are several ways of pre-processing the input
830 data with a filter.
831 The streams that will be discarded should then be freed by calling
832 .Fn deflateEnd .
833 Note that
834 .Fn deflateCopy
835 duplicates the internal compression state which can be quite large,
836 so this strategy is slow and can consume lots of memory.
837 .Pp
838 .Fn deflateCopy
839 returns
840 .Dv Z_OK
841 if successful,
842 .Dv Z_MEM_ERROR
843 if there was not enough memory,
844 .Dv Z_STREAM_ERROR
845 if the source stream state was inconsistent
846 (such as
847 .Fa zalloc
848 being NULL).
849 .Fa msg
850 is left unchanged in both source and destination.
851 .It Fa int Fn deflateReset "z_streamp strm" ;
852 .Pp
853 This function is equivalent to
854 .Fn deflateEnd
855 followed by
856 .Fn deflateInit ,
857 but does not free and reallocate all the internal compression state.
858 The stream will keep the same compression level and any other attributes
859 that may have been set by
860 .Fn deflateInit2 .
861 .Pp
862 .Fn deflateReset
863 returns
864 .Dv Z_OK
865 if successful, or
866 .Dv Z_STREAM_ERROR
867 if the source stream state was inconsistent
868 (such as
869 .Fa zalloc
870 or
871 .Fa state
872 being NULL).
873 .It Fa int Fn deflateParams "z_streamp strm" "int level" "int strategy" ;
874 .Pp
875 The
876 .Fn deflateParams
877 function dynamically updates the compression level and compression strategy.
878 The interpretation of level and strategy is as in
879 .Fn deflateInit2 .
880 This can be used to switch between compression and straight copy
881 of the input data, or to switch to a different kind of input data
882 requiring a different strategy.
883 If the compression level is changed, the input available so far
884 is compressed with the old level
885 .Pq and may be flushed ;
886 the new level will take effect only at the next call to
887 .Fn deflate .
888 .Pp
889 Before the call to
890 .Fn deflateParams ,
891 the stream state must be set as for a call to
892 .Fn deflate ,
893 since the currently available input may have to be compressed and flushed.
894 In particular, strm-\*[Gt]avail_out must be non-zero.
895 .Pp
896 .Fn deflateParams
897 returns
898 .Dv Z_OK
899 if successful,
900 .Dv Z_STREAM_ERROR
901 if the source stream state was inconsistent or if a parameter was invalid, or
902 .Dv Z_BUF_ERROR
903 if strm-\*[Gt]avail_out was zero.
904 .It Fa int Fn inflateInit2 "z_streamp strm" "int windowBits" ;
905 .Pp
906 This is another version of
907 .Fn inflateInit
908 with an extra parameter.
909 The fields
910 .Fa next_in ,
911 .Fa avail_in ,
912 .Fa zalloc ,
913 .Fa zfree ,
914 and
915 .Fa opaque
916 must be initialized before by the caller.
917 .Pp
918 The
919 .Fa windowBits
920 parameter is the base two logarithm of the maximum window size
921 .Pq the size of the history buffer .
922 It should be in the range 8..15 for this version of the library.
923 The default value is 15 if
924 .Fn inflateInit
925 is used instead.
926 If a compressed stream with a larger window size is given as input,
927 .Fn inflate
928 will return with the error code
929 .Dv Z_DATA_ERROR
930 instead of trying to allocate a larger window.
931 .Pp
932 .Fn inflateInit2
933 returns
934 .Dv Z_OK
935 if successful,
936 .Dv Z_MEM_ERROR
937 if there was not enough memory,
938 .Dv Z_STREAM_ERROR
939 if a parameter is invalid
940 (such as a negative
941 .Fa memLevel ) .
942 .Fa msg
943 is set to null if there is no error message.
944 .Fn inflateInit2
945 does not perform any decompression apart from reading the
946 .Nm
947 header if present: this will be done by
948 .Fn inflate .
949 (So
950 .Fa next_in
951 and
952 .Fa avail_in
953 may be modified, but
954 .Fa next_out
955 and
956 .Fa avail_out
957 are unchanged.)
958 .It Fa int Fn inflateSetDictionary "z_streamp strm" \
959 "const Bytef *dictionary" "uInt dictLength" ;
960 .Pp
961 Initializes the decompression dictionary from the given uncompressed byte
962 sequence.
963 This function must be called immediately after a call to
964 .Fn inflate
965 if this call returned
966 .Dv Z_NEED_DICT .
967 The dictionary chosen by the compressor can be determined from the
968 Adler-32 value returned by this call to
969 .Fn inflate .
970 The compressor and decompressor must use exactly the same dictionary
971 (see
972 .Fn deflateSetDictionary ) .
973 .Pp
974 .Fn inflateSetDictionary
975 returns
976 .Dv Z_OK
977 if successful,
978 .Dv Z_STREAM_ERROR
979 if a parameter is invalid
980 .Pq such as NULL dictionary
981 or the stream state is inconsistent,
982 .Dv Z_DATA_ERROR
983 if the given dictionary doesn't match the expected one
984 .Pq incorrect Adler-32 value .
985 .Fn inflateSetDictionary
986 does not perform any decompression: this will be done by subsequent calls of
987 .Fn inflate .
988 .It Fa int Fn inflateSync "z_streamp strm" ;
989 .Pp
990 Skips invalid compressed data until a full flush point
991 (see above the description of
992 .Fn deflate
993 with
994 .Dv Z_FULL_FLUSH )
995 can be found, or until all available input is skipped.
996 No output is provided.
997 .Pp
998 .Fn inflateSync
999 returns
1000 .Dv Z_OK
1001 if a full flush point has been found,
1002 .Dv Z_BUF_ERROR
1003 if no more input was provided,
1004 .Dv Z_DATA_ERROR
1005 if no flush point has been found, or
1006 .Dv Z_STREAM_ERROR
1007 if the stream structure was inconsistent.
1008 In the success case, the application may save the current value of
1009 .Fa total_in
1010 which indicates where valid compressed data was found.
1011 In the error case, the application may repeatedly call
1012 .Fn inflateSync ,
1013 providing more input each time, until success or end of the input data.
1014 .It Fa int Fn inflateReset "z_streamp strm" ;
1015 .Pp
1016 This function is equivalent to
1017 .Fn inflateEnd
1018 followed by
1019 .Fn inflateInit ,
1020 but does not free and reallocate all the internal decompression state.
1021 The stream will keep attributes that may have been set by
1022 .Fn inflateInit2 .
1023 .Pp
1024 .Fn inflateReset
1025 returns
1026 .Dv Z_OK
1027 if successful, or
1028 .Dv Z_STREAM_ERROR
1029 if the source stream state was inconsistent
1030 (such as
1031 .Fa zalloc
1032 or
1033 .Fa state
1034 being NULL).
1035 .El
1036 .Sh UTILITY FUNCTIONS
1037 The following utility functions are implemented on top of the
1038 basic stream-oriented functions.
1039 To simplify the interface,
1040 some default options are assumed (compression level and memory usage,
1041 standard memory allocation functions).
1042 The source code of these utility functions can easily be modified
1043 if you need special options.
1044 .Bl -tag -width Ds
1045 .It Fa int Fn compress "Bytef *dest" "uLongf *destLen" \
1046 "const Bytef *source" "uLong sourceLen" ;
1047 .Pp
1048 The
1049 .Fn compress
1050 function compresses the source buffer into the destination buffer.
1051 .Fa sourceLen
1052 is the byte length of the source buffer.
1053 Upon entry,
1054 .Fa destLen
1055 is the total size of the destination buffer,
1056 which must be at least 0.1% larger than
1057 .Fa sourceLen
1058 plus 12 bytes.
1059 Upon exit,
1060 .Fa destLen
1061 is the actual size of the compressed buffer.
1062 This function can be used to compress a whole file at once if the
1063 input file is mmap'ed.
1064 .Pp
1065 .Fn compress
1066 returns
1067 .Dv Z_OK
1068 if successful,
1069 .Dv Z_MEM_ERROR
1070 if there was not enough memory, or
1071 .Dv Z_BUF_ERROR
1072 if there was not enough room in the output buffer.
1073 .It Fa int Fn compress2 "Bytef *dest" "uLongf *destLen" \
1074 "const Bytef *source" "uLong sourceLen" "int level" ;
1075 .Pp
1076 The
1077 .Fn compress2
1078 function compresses the source buffer into the destination buffer.
1079 The
1080 .Fa level
1081 parameter has the same meaning as in
1082 .Fn deflateInit .
1083 .Fa sourceLen
1084 is the byte length of the source buffer.
1085 Upon entry,
1086 .Fa destLen
1087 is the total size of the destination buffer,
1088 which must be at least 0.1% larger than
1089 .Fa sourceLen
1090 plus 12 bytes.
1091 Upon exit,
1092 .Fa destLen
1093 is the actual size of the compressed buffer.
1094 .Pp
1095 .Fn compress2
1096 returns
1097 .Dv Z_OK
1098 if successful,
1099 .Dv Z_MEM_ERROR
1100 if there was not enough memory,
1101 .Dv Z_BUF_ERROR
1102 if there was not enough room in the output buffer, or
1103 .Dv Z_STREAM_ERROR
1104 if the level parameter is invalid.
1105 .It Fa int Fn uncompress "Bytef *dest" "uLongf *destLen" \
1106 "const Bytef *source" "uLong sourceLen" ;
1107 .Pp
1108 The
1109 .Fn uncompress
1110 function decompresses the source buffer into the destination buffer.
1111 .Fa sourceLen
1112 is the byte length of the source buffer.
1113 Upon entry,
1114 .Fa destLen
1115 is the total size of the destination buffer,
1116 which must be large enough to hold the entire uncompressed data.
1117 (The size of the uncompressed data must have been saved previously
1118 by the compressor and transmitted to the decompressor
1119 by some mechanism outside the scope of this compression library.)
1120 Upon exit,
1121 .Fa destLen
1122 is the actual size of the compressed buffer.
1123 This function can be used to decompress a whole file at once if the
1124 input file is mmap'ed.
1125 .Pp
1126 .Fn uncompress
1127 returns
1128 .Dv Z_OK
1129 if successful,
1130 .Dv Z_MEM_ERROR
1131 if there was not enough memory,
1132 .Dv Z_BUF_ERROR
1133 if there was not enough room in the output buffer, or
1134 .Dv Z_DATA_ERROR
1135 if the input data was corrupted.
1136 .It Fa gzFile Fn gzopen "const char *path" "const char *mode" ;
1137 .Pp
1138 The
1139 .Fn gzopen
1140 function opens a gzip
1141 .Pq .gz
1142 file for reading or writing.
1143 The mode parameter is as in
1144 .Xr fopen 3
1145 .Po
1146 .Qq rb
1147 or
1148 .Qq wb
1149 .Pc
1150 but can also include a compression level
1151 .Pq Qq wb9
1152 or a strategy:
1153 .Sq f
1154 for filtered data, as in
1155 .Qq wb6f ;
1156 .Sq h
1157 for Huffman only compression, as in
1158 .Qq wb1h .
1159 (See the description of
1160 .Fn deflateInit2
1161 for more information about the strategy parameter.)
1162 .Pp
1163 .Fn gzopen
1164 can be used to read a file which is not in gzip format;
1165 in this case
1166 .Fn gzread
1167 will directly read from the file without decompression.
1168 .Pp
1169 .Fn gzopen
1170 returns
1171 .Dv NULL
1172 if the file could not be opened or if there was
1173 insufficient memory to allocate the (de)compression state;
1174 errno can be checked to distinguish the two cases (if errno is zero, the
1175 .Nm
1176 error is
1177 .Dv Z_MEM_ERROR ) .
1178 .It Fa gzFile Fn gzdopen "int fd" "const char *mode" ;
1179 .Pp
1180 The
1181 .Fn gzdopen
1182 function associates a gzFile with the file descriptor
1183 .Fa fd .
1184 File descriptors are obtained from calls like
1185 .Xr open 2 ,
1186 .Xr dup 2 ,
1187 .Xr creat 3 ,
1188 .Xr pipe 2 ,
1189 or
1190 .Xr fileno 3
1191 (if the file has been previously opened with
1192 .Xr fopen 3 ) .
1193 The
1194 .Fa mode
1195 parameter is as in
1196 .Fn gzopen .
1197 .Pp
1198 The next call to
1199 .Fn gzclose
1200 on the returned gzFile will also close the file descriptor fd,
1201 just like fclose(fdopen(fd), mode) closes the file descriptor fd.
1202 If you want to keep fd open, use gzdopen(dup(fd), mode).
1203 .Pp
1204 .Fn gzdopen
1205 returns
1206 .Dv NULL
1207 if there was insufficient memory to allocate the (de)compression state.
1208 .It Fa int Fn gzsetparams "gzFile file" "int level" "int strategy" ;
1209 .Pp
1210 The
1211 .Fn gzsetparams
1212 function dynamically updates the compression level or strategy.
1213 See the description of
1214 .Fn deflateInit2
1215 for the meaning of these parameters.
1216 .Pp
1217 .Fn gzsetparams
1218 returns
1219 .Dv Z_OK
1220 if successful, or
1221 .Dv Z_STREAM_ERROR
1222 if the file was not opened for writing.
1223 .It Fa int Fn gzread "gzFile file" "voidp buf" "unsigned len" ;
1224 .Pp
1225 The
1226 .Fn gzread
1227 function reads the given number of uncompressed bytes from the compressed file.
1228 If the input file was not in gzip format,
1229 .Fn gzread
1230 copies the given number of bytes into the buffer.
1231 .Pp
1232 .Fn gzread
1233 returns the number of uncompressed bytes actually read
1234 (0 for end of file, \-1 for error).
1235 .It Fa int Fn gzwrite "gzFile file" "const voidp buf" "unsigned len" ;
1236 .Pp
1237 The
1238 .Fn gzwrite
1239 function writes the given number of uncompressed bytes into the compressed file.
1240 .Fn gzwrite
1241 returns the number of uncompressed bytes actually written
1242 .Pq 0 in case of error .
1243 .It Fa int Fn gzprintf "gzFile file" "const char *format" "..." ;
1244 .Pp
1245 The
1246 .Fn gzprintf
1247 function converts, formats, and writes the args to the compressed file
1248 under control of the format string, as in
1249 .Xr fprintf 3 .
1250 .Fn gzprintf
1251 returns the number of uncompressed bytes actually written
1252 .Pq 0 in case of error .
1253 .It Fa int Fn gzputs "gzFile file" "const char *s" ;
1254 .Pp
1255 The
1256 .Fn gzputs
1257 function writes the given null-terminated string to the compressed file,
1258 excluding the terminating null character.
1259 .Pp
1260 .Fn gzputs
1261 returns the number of characters written, or \-1 in case of error.
1262 .It Fa char * Fn gzgets "gzFile file" "char *buf" "int len" ;
1263 .Pp
1264 The
1265 .Fn gzgets
1266 function reads bytes from the compressed file until len\-1 characters are read,
1267 or a newline character is read and transferred to
1268 .Fa buf ,
1269 or an end-of-file condition is encountered.
1270 The string is then terminated with a null character.
1271 .Pp
1272 .Fn gzgets
1273 returns
1274 .Fa buf ,
1275 or
1276 .Dv Z_NULL
1277 in case of error.
1278 .It Fa int Fn gzputc "gzFile file" "int c" ;
1279 .Pp
1280 The
1281 .Fn gzputc
1282 function writes
1283 .Fa c ,
1284 converted to an unsigned char, into the compressed file.
1285 .Fn gzputc
1286 returns the value that was written, or \-1 in case of error.
1287 .It Fa int Fn gzgetc "gzFile file" ;
1288 .Pp
1289 The
1290 .Fn gzgetc
1291 function reads one byte from the compressed file.
1292 .Fn gzgetc
1293 returns this byte or \-1 in case of end of file or error.
1294 .It Fa int Fn gzflush "gzFile file" "int flush" ;
1295 .Pp
1296 The
1297 .Fn gzflush
1298 function flushes all pending output into the compressed file.
1299 The parameter
1300 .Fa flush
1301 is as in the
1302 .Fn deflate
1303 function.
1304 The return value is the
1305 .Nm
1306 error number (see function
1307 .Fn gzerror
1308 below).
1309 .Fn gzflush
1310 returns
1311 .Dv Z_OK
1312 if the flush parameter is
1313 .Dv Z_FINISH
1314 and all output could be flushed.
1315 .Pp
1316 .Fn gzflush
1317 should be called only when strictly necessary because it can
1318 degrade compression.
1319 .It Fa z_off_t Fn gzseek "gzFile file" "z_off_t offset" "int whence" ;
1320 .Pp
1321 Sets the starting position for the next
1322 .Fn gzread
1323 or
1324 .Fn gzwrite
1325 on the given compressed file.
1326 The offset represents a number of bytes in the uncompressed data stream.
1327 The whence parameter is defined as in
1328 .Xr lseek 2 ;
1329 the value
1330 .Dv SEEK_END
1331 is not supported.
1332 .Pp
1333 If the file is opened for reading, this function is emulated but can be
1334 extremely slow.
1335 If the file is opened for writing, only forward seeks are supported;
1336 .Fn gzseek
1337 then compresses a sequence of zeroes up to the new starting position.
1338 .Pp
1339 .Fn gzseek
1340 returns the resulting offset location as measured in bytes from
1341 the beginning of the uncompressed stream, or \-1 in case of error,
1342 in particular if the file is opened for writing and the new starting position
1343 would be before the current position.
1344 .It Fa int Fn gzrewind "gzFile file" ;
1345 .Pp
1346 The
1347 .Fn gzrewind
1348 function rewinds the given
1349 .Fa file .
1350 This function is supported only for reading.
1351 .Pp
1352 gzrewind(file) is equivalent to (int)gzseek(file, 0L, SEEK_SET).
1353 .It Fa z_off_t Fn gztell "gzFile file" ;
1354 .Pp
1355 The
1356 .Fn gztell
1357 function returns the starting position for the next
1358 .Fn gzread
1359 or
1360 .Fn gzwrite
1361 on the given compressed file.
1362 This position represents a number of bytes in the uncompressed data stream.
1363 .Pp
1364 gztell(file) is equivalent to gzseek(file, 0L, SEEK_CUR).
1365 .It Fa int Fn gzeof "gzFile file" ;
1366 .Pp
1367 The
1368 .Fn gzeof
1369 function returns 1 when
1370 .Dv EOF
1371 has previously been detected reading the given input stream, otherwise zero.
1372 .It Fa int Fn gzclose "gzFile file" ;
1373 .Pp
1374 The
1375 .Fn gzclose
1376 function flushes all pending output if necessary, closes the compressed file
1377 and deallocates all the (de)compression state.
1378 The return value is the
1379 .Nm
1380 error number (see function
1381 .Fn gzerror
1382 below).
1383 .It Fa const char * Fn gzerror "gzFile file" "int *errnum" ;
1384 .Pp
1385 The
1386 .Fn gzerror
1387 function returns the error message for the last error which occurred on the
1388 given compressed
1389 .Fa file .
1390 .Fa errnum
1391 is set to the
1392 .Nm
1393 error number.
1394 If an error occurred in the file system and not in the compression library,
1395 .Fa errnum
1396 is set to
1397 .Dv Z_ERRNO
1398 and the application may consult errno to get the exact error code.
1399 .El
1400 .Sh CHECKSUM FUNCTIONS
1401 These functions are not related to compression but are exported
1402 anyway because they might be useful in applications using the
1403 compression library.
1404 .Bl -tag -width Ds
1405 .It Fa uLong Fn adler32 "uLong adler" "const Bytef *buf" "uInt len" ;
1406 The
1407 .Fn adler32
1408 function updates a running Adler-32 checksum with the bytes buf[0..len-1]
1409 and returns the updated checksum.
1410 If
1411 .Fa buf
1412 is
1413 .Dv NULL ,
1414 this function returns the required initial value for the checksum.
1415 .Pp
1416 An Adler-32 checksum is almost as reliable as a CRC32 but can be computed
1417 much faster.
1418 Usage example:
1419 .Bd -literal -offset indent
1420 uLong adler = adler32(0L, Z_NULL, 0);
1422 while (read_buffer(buffer, length) != EOF) {
1423 adler = adler32(adler, buffer, length);
1424 }
1425 if (adler != original_adler) error();
1426 .Ed
1427 .It Fa uLong Fn crc32 "uLong crc" "const Bytef *buf" "uInt len" ;
1428 The
1429 .Fn crc32
1430 function updates a running CRC with the bytes buf[0..len-1]
1431 and returns the updated CRC.
1432 If
1433 .Fa buf
1434 is
1435 .Dv NULL ,
1436 this function returns the required initial value for the CRC.
1437 Pre- and post-conditioning
1438 .Pq one's complement
1439 is performed within this function so it shouldn't be done by the application.
1440 Usage example:
1441 .Bd -literal -offset indent
1442 uLong crc = crc32(0L, Z_NULL, 0);
1444 while (read_buffer(buffer, length) != EOF) {
1445 crc = crc32(crc, buffer, length);
1446 }
1447 if (crc != original_crc) error();
1448 .Ed
1449 .El
1450 .Sh STRUCTURES
1451 .Bd -literal
1452 struct internal_state;
1454 typedef struct z_stream_s {
1455 Bytef *next_in; /* next input byte */
1456 uInt avail_in; /* number of bytes available at next_in */
1457 uLong total_in; /* total nb of input bytes read so far */
1459 Bytef *next_out; /* next output byte should be put there */
1460 uInt avail_out; /* remaining free space at next_out */
1461 uLong total_out; /* total nb of bytes output so far */
1463 char *msg; /* last error message, NULL if no error */
1464 struct internal_state FAR *state; /* not visible by applications */
1466 alloc_func zalloc; /* used to allocate the internal state */
1467 free_func zfree; /* used to free the internal state */
1468 voidpf opaque; /* private data object passed to zalloc and zfree*/
1470 int data_type; /*best guess about the data type: ascii or binary*/
1471 uLong adler; /* Adler-32 value of the uncompressed data */
1472 uLong reserved; /* reserved for future use */
1473 } z_stream;
1475 typedef z_stream FAR * z_streamp;
1476 .Ed
1477 .Pp
1478 The application must update
1479 .Fa next_in
1480 and
1481 .Fa avail_in
1482 when
1483 .Fa avail_in
1484 has dropped to zero.
1485 It must update
1486 .Fa next_out
1487 and
1488 .Fa avail_out
1489 when
1490 .Fa avail_out
1491 has dropped to zero.
1492 The application must initialize
1493 .Fa zalloc ,
1494 .Fa zfree ,
1495 and
1496 .Fa opaque
1497 before calling the init function.
1498 All other fields are set by the compression library
1499 and must not be updated by the application.
1500 .Pp
1501 The
1502 .Fa opaque
1503 value provided by the application will be passed as the first
1504 parameter for calls to
1505 .Fn zalloc
1506 and
1507 .Fn zfree .
1508 This can be useful for custom memory management.
1509 The compression library attaches no meaning to the
1510 .Fa opaque
1511 value.
1512 .Pp
1513 .Fa zalloc
1514 must return
1515 .Dv Z_NULL
1516 if there is not enough memory for the object.
1517 If
1518 .Nm
1519 is used in a multi-threaded application,
1520 .Fa zalloc
1521 and
1522 .Fa zfree
1523 must be thread safe.
1524 .Pp
1525 On 16-bit systems, the functions
1526 .Fa zalloc
1527 and
1528 .Fa zfree
1529 must be able to allocate exactly 65536 bytes,
1530 but will not be required to allocate more than this if the symbol MAXSEG_64K
1531 is defined (see
1532 .In zconf.h ) .
1533 .Pp
1534 WARNING: On MSDOS, pointers returned by
1535 .Fa zalloc
1536 for objects of exactly 65536 bytes *must* have their offset normalized to zero.
1537 The default allocation function provided by this library ensures this (see
1538 .Pa zutil.c ) .
1539 To reduce memory requirements and avoid any allocation of 64K objects,
1540 at the expense of compression ratio,
1541 compile the library with -DMAX_WBITS=14 (see
1542 .In zconf.h ) .
1543 .Pp
1544 The fields
1545 .Fa total_in
1546 and
1547 .Fa total_out
1548 can be used for statistics or progress reports.
1549 After compression,
1550 .Fa total_in
1551 holds the total size of the uncompressed data and may be saved for use
1552 in the decompressor
1553 (particularly if the decompressor wants to decompress everything
1554 in a single step).
1555 .Sh CONSTANTS
1556 .Bd -literal
1557 #define Z_NO_FLUSH 0
1558 #define Z_PARTIAL_FLUSH 1 /* will be removed, use Z_SYNC_FLUSH instead */
1559 #define Z_SYNC_FLUSH 2
1560 #define Z_FULL_FLUSH 3
1561 #define Z_FINISH 4
1562 /* Allowed flush values; see deflate() below for details */
1564 #define Z_OK 0
1565 #define Z_STREAM_END 1
1566 #define Z_NEED_DICT 2
1567 #define Z_ERRNO (-1)
1568 #define Z_STREAM_ERROR (-2)
1569 #define Z_DATA_ERROR (-3)
1570 #define Z_MEM_ERROR (-4)
1571 #define Z_BUF_ERROR (-5)
1572 #define Z_VERSION_ERROR (-6)
1573 /* Return codes for the compression/decompression functions.
1574 * Negative values are errors,
1575 * positive values are used for special but normal events.
1576 */
1578 #define Z_NO_COMPRESSION 0
1579 #define Z_BEST_SPEED 1
1580 #define Z_BEST_COMPRESSION 9
1581 #define Z_DEFAULT_COMPRESSION (-1)
1582 /* compression levels */
1584 #define Z_FILTERED 1
1585 #define Z_HUFFMAN_ONLY 2
1586 #define Z_DEFAULT_STRATEGY 0
1587 /* compression strategy; see deflateInit2() below for details */
1589 #define Z_BINARY 0
1590 #define Z_ASCII 1
1591 #define Z_UNKNOWN 2
1592 /* Possible values of the data_type field */
1594 #define Z_DEFLATED 8
1595 /* The deflate compression method
1596 * (the only one supported in this version)
1597 */
1599 #define Z_NULL 0 /* for initializing zalloc, zfree, opaque */
1601 #define zlib_version zlibVersion()
1602 /* for compatibility with versions \*[Lt] 1.0.2 */
1603 .Ed
1604 .Sh VARIOUS HACKS
1605 deflateInit and inflateInit are macros to allow checking the
1606 .Nm
1607 version and the compiler's view of
1608 .Fa z_stream .
1609 .Bl -tag -width Ds
1610 .It Fa int Fn deflateInit_ "z_stream strm" "int level" \
1611 "const char *version" "int stream_size" ;
1612 .It Fa int Fn inflateInit_ "z_stream strm" "const char *version" \
1613 "int stream_size" ;
1614 .It Fa int Fn deflateInit2_ "z_stream strm" "int level" "int method" \
1615 "int windowBits" "int memLevel" "int strategy" "const char *version" \
1616 "int stream_size" ;
1617 .It Fa int Fn inflateInit2_ "z_stream strm" "int windowBits" \
1618 "const char *version" "int stream_size" ;
1619 .It Fa const char * Fn zError "int err" ;
1620 .It Fa int Fn inflateSyncPoint "z_streamp z" ;
1621 .It Fa const uLongf * Fn "get_crc_table" "void" ;
1622 .El
1623 .Sh SEE ALSO
1624 .Bl -tag -width 12n -compact
1625 .It RFC 1950
1626 ZLIB Compressed Data Format Specification.
1627 .It RFC 1951
1628 DEFLATE Compressed Data Format Specification.
1629 .It RFC 1952
1630 GZIP File Format Specification.
1631 .El
1632 .Pp
1633 .Lk http://www.gzip.org/zlib/ "zlib"
1634 .Sh HISTORY
1635 This manual page is based on an HTML version of
1636 .In zlib.h
1637 converted by
1638 .An piaip Aq Mt piaip@csie.ntu.edu.tw
1639 and was converted to mdoc format by the
1640 .Ox
1641 project.
1642 .Sh AUTHORS
1643 .An Jean-loup Gailly Aq Mt jloup@gzip.org
1644 .An Mark Adler Aq Mt madler@alumni.caltech.edu