-
Notifications
You must be signed in to change notification settings - Fork 0
/
gzip.mli
122 lines (113 loc) · 6.67 KB
/
gzip.mli
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
(***********************************************************************)
(* *)
(* The CamlZip library *)
(* *)
(* Xavier Leroy, projet Cristal, INRIA Rocquencourt *)
(* *)
(* Copyright 2001 Institut National de Recherche en Informatique et *)
(* en Automatique. All rights reserved. This file is distributed *)
(* under the terms of the GNU Library General Public License, with *)
(* the special exception on linking described in file LICENSE. *)
(* *)
(***********************************************************************)
(* $Id: gzip.mli 18 2007-01-21 15:12:55Z xleroy $ *)
(** Reading and writing to/from [gzip] compressed files
This module provides functions to read and write compressed data
to/from files in [gzip] format. *)
(** {6 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: Pervasives.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 -> string -> 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 -> string -> 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 [Pervasives.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 [Pervasives.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. *)
(** {6 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 -> Pervasives.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 -> string -> 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 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 [Pervasives.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 [Pervasives.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. *)
(** {6 Error reporting} *)
exception Error of string
(** Exception raised by the functions above to signal errors during
compression or decompression, or ill-formed input files. *)