1 .TH FLATE 3
2 .SH NAME
3 deflateinit, deflate, deflatezlib, deflateblock, deflatezlibblock, inflateinit, inflate, inflatezlib, inflateblock, inflatezlibblock, flateerr, mkcrctab, blockcrc, adler32 \- deflate compression
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .br
9 .B #include <flate.h>
10 .PP
11 .ta \w'\fLulongmm'u +\w'\fL  'u
12 .PP
13 .B
14 int	deflateinit(void)
15 .PP
16 .B
17 int	deflate(void *wr, int (*w)(void*,void*,int),
18 .br
19 .B
20 		void *rr, int (*r)(void*,void*,int),
21 .br
22 .B
23 		int level, int debug)
24 .PP
25 .B
26 int	deflatezlib(void *wr, int (*w)(void*,void*,int),
27 .br
28 .B
29 		void *rr, int (*r)(void*,void*,int),
30 .br
31 .B
32 		int level, int debug)
33 .PP
34 .B
35 int	deflateblock(uchar *dst, int dsize,
36 .br
37 .B
38 		uchar *src, int ssize,
39 .br
40 .B
41 		int level, int debug)
42 .PP
43 .B
44 int	deflatezlibblock(uchar *dst, int dsize,
45 .br
46 .B
47 		uchar *src, int ssize,
48 .br
49 .B
50 		int level, int debug)
51 .PP
52 .B
53 int	inflateinit(void)
54 .PP
55 .B
56 int	inflate(void *wr, int (*w)(void*, void*, int),
57 .br
58 .B
59 		void *getr, int (*get)(void*))
60 .PP
61 .B
62 int	inflatezlib(void *wr, int (*w)(void*, void*, int),
63 .br
64 .B
65 		void *getr, int (*get)(void*))
66 .PP
67 .B
68 int	inflateblock(uchar *dst, int dsize,
69 .br
70 .B
71 		uchar *src, int ssize)
72 .PP
73 .B
74 int	inflatezlibblock(uchar *dst, int dsize,
75 .br
76 .B
77 		uchar *src, int ssize)
78 .PP
79 .B
80 char	*flateerr(int error)
81 .PP
82 .B
83 ulong	*mkcrctab(ulong poly)
84 .PP
85 .B
86 ulong	blockcrc(ulong *tab, ulong crc, void *buf, int n)
87 .PP
88 .B
89 ulong	adler32(ulong adler, void *buf, int n)
90 .SH DESCRIPTION
91 These routines compress and decompress data using the deflate compression algorithm,
92 which is used for most gzip, zip, and zlib files.
93 .PP
94 .I Deflate
95 compresses input data retrieved by calls to
96 .I r
97 with arguments
98 .IR rr ,
99 an input buffer, and a count of bytes to read.
100 .I R
101 should return the number of bytes read;
102 end of input is signaled by returning zero, an input error by
103 returning a negative number.
104 The compressed output is written to
105 .I w
106 with arguments
107 .IR wr ,
108 the output data, and the number of bytes to write.
109 .I W
110 should return the number of bytes written;
111 writing fewer than the requested number of bytes is an error.
112 .I Level
113 indicates the amount of computation deflate should do while compressing the data.
114 Higher
115 .I levels
116 usually take more time and produce smaller outputs.
117 Valid values are 1 to 9, inclusive; 6 is a good compromise.
118 If
119 .I debug
120 is non-zero, cryptic debugging information is produced on standard error.
121 .PP
122 .I Inflate
123 reverses the process, converting compressed data into uncompressed output.
124 Input is retrieved one byte at a time by calling
125 .I get
126 with the argument
127 .IR getr .
128 End of input of signaled by returning a negative value.
129 The uncompressed output is written to
130 .IR w ,
131 which has the same interface as for
132 .IR deflate .
133 .PP
134 .I
135 Deflateblock
136 and
137 .I inflateblock
138 operate on blocks of memory but are otherwise similar to
139 .I deflate
140 and
141 .IR inflate .
142 .PP
143 The zlib functions are similar, but operate on files with a zlib header and trailer.
144 .PP
145 .I Deflateinit
146 or
147 .I inflateinit
148 must be called once before any call to the corresponding routines.
149 .PP
150 If the above routines fail,
151 they return a negative number indicating the problem.
152 The possible values are
153 .IR FlateNoMem ,
154 .IR FlateInputFail ,
155 .IR FlateOutputFail ,
156 .IR FlateCorrupted ,
157 and 
158 .IR FlateInternal .
159 .I Flateerr
160 converts the number into a printable message.
161 .I FlateOk
162 is defined to be zero,
163 the successful return value for
164 .IR deflateinit ,
165 .IR deflate ,
166 .IR deflatezlib ,
167 .IR inflateinit ,
168 .IR inflate ,
169 and 
170 .IR inflatezlib .
171 The block functions return the number of bytes produced when they succeed.
172 .PP
173 .I Mkcrctab
174 allocates
175 (using
176 .MR malloc (3) ),
177 initializes, and returns a table for rapid computation of 32 bit CRC values using the polynomial
178 .IR poly .
179 .I Blockcrc
180 uses
181 .IR tab ,
182 a table returned by
183 .IR mkcrctab ,
184 to update
185 .I crc
186 for the
187 .I n
188 bytes of data in
189 .IR buf ,
190 and returns the new value.
191 .I Crc
192 should initially be zero.
193 .I Blockcrc
194 pre-conditions and post-conditions
195 .I crc
196 by ones complementation.
197 .PP
198 .I Adler32
199 updates the Adler 32-bit checksum of the
200 .I n
201 butes of data in
202 .IR buf.
203 The initial value of
204 .I adler
205 (that is, its value after seeing zero bytes) should be 1.
206 .SH SOURCE
207 .B \*9/src/libflate