src/utils/cdk/gzip.mli

   1 (***********************************************************************)
   2 (*                                                                     *)
   3 (*                         The CamlZip library                         *)
   4 (*                                                                     *)
   5 (*            Xavier Leroy, projet Cristal, INRIA Rocquencourt         *)
   6 (*                                                                     *)
   7 (*  Copyright 2001 Institut National de Recherche en Informatique et   *)
   8 (*  en Automatique.  All rights reserved.  This file is distributed    *)
   9 (*  under the terms of the GNU Library General Public License.         *)
  10 (*                                                                     *)
  11 (***********************************************************************)
  12
  13 (* $Id$ *)
  14
  15 (* Module [Gzip]: reading and writing to/from [gzip] compressed files *)
  16
  17 (* This module provides functions to read and write compressed data
  18    to/from files in [gzip] format. *)
  19
  20 (*** Reading from compressed files *)
  21
  22 type in_channel
  23         (* Abstract type representing a channel opened for reading
  24            from a compressed file. *)
  25 val open_in: string -> in_channel
  26         (* Open a compressed file for reading.  The argument is the file
  27            name. *)
  28 val open_in_chan: Pervasives.in_channel -> in_channel
  29         (* Open a compressed file for reading.  The argument is a
  30            regular file channel already opened on the compressed file. *)
  31 val input_char: in_channel -> char
  32         (* Uncompress one character from the given channel, and return it.
  33            Raise [End_of_file] if no more compressed data is available. *)
  34 val input_byte: in_channel -> int
  35         (* Same as [Gzip.input_char], but return the 8-bit integer representing
  36            the character.
  37            Raise [End_of_file] if no more compressed data is available. *)
  38 val input: in_channel -> string -> int -> int -> int
  39         (* [input ic buf pos len] uncompresses up to [len] characters
  40            from the given channel [ic],
  41            storing them in string [buf], starting at character number [pos].
  42            It returns the actual number of characters read, between 0 and
  43            [len] (inclusive).
  44            A return value of 0 means that the end of file was reached.
  45            A return value between 0 and [len] exclusive means that
  46            not all requested [len] characters were read, either because
  47            no more characters were available at that time, or because
  48            the implementation found it convenient to do a partial read;
  49            [input] must be called again to read the remaining characters,
  50            if desired.  (See also [Gzip.really_input] for reading
  51            exactly [len] characters.)
  52            Exception [Invalid_argument "Gzip.input"] is raised if
  53            [pos] and [len] do not designate a valid substring of [buf]. *)
  54 val really_input: in_channel -> string -> int -> int -> unit
  55         (* [really_input ic buf pos len] uncompresses [len] characters
  56            from the given channel, storing them in
  57            string [buf], starting at character number [pos].
  58            Raise [End_of_file] if fewer than [len] characters can be read.
  59            Raise [Invalid_argument "Gzip.input"] if
  60            [pos] and [len] do not designate a valid substring of [buf]. *)
  61 val close_in: in_channel -> unit
  62         (* Close the given input channel.  If the channel was created with
  63            [Gzip.open_in_chan], the underlying regular file channel
  64            (of type [Pervasives.in_channel]) is also closed.
  65            Do not apply any of the functions above to a closed channel. *)
  66 val dispose: in_channel -> unit
  67         (* Same as [Gzip.close_in], but does not close the underlying
  68            regular file channel (of type [Pervasives.in_channel]);
  69            just dispose of the resources associated with the decompression
  70            channel.  This can be useful if e.g. the underlying file channel
  71            is a network socket on which more (uncompressed) data
  72            is expected. *)
  73
  74 (*** Writing to compressed files *)
  75
  76 type out_channel
  77         (* Abstract type representing a channel opened for writing
  78            to a compressed file. *)
  79 val open_out: ?level:int -> string -> out_channel
  80         (* Open a compressed file for writing.  The argument is the file
  81            name.  The file is created if it does not exist, or
  82            truncated to zero length if it exists.
  83            The optional [level] argument (an integer between 1 and 9)
  84            indicates the compression level, with 1 being the weakest
  85            (but fastest) compression and 9 being the strongest
  86            (but slowest) compression.  The default level is 6
  87            (medium compression). *)
  88 val open_out_chan: ?level:int -> Pervasives.out_channel -> out_channel
  89         (* Open a compressed file for writing.  The argument is a
  90            regular file channel already opened on the compressed file.
  91            The optional [level] argument sets the compression level
  92            as documented for [Gzip.open_out]. *)
  93 val output_char: out_channel -> char -> unit
  94         (* Output one character to the given compressed channel. *)
  95 val output_byte: out_channel -> int -> unit
  96         (* Same as [Gzip.output_char], but the output character is given
  97            by its code.  The given integer is taken modulo 256. *)
  98 val output: out_channel -> string -> int -> int -> unit
  99         (* [output oc buf pos len] compresses and writes [len] characters
 100            from string [buf], starting at offset [pos], and writes the
 101            compressed data to the channel [oc].
 102            Raise [Invalid_argument "Gzip.output"] if
 103            [pos] and [len] do not designate a valid substring of [buf]. *)
 104 val close_out: out_channel -> unit
 105         (* Close the given output channel.  If the channel was created with
 106            [Gzip.open_out_chan], the underlying regular file channel
 107            (of type [Pervasives.out_channel]) is also closed.
 108            Do not apply any of the functions above to a closed channel. *)
 109 val flush: out_channel -> unit
 110         (* Same as [Gzip.close_out], but do not close the underlying
 111            regular file channel (of type [Pervasives.out_channel]);
 112            just flush all pending compressed data and
 113            dispose of the resources associated with the compression
 114            channel.  This can be useful if e.g. the underlying file channel
 115            is a network socket on which more data is to be sent. *)
 116
 117 (*** Error reporting *)
 118
 119 exception Error of string
 120         (* Exception raised by the functions above to signal errors during
 121            compression or decompression, or ill-formed input files. *)