package zlib

  1. Overview
  2. Docs
Legend:
Library
Module
Module type
Parameter
Class
Class type

Bindings to the zlib compression library providing deflate compression with or without zlib or gzip headers.

This library uses bigarrays as buffers and can therefore release the OCaml runtime during (de)compression, allowing other OCaml threads to continue.

  • author Christopher Zimmermann
type status =
  1. | Ok
    (*

    0

    *)
  2. | Stream_end
    (*

    1

    *)
  3. | Need_dict
    (*

    2

    *)
  4. | Buf_error
    (*

    3 (zlib -5)

    *)
  5. | Data_error of string
    (*

    0 (zlib -3)

    *)

Zlib return codes. Only non-fatal return codes are returned. Fatal error codes are translated to the standard exceptions Failure _, Invalid_argument _ or Out_of_memory.

type algo =
  1. | Deflated
    (*

    Compression algorithm. Only deflate is provided by current zlib.

    *)
type strategy =
  1. | Default_strategy
    (*

    0

    *)
  2. | Filtered
    (*

    1

    *)
  3. | Huffman_only
    (*

    2

    *)
  4. | RLE
    (*

    3

    *)
  5. | Fixed
    (*

    4

    *)

Compression strategy - see zlib manual for details.

type flush =
  1. | No_flush
    (*

    0

    *)
  2. | Partial_flush
    (*

    1

    *)
  3. | Sync_flush
    (*

    2

    *)
  4. | Full_flush
    (*

    3

    *)
  5. | Finish
    (*

    4

    *)
  6. | Block
    (*

    5

    *)
  7. | Trees
    (*

    6

    *)

The type of the flush parameter passed to flate. Use Finish when all input has been provided, otherwise use No_flush. For the other flush values see the zlib manual.

type data_type =
  1. | Binary
    (*

    0

    *)
  2. | Text
    (*

    1

    *)
  3. | Unknown
    (*

    2

    *)

Best guess of flate about the type of data being compressed.

type deflate
type inflate

Pseudo types to specify whether a zlib stream state is used to inflate or deflate.

type 'a state

Internal state

type 'a t = {
  1. state : 'a state;
  2. mutable in_buf : bigstring;
    (*

    bigstring input buffer

    *)
  3. mutable out_buf : bigstring;
    (*

    bigstring output buffer

    *)
  4. mutable in_ofs : int;
    (*

    offset into the input buffer

    *)
  5. mutable out_ofs : int;
    (*

    offset into the output buffer

    *)
  6. mutable in_len : int;
    (*

    Length of available input data

    *)
  7. mutable out_len : int;
    (*

    Length of available output data

    *)
  8. mutable in_total : int;
    (*

    Length of input data processed so far

    *)
  9. mutable out_total : int;
    (*

    Length of output data processed so far

    *)
  10. mutable data_type : int;
    (*

    For deflate streams a guess about the type of data is returned here: 0 for binary data, 1 for text and 2 for unknown.

    For inflate streams the number of unused bits in the last byte taken from the input stream is stored here. If flate just finished decoding the header or returned after an end-of-block code 128 is added. If flate is currentry decoding the last block 64 is added.

    *)
  11. mutable cksum : int32;
    (*

    The checksum of the decompressed data produced resp. consumed so far. When flate returns status.Need_dict the adler32 checksum of the required dictionary is returned here instead.

    *)
}

Record holding the internal state and input / output buffers of data as well as other data returned from the zlib inflate and deflate routines.

type header = {
  1. text : bool;
    (*

    Compressed data believed to be text?

    *)
  2. mtime : int32;
    (*

    mtime of compressed file. Set to zero if unknown.

    *)
  3. os : int;
    (*

    filesystem type on which the compressed file was stored. See RFC1952 for possible values.

    *)
  4. xflags : int;
    (*

    Extra flags according to RFC1952. For deflate compression method the compression level is stored here.

    *)
  5. extra : string option;
    (*

    Extra header field according to RFC1952.

    *)
  6. name : string option;
    (*

    Original file name of the compressed file translated to ISO 8859-1 (LATIN-1).

    *)
  7. comment : string option;
    (*

    File comment. According to RFC1952 only ISO 8859-1 (LATIN-1) characters are allowed. Linebreak is a single linefeed.

    *)
}

