aboutsummaryrefslogtreecommitdiff
path: root/man/man3/flate.3
blob: 7557487333bd3e9f825694706c4f57f897dd5bb2 (plain)
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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
.TH FLATE 3
.SH NAME
deflateinit, deflate, deflatezlib, deflateblock, deflatezlibblock, inflateinit, inflate, inflatezlib, inflateblock, inflatezlibblock, flateerr, mkcrctab, blockcrc, adler32 \- deflate compression
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <flate.h>
.PP
.ta \w'ulongmm'u
.PP
.B
int	deflateinit(void)
.PP
.B
int	deflate(void *wr, int (*w)(void*,void*,int),
.br
.B
	void *rr, int (*r)(void*,void*,int),
.br
.B
	int level, int debug)
.PP
.B
int	deflatezlib(void *wr, int (*w)(void*,void*,int),
.br
.B
	void *rr, int (*r)(void*,void*,int),
.br
.B
	int level, int debug)
.PP
.B
int	deflateblock(uchar *dst, int dsize,
.br
.B
	uchar *src, int ssize,
.br
.B
	int level, int debug)
.PP
.B
int	deflatezlibblock(uchar *dst, int dsize,
.br
.B
	uchar *src, int ssize,
.br
.B
	int level, int debug)
.PP
.B
int	inflateinit(void)
.PP
.B
int	inflate(void *wr, int (*w)(void*, void*, int),
.br
.B
	void *getr, int (*get)(void*))
.PP
.B
int	inflatezlib(void *wr, int (*w)(void*, void*, int),
.br
.B
	void *getr, int (*get)(void*))
.PP
.B
int	inflateblock(uchar *dst, int dsize,
.br
.B
	uchar *src, int ssize)
.PP
.B
int	inflatezlibblock(uchar *dst, int dsize,
.br
.B
	uchar *src, int ssize)
.PP
.B
char	*flateerr(int error)
.PP
.B
ulong	*mkcrctab(ulong poly)
.PP
.B
ulong	blockcrc(ulong *tab, ulong crc, void *buf, int n)
.PP
.B
ulong	adler32(ulong adler, void *buf, int n)
.SH DESCRIPTION
These routines compress and decompress data using the deflate compression algorithm,
which is used for most gzip, zip, and zlib files.
.PP
.I Deflate
compresses input data retrieved by calls to
.I r
with arguments
.IR rr ,
an input buffer, and a count of bytes to read.
.I R
should return the number of bytes read;
end of input is signaled by returning zero, an input error by
returning a negative number.
The compressed output is written to
.I w
with arguments
.IR wr ,
the output data, and the number of bytes to write.
.I W
should return the number of bytes written;
writing fewer than the requested number of bytes is an error.
.I Level
indicates the amount of computation deflate should do while compressing the data.
Higher
.I levels
usually take more time and produce smaller outputs.
Valid values are 1 to 9, inclusive; 6 is a good compromise.
If
.I debug
is non-zero, cryptic debugging information is produced on standard error.
.PP
.I Inflate
reverses the process, converting compressed data into uncompressed output.
Input is retrieved one byte at a time by calling
.I get
with the argument
.IR getr .
End of input of signaled by returning a negative value.
The uncompressed output is written to
.IR w ,
which has the same interface as for
.IR deflate .
.PP
.I
Deflateblock
and
.I inflateblock
operate on blocks of memory but are otherwise similar to
.I deflate
and
.IR inflate .
.PP
The zlib functions are similar, but operate on files with a zlib header and trailer.
.PP
.I Deflateinit
or
.I inflateinit
must be called once before any call to the corresponding routines.
.PP
If the above routines fail,
they return a negative number indicating the problem.
The possible values are
.IR FlateNoMem ,
.IR FlateInputFail ,
.IR FlateOutputFail ,
.IR FlateCorrupted ,
and 
.IR FlateInternal .
.I Flateerr
converts the number into a printable message.
.I FlateOk
is defined to be zero,
the successful return value for
.IR deflateinit ,
.IR deflate ,
.IR deflatezlib ,
.IR inflateinit ,
.IR inflate ,
and 
.IR inflatezlib .
The block functions return the number of bytes produced when they succeed.
.PP
.I Mkcrctab
allocates
(using
.IR malloc (3)),
initializes, and returns a table for rapid computation of 32 bit CRC values using the polynomial
.IR poly .
.I Blockcrc
uses
.IR tab ,
a table returned by
.IR mkcrctab ,
to update
.I crc
for the
.I n
bytes of data in
.IR buf ,
and returns the new value.
.I Crc
should initially be zero.
.I Blockcrc
pre-conditions and post-conditions
.I crc
by ones complementation.
.PP
.I Adler32
updates the Adler 32-bit checksum of the
.I n
butes of data in
.IR buf.
The initial value of
.I adler
(that is, its value after seeing zero bytes) should be 1.
.SH SOURCE
.B /sys/src/libflate