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