1.\" $OpenBSD: compress.3,v 1.20 2021/02/08 20:32:07 jmc Exp $ 2.\" 3.\" Copyright (C) 1995-2005 Jean-loup Gailly and Mark Adler 4.\" 5.\" This software is provided 'as-is', without any express or implied 6.\" warranty. In no event will the authors be held liable for any damages 7.\" arising from the use of this software. 8.\" 9.\" Permission is granted to anyone to use this software for any purpose, 10.\" including commercial applications, and to alter it and redistribute it 11.\" freely, subject to the following restrictions: 12.\" 13.\" The origin of this software must not be misrepresented; you must not 14.\" claim that you wrote the original software. If you use this software 15.\" in a product, an acknowledgment in the product documentation would be 16.\" appreciated but is not required. 17.\" Altered source versions must be plainly marked as such, and must not be 18.\" misrepresented as being the original software. 19.\" This notice may not be removed or altered from any source distribution. 20.\" 21.\" Converted to mdoc format for the OpenBSD project 22.\" by Jason McIntyre <jmc@openbsd.org> 23.\" 24.\" This page corresponds to zlib version 1.2.3 25.\" 26.Dd $Mdocdate: February 8 2021 $ 27.Dt COMPRESS 3 28.Os 29.Sh NAME 30.Nm compress , 31.Nm zlibVersion , 32.Nm deflateInit , 33.Nm deflate , 34.Nm deflateEnd , 35.Nm inflateInit , 36.Nm inflate , 37.Nm inflateEnd , 38.Nm deflateInit2 , 39.Nm deflateSetDictionary , 40.Nm deflateCopy , 41.Nm deflateReset , 42.Nm deflateParams , 43.Nm deflateTune , 44.Nm deflateBound , 45.Nm deflatePrime , 46.Nm deflateSetHeader , 47.Nm inflateInit2 , 48.Nm inflateSetDictionary , 49.Nm inflateSync , 50.Nm inflateCopy , 51.Nm inflateReset , 52.Nm inflatePrime , 53.Nm inflateGetHeader , 54.Nm inflateBackInit , 55.Nm inflateBack , 56.Nm inflateBackEnd , 57.Nm zlibCompileFlags , 58.Nm compress2 , 59.Nm compressBound , 60.Nm uncompress , 61.Nm gzopen , 62.Nm gzdopen , 63.Nm gzsetparams , 64.Nm gzread , 65.Nm gzwrite , 66.Nm gzprintf , 67.Nm gzputs , 68.Nm gzgets , 69.Nm gzputc , 70.Nm gzgetc , 71.Nm gzungetc , 72.Nm gzflush , 73.Nm gzseek , 74.Nm gzrewind , 75.Nm gztell , 76.Nm gzeof , 77.Nm gzdirect , 78.Nm gzclose , 79.Nm gzerror , 80.Nm gzclearerr , 81.Nm adler32 , 82.Nm adler32_combine , 83.Nm crc32 , 84.Nm crc32_combine 85.Nd zlib general purpose compression library 86.Sh SYNOPSIS 87.In zlib.h 88.Pp 89Basic functions 90.Pp 91.Ft const char * 92.Fn zlibVersion "void" 93.Ft int 94.Fn deflateInit "z_streamp strm" "int level" 95.Ft int 96.Fn deflate "z_streamp strm" "int flush" 97.Ft int 98.Fn deflateEnd "z_streamp strm" 99.Ft int 100.Fn inflateInit "z_streamp strm" 101.Ft int 102.Fn inflate "z_streamp strm" "int flush" 103.Ft int 104.Fn inflateEnd "z_streamp strm" 105.Pp 106Advanced functions 107.Pp 108.Ft int 109.Fn deflateInit2 "z_streamp strm" "int level" "int method" "int windowBits" "int memLevel" "int strategy" 110.Ft int 111.Fn deflateSetDictionary "z_streamp strm" "const Bytef *dictionary" "uInt dictLength" 112.Ft int 113.Fn deflateCopy "z_streamp dest" "z_streamp source" 114.Ft int 115.Fn deflateReset "z_streamp strm" 116.Ft int 117.Fn deflateParams "z_streamp strm" "int level" "int strategy" 118.Ft int 119.Fn deflateTune "z_streamp strm" "int good_length" "int max_lazy" "int nice_length" "int max_chain" 120.Ft uLong 121.Fn deflateBound "z_streamp strm" "uLong sourceLen" 122.Ft int 123.Fn deflatePrime "z_streamp strm" "int bits" "int value" 124.Ft int 125.Fn deflateSetHeader "z_streamp strm" "gz_headerp head" 126.Ft int 127.Fn inflateInit2 "z_streamp strm" "int windowBits" 128.Ft int 129.Fn inflateSetDictionary "z_streamp strm" "const Bytef *dictionary" "uInt dictLength" 130.Ft int 131.Fn inflateSync "z_streamp strm" 132.Ft int 133.Fn inflateCopy "z_streamp dst" "z_streamp source" 134.Ft int 135.Fn inflateReset "z_streamp strm" 136.Ft int 137.Fn inflatePrime "z_streamp strm" "int bits" "int value" 138.Ft int 139.Fn inflateGetHeader "z_streamp strm" "gz_headerp head" 140.Ft int 141.Fn inflateBackInit "z_stream *strm" "int windowBits" "unsigned char FAR *window" 142.Ft int 143.Fn inflateBack "z_stream *strm" "in_func in" "void FAR *in_desc" "out_func out" "void FAR *out_desc" 144.Ft int 145.Fn inflateBackEnd "z_stream *strm" 146.Ft uLong 147.Fn zlibCompileFlags "void" 148.Pp 149Utility functions 150.Pp 151.Fd typedef voidp gzFile; 152.Pp 153.Ft int 154.Fn compress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" 155.Ft int 156.Fn compress2 "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" "int level" 157.Ft uLong 158.Fn compressBound "uLong sourceLen" 159.Ft int 160.Fn uncompress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" 161.Ft gzFile 162.Fn gzopen "const char *path" "const char *mode" 163.Ft gzFile 164.Fn gzdopen "int fd" "const char *mode" 165.Ft int 166.Fn gzsetparams "gzFile file" "int level" "int strategy" 167.Ft int 168.Fn gzread "gzFile file" "voidp buf" "unsigned len" 169.Ft int 170.Fn gzwrite "gzFile file" "voidpc buf" "unsigned len" 171.Ft int 172.Fn gzprintf "gzFile file" "const char *format" "..." 173.Ft int 174.Fn gzputs "gzFile file" "const char *s" 175.Ft char * 176.Fn gzgets "gzFile file" "char *buf" "int len" 177.Ft int 178.Fn gzputc "gzFile file" "int c" 179.Ft int 180.Fn gzgetc "gzFile file" 181.Ft int 182.Fn gzungetc "int c" "gzFile file" 183.Ft int 184.Fn gzflush "gzFile file" "int flush" 185.Ft z_off_t 186.Fn gzseek "gzFile file" "z_off_t offset" "int whence" 187.Ft int 188.Fn gzrewind "gzFile file" 189.Ft z_off_t 190.Fn gztell "gzFile file" 191.Ft int 192.Fn gzeof "gzFile file" 193.Ft int 194.Fn gzdirect "gzFile file" 195.Ft int 196.Fn gzclose "gzFile file" 197.Ft const char * 198.Fn gzerror "gzFile file" "int *errnum" 199.Ft void 200.Fn gzclearerr "gzFile file" 201.Pp 202Checksum functions 203.Pp 204.Ft uLong 205.Fn adler32 "uLong adler" "const Bytef *buf" "uInt len" 206.Ft uLong 207.Fn adler32_combine "uLong adler1" "uLong adler2" "z_off_t len2" 208.Ft uLong 209.Fn crc32 "uLong crc" "const Bytef *buf" "uInt len" 210.Ft uLong 211.Fn crc32_combine "uLong crc1" "uLong crc2" "z_off_t len2" 212.Sh DESCRIPTION 213This manual page describes the 214.Nm zlib 215general purpose compression library, version 1.2.3. 216.Pp 217The 218.Nm zlib 219compression library provides in-memory compression and decompression functions, 220including integrity checks of the uncompressed data. 221This version of the library supports only one compression method 222.Pq deflation 223but other algorithms will be added later and will have the same 224stream interface. 225.Pp 226Compression can be done in a single step if the buffers are large enough 227.Pq for example if an input file is mmap'ed , 228or can be done by repeated calls of the compression function. 229In the latter case, the application must provide more input 230and/or consume the output 231.Pq providing more output space 232before each call. 233.Pp 234The compressed data format used by default by the in-memory functions is the 235.Nm zlib 236format, which is a zlib wrapper documented in RFC 1950, 237wrapped around a deflate stream, which is itself documented in RFC 1951. 238.Pp 239The library also supports reading and writing files in 240.Xr gzip 1 241.Pq .gz 242format with an interface similar to that of 243.Xr stdio 3 244using the functions that start with 245.Qq gz . 246The gzip format is different from the zlib format. 247gzip is a gzip wrapper, documented in RFC 1952, wrapped around a deflate stream. 248This library can optionally read and write gzip streams in memory as well. 249.Pp 250The zlib format was designed to be compact and fast for use in memory 251and on communications channels. 252The gzip format was designed for single-file compression on file systems, 253has a larger header than zlib to maintain directory information, 254and uses a different, slower, check method than zlib. 255.Pp 256The library does not install any signal handler. 257The decoder checks the consistency of the compressed data, 258so the library should never crash even in case of corrupted input. 259.Pp 260The functions within the library are divided into the following sections: 261.Pp 262.Bl -dash -offset indent -compact 263.It 264Basic functions 265.It 266Advanced functions 267.It 268Utility functions 269.It 270Checksum functions 271.El 272.Sh BASIC FUNCTIONS 273.Bl -tag -width Ds 274.It Xo 275.Fa const char * 276.Fn zlibVersion "void" ; 277.Xc 278.Pp 279The application can compare 280.Fn zlibVersion 281and 282.Dv ZLIB_VERSION 283for consistency. 284If the first character differs, the library code actually used is 285not compatible with the 286.In zlib.h 287header file used by the application. 288This check is automatically made by 289.Fn deflateInit 290and 291.Fn inflateInit . 292.It Xo 293.Fa int 294.Fn deflateInit "z_streamp strm" "int level" ; 295.Xc 296.Pp 297The 298.Fn deflateInit 299function initializes the internal stream state for compression. 300The fields 301.Fa zalloc , 302.Fa zfree , 303and 304.Fa opaque 305must be initialized before by the caller. 306If 307.Fa zalloc 308and 309.Fa zfree 310are set to 311.Dv Z_NULL , 312.Fn deflateInit 313updates them to use default allocation functions. 314.Pp 315The compression level must be 316.Dv Z_DEFAULT_COMPRESSION , 317or between 0 and 9: 3181 gives best speed, 9 gives best compression, 0 gives no compression at all 319(the input data is simply copied a block at a time). 320.Pp 321.Dv Z_DEFAULT_COMPRESSION 322requests a default compromise between speed and compression 323.Pq currently equivalent to level 6 . 324.Pp 325.Fn deflateInit 326returns 327.Dv Z_OK 328if successful, 329.Dv Z_MEM_ERROR 330if there was not enough memory, 331.Dv Z_STREAM_ERROR 332if level is not a valid compression level, 333.Dv Z_VERSION_ERROR 334if the 335.Nm zlib 336library version 337.Pq zlib_version 338is incompatible with the version assumed by the caller 339.Pq ZLIB_VERSION . 340.Fa msg 341is set to null if there is no error message. 342.Fn deflateInit 343does not perform any compression: this will be done by 344.Fn deflate . 345.It Xo 346.Fa int 347.Fn deflate "z_streamp strm" "int flush" ; 348.Xc 349.Pp 350.Fn deflate 351compresses as much data as possible, and stops when the input 352buffer becomes empty or the output buffer becomes full. 353It may introduce some output latency 354.Pq reading input without producing any output 355except when forced to flush. 356.Pp 357The detailed semantics are as follows. 358.Fn deflate 359performs one or both of the following actions: 360.Pp 361Compress more input starting at 362.Fa next_in 363and update 364.Fa next_in 365and 366.Fa avail_in 367accordingly. 368If not all input can be processed 369(because there is not enough room in the output buffer), 370.Fa next_in 371and 372.Fa avail_in 373are updated and processing will resume at this point for the next call to 374.Fn deflate . 375.Pp 376Provide more output starting at 377.Fa next_out 378and update 379.Fa next_out 380and 381.Fa avail_out 382accordingly. 383This action is forced if the parameter 384.Fa flush 385is non-zero. 386Forcing 387.Fa flush 388frequently degrades the compression ratio, 389so this parameter should be set only when necessary 390.Pq in interactive applications . 391Some output may be provided even if 392.Fa flush 393is not set. 394.Pp 395Before the call to 396.Fn deflate , 397the application should ensure that at least 398one of the actions is possible, by providing more input and/or consuming 399more output, and updating 400.Fa avail_in 401or 402.Fa avail_out 403accordingly; 404.Fa avail_out 405should never be zero before the call. 406The application can consume the compressed output when it wants, 407for example when the output buffer is full 408.Pq avail_out == 0 , 409or after each call to 410.Fn deflate . 411If 412.Fn deflate 413returns 414.Dv Z_OK 415and with zero 416.Fa avail_out , 417it must be called again after making room in the 418output buffer because there might be more output pending. 419.Pp 420Normally the parameter 421.Fa flush 422is set to 423.Dv Z_NO_FLUSH , 424which allows 425.Fn deflate 426to decide how much data to accumulate before producing output, 427in order to maximise compression. 428.Pp 429If the parameter 430.Fa flush 431is set to 432.Dv Z_SYNC_FLUSH , 433all pending output is flushed to the output buffer and the output 434is aligned on a byte boundary, so that the decompressor can get all 435input data available so far. 436(In particular, 437.Fa avail_in 438is zero after the call if enough output space 439has been provided before the call.) 440Flushing may degrade compression for some compression algorithms 441and so it should be used only when necessary. 442.Pp 443If 444.Fa flush 445is set to 446.Dv Z_FULL_FLUSH , 447all output is flushed as with 448.Dv Z_SYNC_FLUSH , 449and the compression state is reset so that decompression can restart from this 450point if previous compressed data has been damaged or if random access 451is desired. 452Using 453.Dv Z_FULL_FLUSH 454too often can seriously degrade compression. 455.Pp 456If 457.Fn deflate 458returns with avail_out == 0, this function must be called again 459with the same value of the flush parameter and more output space 460(updated 461.Fa avail_out ) , 462until the flush is complete 463.Pf ( Fn deflate 464returns with non-zero 465.Fa avail_out ) . 466In the case of a 467.Dv Z_FULL_FLUSH 468or a 469.Dv Z_SYNC_FLUSH , 470make sure that 471.Fa avail_out 472is greater than six to avoid repeated flush markers due to avail_out == 0 473on return. 474.Pp 475If the parameter 476.Fa flush 477is set to 478.Dv Z_FINISH , 479pending input is processed, pending output is flushed and 480.Fn deflate 481returns with 482.Dv Z_STREAM_END 483if there was enough output space; if 484.Fn deflate 485returns with 486.Dv Z_OK , 487this function must be called again with 488.Dv Z_FINISH 489and more output space 490(updated 491.Fa avail_out 492but no more input data, until it returns with 493.Dv Z_STREAM_END 494or an error. 495After 496.Fn deflate 497has returned 498.Dv Z_STREAM_END , 499the only possible operations on the stream are 500.Fn deflateReset 501or 502.Fn deflateEnd . 503.Pp 504.Dv Z_FINISH 505can be used immediately after 506.Fn deflateInit 507if all the compression is to be done in a single step. 508In this case, 509.Fa avail_out 510must be at least the value returned by 511.Fn deflateBound 512.Pq see below . 513If 514.Fn deflate 515does not return 516.Dv Z_STREAM_END , 517then it must be called again as described above. 518.Pp 519.Fn deflate 520sets strm->adler to the Adler-32 checksum of all input read so far 521(that is, 522.Fa total_in 523bytes). 524.Pp 525.Fn deflate 526may update strm->data_type 527if it can make a good guess about the input data type 528.Pq Z_BINARY or Z_TEXT . 529If in doubt, the data is considered binary. 530This field is only for information purposes and does not affect 531the compression algorithm in any manner. 532.Pp 533.Fn deflate 534returns 535.Dv Z_OK 536if some progress has been made 537.Pq more input processed or more output produced , 538.Dv Z_STREAM_END 539if all input has been consumed and all output has been produced 540(only when 541.Fa flush 542is set to 543.Dv Z_FINISH ) , 544.Dv Z_STREAM_ERROR 545if the stream state was inconsistent 546(for example, if 547.Fa next_in 548or 549.Fa next_out 550was 551.Dv NULL ) , 552.Dv Z_BUF_ERROR 553if no progress is possible 554(for example, 555.Fa avail_in 556or 557.Fa avail_out 558was zero). 559Note that 560.Dv Z_BUF_ERROR 561is not fatal, and 562.Fn deflate 563can be called again with more input and more output space 564to continue processing. 565.It Xo 566.Fa int 567.Fn deflateEnd "z_streamp strm" ; 568.Xc 569.Pp 570All dynamically allocated data structures for this stream are freed. 571This function discards any unprocessed input and does not flush any 572pending output. 573.Pp 574.Fn deflateEnd 575returns 576.Dv Z_OK 577if successful, 578.Dv Z_STREAM_ERROR 579if the stream state was inconsistent, 580.Dv Z_DATA_ERROR 581if the stream was freed prematurely 582.Pq some input or output was discarded . 583In the error case, 584.Fa msg 585may be set but then points to a static string 586.Pq which must not be deallocated . 587.It Xo 588.Fa int 589.Fn inflateInit "z_streamp strm" ; 590.Xc 591The 592.Fn inflateInit 593function initializes the internal stream state for decompression. 594The fields 595.Fa next_in , 596.Fa avail_in , 597.Fa zalloc , 598.Fa zfree , 599and 600.Fa opaque 601must be initialized before by the caller. 602If 603.Fa next_in 604is not 605.Dv Z_NULL 606and 607.Fa avail_in 608is large enough 609.Pq the exact value depends on the compression method , 610.Fn inflateInit 611determines the compression method from the 612.Nm zlib 613header and allocates all data structures accordingly; 614otherwise the allocation will be deferred to the first call to 615.Fn inflate . 616If 617.Fa zalloc 618and 619.Fa zfree 620are set to 621.Dv Z_NULL , 622.Fn inflateInit 623updates them to use default allocation functions. 624.Pp 625.Fn inflateInit 626returns 627.Dv Z_OK 628if successful, 629.Dv Z_MEM_ERROR 630if there was not enough memory, 631.Dv Z_VERSION_ERROR 632if the 633.Nm zlib 634library version is incompatible with the version assumed by the caller. 635.Fa msg 636is set to null if there is no error message. 637.Fn inflateInit 638does not perform any decompression apart from reading the 639.Nm zlib 640header if present: this will be done by 641.Fn inflate . 642(So 643.Fa next_in 644and 645.Fa avail_in 646may be modified, 647but 648.Fa next_out 649and 650.Fa avail_out 651are unchanged.) 652.It Xo 653.Fa int 654.Fn inflate "z_streamp strm" "int flush" ; 655.Xc 656.Fn inflate 657decompresses as much data as possible, and stops when the input 658buffer becomes empty or the output buffer becomes full. 659It may introduce some output latency 660.Pq reading input without producing any output 661except when forced to flush. 662.Pp 663The detailed semantics are as follows. 664.Fn inflate 665performs one or both of the following actions: 666.Pp 667Decompress more input starting at 668.Fa next_in 669and update 670.Fa next_in 671and 672.Fa avail_in 673accordingly. 674If not all input can be processed 675(because there is not enough room in the output buffer), 676.Fa next_in 677is updated and processing will resume at this point for the next call to 678.Fn inflate . 679.Pp 680Provide more output starting at 681.Fa next_out 682and update 683.Fa next_out 684and 685.Fa avail_out 686accordingly. 687.Fn inflate 688provides as much output as possible, 689until there is no more input data or no more space in the output buffer 690.Pq see below about the flush parameter . 691.Pp 692Before the call to 693.Fn inflate , 694the application should ensure that at least one of the actions is possible, 695by providing more input and/or consuming more output, 696and updating the next_* and avail_* values accordingly. 697The application can consume the uncompressed output when it wants, 698for example when the output buffer is full (avail_out == 0), 699or after each call to 700.Fn inflate . 701If 702.Fn inflate 703returns 704.Dv Z_OK 705and with zero 706.Fa avail_out , 707it must be called again after making room 708in the output buffer because there might be more output pending. 709.Pp 710The 711.Fa flush 712parameter of 713.Fn inflate 714can be 715.Dv Z_NO_FLUSH , Z_SYNC_FLUSH , Z_FINISH , 716or 717.Dv Z_BLOCK . 718.Dv Z_SYNC_FLUSH 719requests that 720.Fn inflate 721flush as much output as possible to the output buffer. 722.Dv Z_BLOCK 723requests that 724.Fn inflate 725stop if and when it gets to the next deflate block boundary. 726When decoding the zlib or gzip format, this will cause 727.Fn inflate 728to return immediately after the header and before the first block. 729When doing a raw inflate, 730.Fn inflate 731will go ahead and process the first block, 732and will return when it gets to the end of that block, 733or when it runs out of data. 734.Pp 735The 736.Dv Z_BLOCK 737option assists in appending to or combining deflate streams. 738Also to assist in this, on return 739.Fn inflate 740will set strm->data_type to the number of unused bits in the last byte 741taken from strm->next_in, plus 64 if 742.Fn inflate 743is currently decoding the last block in the deflate stream, plus 128 if 744.Fn inflate 745returned immediately after decoding an end-of-block code or decoding 746the complete header up to just before the first byte of the deflate stream. 747The end-of-block will not be indicated until all of the uncompressed data 748from that block has been written to strm->next_out. 749The number of unused bits may in general be greater than seven, 750except when bit 7 of data_type is set, 751in which case the number of unused bits will be less than eight. 752.Pp 753.Fn inflate 754should normally be called until it returns 755.Dv Z_STREAM_END 756or an error. 757However if all decompression is to be performed in a single step 758.Pq a single call to inflate , 759the parameter 760.Fa flush 761should be set to 762.Dv Z_FINISH . 763In this case all pending input is processed and all pending output is flushed; 764.Fa avail_out 765must be large enough to hold all the uncompressed data. 766(The size of the uncompressed data may have been saved 767by the compressor for this purpose.) 768The next operation on this stream must be 769.Fn inflateEnd 770to deallocate the decompression state. 771The use of 772.Dv Z_FINISH 773is never required, but can be used to inform 774.Fn inflate 775that a faster approach may be used for the single 776.Fn inflate 777call. 778.Pp 779In this implementation, 780.Fn inflate 781always flushes as much output as possible to the output buffer, 782and always uses the faster approach on the first call. 783So the only effect of the 784.Fa flush 785parameter in this implementation is on the return value of 786.Fn inflate , 787as noted below, or when it returns early because 788.Dv Z_BLOCK 789is used. 790.Pp 791If a preset dictionary is needed after this call (see 792.Fn inflateSetDictionary 793below), 794.Fn inflate 795sets strm->adler to the Adler-32 checksum of the dictionary 796chosen by the compressor and returns Z_NEED_DICT; otherwise it sets 797strm->adler to the Adler-32 checksum of all output produced so far 798(that is, 799.Fa total_out 800bytes) and returns 801.Dv Z_OK , Z_STREAM_END 802or an error code as described below. 803At the end of the stream, 804.Fn inflate 805checks that its computed Adler-32 checksum is equal to that saved by 806the compressor and returns 807.Dv Z_STREAM_END 808only if the checksum is correct. 809.Pp 810.Fn inflate 811will decompress and check either zlib-wrapped or gzip-wrapped deflate data. 812The header type is detected automatically. 813Any information contained in the gzip header is not retained, 814so applications that need that information should instead use raw inflate; see 815.Fn inflateInit2 816below, or 817.Fn inflateBack 818and perform their own processing of the gzip header and trailer. 819.Pp 820.Fn inflate 821returns 822.Dv Z_OK 823if some progress has been made 824.Pq more input processed or more output produced , 825.Dv Z_STREAM_END 826if the end of the compressed data has been reached and all uncompressed output 827has been produced, 828.Dv Z_NEED_DICT 829if a preset dictionary is needed at this point, 830.Dv Z_DATA_ERROR 831if the input data was corrupted (input stream not conforming to the 832.Nm zlib 833format or incorrect check value), 834.Dv Z_STREAM_ERROR 835if the stream structure was inconsistent 836(for example, if 837.Fa next_in 838or 839.Fa next_out 840was 841.Dv NULL ) , 842.Dv Z_MEM_ERROR 843if there was not enough memory, 844.Dv Z_BUF_ERROR 845if no progress is possible or if there was not enough room in the output buffer 846when 847.Dv Z_FINISH 848is used. 849Note that 850.Dv Z_BUF_ERROR 851is not fatal, and 852.Fn inflate 853can be called again with more input and more output space 854to continue compressing. 855If 856.Dv Z_DATA_ERROR 857is returned, the application may then call 858.Fn inflateSync 859to look for a good compression block if a partial recovery 860of the data is desired. 861.It Xo 862.Fa int 863.Fn inflateEnd "z_streamp strm" ; 864.Xc 865All dynamically allocated data structures for this stream are freed. 866This function discards any unprocessed input and does not flush any 867pending output. 868.Pp 869.Fn inflateEnd 870returns 871.Dv Z_OK 872if successful, or 873.Dv Z_STREAM_ERROR 874if the stream state was inconsistent. 875In the error case, 876.Fa msg 877may be set but then points to a static string 878.Pq which must not be deallocated . 879.El 880.Sh ADVANCED FUNCTIONS 881The following functions are needed only in some special applications. 882.Bl -tag -width Ds 883.It Xo 884.Fa int 885.Fn deflateInit2 "z_streamp strm" "int level" "int method" "int windowBits" "int memLevel" "int strategy" ; 886.Xc 887.Pp 888This is another version of 889.Fn deflateInit 890with more compression options. 891The fields 892.Fa next_in , 893.Fa zalloc , 894.Fa zfree , 895and 896.Fa opaque 897must be initialized before by the caller. 898.Pp 899The 900.Fa method 901parameter is the compression method. 902It must be 903.Dv Z_DEFLATED 904in this version of the library. 905.Pp 906The 907.Fa windowBits 908parameter is the base two logarithm of the window size 909.Pq the size of the history buffer . 910It should be in the range 8..15 for this version of the library. 911Larger values of this parameter result in better compression 912at the expense of memory usage. 913The default value is 15 if 914.Fn deflateInit 915is used instead. 916.Pp 917.Fa windowBits 918can also be -8..-15 for raw deflate. 919In this case, -windowBits determines the window size. 920.Fn deflate 921will then generate raw deflate data with no zlib header or trailer, 922and will not compute an Adler-32 check value. 923.Pp 924.Fa windowBits 925can also be greater than 15 for optional gzip encoding. 926Add 16 to 927.Fa windowBits 928to write a simple gzip header and trailer around the 929compressed data instead of a zlib wrapper. 930The gzip header will have no file name, no extra data, no comment, 931no modification time 932.Pq set to zero , 933no header crc, and the operating system will be set to 255 934.Pq unknown . 935If a gzip stream is being written, 936strm->adler is a crc32 instead of an adler32. 937.Pp 938The 939.Fa memLevel 940parameter specifies how much memory should be allocated 941for the internal compression state. 942memLevel=1 uses minimum memory but is slow and reduces compression ratio; 943memLevel=9 uses maximum memory for optimal speed. 944The default value is 8. 945See 946.In zconf.h 947for total memory usage as a function of 948.Fa windowBits 949and 950.Fa memLevel . 951.Pp 952The 953.Fa strategy 954parameter is used to tune the compression algorithm. 955Use the value 956.Dv Z_DEFAULT_STRATEGY 957for normal data; 958.Dv Z_FILTERED 959for data produced by a filter 960.Pq or predictor ; 961.Dv Z_HUFFMAN_ONLY 962to force Huffman encoding only 963.Pq no string match , 964or 965.Dv Z_RLE 966to limit match distances to one 967.Pq run-length encoding . 968Filtered data consists mostly of small values with a 969somewhat random distribution. 970In this case, the compression algorithm is tuned to compress them better. 971The effect of 972.Dv Z_FILTERED 973is to force more Huffman coding and less string matching; 974it is somewhat intermediate between 975.Dv Z_DEFAULT 976and 977.Dv Z_HUFFMAN_ONLY . 978.Dv Z_RLE 979is designed to be almost as fast as 980.Dv Z_HUFFMAN_ONLY , 981but gives better compression for PNG image data. 982The 983.Fa strategy 984parameter only affects the compression ratio but not the correctness of the 985compressed output, even if it is not set appropriately. 986.Dv Z_FIXED 987prevents the use of dynamic Huffman codes, 988allowing for a simpler decoder for special applications. 989.Pp 990.Fn deflateInit2 991returns 992.Dv Z_OK 993if successful, 994.Dv Z_MEM_ERROR 995if there was not enough memory, 996.Dv Z_STREAM_ERROR 997if a parameter is invalid 998.Pq such as an invalid method . 999.Fa msg 1000is set to null if there is no error message. 1001.Fn deflateInit2 1002does not perform any compression: this will be done by 1003.Fn deflate . 1004.It Xo 1005.Fa int 1006.Fn deflateSetDictionary "z_streamp strm" "const Bytef *dictionary" "uInt dictLength" ; 1007.Xc 1008.Pp 1009Initializes the compression dictionary from the given byte sequence 1010without producing any compressed output. 1011This function must be called immediately after 1012.Fn deflateInit , 1013.Fn deflateInit2 , 1014or 1015.Fn deflateReset , 1016before any call to 1017.Fn deflate . 1018The compressor and decompressor must use exactly the same dictionary 1019(see 1020.Fn inflateSetDictionary ) . 1021.Pp 1022The dictionary should consist of strings 1023.Pq byte sequences 1024that are likely to be encountered later in the data to be compressed, 1025with the most commonly used strings preferably put towards 1026the end of the dictionary. 1027Using a dictionary is most useful when the data to be compressed is short 1028and can be predicted with good accuracy; 1029the data can then be compressed better than with the default empty dictionary. 1030.Pp 1031Depending on the size of the compression data structures selected by 1032.Fn deflateInit 1033or 1034.Fn deflateInit2 , 1035a part of the dictionary may in effect be discarded, 1036for example if the dictionary is larger than the window size in 1037.Fn deflate 1038or 1039.Fn deflate2 . 1040Thus the strings most likely to be useful should be 1041put at the end of the dictionary, not at the front. 1042In addition, the current implementation of 1043.Fn deflate 1044will use at most the window size minus 262 bytes of the provided dictionary. 1045.Pp 1046Upon return of this function, strm->adler is set to the Adler-32 value 1047of the dictionary; the decompressor may later use this value to determine 1048which dictionary has been used by the compressor. 1049(The Adler-32 value applies to the whole dictionary even if only a subset 1050of the dictionary is actually used by the compressor.) 1051If a raw deflate was requested, then the Adler-32 value is not computed 1052and strm->adler is not set. 1053.Pp 1054.Fn deflateSetDictionary 1055returns 1056.Dv Z_OK 1057if successful, 1058or 1059.Dv Z_STREAM_ERROR 1060if a parameter is invalid 1061.Pq such as NULL dictionary 1062or the stream state is inconsistent 1063(for example if 1064.Fn deflate 1065has already been called for this stream or if the compression method is bsort). 1066.Fn deflateSetDictionary 1067does not perform any compression: this will be done by 1068.Fn deflate . 1069.It Xo 1070.Fa int 1071.Fn deflateCopy "z_streamp dest" "z_streamp source" ; 1072.Xc 1073.Pp 1074The 1075.Fn deflateCopy 1076function sets the destination stream as a complete copy of the source stream. 1077.Pp 1078This function can be useful when several compression strategies will be 1079tried, for example when there are several ways of pre-processing the input 1080data with a filter. 1081The streams that will be discarded should then be freed by calling 1082.Fn deflateEnd . 1083Note that 1084.Fn deflateCopy 1085duplicates the internal compression state which can be quite large, 1086so this strategy is slow and can consume lots of memory. 1087.Pp 1088.Fn deflateCopy 1089returns 1090.Dv Z_OK 1091if successful, 1092.Dv Z_MEM_ERROR 1093if there was not enough memory, 1094.Dv Z_STREAM_ERROR 1095if the source stream state was inconsistent 1096(such as 1097.Fa zalloc 1098being NULL). 1099.Fa msg 1100is left unchanged in both source and destination. 1101.It Xo 1102.Fa int 1103.Fn deflateReset "z_streamp strm" ; 1104.Xc 1105.Pp 1106This function is equivalent to 1107.Fn deflateEnd 1108followed by 1109.Fn deflateInit , 1110but does not free and reallocate all the internal compression state. 1111The stream will keep the same compression level and any other attributes 1112that may have been set by 1113.Fn deflateInit2 . 1114.Pp 1115.Fn deflateReset 1116returns 1117.Dv Z_OK 1118if successful, or 1119.Dv Z_STREAM_ERROR 1120if the source stream state was inconsistent 1121(such as 1122.Fa zalloc 1123or 1124.Fa state 1125being NULL). 1126.It Xo 1127.Fa int 1128.Fn deflateParams "z_streamp strm" "int level" "int strategy" ; 1129.Xc 1130.Pp 1131The 1132.Fn deflateParams 1133function dynamically updates the compression level and compression strategy. 1134The interpretation of level and strategy is as in 1135.Fn deflateInit2 . 1136This can be used to switch between compression and straight copy 1137of the input data, or to switch to a different kind of input data 1138requiring a different strategy. 1139If the compression level is changed, the input available so far 1140is compressed with the old level 1141.Pq and may be flushed ; 1142the new level will take effect only at the next call to 1143.Fn deflate . 1144.Pp 1145Before the call to 1146.Fn deflateParams , 1147the stream state must be set as for a call to 1148.Fn deflate , 1149since the currently available input may have to be compressed and flushed. 1150In particular, strm->avail_out must be non-zero. 1151.Pp 1152.Fn deflateParams 1153returns 1154.Dv Z_OK 1155if successful, 1156.Dv Z_STREAM_ERROR 1157if the source stream state was inconsistent or if a parameter was invalid, or 1158.Dv Z_BUF_ERROR 1159if strm->avail_out was zero. 1160.It Xo 1161.Fa int 1162.Fn deflateTune "z_streamp strm" "int good_length" "int max_lazy" "int nice_length" "int max_chain" 1163.Xc 1164.Pp 1165Fine tune 1166.Fn deflate Ns 's 1167internal compression parameters. 1168This should only be used by someone who understands the algorithm 1169used by zlib's deflate for searching for the best matching string, 1170and even then only by the most fanatic optimizer 1171trying to squeeze out the last compressed bit for their specific input data. 1172Read the 1173.Pa deflate.c 1174source code for the meaning of the 1175.Fa max_lazy , good_length , nice_length , 1176and 1177.Fa max_chain 1178parameters. 1179.Pp 1180.Fn deflateTune 1181can be called after 1182.Fn deflateInit 1183or 1184.Fn deflateInit2 , 1185and returns 1186.Dv Z_OK 1187on success, or 1188.Dv Z_STREAM_ERROR 1189for an invalid deflate stream. 1190.It Xo 1191.Fa uLong 1192.Fn deflateBound "z_streamp strm" "uLong sourceLen" 1193.Xc 1194.Pp 1195.Fn deflateBound 1196returns an upper bound on the compressed size after deflation of 1197.Fa sourceLen 1198bytes. 1199It must be called after 1200.Fn deflateInit 1201or 1202.Fn deflateInit2 . 1203This would be used to allocate an output buffer for deflation in a single pass, 1204and so would be called before 1205.Fn deflate . 1206.It Xo 1207.Fa int 1208.Fn deflatePrime "z_streamp strm" "int bits" "int value" 1209.Xc 1210.Pp 1211.Fn deflatePrime 1212inserts 1213.Fa bits 1214in the deflate output stream. 1215The intent is that this function is used to start off the deflate output 1216with the bits leftover from a previous deflate stream when appending to it. 1217As such, this function can only be used for raw deflate, 1218and must be used before the first 1219.Fn deflate 1220call after a 1221.Fn deflateInit2 1222or 1223.Fn deflateReset . 1224.Fa bits 1225must be less than or equal to 16, 1226and that many of the least significant bits of 1227.Fa value 1228will be inserted in the output. 1229.Pp 1230.Fn deflatePrime 1231returns 1232.Dv Z_OK 1233if successful, or 1234.Dv Z_STREAM_ERROR 1235if the source stream state was inconsistent. 1236.It Xo 1237.Fa int 1238.Fn deflateSetHeader "z_streamp strm" "gz_headerp head" 1239.Xc 1240.Pp 1241.Fn deflateSetHeader 1242provides gzip header information for when a gzip 1243stream is requested by 1244.Fn deflateInit2 . 1245.Fn deflateSetHeader 1246may be called after 1247.Fn deflateInit2 1248or 1249.Fn deflateReset 1250and before the first call of 1251.Fn deflate . 1252The text, time, os, extra field, name, and comment information 1253in the provided gz_header structure are written to the gzip header 1254(xflag is ignored \- the extra flags are set 1255according to the compression level). 1256The caller must assure that, if not 1257.Dv Z_NULL , 1258.Fa name 1259and 1260.Fa comment 1261are terminated with a zero byte, 1262and that if 1263.Fa extra 1264is not 1265.Dv Z_NULL , 1266that 1267.Fa extra_len 1268bytes are available there. 1269If hcrc is true, a gzip header CRC is included. 1270Note that the current versions of the command-line version of 1271.Xr gzip 1 1272do not support header CRCs, and will report that it is a 1273.Dq multi-part gzip file 1274and give up. 1275.Pp 1276If 1277.Fn deflateSetHeader 1278is not used, the default gzip header has text false, 1279the time set to zero, and os set to 255, with no extra, name, or comment 1280fields. 1281The gzip header is returned to the default state by 1282.Fn deflateReset . 1283.Pp 1284.Fn deflateSetHeader 1285returns 1286.Dv Z_OK 1287if successful, or 1288.Dv Z_STREAM_ERROR 1289if the source stream state was inconsistent. 1290.It Xo 1291.Fa int 1292.Fn inflateInit2 "z_streamp strm" "int windowBits" ; 1293.Xc 1294.Pp 1295This is another version of 1296.Fn inflateInit 1297with an extra parameter. 1298The fields 1299.Fa next_in , 1300.Fa avail_in , 1301.Fa zalloc , 1302.Fa zfree , 1303and 1304.Fa opaque 1305must be initialized before by the caller. 1306.Pp 1307The 1308.Fa windowBits 1309parameter is the base two logarithm of the maximum window size 1310.Pq the size of the history buffer . 1311It should be in the range 8..15 for this version of the library. 1312The default value is 15 if 1313.Fn inflateInit 1314is used instead. 1315.Fa windowBits 1316must be greater than or equal to the 1317.Fa windowBits 1318value provided to 1319.Fn deflateInit2 1320while compressing, or it must be equal to 15 if 1321.Fn deflateInit2 1322was not used. 1323If a compressed stream with a larger window size is given as input, 1324.Fn inflate 1325will return with the error code 1326.Dv Z_DATA_ERROR 1327instead of trying to allocate a larger window. 1328.Pp 1329.Fa windowBits 1330can also be -8..-15 for raw inflate. 1331In this case, -windowBits determines the window size. 1332.Fn inflate 1333will then process raw deflate data, not looking for a zlib or gzip header, 1334not generating a check value, and not looking for any check values 1335for comparison at the end of the stream. 1336This is for use with other formats that use the deflate compressed data format 1337such as zip. 1338Those formats provide their own check values. 1339If a custom format is developed using the raw deflate format 1340for compressed data, it is recommended that a check value such as an Adler-32 1341or a crc32 be applied to the uncompressed data as is done in the zlib, gzip, 1342and zip formats. 1343For most applications, the zlib format should be used as is. 1344Note that comments above on the use in 1345.Fn deflateInit2 1346applies to the magnitude of 1347.Fa windowBits . 1348.Pp 1349.Fa windowBits 1350can also be greater than 15 for optional gzip decoding. 1351Add 32 to windowBits to enable zlib and gzip decoding with automatic header 1352detection, or add 16 to decode only the gzip format 1353(the zlib format will return a 1354.Dv Z_DATA_ERROR ) . 1355If a gzip stream is being decoded, 1356strm->adler is a crc32 instead of an adler32. 1357.Pp 1358.Fn inflateInit2 1359returns 1360.Dv Z_OK 1361if successful, 1362.Dv Z_MEM_ERROR 1363if there was not enough memory, 1364.Dv Z_STREAM_ERROR 1365if a parameter is invalid 1366(such as a null strm). 1367.Fa msg 1368is set to null if there is no error message. 1369.Fn inflateInit2 1370does not perform any decompression apart from reading the 1371.Nm zlib 1372header if present: this will be done by 1373.Fn inflate . 1374(So 1375.Fa next_in 1376and 1377.Fa avail_in 1378may be modified, but 1379.Fa next_out 1380and 1381.Fa avail_out 1382are unchanged.) 1383.It Xo 1384.Fa int 1385.Fn inflateSetDictionary "z_streamp strm" "const Bytef *dictionary" "uInt dictLength" ; 1386.Xc 1387.Pp 1388Initializes the decompression dictionary from the given uncompressed byte 1389sequence. 1390This function must be called immediately after a call to 1391.Fn inflate 1392if that call returned 1393.Dv Z_NEED_DICT . 1394The dictionary chosen by the compressor can be determined from the 1395Adler-32 value returned by that call to 1396.Fn inflate . 1397The compressor and decompressor must use exactly the same dictionary 1398(see 1399.Fn deflateSetDictionary ) . 1400For raw inflate, this function can be called immediately after 1401.Fn inflateInit2 1402or 1403.Fn inflateReset 1404and before any call to 1405.Fn inflate 1406to set the dictionary. 1407The application must ensure that the dictionary 1408that was used for compression is provided. 1409.Pp 1410.Fn inflateSetDictionary 1411returns 1412.Dv Z_OK 1413if successful, 1414.Dv Z_STREAM_ERROR 1415if a parameter is invalid 1416.Pq such as NULL dictionary 1417or the stream state is inconsistent, 1418.Dv Z_DATA_ERROR 1419if the given dictionary doesn't match the expected one 1420.Pq incorrect Adler-32 value . 1421.Fn inflateSetDictionary 1422does not perform any decompression: this will be done by subsequent calls of 1423.Fn inflate . 1424.It Xo 1425.Fa int 1426.Fn inflateSync "z_streamp strm" ; 1427.Xc 1428.Pp 1429Skips invalid compressed data until a full flush point 1430(see above the description of 1431.Fn deflate 1432with 1433.Dv Z_FULL_FLUSH ) 1434can be found, or until all available input is skipped. 1435No output is provided. 1436.Pp 1437.Fn inflateSync 1438returns 1439.Dv Z_OK 1440if a full flush point has been found, 1441.Dv Z_BUF_ERROR 1442if no more input was provided, 1443.Dv Z_DATA_ERROR 1444if no flush point has been found, or 1445.Dv Z_STREAM_ERROR 1446if the stream structure was inconsistent. 1447In the success case, the application may save the current value of 1448.Fa total_in 1449which indicates where valid compressed data was found. 1450In the error case, the application may repeatedly call 1451.Fn inflateSync , 1452providing more input each time, until success or end of the input data. 1453.It Xo 1454.Fa int 1455.Fn inflateCopy "z_streamp dest" "z_streamp source" 1456.Xc 1457.Pp 1458Sets the destination stream as a complete copy of the source stream. 1459.Pp 1460This function can be useful when randomly accessing a large stream. 1461The first pass through the stream can periodically record the inflate state, 1462allowing restarting inflate at those points when randomly accessing the stream. 1463.Pp 1464.Fn inflateCopy 1465returns 1466.Dv Z_OK 1467if success, 1468.Dv Z_MEM_ERROR 1469if there was not enough memory, 1470.Dv Z_STREAM_ERROR 1471if the source stream state was inconsistent 1472(such as 1473.Fa zalloc 1474being NULL). 1475.Fa msg 1476is left unchanged in both 1477.Fa source 1478and 1479.Fa dest . 1480.It Xo 1481.Fa int 1482.Fn inflateReset "z_streamp strm" ; 1483.Xc 1484.Pp 1485This function is equivalent to 1486.Fn inflateEnd 1487followed by 1488.Fn inflateInit , 1489but does not free and reallocate all the internal decompression state. 1490The stream will keep attributes that may have been set by 1491.Fn inflateInit2 . 1492.Pp 1493.Fn inflateReset 1494returns 1495.Dv Z_OK 1496if successful, or 1497.Dv Z_STREAM_ERROR 1498if the source stream state was inconsistent 1499(such as 1500.Fa zalloc 1501or 1502.Fa state 1503being NULL). 1504.It Xo 1505.Fa int 1506.Fn inflatePrime "z_stream strm" "int bits" "int value" 1507.Xc 1508.Pp 1509This function inserts bits in the inflate input stream. 1510The intent is that this function is used 1511to start inflating at a bit position in the middle of a byte. 1512The provided bits will be used before any bytes are used from 1513.Fa next_in . 1514This function should only be used with raw inflate, 1515and should be used before the first 1516.Fn inflate 1517call after 1518.Fn inflateInit2 1519or 1520.Fn inflateReset . 1521.Fa bits 1522must be less than or equal to 16, 1523and that many of the least significant bits of value 1524will be inserted in the input. 1525.Pp 1526.Fn inflatePrime 1527returns 1528.Dv Z_OK 1529if successful, or 1530.Dv Z_STREAM_ERROR 1531if the source stream state was inconsistent. 1532.It Xo 1533.Fa int 1534.Fn inflateGetHeader "z_streamp strm" "gz_headerp head" 1535.Xc 1536.Pp 1537.Fn inflateGetHeader 1538requests that gzip header information be stored in the 1539provided gz_header structure. 1540.Fn inflateGetHeader 1541may be called after 1542.Fn inflateInit2 1543or 1544.Fn inflateReset , 1545and before the first call of 1546.Fn inflate . 1547As 1548.Fn inflate 1549processes the gzip stream, head->done is zero until the header 1550is completed, at which time head->done is set to one. 1551If a zlib stream is being decoded, 1552then head->done is set to \-1 to indicate that there will be 1553no gzip header information forthcoming. 1554Note that 1555.Dv Z_BLOCK 1556can be used to force 1557.Fn inflate 1558to return immediately after header processing is complete 1559and before any actual data is decompressed. 1560.Pp 1561The text, time, xflags, and os fields are filled in with the gzip header 1562contents. 1563hcrc is set to true if there is a header CRC. 1564(The header CRC was valid if done is set to one.) 1565If extra is not 1566.Dv Z_NULL , 1567then 1568.Fa extra_max 1569contains the maximum number of bytes to write to 1570.Fa extra . 1571Once done is true, 1572.Fa extra_len 1573contains the actual extra field length, and 1574.Fa extra 1575contains the extra field, or that field truncated if 1576.Fa extra_max 1577is less than 1578.Fa extra_len . 1579If name is not 1580.Dv Z_NULL , 1581then up to 1582.Fa name_max 1583characters are written there, 1584terminated with a zero unless the length is greater than 1585.Fa name_max . 1586If comment is not 1587.Dv Z_NULL , 1588then up to 1589.Fa comm_max 1590characters are written there, 1591terminated with a zero unless the length is greater than 1592.Fa comm_max . 1593When any of extra, name, or comment are not 1594.Dv Z_NULL 1595and the respective field is not present in the header, 1596then that field is set to 1597.Dv Z_NULL 1598to signal its absence. 1599This allows the use of 1600.Fn deflateSetHeader 1601with the returned structure to duplicate the header. 1602However if those fields are set to allocated memory, 1603then the application will need to save those pointers 1604elsewhere so that they can be eventually freed. 1605.Pp 1606If 1607.Fn inflateGetHeader 1608is not used, then the header information is simply discarded. 1609The header is always checked for validity, 1610including the header CRC if present. 1611.Fn inflateReset 1612will reset the process to discard the header information. 1613The application would need to call 1614.Fn inflateGetHeader 1615again to retrieve the header from the next gzip stream. 1616.Pp 1617.Fn inflateGetHeader 1618returns 1619.Dv Z_OK 1620if successful, 1621or 1622.Dv Z_STREAM_ERROR 1623if the source stream state was inconsistent. 1624.It Xo 1625.Fa int 1626.Fn inflateBackInit "z_stream *strm" "int windowBits" "unsigned char FAR *window" 1627.Xc 1628.Pp 1629Initialize the internal stream state for decompression using 1630.Fn inflateBack 1631calls. 1632The fields 1633.Fa zalloc , zfree 1634and 1635.Fa opaque 1636in 1637.Fa strm 1638must be initialized before the call. 1639If 1640.Fa zalloc 1641and 1642.Fa zfree 1643are 1644.Dv Z_NULL , 1645then the default library-derived memory allocation routines are used. 1646.Fa windowBits 1647is the base two logarithm of the window size, in the range 8..15. 1648.Fa window 1649is a caller supplied buffer of that size. 1650Except for special applications where it is assured that 1651.Fn deflate 1652was used with small window sizes, 1653.Fa windowBits 1654must be 15 and a 32K byte window must be supplied to be able to decompress 1655general deflate streams. 1656.Pp 1657See 1658.Fn inflateBack 1659for the usage of these routines. 1660.Pp 1661.Fn inflateBackInit 1662will return 1663.Dv Z_OK 1664on success, 1665.Dv Z_STREAM_ERROR 1666if any of the parameters are invalid, 1667.Dv Z_MEM_ERROR 1668if the internal state could not be allocated, or 1669.Dv Z_VERSION_ERROR 1670if the version of the library does not match the version of the header file. 1671.It Xo 1672.Fa int 1673.Fn inflateBack "z_stream *strm" "in_func in" "void FAR *in_desc" "out_func out" "void FAR *out_desc" 1674.Xc 1675.Pp 1676.Fn inflateBack 1677does a raw inflate with a single call using a call-back 1678interface for input and output. 1679This is more efficient than 1680.Fn inflate 1681for file I/O applications in that it avoids copying between the output and the 1682sliding window by simply making the window itself the output buffer. 1683This function trusts the application to not change the output buffer passed by 1684the output function, at least until 1685.Fn inflateBack 1686returns. 1687.Pp 1688.Fn inflateBackInit 1689must be called first to allocate the internal state 1690and to initialize the state with the user-provided window buffer. 1691.Fn inflateBack 1692may then be used multiple times to inflate a complete, raw 1693deflate stream with each call. 1694.Fn inflateBackEnd 1695is then called to free the allocated state. 1696.Pp 1697A raw deflate stream is one with no zlib or gzip header or trailer. 1698This routine would normally be used in a utility that reads zip or gzip 1699files and writes out uncompressed files. 1700The utility would decode the header and process the trailer on its own, 1701hence this routine expects only the raw deflate stream to decompress. 1702This is different from the normal behavior of 1703.Fn inflate , 1704which expects either a zlib or gzip header and 1705trailer around the deflate stream. 1706.Pp 1707.Fn inflateBack 1708uses two subroutines supplied by the caller that are then called by 1709.Fn inflateBack 1710for input and output. 1711.Fn inflateBack 1712calls those routines until it reads a complete deflate stream and writes out 1713all of the uncompressed data, or until it encounters an error. 1714The function's parameters and return types are defined above in the 1715in_func and out_func typedefs. 1716.Fn inflateBack 1717will call in(in_desc, &buf) which should return the 1718number of bytes of provided input, and a pointer to that input in 1719.Fa buf . 1720If there is no input available, 1721.Fn in 1722must return zero 1723\(em buf is ignored in that case \(em 1724and 1725.Fn inflateBack 1726will return a buffer error. 1727.Fn inflateBack 1728will call out(out_desc, buf, len) to write the uncompressed data buf[0..len-1]. 1729.Fn out 1730should return zero on success, or non-zero on failure. 1731If 1732.Fn out 1733returns non-zero, 1734.Fn inflateBack 1735will return with an error. 1736Neither 1737.Fn in 1738nor 1739.Fn out 1740are permitted to change the contents of the window provided to 1741.Fn inflateBackInit , 1742which is also the buffer that 1743.Fn out 1744uses to write from. 1745The length written by 1746.Fn out 1747will be at most the window size. 1748Any non-zero amount of input may be provided by 1749.Fn in . 1750.Pp 1751For convenience, 1752.Fn inflateBack 1753can be provided input on the first call by setting strm->next_in 1754and strm->avail_in. 1755If that input is exhausted, then 1756.Fn in 1757will be called. 1758Therefore strm->next_in must be initialized before calling 1759.Fn inflateBack . 1760If strm->next_in is 1761.Dv Z_NULL , 1762then 1763.Fn in 1764will be called immediately for input. 1765If strm->next_in is not 1766.Dv Z_NULL , 1767then strm->avail_in must also be initialized, 1768and then if strm->avail_in is not zero, 1769input will initially be taken from 1770strm->next_in[0 .. strm->avail_in \- 1]. 1771.Pp 1772The 1773.Fa in_desc 1774and 1775.Fa out_desc 1776parameters of 1777.Fn inflateBack 1778are passed as the first parameter of 1779.Fn in 1780and 1781.Fn out 1782respectively when they are called. 1783These descriptors can be optionally used to pass any information that the 1784caller-supplied 1785.Fn in 1786and 1787.Fn out 1788functions need to do their job. 1789.Pp 1790On return, 1791.Fn inflateBack 1792will set strm->next_in and strm->avail_in to pass back any unused input 1793that was provided by the last 1794.Fn in 1795call. 1796The return values of 1797.Fn inflateBack 1798can be 1799.Dv Z_STREAM_END 1800on success, 1801.Dv Z_BUF_ERROR 1802if 1803.Fn in 1804or 1805.Fn out 1806returned an error, 1807.Dv Z_DATA_ERROR 1808if there was a format error in the deflate stream 1809(in which case strm->msg is set to indicate the nature of the error), 1810or 1811.Dv Z_STREAM_ERROR 1812if the stream was not properly initialized. 1813In the case of 1814.Dv Z_BUF_ERROR , 1815an input or output error can be distinguished using strm->next_in which 1816will be 1817.Dv Z_NULL 1818only if 1819.Fn in 1820returned an error. 1821If strm->next is not 1822.Dv Z_NULL , 1823then the 1824.Dv Z_BUF_ERROR 1825was due to 1826.Fn out 1827returning non-zero. 1828.Po 1829.Fn in 1830will always be called before 1831.Fn out , 1832so strm->next_in is assured to be defined if 1833.Fn out 1834returns non-zero. 1835.Pc 1836Note that 1837.Fn inflateBack 1838cannot return 1839.Dv Z_OK . 1840.It Xo 1841.Fa int 1842.Fn inflateBackEnd "z_stream *strm" 1843.Xc 1844.Pp 1845All memory allocated by 1846.Fn inflateBackInit 1847is freed. 1848.Pp 1849.Fn inflateBackEnd 1850returns 1851.Dv Z_OK 1852on success, or 1853.Dv Z_STREAM_ERROR 1854if the stream state was inconsistent. 1855.It Xo 1856.Fa uLong 1857.Fn zlibCompileFlags "void" 1858.Xc 1859.Pp 1860This function returns flags indicating compile-time options. 1861.Pp 1862Type sizes, two bits each: 1863.Pp 1864.Bl -tag -width Ds -offset indent -compact 1865.It 00 186616 bits 1867.It 01 186832 bits 1869.It 10 187064 bits 1871.It 11 1872other: 1873.Pp 1874.Bl -tag -width Ds -offset indent -compact 1875.It 1.0 1876size of uInt 1877.It 3.2 1878size of uLong 1879.It 5.4 1880size of voidpf 1881.Pq pointer 1882.It 7.6 1883size of z_off_t 1884.El 1885.El 1886.Pp 1887Compiler, assembler, and debug options: 1888.Pp 1889.Bl -tag -width Ds -offset indent -compact 1890.It 8 1891DEBUG 1892.It 9 1893ASMV or ASMINF \(em use ASM code 1894.It 10 1895ZLIB_WINAPI \(em exported functions use the WINAPI calling convention 1896.It 11 18970 1898.Pq reserved 1899.El 1900.Pp 1901One-time table building 1902.Pq smaller code, but not thread-safe if true : 1903.Pp 1904.Bl -tag -width Ds -offset indent -compact 1905.It 12 1906BUILDFIXED \(em build static block decoding tables when needed 1907.It 13 1908DYNAMIC_CRC_TABLE \(em build CRC calculation tables when needed 1909.It 14,15 19100 1911.Pq reserved 1912.El 1913.Pp 1914Library content (indicates missing functionality): 1915.Pp 1916.Bl -tag -width Ds -offset indent -compact 1917.It 16 1918NO_GZCOMPRESS \(em gz* functions cannot compress 1919.Pq to avoid linking deflate code when not needed 1920.It 17 1921NO_GZIP \(em deflate can't write gzip streams, and inflate can't detect 1922and decode gzip streams 1923.Pq to avoid linking CRC code 1924.It 18-19 19250 1926.Pq reserved 1927.El 1928.Pp 1929Operation variations (changes in library functionality): 1930.Pp 1931.Bl -tag -width Ds -offset indent -compact 1932.It 20 1933PKZIP_BUG_WORKAROUND \(em slightly more permissive inflate 1934.It 21 1935FASTEST \(em deflate algorithm with only one, lowest compression level 1936.It 22,23 19370 1938.Pq reserved 1939.El 1940.Pp 1941The sprintf variant used by gzprintf 1942.Pq zero is best : 1943.Pp 1944.Bl -tag -width Ds -offset indent -compact 1945.It 24 19460 = vs*, 1 = s* \(em 1 means limited to 20 arguments after the format 1947.It 25 19480 = *nprintf, 1 = *printf \(em 1 means 1949.Fn gzprintf 1950not secure! 1951.It 26 19520 = returns value, 1 = void \(em 1 means inferred string length returned 1953.El 1954.Pp 1955Remainder: 1956.Pp 1957.Bl -tag -width Ds -offset indent -compact 1958.It 27-31 19590 1960.Pq reserved 1961.El 1962.El 1963.Sh UTILITY FUNCTIONS 1964The following utility functions are implemented on top of the 1965basic stream-oriented functions. 1966To simplify the interface, 1967some default options are assumed (compression level and memory usage, 1968standard memory allocation functions). 1969The source code of these utility functions can easily be modified 1970if you need special options. 1971.Bl -tag -width Ds 1972.It Xo 1973.Fa int 1974.Fn compress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" ; 1975.Xc 1976.Pp 1977The 1978.Fn compress 1979function compresses the source buffer into the destination buffer. 1980.Fa sourceLen 1981is the byte length of the source buffer. 1982Upon entry, 1983.Fa destLen 1984is the total size of the destination buffer, 1985which must be at least the value returned by 1986.Fn compressBound sourcelen . 1987Upon exit, 1988.Fa destLen 1989is the actual size of the compressed buffer. 1990This function can be used to compress a whole file at once if the 1991input file is mmap'ed. 1992.Pp 1993.Fn compress 1994returns 1995.Dv Z_OK 1996if successful, 1997.Dv Z_MEM_ERROR 1998if there was not enough memory, or 1999.Dv Z_BUF_ERROR 2000if there was not enough room in the output buffer. 2001.It Xo 2002.Fa int 2003.Fn compress2 "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" "int level" ; 2004.Xc 2005.Pp 2006The 2007.Fn compress2 2008function compresses the source buffer into the destination buffer. 2009The 2010.Fa level 2011parameter has the same meaning as in 2012.Fn deflateInit . 2013.Fa sourceLen 2014is the byte length of the source buffer. 2015Upon entry, 2016.Fa destLen 2017is the total size of the destination buffer, 2018which must be at least the value returned by 2019.Fn compressBound sourceLen . 2020Upon exit, 2021.Fa destLen 2022is the actual size of the compressed buffer. 2023.Pp 2024.Fn compress2 2025returns 2026.Dv Z_OK 2027if successful, 2028.Dv Z_MEM_ERROR 2029if there was not enough memory, 2030.Dv Z_BUF_ERROR 2031if there was not enough room in the output buffer, or 2032.Dv Z_STREAM_ERROR 2033if the level parameter is invalid. 2034.It Xo 2035.Fa uLong 2036.Fn compressBound "uLong sourceLen" 2037.Xc 2038.Pp 2039.Fn compressBound 2040returns an upper bound on the compressed size after 2041.Fn compress 2042or 2043.Fn compress2 2044on 2045.Fa sourceLen 2046bytes. 2047It would be used before a 2048.Fn compress 2049or 2050.Fn compress2 2051call to allocate the destination buffer. 2052.It Xo 2053.Fa int 2054.Fn uncompress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" ; 2055.Xc 2056.Pp 2057The 2058.Fn uncompress 2059function decompresses the source buffer into the destination buffer. 2060.Fa sourceLen 2061is the byte length of the source buffer. 2062Upon entry, 2063.Fa destLen 2064is the total size of the destination buffer, 2065which must be large enough to hold the entire uncompressed data. 2066(The size of the uncompressed data must have been saved previously 2067by the compressor and transmitted to the decompressor 2068by some mechanism outside the scope of this compression library.) 2069Upon exit, 2070.Fa destLen 2071is the actual size of the compressed buffer. 2072This function can be used to decompress a whole file at once if the 2073input file is mmap'ed. 2074.Pp 2075.Fn uncompress 2076returns 2077.Dv Z_OK 2078if successful, 2079.Dv Z_MEM_ERROR 2080if there was not enough memory, 2081.Dv Z_BUF_ERROR 2082if there was not enough room in the output buffer, or 2083.Dv Z_DATA_ERROR 2084if the input data was corrupted or incomplete. 2085.It Xo 2086.Fa gzFile 2087.Fn gzopen "const char *path" "const char *mode" ; 2088.Xc 2089.Pp 2090The 2091.Fn gzopen 2092function opens a gzip 2093.Pq .gz 2094file for reading or writing. 2095The mode parameter is as in 2096.Xr fopen 3 2097.Po 2098.Qq rb 2099or 2100.Qq wb 2101.Pc 2102but can also include a compression level 2103.Pq "wb9" 2104or a strategy: 2105.Sq f 2106for filtered data, as in 2107.Qq wb6f ; 2108.Sq h 2109for Huffman only compression, as in 2110.Qq wb1h , 2111or 2112.Sq R 2113for run-length encoding as in 2114.Qq wb1R . 2115(See the description of 2116.Fn deflateInit2 2117for more information about the strategy parameter.) 2118.Pp 2119.Fn gzopen 2120can be used to read a file which is not in gzip format; 2121in this case 2122.Fn gzread 2123will directly read from the file without decompression. 2124.Pp 2125.Fn gzopen 2126returns 2127.Dv NULL 2128if the file could not be opened or if there was 2129insufficient memory to allocate the (de)compression state; 2130errno can be checked to distinguish the two cases (if errno is zero, the 2131.Nm zlib 2132error is 2133.Dv Z_MEM_ERROR ) . 2134.It Xo 2135.Fa gzFile 2136.Fn gzdopen "int fd" "const char *mode" ; 2137.Xc 2138.Pp 2139The 2140.Fn gzdopen 2141function associates a gzFile with the file descriptor 2142.Fa fd . 2143File descriptors are obtained from calls like 2144.Xr open 2 , 2145.Xr dup 2 , 2146.Xr creat 3 , 2147.Xr pipe 2 , 2148or 2149.Xr fileno 3 2150(if the file has been previously opened with 2151.Xr fopen 3 ) . 2152The 2153.Fa mode 2154parameter is as in 2155.Fn gzopen . 2156.Pp 2157The next call to 2158.Fn gzclose 2159on the returned gzFile will also close the file descriptor fd, 2160just like fclose(fdopen(fd), mode) closes the file descriptor fd. 2161If you want to keep fd open, use gzdopen(dup(fd), mode). 2162.Pp 2163.Fn gzdopen 2164returns 2165.Dv NULL 2166if there was insufficient memory to allocate the (de)compression state. 2167.It Xo 2168.Fa int 2169.Fn gzsetparams "gzFile file" "int level" "int strategy" ; 2170.Xc 2171.Pp 2172The 2173.Fn gzsetparams 2174function dynamically updates the compression level or strategy. 2175See the description of 2176.Fn deflateInit2 2177for the meaning of these parameters. 2178.Pp 2179.Fn gzsetparams 2180returns 2181.Dv Z_OK 2182if successful, or 2183.Dv Z_STREAM_ERROR 2184if the file was not opened for writing. 2185.It Xo 2186.Fa int 2187.Fn gzread "gzFile file" "voidp buf" "unsigned len" ; 2188.Xc 2189.Pp 2190The 2191.Fn gzread 2192function reads the given number of uncompressed bytes from the compressed file. 2193If the input file was not in gzip format, 2194.Fn gzread 2195copies the given number of bytes into the buffer. 2196.Pp 2197.Fn gzread 2198returns the number of uncompressed bytes actually read 2199(0 for end of file, \-1 for error). 2200.It Xo 2201.Fa int 2202.Fn gzwrite "gzFile file" "voidpc buf" "unsigned len" ; 2203.Xc 2204.Pp 2205The 2206.Fn gzwrite 2207function writes the given number of uncompressed bytes into the compressed file. 2208.Fn gzwrite 2209returns the number of uncompressed bytes actually written 2210.Pq 0 in case of error . 2211.It Xo 2212.Fa int 2213.Fn gzprintf "gzFile file" "const char *format" "..." ; 2214.Xc 2215.Pp 2216The 2217.Fn gzprintf 2218function converts, formats, and writes the args to the compressed file 2219under control of the format string, as in 2220.Xr fprintf 3 . 2221.Fn gzprintf 2222returns the number of uncompressed bytes actually written 2223.Pq 0 in case of error . 2224The number of uncompressed bytes written is limited to 4095. 2225The caller should make sure that this limit is not exceeded. 2226If it is exceeded, then 2227.Fn gzprintf 2228will return an error 2229.Pq 0 2230with nothing written. 2231In this case, there may also be a buffer overflow 2232with unpredictable consequences, which is possible only if 2233.Nm zlib 2234was compiled with the insecure functions 2235.Fn sprintf 2236or 2237.Fn vsprintf 2238because the secure 2239.Fn snprintf 2240or 2241.Fn vsnprintf 2242functions were not available. 2243.It Xo 2244.Fa int 2245.Fn gzputs "gzFile file" "const char *s" ; 2246.Xc 2247.Pp 2248The 2249.Fn gzputs 2250function writes the given null-terminated string to the compressed file, 2251excluding the terminating null character. 2252.Pp 2253.Fn gzputs 2254returns the number of characters written, or \-1 in case of error. 2255.It Xo 2256.Fa char * 2257.Fn gzgets "gzFile file" "char *buf" "int len" ; 2258.Xc 2259.Pp 2260The 2261.Fn gzgets 2262function reads bytes from the compressed file until len\-1 characters are read, 2263or a newline character is read and transferred to 2264.Fa buf , 2265or an end-of-file condition is encountered. 2266The string is then terminated with a null character. 2267.Pp 2268.Fn gzgets 2269returns 2270.Fa buf , 2271or 2272.Dv Z_NULL 2273in case of error. 2274.It Xo 2275.Fa int 2276.Fn gzputc "gzFile file" "int c" ; 2277.Xc 2278.Pp 2279The 2280.Fn gzputc 2281function writes 2282.Fa c , 2283converted to an unsigned char, into the compressed file. 2284.Fn gzputc 2285returns the value that was written, or \-1 in case of error. 2286.It Xo 2287.Fa int 2288.Fn gzgetc "gzFile file" ; 2289.Xc 2290.Pp 2291The 2292.Fn gzgetc 2293function reads one byte from the compressed file. 2294.Fn gzgetc 2295returns this byte or \-1 in case of end of file or error. 2296.It Xo 2297.Fa int 2298.Fn gzungetc "int c" "gzFile file" 2299.Xc 2300.Pp 2301Push one character back onto the stream to be read again later. 2302Only one character of push-back is allowed. 2303.Fn gzungetc 2304returns the character pushed, or \-1 on failure. 2305.Fn gzungetc 2306will fail if a character has been pushed but not read yet, or if 2307.Fa c 2308is \-1. 2309The pushed character will be discarded if the stream is repositioned with 2310.Fn gzseek 2311or 2312.Fn gzrewind . 2313.It Xo 2314.Fa int 2315.Fn gzflush "gzFile file" "int flush" ; 2316.Xc 2317.Pp 2318The 2319.Fn gzflush 2320function flushes all pending output into the compressed file. 2321The parameter 2322.Fa flush 2323is as in the 2324.Fn deflate 2325function. 2326The return value is the 2327.Nm zlib 2328error number (see function 2329.Fn gzerror 2330below). 2331.Fn gzflush 2332returns 2333.Dv Z_OK 2334if the flush parameter is 2335.Dv Z_FINISH 2336and all output could be flushed. 2337.Pp 2338.Fn gzflush 2339should be called only when strictly necessary because it can 2340degrade compression. 2341.It Xo 2342.Fa z_off_t 2343.Fn gzseek "gzFile file" "z_off_t offset" "int whence" ; 2344.Xc 2345.Pp 2346Sets the starting position for the next 2347.Fn gzread 2348or 2349.Fn gzwrite 2350on the given compressed file. 2351The offset represents a number of bytes in the uncompressed data stream. 2352The whence parameter is defined as in 2353.Xr lseek 2 ; 2354the value 2355.Dv SEEK_END 2356is not supported. 2357.Pp 2358If the file is opened for reading, this function is emulated but can be 2359extremely slow. 2360If the file is opened for writing, only forward seeks are supported; 2361.Fn gzseek 2362then compresses a sequence of zeroes up to the new starting position. 2363.Pp 2364.Fn gzseek 2365returns the resulting offset location as measured in bytes from 2366the beginning of the uncompressed stream, or \-1 in case of error, 2367in particular if the file is opened for writing and the new starting position 2368would be before the current position. 2369.It Xo 2370.Fa int 2371.Fn gzrewind "gzFile file" ; 2372.Xc 2373.Pp 2374The 2375.Fn gzrewind 2376function rewinds the given 2377.Fa file . 2378This function is supported only for reading. 2379.Pp 2380gzrewind(file) is equivalent to (int)gzseek(file, 0L, SEEK_SET). 2381.It Xo 2382.Fa z_off_t 2383.Fn gztell "gzFile file" ; 2384.Xc 2385.Pp 2386The 2387.Fn gztell 2388function returns the starting position for the next 2389.Fn gzread 2390or 2391.Fn gzwrite 2392on the given compressed file. 2393This position represents a number of bytes in the uncompressed data stream. 2394.Pp 2395gztell(file) is equivalent to gzseek(file, 0L, SEEK_CUR). 2396.It Xo 2397.Fa int 2398.Fn gzeof "gzFile file" ; 2399.Xc 2400.Pp 2401The 2402.Fn gzeof 2403function returns 1 when 2404.Dv EOF 2405has previously been detected reading the given input stream, otherwise zero. 2406.It Xo 2407.Fa int 2408.Fn gzdirect "gzFile file" ; 2409.Xc 2410.Pp 2411The 2412.Fn gzdirect 2413function returns 1 if the file is being read directly 2414without compression; 2415otherwise it returns 0. 2416.It Xo 2417.Fa int 2418.Fn gzclose "gzFile file" ; 2419.Xc 2420.Pp 2421The 2422.Fn gzclose 2423function flushes all pending output if necessary, closes the compressed file 2424and deallocates all the (de)compression state. 2425The return value is the 2426.Nm zlib 2427error number (see function 2428.Fn gzerror 2429below). 2430.It Xo 2431.Fa const char * 2432.Fn gzerror "gzFile file" "int *errnum" ; 2433.Xc 2434.Pp 2435The 2436.Fn gzerror 2437function returns the error message for the last error which occurred on the 2438given compressed 2439.Fa file . 2440.Fa errnum 2441is set to the 2442.Nm zlib 2443error number. 2444If an error occurred in the file system and not in the compression library, 2445.Fa errnum 2446is set to 2447.Dv Z_ERRNO 2448and the application may consult errno to get the exact error code. 2449.It Xo 2450.Fa void 2451.Fn gzclearerr "gzFile file" 2452.Xc 2453Clears the error and end-of-file flags for 2454.Fa file . 2455This is analogous to the 2456.Fn clearerr 2457function in stdio. 2458This is useful for continuing to read a gzip file 2459that is being written concurrently. 2460.El 2461.Sh CHECKSUM FUNCTIONS 2462These functions are not related to compression but are exported 2463anyway because they might be useful in applications using the 2464compression library. 2465.Bl -tag -width Ds 2466.It Xo 2467.Fa uLong 2468.Fn adler32 "uLong adler" "const Bytef *buf" "uInt len" ; 2469.Xc 2470The 2471.Fn adler32 2472function updates a running Adler-32 checksum with the bytes buf[0..len-1] 2473and returns the updated checksum. 2474If 2475.Fa buf 2476is 2477.Dv NULL , 2478this function returns the required initial value for the checksum. 2479.Pp 2480An Adler-32 checksum is almost as reliable as a CRC32 but can be computed 2481much faster. 2482Usage example: 2483.Bd -unfilled -offset indent 2484uLong adler = adler32(0L, Z_NULL, 0); 2485 2486while (read_buffer(buffer, length) != EOF) { 2487adler = adler32(adler, buffer, length); 2488} 2489if (adler != original_adler) error(); 2490.Ed 2491.It Xo 2492.Fa uLong 2493.Fn adler32_combine "uLong adler1" "uLong adler2" "z_off_t len2" 2494.Xc 2495.Pp 2496The 2497.Fn adler32_combine 2498function combines two Adler-32 checksums into one. 2499For two sequences of bytes, seq1 and seq2 with lengths len1 and len2, 2500Adler-32 checksums are calculated for each, adler1 and adler2. 2501.Fn adler32_combine 2502returns the Adler-32 checksum of seq1 and seq2 concatenated, 2503requiring only adler1, adler2, and len2. 2504.It Xo 2505.Fa uLong 2506.Fn crc32 "uLong crc" "const Bytef *buf" "uInt len" ; 2507.Xc 2508.Pp 2509The 2510.Fn crc32 2511function updates a running CRC-32 with the bytes buf[0..len-1] 2512and returns the updated CRC-32. 2513If 2514.Fa buf 2515is 2516.Dv NULL , 2517this function returns the required initial value for the CRC. 2518Pre- and post-conditioning 2519.Pq one's complement 2520is performed within this function so it shouldn't be done by the application. 2521Usage example: 2522.Bd -unfilled -offset indent 2523uLong crc = crc32(0L, Z_NULL, 0); 2524 2525while (read_buffer(buffer, length) != EOF) { 2526crc = crc32(crc, buffer, length); 2527} 2528if (crc != original_crc) error(); 2529.Ed 2530.It Xo 2531.Fa uLong 2532.Fn crc32_combine "uLong crc1" "uLong crc2" "z_off_t len2" 2533.Xc 2534.Pp 2535The 2536.Fn crc32_combine 2537function combines two CRC-32 check values into one. 2538For two sequences of bytes, 2539seq1 and seq2 with lengths len1 and len2, 2540CRC-32 check values are calculated for each, crc1 and crc2. 2541.Fn crc32_combine 2542returns the CRC-32 check value of seq1 and seq2 concatenated, 2543requiring only crc1, crc2, and len2. 2544.El 2545.Sh STRUCTURES 2546.Bd -unfilled 2547struct internal_state; 2548 2549typedef struct z_stream_s { 2550 Bytef *next_in; /* next input byte */ 2551 uInt avail_in; /* number of bytes available at next_in */ 2552 off_t total_in; /* total nb of input bytes read so far */ 2553 2554 Bytef *next_out; /* next output byte should be put there */ 2555 uInt avail_out; /* remaining free space at next_out */ 2556 off_t total_out; /* total nb of bytes output so far */ 2557 2558 char *msg; /* last error message, NULL if no error */ 2559 struct internal_state FAR *state; /* not visible by applications */ 2560 2561 alloc_func zalloc; /* used to allocate the internal state */ 2562 free_func zfree; /* used to free the internal state */ 2563 voidpf opaque; /* private data object passed to zalloc and zfree*/ 2564 2565 int data_type; /* best guess about the data type: binary or text*/ 2566 uLong adler; /* adler32 value of the uncompressed data */ 2567 uLong reserved; /* reserved for future use */ 2568} z_stream; 2569 2570typedef z_stream FAR * z_streamp; 2571.Ed 2572.Bd -unfilled 2573/* 2574 gzip header information passed to and from zlib routines. 2575 See RFC 1952 for more details on the meanings of these fields. 2576*/ 2577typedef struct gz_header_s { 2578 int text; /* true if compressed data believed to be text */ 2579 uLong time; /* modification time */ 2580 int xflags; /*extra flags (not used when writing a gzip file)*/ 2581 int os; /* operating system */ 2582 Bytef *extra; /* pointer to extra field or Z_NULL if none */ 2583 uInt extra_len; /* extra field length (valid if extra != Z_NULL) */ 2584 uInt extra_max; /* space at extra (only when reading header) */ 2585 Bytef *name; /* pointer to zero-terminated file name or Z_NULL*/ 2586 uInt name_max; /* space at name (only when reading header) */ 2587 Bytef *comment; /* pointer to zero-terminated comment or Z_NULL */ 2588 uInt comm_max; /* space at comment (only when reading header) */ 2589 int hcrc; /* true if there was or will be a header crc */ 2590 int done; /* true when done reading gzip header (not used 2591 when writing a gzip file) */ 2592} gz_header; 2593 2594typedef gz_header FAR *gz_headerp; 2595.Ed 2596.Pp 2597The application must update 2598.Fa next_in 2599and 2600.Fa avail_in 2601when 2602.Fa avail_in 2603has dropped to zero. 2604It must update 2605.Fa next_out 2606and 2607.Fa avail_out 2608when 2609.Fa avail_out 2610has dropped to zero. 2611The application must initialize 2612.Fa zalloc , 2613.Fa zfree , 2614and 2615.Fa opaque 2616before calling the init function. 2617All other fields are set by the compression library 2618and must not be updated by the application. 2619.Pp 2620The 2621.Fa opaque 2622value provided by the application will be passed as the first 2623parameter for calls to 2624.Fn zalloc 2625and 2626.Fn zfree . 2627This can be useful for custom memory management. 2628The compression library attaches no meaning to the 2629.Fa opaque 2630value. 2631.Pp 2632.Fa zalloc 2633must return 2634.Dv Z_NULL 2635if there is not enough memory for the object. 2636If 2637.Nm zlib 2638is used in a multi-threaded application, 2639.Fa zalloc 2640and 2641.Fa zfree 2642must be thread safe. 2643.Pp 2644On 16-bit systems, the functions 2645.Fa zalloc 2646and 2647.Fa zfree 2648must be able to allocate exactly 65536 bytes, 2649but will not be required to allocate more than this if the symbol MAXSEG_64K 2650is defined (see 2651.In zconf.h ) . 2652.Pp 2653WARNING: On MSDOS, pointers returned by 2654.Fa zalloc 2655for objects of exactly 65536 bytes *must* have their offset normalized to zero. 2656The default allocation function provided by this library ensures this (see 2657.Pa zutil.c ) . 2658To reduce memory requirements and avoid any allocation of 64K objects, 2659at the expense of compression ratio, 2660compile the library with -DMAX_WBITS=14 (see 2661.In zconf.h ) . 2662.Pp 2663The fields 2664.Fa total_in 2665and 2666.Fa total_out 2667can be used for statistics or progress reports. 2668After compression, 2669.Fa total_in 2670holds the total size of the uncompressed data and may be saved for use 2671in the decompressor 2672(particularly if the decompressor wants to decompress everything 2673in a single step). 2674.Sh CONSTANTS 2675.Bd -unfilled 2676#define Z_NO_FLUSH 0 2677#define Z_PARTIAL_FLUSH 1 /* will be removed, use Z_SYNC_FLUSH instead */ 2678#define Z_SYNC_FLUSH 2 2679#define Z_FULL_FLUSH 3 2680#define Z_FINISH 4 2681#define Z_BLOCK 5 2682/* Allowed flush values; see deflate() and inflate() below for details */ 2683 2684#define Z_OK 0 2685#define Z_STREAM_END 1 2686#define Z_NEED_DICT 2 2687#define Z_ERRNO (-1) 2688#define Z_STREAM_ERROR (-2) 2689#define Z_DATA_ERROR (-3) 2690#define Z_MEM_ERROR (-4) 2691#define Z_BUF_ERROR (-5) 2692#define Z_VERSION_ERROR (-6) 2693/* Return codes for the compression/decompression functions. 2694 * Negative values are errors, 2695 * positive values are used for special but normal events. 2696 */ 2697 2698#define Z_NO_COMPRESSION 0 2699#define Z_BEST_SPEED 1 2700#define Z_BEST_COMPRESSION 9 2701#define Z_DEFAULT_COMPRESSION (-1) 2702/* compression levels */ 2703 2704#define Z_FILTERED 1 2705#define Z_HUFFMAN_ONLY 2 2706#define Z_RLE 3 2707#define Z_FIXED 4 2708#define Z_DEFAULT_STRATEGY 0 2709/* compression strategy; see deflateInit2() below for details */ 2710 2711#define Z_BINARY 0 2712#define Z_TEXT 1 2713#define Z_ASCII Z_TEXT /* for compatibility with 1.2.2 and earlier */ 2714#define Z_UNKNOWN 2 2715/* Possible values of the data_type field (though see inflate()) */ 2716 2717#define Z_DEFLATED 8 2718/* The deflate compression method 2719 * (the only one supported in this version) 2720*/ 2721 2722#define Z_NULL 0 /* for initializing zalloc, zfree, opaque */ 2723 2724#define zlib_version zlibVersion() 2725/* for compatibility with versions < 1.0.2 */ 2726.Ed 2727.Sh VARIOUS HACKS 2728deflateInit and inflateInit are macros to allow checking the 2729.Nm zlib 2730version and the compiler's view of 2731.Fa z_stream . 2732.Bl -tag -width Ds 2733.It Xo 2734.Fa int 2735.Fn deflateInit_ "z_stream strm" "int level" "const char *version" "int stream_size" ; 2736.Xc 2737.It Xo 2738.Fa int 2739.Fn inflateInit_ "z_stream strm" "const char *version" "int stream_size" ; 2740.Xc 2741.It Xo 2742.Fa int 2743.Fo deflateInit2_ 2744.Fa "z_stream strm" 2745.Fa "int level" 2746.Fa "int method" 2747.Fa "int windowBits" 2748.Fa "int memLevel" 2749.Fa "int strategy" 2750.Fa "const char *version" 2751.Fa "int stream_size" 2752.Fc 2753.Xc 2754.It Xo 2755.Fa int 2756.Fn inflateInit2_ "z_stream strm" "int windowBits" "const char *version" "int stream_size" ; 2757.Xc 2758.It Xo 2759.Fa int 2760.Fn inflateBackInit_ "z_stream *strm" "int windowBits" "unsigned char FAR *window" "const char *version" "int stream_size" 2761.Xc 2762.It Xo 2763.Fa const char * 2764.Fn zError "int err" ; 2765.Xc 2766.It Xo 2767.Fa int 2768.Fn inflateSyncPoint "z_streamp z" ; 2769.Xc 2770.It Xo 2771.Fa const uLongf * 2772.Fn "get_crc_table" "void" ; 2773.Xc 2774.El 2775.Sh SEE ALSO 2776.Xr compress 1 , 2777.Xr gzip 1 2778.Sh STANDARDS 2779.Rs 2780.%A P. Deutsch 2781.%A J-L. Gailly 2782.%D May 1996 2783.%R RFC 1950 2784.%T ZLIB Compressed Data Format Specification version 3.3 2785.Re 2786.Pp 2787.Rs 2788.%A P. Deutsch 2789.%D May 1996 2790.%R RFC 1951 2791.%T DEFLATE Compressed Data Format Specification version 1.3 2792.Re 2793.Pp 2794.Rs 2795.%A P. Deutsch 2796.%D May 1996 2797.%R RFC 1952 2798.%T GZIP file format specification version 4.3 2799.Re 2800.Sh HISTORY 2801This manual page is based on an HTML version of 2802.In zlib.h 2803converted by 2804.An piaip Aq Mt piaip@csie.ntu.edu.tw 2805and was converted to mdoc format by the 2806.Ox 2807project. 2808.Sh AUTHORS 2809.An Jean-loup Gailly Aq Mt jloup@gzip.org 2810.An Mark Adler Aq Mt madler@alumni.caltech.edu 2811