Module Gzip

module Gzip: sig .. end

Reading and writing to/from gzip compressed files

This module provides functions to read and write compressed data to/from files in gzip format.

Reading from compressed files

type in_channel

Abstract type representing a channel opened for reading from a compressed file.

val open_in : string -> in_channel

Open a compressed file for reading. The argument is the file name.

val open_in_chan : Stdlib.in_channel -> in_channel

Open a compressed file for reading. The argument is a regular file channel already opened on the compressed file.

val input_char : in_channel -> char

Uncompress one character from the given channel, and return it. Raise End_of_file if no more compressed data is available.

val input_byte : in_channel -> int

Same as Gzip.input_char, but return the 8-bit integer representing the character. Raise End_of_file if no more compressed data is available.

val input : in_channel -> bytes -> int -> int -> int

input ic buf pos len uncompresses up to len characters from the given channel ic, storing them in string buf, starting at character number pos. It returns the actual number of characters read, between 0 and len (inclusive). A return value of 0 means that the end of file was reached. A return value between 0 and len exclusive means that not all requested len characters were read, either because no more characters were available at that time, or because the implementation found it convenient to do a partial read; input must be called again to read the remaining characters, if desired. (See also Gzip.really_input for reading exactly len characters.) Exception Invalid_argument "Gzip.input" is raised if pos and len do not designate a valid substring of buf.

val really_input : in_channel -> bytes -> int -> int -> unit

really_input ic buf pos len uncompresses len characters from the given channel, storing them in string buf, starting at character number pos. Raise End_of_file if fewer than len characters can be read. Raise Invalid_argument "Gzip.input" if pos and len do not designate a valid substring of buf.

val close_in : in_channel -> unit

Close the given input channel. If the channel was created with Gzip.open_in_chan, the underlying regular file channel (of type Stdlib.in_channel) is also closed. Do not apply any of the functions above to a closed channel.

val dispose : in_channel -> unit

Same as Gzip.close_in, but does not close the underlying regular file channel (of type Stdlib.in_channel); just dispose of the resources associated with the decompression channel. This can be useful if e.g. the underlying file channel is a network socket on which more (uncompressed) data is expected.

Writing to compressed files

type out_channel

Abstract type representing a channel opened for writing to a compressed file.

val open_out : ?level:int -> string -> out_channel

Open a compressed file for writing. The argument is the file name. The file is created if it does not exist, or truncated to zero length if it exists. The optional level argument (an integer between 1 and 9) indicates the compression level, with 1 being the weakest (but fastest) compression and 9 being the strongest (but slowest) compression. The default level is 6 (medium compression).

val open_out_chan : ?level:int -> Stdlib.out_channel -> out_channel

Open a compressed file for writing. The argument is a regular file channel already opened on the compressed file. The optional level argument sets the compression level as documented for Gzip.open_out.

val output_char : out_channel -> char -> unit

Output one character to the given compressed channel.

val output_byte : out_channel -> int -> unit

Same as Gzip.output_char, but the output character is given by its code. The given integer is taken modulo 256.

val output : out_channel -> bytes -> int -> int -> unit

output oc buf pos len compresses and writes len characters from string buf, starting at offset pos, and writes the compressed data to the channel oc. Raise Invalid_argument "Gzip.output" if pos and len do not designate a valid substring of buf.

val output_substring : out_channel -> string -> int -> int -> unit

Same as output, but takes a string as argument instead of a byte sequence.

Since 1.06

val close_out : out_channel -> unit

Close the given output channel. If the channel was created with Gzip.open_out_chan, the underlying regular file channel (of type Stdlib.out_channel) is also closed. Do not apply any of the functions above to a closed channel.

val flush : out_channel -> unit

Same as Gzip.close_out, but do not close the underlying regular file channel (of type Stdlib.out_channel); just flush all pending compressed data and dispose of the resources associated with the compression channel. This can be useful if e.g. the underlying file channel is a network socket on which more data is to be sent.

val flush_continue : out_channel -> unit

Flush all pending compressed data through both the compression channel and the underlying regular file channel, but keep both channels open to accept further data.

Error reporting

exception Error of string

Exception raised by the functions above to signal errors during compression or decompression, or ill-formed input files.