1.\" $OpenBSD: compress.3,v 1.17 2015/11/10 23:48:18 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: November 10 2015 $ 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-\*(Gtadler 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-\*(Gtdata_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-\*(Gtdata_type to the number of unused bits in the last byte 741taken from strm-\*(Gtnext_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-\*(Gtnext_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-\*(Gtadler to the Adler-32 checksum of the dictionary 796chosen by the compressor and returns Z_NEED_DICT; otherwise it sets 797strm-\*(Gtadler 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-\*(Gtadler 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-\*(Gtadler 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-\*(Gtadler 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-\*(Gtavail_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-\*(Gtavail_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-\*(Gtadler 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-\*(Gtdone is zero until the header 1550is completed, at which time head-\*(Gtdone is set to one. 1551If a zlib stream is being decoded, 1552then head-\*(Gtdone 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-\*(Gtnext_in 1754and strm-\*(Gtavail_in. 1755If that input is exhausted, then 1756.Fn in 1757will be called. 1758Therefore strm-\*(Gtnext_in must be initialized before calling 1759.Fn inflateBack . 1760If strm-\*(Gtnext_in is 1761.Dv Z_NULL , 1762then 1763.Fn in 1764will be called immediately for input. 1765If strm-\*(Gtnext_in is not 1766.Dv Z_NULL , 1767then strm-\*(Gtavail_in must also be initialized, 1768and then if strm-\*(Gtavail_in is not zero, 1769input will initially be taken from 1770strm-\*(Gtnext_in[0 .. strm-\*(Gtavail_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-\*(Gtnext_in and strm-\*(Gtavail_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-\*(Gtmsg 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-\*(Gtnext_in which 1816will be 1817.Dv Z_NULL 1818only if 1819.Fn in 1820returned an error. 1821If strm-\*(Gtnext is not 1822.Dv Z_NULL , 1823then the 1824.Dv Z_BUF_ERROR 1825was due to 1826.Fn out 1827returning non-zero. 1828(in() will always be called before out(), 1829so strm-\*(Gtnext_in is assured to be defined if out() returns non-zero.) 1830Note that 1831.Fn inflateBack 1832cannot return 1833.Dv Z_OK . 1834.It Xo 1835.Fa int 1836.Fn inflateBackEnd "z_stream *strm" 1837.Xc 1838.Pp 1839All memory allocated by 1840.Fn inflateBackInit 1841is freed. 1842.Pp 1843.Fn inflateBackEnd 1844returns 1845.Dv Z_OK 1846on success, or 1847.Dv Z_STREAM_ERROR 1848if the stream state was inconsistent. 1849.It Xo 1850.Fa uLong 1851.Fn zlibCompileFlags "void" 1852.Xc 1853.Pp 1854This function returns flags indicating compile-time options. 1855.Pp 1856Type sizes, two bits each: 1857.Pp 1858.Bl -tag -width Ds -offset indent -compact 1859.It 00 186016 bits 1861.It 01 186232 bits 1863.It 10 186464 bits 1865.It 11 1866other: 1867.Pp 1868.Bl -tag -width Ds -offset indent -compact 1869.It 1.0 1870size of uInt 1871.It 3.2 1872size of uLong 1873.It 5.4 1874size of voidpf 1875.Pq pointer 1876.It 7.6 1877size of z_off_t 1878.El 1879.El 1880.Pp 1881Compiler, assembler, and debug options: 1882.Pp 1883.Bl -tag -width Ds -offset indent -compact 1884.It 8 1885DEBUG 1886.It 9 1887ASMV or ASMINF \(em use ASM code 1888.It 10 1889ZLIB_WINAPI \(em exported functions use the WINAPI calling convention 1890.It 11 18910 1892.Pq reserved 1893.El 1894.Pp 1895One-time table building 1896.Pq smaller code, but not thread-safe if true : 1897.Pp 1898.Bl -tag -width Ds -offset indent -compact 1899.It 12 1900BUILDFIXED -- build static block decoding tables when needed 1901.It 13 1902DYNAMIC_CRC_TABLE -- build CRC calculation tables when needed 1903.It 14,15 19040 1905.Pq reserved 1906.El 1907.Pp 1908Library content (indicates missing functionality): 1909.Pp 1910.Bl -tag -width Ds -offset indent -compact 1911.It 16 1912NO_GZCOMPRESS \(em gz* functions cannot compress 1913.Pq to avoid linking deflate code when not needed 1914.It 17 1915NO_GZIP \(em deflate can't write gzip streams, and inflate can't detect 1916and decode gzip streams 1917.Pq to avoid linking CRC code 1918.It 18-19 19190 1920.Pq reserved 1921.El 1922.Pp 1923Operation variations (changes in library functionality): 1924.Pp 1925.Bl -tag -width Ds -offset indent -compact 1926.It 20 1927PKZIP_BUG_WORKAROUND \(em slightly more permissive inflate 1928.It 21 1929FASTEST \(em deflate algorithm with only one, lowest compression level 1930.It 22,23 19310 1932.Pq reserved 1933.El 1934.Pp 1935The sprintf variant used by gzprintf 1936.Pq zero is best : 1937.Pp 1938.Bl -tag -width Ds -offset indent -compact 1939.It 24 19400 = vs*, 1 = s* \(em 1 means limited to 20 arguments after the format 1941.It 25 19420 = *nprintf, 1 = *printf \(em 1 means 1943.Fn gzprintf 1944not secure! 1945.It 26 19460 = returns value, 1 = void \(em 1 means inferred string length returned 1947.El 1948.Pp 1949Remainder: 1950.Pp 1951.Bl -tag -width Ds -offset indent -compact 1952.It 27-31 19530 1954.Pq reserved 1955.El 1956.El 1957.Sh UTILITY FUNCTIONS 1958The following utility functions are implemented on top of the 1959basic stream-oriented functions. 1960To simplify the interface, 1961some default options are assumed (compression level and memory usage, 1962standard memory allocation functions). 1963The source code of these utility functions can easily be modified 1964if you need special options. 1965.Bl -tag -width Ds 1966.It Xo 1967.Fa int 1968.Fn compress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" ; 1969.Xc 1970.Pp 1971The 1972.Fn compress 1973function compresses the source buffer into the destination buffer. 1974.Fa sourceLen 1975is the byte length of the source buffer. 1976Upon entry, 1977.Fa destLen 1978is the total size of the destination buffer, 1979which must be at least the value returned by 1980.Fn compressBound sourcelen . 1981Upon exit, 1982.Fa destLen 1983is the actual size of the compressed buffer. 1984This function can be used to compress a whole file at once if the 1985input file is mmap'ed. 1986.Pp 1987.Fn compress 1988returns 1989.Dv Z_OK 1990if successful, 1991.Dv Z_MEM_ERROR 1992if there was not enough memory, or 1993.Dv Z_BUF_ERROR 1994if there was not enough room in the output buffer. 1995.It Xo 1996.Fa int 1997.Fn compress2 "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" "int level" ; 1998.Xc 1999.Pp 2000The 2001.Fn compress2 2002function compresses the source buffer into the destination buffer. 2003The 2004.Fa level 2005parameter has the same meaning as in 2006.Fn deflateInit . 2007.Fa sourceLen 2008is the byte length of the source buffer. 2009Upon entry, 2010.Fa destLen 2011is the total size of the destination buffer, 2012which must be at least the value returned by 2013.Fn compressBound sourceLen . 2014Upon exit, 2015.Fa destLen 2016is the actual size of the compressed buffer. 2017.Pp 2018.Fn compress2 2019returns 2020.Dv Z_OK 2021if successful, 2022.Dv Z_MEM_ERROR 2023if there was not enough memory, 2024.Dv Z_BUF_ERROR 2025if there was not enough room in the output buffer, or 2026.Dv Z_STREAM_ERROR 2027if the level parameter is invalid. 2028.It Xo 2029.Fa int 2030.Fn compressBound "uLong sourceLen" 2031.Xc 2032.Pp 2033.Fn compressBound 2034returns an upper bound on the compressed size after 2035.Fn compress 2036or 2037.Fn compress2 2038on 2039.Fa sourceLen 2040bytes. 2041It would be used before a 2042.Fn compress 2043or 2044.Fn compress2 2045call to allocate the destination buffer. 2046.It Xo 2047.Fa int 2048.Fn uncompress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" ; 2049.Xc 2050.Pp 2051The 2052.Fn uncompress 2053function decompresses the source buffer into the destination buffer. 2054.Fa sourceLen 2055is the byte length of the source buffer. 2056Upon entry, 2057.Fa destLen 2058is the total size of the destination buffer, 2059which must be large enough to hold the entire uncompressed data. 2060(The size of the uncompressed data must have been saved previously 2061by the compressor and transmitted to the decompressor 2062by some mechanism outside the scope of this compression library.) 2063Upon exit, 2064.Fa destLen 2065is the actual size of the compressed buffer. 2066This function can be used to decompress a whole file at once if the 2067input file is mmap'ed. 2068.Pp 2069.Fn uncompress 2070returns 2071.Dv Z_OK 2072if successful, 2073.Dv Z_MEM_ERROR 2074if there was not enough memory, 2075.Dv Z_BUF_ERROR 2076if there was not enough room in the output buffer, or 2077.Dv Z_DATA_ERROR 2078if the input data was corrupted or incomplete. 2079.It Xo 2080.Fa gzFile 2081.Fn gzopen "const char *path" "const char *mode" ; 2082.Xc 2083.Pp 2084The 2085.Fn gzopen 2086function opens a gzip 2087.Pq .gz 2088file for reading or writing. 2089The mode parameter is as in 2090.Xr fopen 3 2091.Po 2092.Qq rb 2093or 2094.Qq wb 2095.Pc 2096but can also include a compression level 2097.Pq "wb9" 2098or a strategy: 2099.Sq f 2100for filtered data, as in 2101.Qq wb6f ; 2102.Sq h 2103for Huffman only compression, as in 2104.Qq wb1h , 2105or 2106.Sq R 2107for run-length encoding as in 2108.Qq wb1R . 2109(See the description of 2110.Fn deflateInit2 2111for more information about the strategy parameter.) 2112.Pp 2113.Fn gzopen 2114can be used to read a file which is not in gzip format; 2115in this case 2116.Fn gzread 2117will directly read from the file without decompression. 2118.Pp 2119.Fn gzopen 2120returns 2121.Dv NULL 2122if the file could not be opened or if there was 2123insufficient memory to allocate the (de)compression state; 2124errno can be checked to distinguish the two cases (if errno is zero, the 2125.Nm zlib 2126error is 2127.Dv Z_MEM_ERROR ) . 2128.It Xo 2129.Fa gzFile 2130.Fn gzdopen "int fd" "const char *mode" ; 2131.Xc 2132.Pp 2133The 2134.Fn gzdopen 2135function associates a gzFile with the file descriptor 2136.Fa fd . 2137File descriptors are obtained from calls like 2138.Xr open 2 , 2139.Xr dup 2 , 2140.Xr creat 3 , 2141.Xr pipe 2 , 2142or 2143.Xr fileno 3 2144(if the file has been previously opened with 2145.Xr fopen 3 ) . 2146The 2147.Fa mode 2148parameter is as in 2149.Fn gzopen . 2150.Pp 2151The next call to 2152.Fn gzclose 2153on the returned gzFile will also close the file descriptor fd, 2154just like fclose(fdopen(fd), mode) closes the file descriptor fd. 2155If you want to keep fd open, use gzdopen(dup(fd), mode). 2156.Pp 2157.Fn gzdopen 2158returns 2159.Dv NULL 2160if there was insufficient memory to allocate the (de)compression state. 2161.It Xo 2162.Fa int 2163.Fn gzsetparams "gzFile file" "int level" "int strategy" ; 2164.Xc 2165.Pp 2166The 2167.Fn gzsetparams 2168function dynamically updates the compression level or strategy. 2169See the description of 2170.Fn deflateInit2 2171for the meaning of these parameters. 2172.Pp 2173.Fn gzsetparams 2174returns 2175.Dv Z_OK 2176if successful, or 2177.Dv Z_STREAM_ERROR 2178if the file was not opened for writing. 2179.It Xo 2180.Fa int 2181.Fn gzread "gzFile file" "voidp buf" "unsigned len" ; 2182.Xc 2183.Pp 2184The 2185.Fn gzread 2186function reads the given number of uncompressed bytes from the compressed file. 2187If the input file was not in gzip format, 2188.Fn gzread 2189copies the given number of bytes into the buffer. 2190.Pp 2191.Fn gzread 2192returns the number of uncompressed bytes actually read 2193(0 for end of file, \-1 for error). 2194.It Xo 2195.Fa int 2196.Fn gzwrite "gzFile file" "voidpc buf" "unsigned len" ; 2197.Xc 2198.Pp 2199The 2200.Fn gzwrite 2201function writes the given number of uncompressed bytes into the compressed file. 2202.Fn gzwrite 2203returns the number of uncompressed bytes actually written 2204.Pq 0 in case of error . 2205.It Xo 2206.Fa int 2207.Fn gzprintf "gzFile file" "const char *format" "..." ; 2208.Xc 2209.Pp 2210The 2211.Fn gzprintf 2212function converts, formats, and writes the args to the compressed file 2213under control of the format string, as in 2214.Xr fprintf 3 . 2215.Fn gzprintf 2216returns the number of uncompressed bytes actually written 2217.Pq 0 in case of error . 2218The number of uncompressed bytes written is limited to 4095. 2219The caller should make sure that this limit is not exceeded. 2220If it is exceeded, then 2221.Fn gzprintf 2222will return an error 2223.Pq 0 2224with nothing written. 2225In this case, there may also be a buffer overflow 2226with unpredictable consequences, which is possible only if 2227.Nm zlib 2228was compiled with the insecure functions 2229.Fn sprintf 2230or 2231.Fn vsprintf 2232because the secure 2233.Fn snprintf 2234or 2235.Fn vsnprintf 2236functions were not available. 2237.It Xo 2238.Fa int 2239.Fn gzputs "gzFile file" "const char *s" ; 2240.Xc 2241.Pp 2242The 2243.Fn gzputs 2244function writes the given null-terminated string to the compressed file, 2245excluding the terminating null character. 2246.Pp 2247.Fn gzputs 2248returns the number of characters written, or \-1 in case of error. 2249.It Xo 2250.Fa char * 2251.Fn gzgets "gzFile file" "char *buf" "int len" ; 2252.Xc 2253.Pp 2254The 2255.Fn gzgets 2256function reads bytes from the compressed file until len\-1 characters are read, 2257or a newline character is read and transferred to 2258.Fa buf , 2259or an end-of-file condition is encountered. 2260The string is then terminated with a null character. 2261.Pp 2262.Fn gzgets 2263returns 2264.Fa buf , 2265or 2266.Dv Z_NULL 2267in case of error. 2268.It Xo 2269.Fa int 2270.Fn gzputc "gzFile file" "int c" ; 2271.Xc 2272.Pp 2273The 2274.Fn gzputc 2275function writes 2276.Fa c , 2277converted to an unsigned char, into the compressed file. 2278.Fn gzputc 2279returns the value that was written, or \-1 in case of error. 2280.It Xo 2281.Fa int 2282.Fn gzgetc "gzFile file" ; 2283.Xc 2284.Pp 2285The 2286.Fn gzgetc 2287function reads one byte from the compressed file. 2288.Fn gzgetc 2289returns this byte or \-1 in case of end of file or error. 2290.It Xo 2291.Fa int 2292.Fn gzungetc "int c" "gzFile file" 2293.Xc 2294.Pp 2295Push one character back onto the stream to be read again later. 2296Only one character of push-back is allowed. 2297.Fn gzungetc 2298returns the character pushed, or \-1 on failure. 2299.Fn gzungetc 2300will fail if a character has been pushed but not read yet, or if 2301.Fa c 2302is \-1. 2303The pushed character will be discarded if the stream is repositioned with 2304.Fn gzseek 2305or 2306.Fn gzrewind . 2307.It Xo 2308.Fa int 2309.Fn gzflush "gzFile file" "int flush" ; 2310.Xc 2311.Pp 2312The 2313.Fn gzflush 2314function flushes all pending output into the compressed file. 2315The parameter 2316.Fa flush 2317is as in the 2318.Fn deflate 2319function. 2320The return value is the 2321.Nm zlib 2322error number (see function 2323.Fn gzerror 2324below). 2325.Fn gzflush 2326returns 2327.Dv Z_OK 2328if the flush parameter is 2329.Dv Z_FINISH 2330and all output could be flushed. 2331.Pp 2332.Fn gzflush 2333should be called only when strictly necessary because it can 2334degrade compression. 2335.It Xo 2336.Fa z_off_t 2337.Fn gzseek "gzFile file" "z_off_t offset" "int whence" ; 2338.Xc 2339.Pp 2340Sets the starting position for the next 2341.Fn gzread 2342or 2343.Fn gzwrite 2344on the given compressed file. 2345The offset represents a number of bytes in the uncompressed data stream. 2346The whence parameter is defined as in 2347.Xr lseek 2 ; 2348the value 2349.Dv SEEK_END 2350is not supported. 2351.Pp 2352If the file is opened for reading, this function is emulated but can be 2353extremely slow. 2354If the file is opened for writing, only forward seeks are supported; 2355.Fn gzseek 2356then compresses a sequence of zeroes up to the new starting position. 2357.Pp 2358.Fn gzseek 2359returns the resulting offset location as measured in bytes from 2360the beginning of the uncompressed stream, or \-1 in case of error, 2361in particular if the file is opened for writing and the new starting position 2362would be before the current position. 2363.It Xo 2364.Fa int 2365.Fn gzrewind "gzFile file" ; 2366.Xc 2367.Pp 2368The 2369.Fn gzrewind 2370function rewinds the given 2371.Fa file . 2372This function is supported only for reading. 2373.Pp 2374gzrewind(file) is equivalent to (int)gzseek(file, 0L, SEEK_SET). 2375.It Xo 2376.Fa z_off_t 2377.Fn gztell "gzFile file" ; 2378.Xc 2379.Pp 2380The 2381.Fn gztell 2382function returns the starting position for the next 2383.Fn gzread 2384or 2385.Fn gzwrite 2386on the given compressed file. 2387This position represents a number of bytes in the uncompressed data stream. 2388.Pp 2389gztell(file) is equivalent to gzseek(file, 0L, SEEK_CUR). 2390.It Xo 2391.Fa int 2392.Fn gzeof "gzFile file" ; 2393.Xc 2394.Pp 2395The 2396.Fn gzeof 2397function returns 1 when 2398.Dv EOF 2399has previously been detected reading the given input stream, otherwise zero. 2400.It Xo 2401.Fa int 2402.Fn gzdirect "gzFile file" ; 2403.Xc 2404.Pp 2405The 2406.Fn gzdirect 2407function returns 1 if the file is being read directly 2408without compression; 2409otherwise it returns 0. 2410.It Xo 2411.Fa int 2412.Fn gzclose "gzFile file" ; 2413.Xc 2414.Pp 2415The 2416.Fn gzclose 2417function flushes all pending output if necessary, closes the compressed file 2418and deallocates all the (de)compression state. 2419The return value is the 2420.Nm zlib 2421error number (see function 2422.Fn gzerror 2423below). 2424.It Xo 2425.Fa const char * 2426.Fn gzerror "gzFile file" "int *errnum" ; 2427.Xc 2428.Pp 2429The 2430.Fn gzerror 2431function returns the error message for the last error which occurred on the 2432given compressed 2433.Fa file . 2434.Fa errnum 2435is set to the 2436.Nm zlib 2437error number. 2438If an error occurred in the file system and not in the compression library, 2439.Fa errnum 2440is set to 2441.Dv Z_ERRNO 2442and the application may consult errno to get the exact error code. 2443.It Xo 2444.Fa void 2445.Fn gzclearerr "gzFile file" 2446.Xc 2447Clears the error and end-of-file flags for 2448.Fa file . 2449This is analogous to the 2450.Fn clearerr 2451function in stdio. 2452This is useful for continuing to read a gzip file 2453that is being written concurrently. 2454.El 2455.Sh CHECKSUM FUNCTIONS 2456These functions are not related to compression but are exported 2457anyway because they might be useful in applications using the 2458compression library. 2459.Bl -tag -width Ds 2460.It Xo 2461.Fa uLong 2462.Fn adler32 "uLong adler" "const Bytef *buf" "uInt len" ; 2463.Xc 2464The 2465.Fn adler32 2466function updates a running Adler-32 checksum with the bytes buf[0..len-1] 2467and returns the updated checksum. 2468If 2469.Fa buf 2470is 2471.Dv NULL , 2472this function returns the required initial value for the checksum. 2473.Pp 2474An Adler-32 checksum is almost as reliable as a CRC32 but can be computed 2475much faster. 2476Usage example: 2477.Bd -unfilled -offset indent 2478uLong adler = adler32(0L, Z_NULL, 0); 2479 2480while (read_buffer(buffer, length) != EOF) { 2481adler = adler32(adler, buffer, length); 2482} 2483if (adler != original_adler) error(); 2484.Ed 2485.It Xo 2486.Fa uLong 2487.Fn adler32_combine "uLong adler1" "uLong adler2" "z_off_t len2" 2488.Xc 2489.Pp 2490The 2491.Fn adler32_combine 2492function combines two Adler-32 checksums into one. 2493For two sequences of bytes, seq1 and seq2 with lengths len1 and len2, 2494Adler-32 checksums are calculated for each, adler1 and adler2. 2495.Fn adler32_combine 2496returns the Adler-32 checksum of seq1 and seq2 concatenated, 2497requiring only adler1, adler2, and len2. 2498.It Xo 2499.Fa uLong 2500.Fn crc32 "uLong crc" "const Bytef *buf" "uInt len" ; 2501.Xc 2502.Pp 2503The 2504.Fn crc32 2505function updates a running CRC-32 with the bytes buf[0..len-1] 2506and returns the updated CRC-32. 2507If 2508.Fa buf 2509is 2510.Dv NULL , 2511this function returns the required initial value for the CRC. 2512Pre- and post-conditioning 2513.Pq one's complement 2514is performed within this function so it shouldn't be done by the application. 2515Usage example: 2516.Bd -unfilled -offset indent 2517uLong crc = crc32(0L, Z_NULL, 0); 2518 2519while (read_buffer(buffer, length) != EOF) { 2520crc = crc32(crc, buffer, length); 2521} 2522if (crc != original_crc) error(); 2523.Ed 2524.It Xo 2525.Fa uLong 2526.Fn crc32_combine "uLong crc1" "uLong crc2" "z_off_t len2" 2527.Xc 2528.Pp 2529The 2530.Fn crc32_combine 2531function combines two CRC-32 check values into one. 2532For two sequences of bytes, 2533seq1 and seq2 with lengths len1 and len2, 2534CRC-32 check values are calculated for each, crc1 and crc2. 2535.Fn crc32_combine 2536returns the CRC-32 check value of seq1 and seq2 concatenated, 2537requiring only crc1, crc2, and len2. 2538.El 2539.Sh STRUCTURES 2540.Bd -unfilled 2541struct internal_state; 2542 2543typedef struct z_stream_s { 2544 Bytef *next_in; /* next input byte */ 2545 uInt avail_in; /* number of bytes available at next_in */ 2546 off_t total_in; /* total nb of input bytes read so far */ 2547 2548 Bytef *next_out; /* next output byte should be put there */ 2549 uInt avail_out; /* remaining free space at next_out */ 2550 off_t total_out; /* total nb of bytes output so far */ 2551 2552 char *msg; /* last error message, NULL if no error */ 2553 struct internal_state FAR *state; /* not visible by applications */ 2554 2555 alloc_func zalloc; /* used to allocate the internal state */ 2556 free_func zfree; /* used to free the internal state */ 2557 voidpf opaque; /* private data object passed to zalloc and zfree*/ 2558 2559 int data_type; /* best guess about the data type: binary or text*/ 2560 uLong adler; /* adler32 value of the uncompressed data */ 2561 uLong reserved; /* reserved for future use */ 2562} z_stream; 2563 2564typedef z_stream FAR * z_streamp; 2565.Ed 2566.Bd -unfilled 2567/* 2568 gzip header information passed to and from zlib routines. 2569 See RFC 1952 for more details on the meanings of these fields. 2570*/ 2571typedef struct gz_header_s { 2572 int text; /* true if compressed data believed to be text */ 2573 uLong time; /* modification time */ 2574 int xflags; /*extra flags (not used when writing a gzip file)*/ 2575 int os; /* operating system */ 2576 Bytef *extra; /* pointer to extra field or Z_NULL if none */ 2577 uInt extra_len; /* extra field length (valid if extra != Z_NULL) */ 2578 uInt extra_max; /* space at extra (only when reading header) */ 2579 Bytef *name; /* pointer to zero-terminated file name or Z_NULL*/ 2580 uInt name_max; /* space at name (only when reading header) */ 2581 Bytef *comment; /* pointer to zero-terminated comment or Z_NULL */ 2582 uInt comm_max; /* space at comment (only when reading header) */ 2583 int hcrc; /* true if there was or will be a header crc */ 2584 int done; /* true when done reading gzip header (not used 2585 when writing a gzip file) */ 2586} gz_header; 2587 2588typedef gz_header FAR *gz_headerp; 2589.Ed 2590.Pp 2591The application must update 2592.Fa next_in 2593and 2594.Fa avail_in 2595when 2596.Fa avail_in 2597has dropped to zero. 2598It must update 2599.Fa next_out 2600and 2601.Fa avail_out 2602when 2603.Fa avail_out 2604has dropped to zero. 2605The application must initialize 2606.Fa zalloc , 2607.Fa zfree , 2608and 2609.Fa opaque 2610before calling the init function. 2611All other fields are set by the compression library 2612and must not be updated by the application. 2613.Pp 2614The 2615.Fa opaque 2616value provided by the application will be passed as the first 2617parameter for calls to 2618.Fn zalloc 2619and 2620.Fn zfree . 2621This can be useful for custom memory management. 2622The compression library attaches no meaning to the 2623.Fa opaque 2624value. 2625.Pp 2626.Fa zalloc 2627must return 2628.Dv Z_NULL 2629if there is not enough memory for the object. 2630If 2631.Nm zlib 2632is used in a multi-threaded application, 2633.Fa zalloc 2634and 2635.Fa zfree 2636must be thread safe. 2637.Pp 2638On 16-bit systems, the functions 2639.Fa zalloc 2640and 2641.Fa zfree 2642must be able to allocate exactly 65536 bytes, 2643but will not be required to allocate more than this if the symbol MAXSEG_64K 2644is defined (see 2645.In zconf.h ) . 2646.Pp 2647WARNING: On MSDOS, pointers returned by 2648.Fa zalloc 2649for objects of exactly 65536 bytes *must* have their offset normalized to zero. 2650The default allocation function provided by this library ensures this (see 2651.Pa zutil.c ) . 2652To reduce memory requirements and avoid any allocation of 64K objects, 2653at the expense of compression ratio, 2654compile the library with -DMAX_WBITS=14 (see 2655.In zconf.h ) . 2656.Pp 2657The fields 2658.Fa total_in 2659and 2660.Fa total_out 2661can be used for statistics or progress reports. 2662After compression, 2663.Fa total_in 2664holds the total size of the uncompressed data and may be saved for use 2665in the decompressor 2666(particularly if the decompressor wants to decompress everything 2667in a single step). 2668.Sh CONSTANTS 2669.Bd -unfilled 2670#define Z_NO_FLUSH 0 2671#define Z_PARTIAL_FLUSH 1 /* will be removed, use Z_SYNC_FLUSH instead */ 2672#define Z_SYNC_FLUSH 2 2673#define Z_FULL_FLUSH 3 2674#define Z_FINISH 4 2675#define Z_BLOCK 5 2676/* Allowed flush values; see deflate() and inflate() below for details */ 2677 2678#define Z_OK 0 2679#define Z_STREAM_END 1 2680#define Z_NEED_DICT 2 2681#define Z_ERRNO (-1) 2682#define Z_STREAM_ERROR (-2) 2683#define Z_DATA_ERROR (-3) 2684#define Z_MEM_ERROR (-4) 2685#define Z_BUF_ERROR (-5) 2686#define Z_VERSION_ERROR (-6) 2687/* Return codes for the compression/decompression functions. 2688 * Negative values are errors, 2689 * positive values are used for special but normal events. 2690 */ 2691 2692#define Z_NO_COMPRESSION 0 2693#define Z_BEST_SPEED 1 2694#define Z_BEST_COMPRESSION 9 2695#define Z_DEFAULT_COMPRESSION (-1) 2696/* compression levels */ 2697 2698#define Z_FILTERED 1 2699#define Z_HUFFMAN_ONLY 2 2700#define Z_RLE 3 2701#define Z_FIXED 4 2702#define Z_DEFAULT_STRATEGY 0 2703/* compression strategy; see deflateInit2() below for details */ 2704 2705#define Z_BINARY 0 2706#define Z_TEXT 1 2707#define Z_ASCII Z_TEXT /* for compatibility with 1.2.2 and earlier */ 2708#define Z_UNKNOWN 2 2709/* Possible values of the data_type field (though see inflate()) */ 2710 2711#define Z_DEFLATED 8 2712/* The deflate compression method 2713 * (the only one supported in this version) 2714*/ 2715 2716#define Z_NULL 0 /* for initializing zalloc, zfree, opaque */ 2717 2718#define zlib_version zlibVersion() 2719/* for compatibility with versions \*(Lt 1.0.2 */ 2720.Ed 2721.Sh VARIOUS HACKS 2722deflateInit and inflateInit are macros to allow checking the 2723.Nm zlib 2724version and the compiler's view of 2725.Fa z_stream . 2726.Bl -tag -width Ds 2727.It Xo 2728.Fa int 2729.Fn deflateInit_ "z_stream strm" "int level" "const char *version" "int stream_size" ; 2730.Xc 2731.It Xo 2732.Fa int 2733.Fn inflateInit_ "z_stream strm" "const char *version" "int stream_size" ; 2734.Xc 2735.It Xo 2736.Fa int 2737.Fo deflateInit2_ 2738.Fa "z_stream strm" 2739.Fa "int level" 2740.Fa "int method" 2741.Fa "int windowBits" 2742.Fa "int memLevel" 2743.Fa "int strategy" 2744.Fa "const char *version" 2745.Fa "int stream_size" 2746.Fc 2747.Xc 2748.It Xo 2749.Fa int 2750.Fn inflateInit2_ "z_stream strm" "int windowBits" "const char *version" "int stream_size" ; 2751.Xc 2752.It Xo 2753.Fa int 2754.Fn inflateBackInit_ "z_stream *strm" "int windowBits" "unsigned char FAR *window" "const char *version" "int stream_size" 2755.Xc 2756.It Xo 2757.Fa const char * 2758.Fn zError "int err" ; 2759.Xc 2760.It Xo 2761.Fa int 2762.Fn inflateSyncPoint "z_streamp z" ; 2763.Xc 2764.It Xo 2765.Fa const uLongf * 2766.Fn "get_crc_table" "void" ; 2767.Xc 2768.El 2769.Sh SEE ALSO 2770.Xr compress 1 , 2771.Xr gzip 1 2772.Sh STANDARDS 2773.Rs 2774.%A P. Deutsch 2775.%A J-L. Gailly 2776.%D May 1996 2777.%R RFC 1950 2778.%T ZLIB Compressed Data Format Specification version 3.3 2779.Re 2780.Pp 2781.Rs 2782.%A P. Deutsch 2783.%D May 1996 2784.%R RFC 1951 2785.%T DEFLATE Compressed Data Format Specification version 1.3 2786.Re 2787.Pp 2788.Rs 2789.%A P. Deutsch 2790.%D May 1996 2791.%R RFC 1952 2792.%T GZIP file format specification version 4.3 2793.Re 2794.Sh HISTORY 2795This manual page is based on an HTML version of 2796.In zlib.h 2797converted by 2798.An piaip Aq Mt piaip@csie.ntu.edu.tw 2799and was converted to mdoc format by the 2800.Ox 2801project. 2802.Sh AUTHORS 2803.An Jean-loup Gailly Aq Mt jloup@gzip.org 2804.An Mark Adler Aq Mt madler@alumni.caltech.edu 2805