Repository navigation
Expand file tree
/
Copy pathzlib.3
More file actions
1644 lines (1629 loc) · 41.8 KB
/
Copy pathzlib.3
File metadata and controls
1644 lines (1629 loc) · 41.8 KB
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
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.\" $NetBSD: zlib.3,v 1.9 2013/07/20 21:39:57 wiz Exp $
.\" $OpenBSD: zlib.3,v 1.1 2003/09/25 09:12:09 jmc Exp $
.\"
.\" Copyright (C) 1995-2002 Jean-loup Gailly and Mark Adler
.\"
.\" This software is provided 'as-is', without any express or implied
.\" warranty. In no event will the authors be held liable for any damages
.\" arising from the use of this software.
.\"
.\" Permission is granted to anyone to use this software for any purpose,
.\" including commercial applications, and to alter it and redistribute it
.\" freely, subject to the following restrictions:
.\"
.\" The origin of this software must not be misrepresented; you must not
.\" claim that you wrote the original software. If you use this software
.\" in a product, an acknowledgment in the product documentation would be
.\" appreciated but is not required.
.\" Altered source versions must be plainly marked as such, and must not be
.\" misrepresented as being the original software.
.\" This notice may not be removed or altered from any source distribution.
.\"
.\" Converted to mdoc format for the OpenBSD project
.\" by Jason McIntyre <jmc@openbsd.org>
.\"
.Dd May 1, 2004
.Dt ZLIB 3
.Os
.Sh NAME
.Nm zlib
.Nd general purpose compression library
.Sh SYNOPSIS
.In zlib.h
.Ss Basic functions
.Ft const char *
.Fn zlibVersion "void"
.Ft int
.Fn deflateInit "z_streamp strm" "int level"
.Ft int
.Fn deflate "z_streamp strm" "int flush"
.Ft int
.Fn deflateEnd "z_streamp strm"
.Ft int
.Fn inflateInit "z_streamp strm"
.Ft int
.Fn inflate "z_streamp strm" "int flush"
.Ft int
.Fn inflateEnd "z_streamp strm"
.Ss Advanced functions
.Ft int
.Fn deflateInit2 "z_streamp strm" "int level" "int method" \
"int windowBits" "int memLevel" "int strategy"
.Ft int
.Fn deflateSetDictionary "z_streamp strm" "const Bytef *dictionary" \
"uInt dictLength"
.Ft int
.Fn deflateCopy "z_streamp dest" "z_streamp source"
.Ft int
.Fn deflateReset "z_streamp strm"
.Ft int
.Fn deflateParams "z_streamp strm" "int level" "int strategy"
.Ft int
.Fn inflateInit2 "z_streamp strm" "int windowBits"
.Ft int
.Fn inflateSetDictionary "z_streamp strm" "const Bytef *dictionary" "uInt dictLength"
.Ft int
.Fn inflateSync "z_streamp strm"
.Ft int
.Fn inflateReset "z_streamp strm"
.Ss Uti
10BC8
lity functions
.Fd typedef voidp gzFile ;
.Pp
.Ft int
.Fn compress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen"
.Ft int
.Fn compress2 "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" "int level"
.Ft int
.Fn uncompress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen"
.Ft gzFile
.Fn gzopen "const char *path" "const char *mode"
.Ft gzFile
.Fn gzdopen "int fd" "const char *mode"
.Ft int
.Fn gzsetparams "gzFile file" "int level" "int strategy"
.Ft int
.Fn gzread "gzFile file" "voidp buf" "unsigned len"
.Ft int
.Fn gzwrite "gzFile file" "const voidp buf" "unsigned len"
.Ft int
.Fn gzprintf "gzFile file" "const char *format" "..."
.Ft int
.Fn gzputs "gzFile file" "const char *s"
.Ft char *
.Fn gzgets "gzFile file" "char *buf" "int len"
.Ft int
.Fn gzputc "gzFile file" "int c"
.Ft int
.Fn gzgetc "gzFile file"
.Ft int
.Fn gzflush "gzFile file" "int flush"
.Ft z_off_t
.Fn gzseek "gzFile file" "z_off_t offset" "int whence"
.Ft int
.Fn gzrewind "gzFile file"
.Ft z_off_t
.Fn gztell "gzFile file"
.Ft int
.Fn gzeof "gzFile file"
.Ft int
.Fn gzclose "gzFile file"
.Ft const char *
.Fn gzerror "gzFile file" "int *errnum"
.Ss Checksum functions
.Ft uLong
.Fn adler32 "uLong adler" "const Bytef *buf" "uInt len"
.Ft uLong
.Fn crc32 "uLong crc" "const Bytef *buf" "uInt len"
.Sh DESCRIPTION
This manual page describes the
.Nm
general purpose compression library, version 1.1.4.
.Pp
The
.Nm
compression library provides in-memory compression and decompression functions,
including integrity checks of the uncompressed data.
This version of the library supports only one compression method
.Pq deflation
but other algorithms will be added later and will have the same
stream interface.
.Pp
Compression can be done in a single step if the buffers are large enough
.Pq for example if an input file is mmap'ed ,
or can be done by repeated calls of the compression function.
In the latter case, the application must provide more input
and/or consume the output
.Pq providing more output space
before each call.
.Pp
The library also supports reading and writing files in
.Xr gzip 1
.Pq .gz
format with an interface similar to that of
.Xr stdio 3 .
.Pp
The library does not install any signal handler.
The decoder checks the consistency of the compressed data,
so the library should never crash even in case of corrupted input.
.Pp
The functions within the library are divided into the following sections:
.Pp
.Bl -dash -offset indent -compact
.It
Basic functions
.It
Advanced functions
.It
Utility functions
.It
Checksum functions
.El
.Sh BASIC FUNCTIONS
.Bl -tag -width Ds
.It Fa const char * Fn zlibVersion "void" ;
.Pp
The application can compare
.Fn zlibVersion
and
.Dv ZLIB_VERSION
for consistency.
If the first character differs, the library code actually used is
not compatible with the
.In zlib.h
header file used by the application.
This check is automatically made by
.Fn deflateInit
and
.Fn inflateInit .
.It Fa int Fn deflateInit "z_streamp strm" "int level" ;
.Pp
The
.Fn deflateInit
function initializes the internal stream state for compression.
The fields
.Fa zalloc ,
.Fa zfree ,
and
.Fa opaque
must be initialized before by the caller.
If
.Fa zalloc
and
.Fa zfree
are set to
.Dv Z_NULL ,
.Fn deflateInit
updates them to use default allocation functions.
.Pp
The compression level must be
.Dv Z_DEFAULT_COMPRESSION ,
or between 0 and 9:
1 gives best speed, 9 gives best compression, 0 gives no compression at all
(the input data is simply copied a block at a time).
.Pp
.Dv Z_DEFAULT_COMPRESSION
requests a default compromise between speed and compression
.Pq currently equivalent to level 6 .
.Pp
.Fn deflateInit
returns
.Dv Z_OK
if successful,
.Dv Z_MEM_ERROR
if there was not enough memory,
.Dv Z_STREAM_ERROR
if level is not a valid compression level,
.Dv Z_VERSION_ERROR
if the
.Nm
library version
.Pq zlib_version
is incompatible with the version assumed by the caller
.Pq ZLIB_VERSION .
.Fa msg
is set to null if there is no error message.
.Fn deflateInit
does not perform any compression: this will be done by
.Fn deflate .
.It Fa int Fn deflate "z_streamp strm" "int flush" ;
.Pp
.Fn deflate
compresses 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
.Pq reading input without producing any output
except when forced to flush.
.Pp
The detailed semantics are as follows.
.Fn deflate
performs one or both of the following actions:
.Pp
Compress 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),
.Fa next_in
and
.Fa avail_in
are updated and processing will resume at this point for the next call to
.Fn deflate .
.Pp
Provide more output starting at
.Fa next_out
and update
.Fa next_out
and
.Fa avail_out
accordingly.
This action is forced if the parameter
.Fa flush
is non-zero.
Forcing
.Fa flush
frequently degrades the compression ratio,
so this parameter should be set only when necessary
.Pq in interactive applications .
Some output may be provided even if
.Fa flush
is not set.
.Pp
Before the call to
.Fn deflate ,
the application should ensure that at least
one of the actions is possible, by providing more input and/or consuming
more output, and updating
.Fa avail_in
or
.Fa avail_out
accordingly;
.Fa avail_out
should never be zero before the call.
The application can consume the compressed output when it wants,
for example when the output buffer is full
.Pq avail_out == 0 ,
or after each call to
.Fn deflate .
If
.Fn deflate
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
If the parameter
.Fa flush
is set to
.Dv Z_SYNC_FLUSH ,
all pending output is flushed to the output buffer and the output
is aligned on a byte boundary, so that the decompressor can get all
input data available so far.
(In particular,
.Fa avail_in
is zero after the call if enough output space
has been provided before the call.)
Flushing may degrade compression for some compression algorithms
and so it should be used only when necessary.
.Pp
If
.Fa flush
is set to
.Dv Z_FULL_FLUSH ,
all output is flushed as with
.Dv Z_SYNC_FLUSH ,
and the compression state is reset so that decompression can restart from this
point if previous compressed data has been damaged or if random access
is desired.
Using
.Dv Z_FULL_FLUSH
too often can seriously degrade the compression.
.Pp
If
.Fn deflate
returns with avail_out == 0, this function must be called again
with the same value of the flush parameter and more output space
(updated
.Fa avail_out ) ,
until the flush is complete
.Pf ( Fn deflate
returns with non-zero
.Fa avail_out ) .
.Pp
If the parameter
.Fa flush
is set to
.Dv Z_FINISH ,
pending input is processed, pending output is flushed and
.Fn deflate
retu
8
rns with
10BC8
.Dv Z_STREAM_END
if there was enough output space; if
.Fn deflate
returns with
.Dv Z_OK ,
this function must be called again with
.Dv Z_FINISH
and more output space
(updated
.Fa avail_out
but no more input data, until it returns with
.Dv Z_STREAM_END
or an error.
After
.Fn deflate
has returned
.Dv Z_STREAM_END ,
the only possible operations on the stream are
.Fn deflateReset
or
.Fn deflateEnd .
.Pp
.Dv Z_FINISH
can be used immediately after
.Fn deflateInit
if all the compression is to be done in a single step.
In this case,
.Fa avail_out
must be at least 0.1% larger than
.Fa avail_in
plus 12 bytes.
If
.Fn deflate
does not return
.Dv Z_STREAM_END ,
then it must be called again as described above.
.Pp
.Fn deflate
sets strm-\*[Gt]adler to the Adler-32 checksum of all input read so far
(that is,
.Fa total_in
bytes).
.Pp
.Fn deflate
may update
.Fa data_type
if it can make a good guess about the input data type
.Pq Z_ASCII or Z_BINARY .
If in doubt, the data is considered binary.
This field is only for information purposes and does not affect
the compression algorithm in any manner.
.Pp
.Fn deflate
returns
.Dv Z_OK
if some progress has been made
.Pq more input processed or more output produced ,
.Dv Z_STREAM_END
if all input has been consumed and all output has been produced
(only when
.Fa flush
is set to
.Dv Z_FINISH ) ,
.Dv Z_STREAM_ERROR
if the stream state was inconsistent
(for example, if
.Fa next_in
or
.Fa next_out
was
.Dv NULL ) ,
.Dv Z_BUF_ERROR
if no progress is possible
(for example,
.Fa avail_in
or
.Fa avail_out
was zero).
.It Fa int Fn deflateEnd "z_streamp strm" ;
.Pp
All dynamically allocated data structures for this stream are freed.
This function discards any unprocessed input and does not flush any
pending output.
.Pp
.Fn deflateEnd
returns
.Dv Z_OK
if successful,
.Dv Z_STREAM_ERROR
if the stream state was inconsistent,
.Dv Z_DATA_ERROR
if the stream was freed prematurely
.Pq some input or output was discarded .
In the error case,
.Fa msg
may be set but then points to a static string
.Pq which must not be deallocated .
.It Fa int Fn inflateInit "z_streamp strm" ;
The
.Fn inflateInit
function initializes the internal stream state for decompression.
The fields
.Fa next_in ,
.Fa avail_in ,
.Fa zalloc ,
.Fa zfree ,
and
.Fa opaque
must be initialized before by the caller.
If
.Fa next_in
is not
.Dv Z_NULL
and
.Fa avail_in
is large enough
.Pq the exact value depends on the compression method ,
.Fn inflateInit
determines the compression method from the
.Nm
header and allocates all data structures accordingly;
otherwise the allocation will be deferred to the first call to
.Fn inflate .
If
.Fa zalloc
and
.Fa zfree
are set to
.Dv Z_NULL ,
.Fn inflateInit
updates them to use default allocation functions.
.Pp
.Fn inflateInit
returns
.Dv Z_OK
if successful,
.Dv Z_MEM_ERROR
if there was not enough memory,
.Dv Z_VERSION_ERROR
if the
.Nm
library version is incompatible with the version assumed by the caller.
.Fa msg
is set to null if there is no error message.
.Fn inflateInit
does not perform any decompression apart from reading the
.Nm
header if present: this will be done by
.Fn inflate .
(So
.Fa next_in
and
.Fa avail_in
may be modified,
but
.Fa next_out
and
.Fa avail_out
are unchanged.)
.It Fa int Fn inflate "z_streamp strm" "int flush" ;
.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
.Pq 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:
.Pp
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),
.Fa next_in
is updated and processing will resume at this point for the next call to
.Fn inflate .
.Pp
Provide 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
.Pq see below about the flush parameter .
.Pp
Before the call to
.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 next_* and avail_* values accordingly.
The application can consume the uncompressed output when it wants,
for example when the output buffer is full (avail_out == 0),
or after each call to
.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
If the parameter
.Fa flush
is set to
.Dv Z_SYNC_FLUSH ,
.Fn inflate
flushes as much output as possible to the output buffer.
The flushing behavior of
.Fn inflate
is not specified for values of the flush parameter other than
.Dv Z_SYNC_FLUSH
and
.Dv Z_FINISH ,
but the current implementation actually flushes as much output
as possible anyway.
.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
.Pq a single call to inflate ,
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 the uncompressed data.
(The size of the uncompressed data may have been saved
by the compressor for this purpose.)
The next operation on this stream must be
.Fn inflateEnd
to deallocate the decompression state.
The use of
.Dv Z_FINISH
is never required, but can be used to inform
.Fn inflate
that a faster routine may be used for the single
.Fn inflate
call.
.Pp
If a preset dictionary is needed at this point (see
.Fn inflateSetDictionary
below),
.Fn inflate
sets strm-\*[Gt]adler to the Adler-32 checksum of the dictionary
chosen by the compressor and returns
.Dv Z_NEED_DICT ;
otherwise it sets strm-\*[Gt]adler to the Adler-32 checksum of all output produced
so far
(that is,
.Fa total_out
bytes)
and returns
.Dv Z_OK ,
.Dv Z_STREAM_END ,
or an error code as described below.
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
returns
.Dv Z_OK
if some progress has been made
.Pq 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 (input stream not conforming to the
.Nm
format or incorrect Adler-32 checksum),
.Dv Z_STREAM_ERROR
if the stream structure was inconsistent
(for example, if
.Fa next_in
or
.Fa next_out
was
.Dv NULL ) ,
.Dv Z_MEM_ERROR
if there was not enough memory,
.Dv Z_BUF_ERROR
if no progress is possible or if there was not enough room in the output buffer
when
.Dv Z_FINISH
is used.
In the
.Dv Z_DATA_ERROR
case, the application may then call
.Fn inflateSync
to look for a good compression block.
.It Fa int Fn inflateEnd "z_streamp strm" ;
All dynamically allocated data structures for this stream are freed.
This function discards any unprocessed input and does not flush any
pending output.
.Pp
.Fn inflateEnd
returns
.Dv Z_OK
if successful, or
.Dv Z_STREAM_ERROR
if the stream state was inconsistent.
In the error case,
.Fa msg
may be set but then points to a static string
.Pq which must not be deallocated .
.El
.Sh ADVANCED FUNCTIONS
The following functions are needed only in some special applications.
.Bl -tag -width Ds
.It Fa int Fn deflateInit2 "z_streamp strm" "int level" "int method" \
"int windowBits" "int memLevel" "int strategy" ;
.Pp
This is another version of
.Fn deflateInit
with more compression options.
The fields
.Fa next_in ,
.Fa zalloc ,
.Fa zfree ,
and
.Fa opaque
must be initialized before by the caller.
.Pp
The
.Fa method
parameter is the compression method.
It must be
.Dv Z_DEFLATED
in this version of the library.
.Pp
The
.Fa windowBits
parameter is the base two logarithm of the window size
.Pq the size of the history buffer .
It should be in the range 8..15 for this version of the library.
Larger values of this parameter result in better compression
at the expense of memory usage.
The default value is 15 if
.Fn deflateInit
is used instead.
.Pp
The
.Fa memLevel
parameter specifies how much memory should be allocated
for the internal compression state.
memLevel=1 uses minimum memory but is slow and reduces compression ratio;
memLevel=9 uses maximum memory for optimal speed.
The default value is 8.
See
.In zconf.h
for total memory usage as a function of
.Fa windowBits
and
.Fa memLevel .
.Pp
The
.Fa strategy
parameter is used to tune the compression algorithm.
Use the value
.Dv Z_DEFAULT_STRATEGY
for normal data;
.Dv Z_FILTERED
for data produced by a filter
.Pq or predictor ;
or
.Dv Z_HUFFMAN_ONLY
to force Huffman encoding only
.Pq no string match .
Filtered data consists mostly of small values with a
somewhat random distribution.
In this case, the compression algorithm is tuned to compress them better.
The effect of
.Dv Z_FILTERED
is to force more Huffman coding and less string matching;
it is somewhat intermediate between
.Dv Z_DEFAULT
and
.Dv Z_HUFFMAN_ONLY .
The
.Fa strategy
parameter only affects the compression ratio but not the correctness of the
compressed output, even if it is not set appropriately.
.Pp
.Fn deflateInit2
returns
.Dv Z_OK
if successful,
.Dv Z_MEM_ERROR
if there was not enough memory,
.Dv Z_STREAM_ERROR
if a parameter is invalid
.Pq such as an invalid method .
.Fa msg
is set to null if there is no error message.
.Fn deflateInit2
does not perform any compression: this will be done by
.Fn deflate .
.It Fa int Fn deflateSetDictionary "z_streamp strm" \
"const Bytef *dictionary" "uInt dictLength" ;
.Pp
Initializes the compression dictionary from the given byte sequence
without producing any compressed output.
This function must be called immediately after
.Fn deflateInit ,
.Fn deflateInit2 ,
or
.Fn deflateReset ,
before any call to
.Fn deflate .
The compressor and decompressor must use exactly the same dictionary
(see
.Fn inflateSetDictionary ) .
.Pp
The dictionary should consist of strings
.Pq byte sequences
that are likely to be encountered later in the data to be compressed,
with the most commonly used strings preferably put towards
the end of the dictionary.
Using a dictionary is most useful when the data to be compressed is short
and can be predicted with good accuracy;
the data can then be compressed better than with the default empty dictionary.
.Pp
Depending on the size of the compression data structures selected by
.Fn deflateInit
or
.Fn deflateInit2 ,
a part of the dictionary may in effect be discarded,
for example if the dictionary is larger than the window size in
.Fn deflate
or
.Fn deflate2 .
Thus the strings most likely to be useful should be
put at the end of the dictionary, not at the front.
.Pp
Upon return of this function, strm-\*[Gt]adler is set to the Adler-32 value
of the dictionary; the decompressor may later use this value to determine
which dictionary has been used by the compressor.
(The Adler-32 value applies to the whole dictionary even if only a subset
of the dictionary is actually used by the compressor.)
.Pp
.Fn deflateSetDictionary
returns
.Dv Z_OK
if successful,
or
.Dv Z_STREAM_ERROR
if a parameter is invalid
.Pq such as NULL dictionary
or the stream state is inconsistent
(for example if
.Fn deflate
has already been called for this stream or if the compression method is bsort).
.Fn deflateSetDictionary
does not perform any compression: this will be done by
.Fn deflate .
.It Fa int Fn deflateCopy "z_streamp dest" "z_streamp source" ;
.Pp
The
.Fn deflateCopy
function sets the destination stream as a complete copy of the source stream.
.Pp
This function can be useful when several compression strategies will be
tried, for example when there are several ways of pre-processing the input
data with a filter.
The streams that will be discarded should then be freed by calling
.Fn deflateEnd .
Note that
.Fn deflateCopy
duplicates the internal compression state which can be quite large,
so this strategy is slow and can consume lots of memory.
.Pp
.Fn deflateCopy
returns
.Dv Z_OK
if successful,
.Dv Z_MEM_ERROR
if there was not enough memory,
.Dv Z_STREAM_ERROR
if the source stream state was inconsistent
(such as
.Fa zalloc
being NULL).
.Fa msg
is left unchanged in both source and destination.
.It Fa int Fn deflateReset "z_streamp strm" ;
.Pp
This function is equivalent to
.Fn deflateEnd
followed by
.Fn deflateInit ,
but does not free and reallocate all the internal compression state.
The stream will keep the same compression level and any other attributes
that may have been set by
.Fn deflateInit2 .
.Pp
.Fn deflateReset
returns
.Dv Z_OK
if successful, or
.Dv Z_STREAM_ERROR
if the source stream state was inconsistent
(such as
.Fa zalloc
or
.Fa state
being NULL).
.It Fa int Fn deflateParams "z_streamp strm" "int level" "int strategy" ;
.Pp
The
.Fn deflateParams
function dynamically updates the compression level and compression strategy.
The interpretation of level and strategy is as in
.Fn deflateInit2 .
This can be used to switch between compression and straight copy
of the input data, or to switch to a different kind of input data
requiring a different strategy.
If the compression level is changed, the input available so far
is compressed with the old level
.Pq and may be flushed ;
the new level will take effect only at the next call to
.Fn deflate .
.Pp
Before the call to
.Fn deflateParams ,
the stream state must be set as for a call to
.Fn deflate ,
since the currently available input may have to be compressed and flushed.
In particular, strm-\*[Gt]avail_out must be non-zero.
.Pp
.Fn deflateParams
returns
.Dv Z_OK
if successful,
.Dv Z_STREAM_ERROR
if the source stream state was inconsistent or if a parameter was invalid, or
.Dv Z_BUF_ERROR
if strm-\*[Gt]avail_out was zero.
.It Fa int Fn inflateInit2 "z_streamp strm" "int windowBits" ;
.Pp
This is another version of
.Fn inflateInit
with an extra parameter.
The fields
.Fa next_in ,
.Fa avail_in ,
.Fa zalloc ,
.Fa zfree ,
and
.Fa opaque
must be initialized before by the caller.
.Pp
The
.Fa windowBits
parameter is the base two logarithm of the maximum window size
.Pq the size of the history buffer .
It should be in the range 8..15 for this version of the library.
The default value is 15 if
.Fn inflateInit
is used instead.
If a compressed stream with a larger window size is given as input,
.Fn inflate
will return with the error code
.Dv Z_DATA_ERROR
instead of trying to allocate a larger window.
.Pp
.Fn inflateInit2
returns
.Dv Z_OK
if successful,
.Dv Z_MEM_ERROR
if there was not enough memory,
.Dv Z_STREAM_ERROR
if a parameter is invalid
(such as a negative
.Fa memLevel ) .
.Fa msg
is set to null if there is no error message.
.Fn inflateInit2
does not perform any decompression apart from reading the
.Nm
header if present: this will be done by
.Fn inflate .
(So
.Fa next_in
and
.Fa avail_in
may be modified, but
.Fa next_out
and
.Fa avail_out
are unchanged.)
.It Fa int Fn inflateSetDictionary "z_streamp strm" \
"const Bytef *dictionary" "uInt dictLength" ;
.Pp
Initializes the decompression dictionary from the given uncompressed byte
sequence.
This function must be called immediately after a call to
.Fn inflate
if this call returned
.Dv Z_NEED_DICT .
The dictionary chosen by the compressor can be determined from the
Adler-32 value returned by this call to
.Fn inflate .
The compressor and decompressor must use exactly the same dictionary
(see
.Fn deflateSetDictionary ) .
.Pp
.Fn inflateSetDictionary
returns
.Dv Z_OK
if successful,
.Dv Z_STREAM_ERROR
if a parameter is invalid
.Pq such as NULL dictionary
or the stream state is inconsistent,
.Dv Z_DATA_ERROR
if the given dictionary doesn't match the expected one
.Pq incorrect Adler-32 value .
.Fn inflateSetDictionary
does not perform any decompression: this will be done by subsequent calls of
.Fn inflate .
.It Fa int Fn inflateSync "z_streamp strm" ;
.Pp
Skips invalid compressed data until a full flush point
(see above the description of
.Fn deflate
with
.Dv Z_FULL_FLUSH )
can be found, or until all available input is skipped.
No output is provided.
.Pp
.Fn inflateSync
returns
.Dv Z_OK