Record holding the data in a gzip header.

val create_inflate : ?window_bits:int -> unit -> inflate t

create_inflate () Creates zlib internal state and buffer description for decompression.

  • parameter window_bits

    the base 2 logarithm of the maximum window size. It should be in tha range 8..15 and greater or equal to the window_bits parameter used for compression. By default the zlib format is decoded. Use a negative value -8..-15 for raw deflate decompression without zlib or gzip header. Add 16 to window_bits to decode the gzip format. Add 32 to window_bits to decode zlib or gzip format with automatic header detection.

val create_deflate : ?level:int -> ?algo:algo -> ?window_bits:int -> ?memory:int -> ?strategy:strategy -> unit -> deflate t

create_deflate () Creates zlib internal state and buffer description for compression.

  • parameter level

    the compression level must be betweed -1 and 9. -1 selects default compression level, 1 gives best speed 9 gives best compression, anything in between is a compromise of speed/compression. 0 gives no compression at all.

  • parameter window_bits

    the base 2 logarithm of the maximum window size. It should be in tha range 8..15 and greater or equal to the window_bits parameter used for compression. Use a negative value -8..-15 for raw deflate compression without zlib or gzip header. Add 16 to window_bits to write a gzip header.

  • parameter memory

    selects how much memory to use for compression in the range 1..9. More memory means faster and better compression. A value of 9 uses 256kb, 8 128kb, 7 64kb...

  • parameter strategy

    See the zlib manual for details about this parameter.

val inflate_init : window_bits:int -> inflate state

inflate_init window_bits like create_inflate, but only creates the internal state.

val deflate_init : level:int -> algo:algo -> window_bits:int -> memory:int -> strategy:strategy -> deflate state

deflate_init level algo window_bits memory strategy like create_deflate, but only creates the internal state.

val deflate_bound : deflate state -> int -> int

deflate_bound state len calculates an upper bound on the size of the compressed data. This functions assumes the zlib format is used. The resulting compressed size might be larger than the returned bound when the gzip format is being used.

  • returns

    An upper bound on the compressed data when using the zlib format.

  • parameter len

    size of the data to be compressed.

val flate : 'a t -> flush -> status

flate buffers flush (de)compresses data from the provided input to the output buffers.

  • parameter buffers

    this record is documented above. It's fields are updated by this function.

  • parameter flush

    Whether and how the output should be flushed. See the type definition above and the zlib manual for details.

val inflate_set_dictionary : inflate state -> string -> status

inflate_set_dictionary state dict Sets a preset dictionary for decompression. Must be called after flate requested a dictionary by returning status.Need_dict; the cksum field of state will then contain the adler32 checksum of the required dictionary.

  • returns

    status.Data_error when the adler32 checksum of the provided dictionary doesn't match the requested checksum.

val deflate_set_dictionary : deflate state -> string -> int32

deflate_set_dictionary state dict Sets a preset dictionary for compression. When using the zlib format this needs to be called before the first call to flate. No dictionary may be used for the gzip format.

  • returns

    the adler32 checksum of the provided dictionary.

val get_header : inflate state -> header

get_header header Retrieve a header after a gzip header has been read by flate.

  • returns

    the header read by flate.

  • raises Failure

    "Zlib.get_header: Header not yet completed." if the header has not yet been completely read.

  • raises Not_found

    if not reading gzip format.

val set_header : deflate state -> header -> unit

set_header state header Provide a header when writing the gzip format. Must be called before any call to flate.

  • parameter header

    fields to be stored th the header. The header.xflags field is not used when compressing.

val reset : 'a t -> unit

reset buffers Prepares for a new stream of data to be (de)compressed. The parameters passed to inflate_init resp. deflate_init are left unchanged.

  • parameter buffers

    resets all fields to sane initial values and resets the internal state.

val get_data_type : deflate t -> data_type

get_data_type buffers gets the data type of the data being compressed.

  • returns

    Best guess on the data being compressed.

  • parameter buffers

    The buffers of the running compression.

val adler32 : int32 -> string -> int32

adler32 cksum buf Updates the running adler32 checksum

  • returns

    updated checksum.

  • parameter cksum

    The running adler32 checksum to be updated.

  • parameter buf

    The data with which to update the cksum.

val adler32_empty : int32

Initial value to be used with adler32