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