Fossil SCM

Merge recent enhancements from trunk

drh 2017-03-10 01:44 optimize-pragma merge

Commit 41d43ec6b93fcf3879fa427d6c6ca6b570a3544d

Parent f32c36e58aaf53f…

10 files changed -209 -630 -972 -687 -103 +4 -2 +1 -1 +3 -3 +3 +1 -1

- compat/zlib/doc/algorithm.txt - compat/zlib/doc/rfc1950.txt - compat/zlib/doc/rfc1951.txt - compat/zlib/doc/rfc1952.txt - compat/zlib/doc/txtvsbin.txt ~ src/checkin.c ~ src/hname.c ~ src/sha3.c ~ src/sqlcmd.c ~ src/wiki.c

D compat/zlib/doc/algorithm.txt

-209

		--- a/compat/zlib/doc/algorithm.txt
		+++ b/compat/zlib/doc/algorithm.txt
		@@ -1,209 +0,0 @@
1		-1. Compression algorithm (deflate)
2		-
3		-The deflation algorithm used by gzip (also zip and zlib) is a variation of
4		-LZ77 (Lempel-Ziv 1977, see reference below). It finds duplicated strings in
5		-the input data. The second occurrence of a string is replaced by a
6		-pointer to the previous string, in the form of a pair (distance,
7		-length). Distances are limited to 32K bytes, and lengths are limited
8		-to 258 bytes. When a string does not occur anywhere in the previous
9		-32K bytes, it is emitted as a sequence of literal bytes. (In this
10		-description, `string' must be taken as an arbitrary sequence of bytes,
11		-and is not restricted to printable characters.)
12		-
13		-Literals or match lengths are compressed with one Huffman tree, and
14		-match distances are compressed with another tree. The trees are stored
15		-in a compact form at the start of each block. The blocks can have any
16		-size (except that the compressed data for one block must fit in
17		-available memory). A block is terminated when deflate() determines that
18		-it would be useful to start another block with fresh trees. (This is
19		-somewhat similar to the behavior of LZW-based _compress_.)
20		-
21		-Duplicated strings are found using a hash table. All input strings of
22		-length 3 are inserted in the hash table. A hash index is computed for
23		-the next 3 bytes. If the hash chain for this index is not empty, all
24		-strings in the chain are compared with the current input string, and
25		-the longest match is selected.
26		-
27		-The hash chains are searched starting with the most recent strings, to
28		-favor small distances and thus take advantage of the Huffman encoding.
29		-The hash chains are singly linked. There are no deletions from the
30		-hash chains, the algorithm simply discards matches that are too old.
31		-
32		-To avoid a worst-case situation, very long hash chains are arbitrarily
33		-truncated at a certain length, determined by a runtime option (level
34		-parameter of deflateInit). So deflate() does not always find the longest
35		-possible match but generally finds a match which is long enough.
36		-
37		-deflate() also defers the selection of matches with a lazy evaluation
38		-mechanism. After a match of length N has been found, deflate() searches for
39		-a longer match at the next input byte. If a longer match is found, the
40		-previous match is truncated to a length of one (thus producing a single
41		-literal byte) and the process of lazy evaluation begins again. Otherwise,
42		-the original match is kept, and the next match search is attempted only N
43		-steps later.
44		-
45		-The lazy match evaluation is also subject to a runtime parameter. If
46		-the current match is long enough, deflate() reduces the search for a longer
47		-match, thus speeding up the whole process. If compression ratio is more
48		-important than speed, deflate() attempts a complete second search even if
49		-the first match is already long enough.
50		-
51		-The lazy match evaluation is not performed for the fastest compression
52		-modes (level parameter 1 to 3). For these fast modes, new strings
53		-are inserted in the hash table only when no match was found, or
54		-when the match is not too long. This degrades the compression ratio
55		-but saves time since there are both fewer insertions and fewer searches.
56		-
57		-
58		-2. Decompression algorithm (inflate)
59		-
60		-2.1 Introduction
61		-
62		-The key question is how to represent a Huffman code (or any prefix code) so
63		-that you can decode fast. The most important characteristic is that shorter
64		-codes are much more common than longer codes, so pay attention to decoding the
65		-short codes fast, and let the long codes take longer to decode.
66		-
67		-inflate() sets up a first level table that covers some number of bits of
68		-input less than the length of longest code. It gets that many bits from the
69		-stream, and looks it up in the table. The table will tell if the next
70		-code is that many bits or less and how many, and if it is, it will tell
71		-the value, else it will point to the next level table for which inflate()
72		-grabs more bits and tries to decode a longer code.
73		-
74		-How many bits to make the first lookup is a tradeoff between the time it
75		-takes to decode and the time it takes to build the table. If building the
76		-table took no time (and if you had infinite memory), then there would only
77		-be a first level table to cover all the way to the longest code. However,
78		-building the table ends up taking a lot longer for more bits since short
79		-codes are replicated many times in such a table. What inflate() does is
80		-simply to make the number of bits in the first table a variable, and then
81		-to set that variable for the maximum speed.
82		-
83		-For inflate, which has 286 possible codes for the literal/length tree, the size
84		-of the first table is nine bits. Also the distance trees have 30 possible
85		-values, and the size of the first table is six bits. Note that for each of
86		-those cases, the table ended up one bit longer than the ``average'' code
87		-length, i.e. the code length of an approximately flat code which would be a
88		-little more than eight bits for 286 symbols and a little less than five bits
89		-for 30 symbols.
90		-
91		-
92		-2.2 More details on the inflate table lookup
93		-
94		-Ok, you want to know what this cleverly obfuscated inflate tree actually
95		-looks like. You are correct that it's not a Huffman tree. It is simply a
96		-lookup table for the first, let's say, nine bits of a Huffman symbol. The
97		-symbol could be as short as one bit or as long as 15 bits. If a particular
98		-symbol is shorter than nine bits, then that symbol's translation is duplicated
99		-in all those entries that start with that symbol's bits. For example, if the
100		-symbol is four bits, then it's duplicated 32 times in a nine-bit table. If a
101		-symbol is nine bits long, it appears in the table once.
102		-
103		-If the symbol is longer than nine bits, then that entry in the table points
104		-to another similar table for the remaining bits. Again, there are duplicated
105		-entries as needed. The idea is that most of the time the symbol will be short
106		-and there will only be one table look up. (That's whole idea behind data
107		-compression in the first place.) For the less frequent long symbols, there
108		-will be two lookups. If you had a compression method with really long
109		-symbols, you could have as many levels of lookups as is efficient. For
110		-inflate, two is enough.
111		-
112		-So a table entry either points to another table (in which case nine bits in
113		-the above example are gobbled), or it contains the translation for the symbol
114		-and the number of bits to gobble. Then you start again with the next
115		-ungobbled bit.
116		-
117		-You may wonder: why not just have one lookup table for how ever many bits the
118		-longest symbol is? The reason is that if you do that, you end up spending
119		-more time filling in duplicate symbol entries than you do actually decoding.
120		-At least for deflate's output that generates new trees every several 10's of
121		-kbytes. You can imagine that filling in a 2^15 entry table for a 15-bit code
122		-would take too long if you're only decoding several thousand symbols. At the
123		-other extreme, you could make a new table for every bit in the code. In fact,
124		-that's essentially a Huffman tree. But then you spend too much time
125		-traversing the tree while decoding, even for short symbols.
126		-
127		-So the number of bits for the first lookup table is a trade of the time to
128		-fill out the table vs. the time spent looking at the second level and above of
129		-the table.
130		-
131		-Here is an example, scaled down:
132		-
133		-The code being decoded, with 10 symbols, from 1 to 6 bits long:
134		-
135		-A: 0
136		-B: 10
137		-C: 1100
138		-D: 11010
139		-E: 11011
140		-F: 11100
141		-G: 11101
142		-H: 11110
143		-I: 111110
144		-J: 111111
145		-
146		-Let's make the first table three bits long (eight entries):
147		-
148		-000: A,1
149		-001: A,1
150		-010: A,1
151		-011: A,1
152		-100: B,2
153		-101: B,2
154		-110: -> table X (gobble 3 bits)
155		-111: -> table Y (gobble 3 bits)
156		-
157		-Each entry is what the bits decode as and how many bits that is, i.e. how
158		-many bits to gobble. Or the entry points to another table, with the number of
159		-bits to gobble implicit in the size of the table.
160		-
161		-Table X is two bits long since the longest code starting with 110 is five bits
162		-long:
163		-
164		-00: C,1
165		-01: C,1
166		-10: D,2
167		-11: E,2
168		-
169		-Table Y is three bits long since the longest code starting with 111 is six
170		-bits long:
171		-
172		-000: F,2
173		-001: F,2
174		-010: G,2
175		-011: G,2
176		-100: H,2
177		-101: H,2
178		-110: I,3
179		-111: J,3
180		-
181		-So what we have here are three tables with a total of 20 entries that had to
182		-be constructed. That's compared to 64 entries for a single table. Or
183		-compared to 16 entries for a Huffman tree (six two entry tables and one four
184		-entry table). Assuming that the code ideally represents the probability of
185		-the symbols, it takes on the average 1.25 lookups per symbol. That's compared
186		-to one lookup for the single table, or 1.66 lookups per symbol for the
187		-Huffman tree.
188		-
189		-There, I think that gives you a picture of what's going on. For inflate, the
190		-meaning of a particular symbol is often more than just a letter. It can be a
191		-byte (a "literal"), or it can be either a length or a distance which
192		-indicates a base value and a number of bits to fetch after the code that is
193		-added to the base value. Or it might be the special end-of-block code. The
194		-data structures created in inftrees.c try to encode all that information
195		-compactly in the tables.
196		-
197		-
198		-Jean-loup Gailly Mark Adler
199		-[email protected] [email protected]
200		-
201		-
202		-References:
203		-
204		-[LZ77] Ziv J., Lempel A., ``A Universal Algorithm for Sequential Data
205		-Compression,'' IEEE Transactions on Information Theory, Vol. 23, No. 3,
206		-pp. 337-343.
207		-
208		-``DEFLATE Compressed Data Format Specification'' available in
209		-http://tools.ietf.org/html/rfc1951

	--- a/compat/zlib/doc/algorithm.txt
	+++ b/compat/zlib/doc/algorithm.txt
	@@ -1,209 +0,0 @@
1	1. Compression algorithm (deflate)
2
3	The deflation algorithm used by gzip (also zip and zlib) is a variation of
4	LZ77 (Lempel-Ziv 1977, see reference below). It finds duplicated strings in
5	the input data. The second occurrence of a string is replaced by a
6	pointer to the previous string, in the form of a pair (distance,
7	length). Distances are limited to 32K bytes, and lengths are limited
8	to 258 bytes. When a string does not occur anywhere in the previous
9	32K bytes, it is emitted as a sequence of literal bytes. (In this
10	description, `string' must be taken as an arbitrary sequence of bytes,
11	and is not restricted to printable characters.)
12
13	Literals or match lengths are compressed with one Huffman tree, and
14	match distances are compressed with another tree. The trees are stored
15	in a compact form at the start of each block. The blocks can have any
16	size (except that the compressed data for one block must fit in
17	available memory). A block is terminated when deflate() determines that
18	it would be useful to start another block with fresh trees. (This is
19	somewhat similar to the behavior of LZW-based _compress_.)
20
21	Duplicated strings are found using a hash table. All input strings of
22	length 3 are inserted in the hash table. A hash index is computed for
23	the next 3 bytes. If the hash chain for this index is not empty, all
24	strings in the chain are compared with the current input string, and
25	the longest match is selected.
26
27	The hash chains are searched starting with the most recent strings, to
28	favor small distances and thus take advantage of the Huffman encoding.
29	The hash chains are singly linked. There are no deletions from the
30	hash chains, the algorithm simply discards matches that are too old.
31
32	To avoid a worst-case situation, very long hash chains are arbitrarily
33	truncated at a certain length, determined by a runtime option (level
34	parameter of deflateInit). So deflate() does not always find the longest
35	possible match but generally finds a match which is long enough.
36
37	deflate() also defers the selection of matches with a lazy evaluation
38	mechanism. After a match of length N has been found, deflate() searches for
39	a longer match at the next input byte. If a longer match is found, the
40	previous match is truncated to a length of one (thus producing a single
41	literal byte) and the process of lazy evaluation begins again. Otherwise,
42	the original match is kept, and the next match search is attempted only N
43	steps later.
44
45	The lazy match evaluation is also subject to a runtime parameter. If
46	the current match is long enough, deflate() reduces the search for a longer
47	match, thus speeding up the whole process. If compression ratio is more
48	important than speed, deflate() attempts a complete second search even if
49	the first match is already long enough.
50
51	The lazy match evaluation is not performed for the fastest compression
52	modes (level parameter 1 to 3). For these fast modes, new strings
53	are inserted in the hash table only when no match was found, or
54	when the match is not too long. This degrades the compression ratio
55	but saves time since there are both fewer insertions and fewer searches.
56
57
58	2. Decompression algorithm (inflate)
59
60	2.1 Introduction
61
62	The key question is how to represent a Huffman code (or any prefix code) so
63	that you can decode fast. The most important characteristic is that shorter
64	codes are much more common than longer codes, so pay attention to decoding the
65	short codes fast, and let the long codes take longer to decode.
66
67	inflate() sets up a first level table that covers some number of bits of
68	input less than the length of longest code. It gets that many bits from the
69	stream, and looks it up in the table. The table will tell if the next
70	code is that many bits or less and how many, and if it is, it will tell
71	the value, else it will point to the next level table for which inflate()
72	grabs more bits and tries to decode a longer code.
73
74	How many bits to make the first lookup is a tradeoff between the time it
75	takes to decode and the time it takes to build the table. If building the
76	table took no time (and if you had infinite memory), then there would only
77	be a first level table to cover all the way to the longest code. However,
78	building the table ends up taking a lot longer for more bits since short
79	codes are replicated many times in such a table. What inflate() does is
80	simply to make the number of bits in the first table a variable, and then
81	to set that variable for the maximum speed.
82
83	For inflate, which has 286 possible codes for the literal/length tree, the size
84	of the first table is nine bits. Also the distance trees have 30 possible
85	values, and the size of the first table is six bits. Note that for each of
86	those cases, the table ended up one bit longer than the ``average'' code
87	length, i.e. the code length of an approximately flat code which would be a
88	little more than eight bits for 286 symbols and a little less than five bits
89	for 30 symbols.
90
91
92	2.2 More details on the inflate table lookup
93
94	Ok, you want to know what this cleverly obfuscated inflate tree actually
95	looks like. You are correct that it's not a Huffman tree. It is simply a
96	lookup table for the first, let's say, nine bits of a Huffman symbol. The
97	symbol could be as short as one bit or as long as 15 bits. If a particular
98	symbol is shorter than nine bits, then that symbol's translation is duplicated
99	in all those entries that start with that symbol's bits. For example, if the
100	symbol is four bits, then it's duplicated 32 times in a nine-bit table. If a
101	symbol is nine bits long, it appears in the table once.
102
103	If the symbol is longer than nine bits, then that entry in the table points
104	to another similar table for the remaining bits. Again, there are duplicated
105	entries as needed. The idea is that most of the time the symbol will be short
106	and there will only be one table look up. (That's whole idea behind data
107	compression in the first place.) For the less frequent long symbols, there
108	will be two lookups. If you had a compression method with really long
109	symbols, you could have as many levels of lookups as is efficient. For
110	inflate, two is enough.
111
112	So a table entry either points to another table (in which case nine bits in
113	the above example are gobbled), or it contains the translation for the symbol
114	and the number of bits to gobble. Then you start again with the next
115	ungobbled bit.
116
117	You may wonder: why not just have one lookup table for how ever many bits the
118	longest symbol is? The reason is that if you do that, you end up spending
119	more time filling in duplicate symbol entries than you do actually decoding.
120	At least for deflate's output that generates new trees every several 10's of
121	kbytes. You can imagine that filling in a 2^15 entry table for a 15-bit code
122	would take too long if you're only decoding several thousand symbols. At the
123	other extreme, you could make a new table for every bit in the code. In fact,
124	that's essentially a Huffman tree. But then you spend too much time
125	traversing the tree while decoding, even for short symbols.
126
127	So the number of bits for the first lookup table is a trade of the time to
128	fill out the table vs. the time spent looking at the second level and above of
129	the table.
130
131	Here is an example, scaled down:
132
133	The code being decoded, with 10 symbols, from 1 to 6 bits long:
134
135	A: 0
136	B: 10
137	C: 1100
138	D: 11010
139	E: 11011
140	F: 11100
141	G: 11101
142	H: 11110
143	I: 111110
144	J: 111111
145
146	Let's make the first table three bits long (eight entries):
147
148	000: A,1
149	001: A,1
150	010: A,1
151	011: A,1
152	100: B,2
153	101: B,2
154	110: -> table X (gobble 3 bits)
155	111: -> table Y (gobble 3 bits)
156
157	Each entry is what the bits decode as and how many bits that is, i.e. how
158	many bits to gobble. Or the entry points to another table, with the number of
159	bits to gobble implicit in the size of the table.
160
161	Table X is two bits long since the longest code starting with 110 is five bits
162	long:
163
164	00: C,1
165	01: C,1
166	10: D,2
167	11: E,2
168
169	Table Y is three bits long since the longest code starting with 111 is six
170	bits long:
171
172	000: F,2
173	001: F,2
174	010: G,2
175	011: G,2
176	100: H,2
177	101: H,2
178	110: I,3
179	111: J,3
180
181	So what we have here are three tables with a total of 20 entries that had to
182	be constructed. That's compared to 64 entries for a single table. Or
183	compared to 16 entries for a Huffman tree (six two entry tables and one four
184	entry table). Assuming that the code ideally represents the probability of
185	the symbols, it takes on the average 1.25 lookups per symbol. That's compared
186	to one lookup for the single table, or 1.66 lookups per symbol for the
187	Huffman tree.
188
189	There, I think that gives you a picture of what's going on. For inflate, the
190	meaning of a particular symbol is often more than just a letter. It can be a
191	byte (a "literal"), or it can be either a length or a distance which
192	indicates a base value and a number of bits to fetch after the code that is
193	added to the base value. Or it might be the special end-of-block code. The
194	data structures created in inftrees.c try to encode all that information
195	compactly in the tables.
196
197
198	Jean-loup Gailly Mark Adler
199	[email protected] [email protected]
200
201
202	References:
203
204	[LZ77] Ziv J., Lempel A., ``A Universal Algorithm for Sequential Data
205	Compression,'' IEEE Transactions on Information Theory, Vol. 23, No. 3,
206	pp. 337-343.
207
208	``DEFLATE Compressed Data Format Specification'' available in
209	http://tools.ietf.org/html/rfc1951

	--- a/compat/zlib/doc/algorithm.txt
	+++ b/compat/zlib/doc/algorithm.txt
	@@ -1,209 +0,0 @@

D compat/zlib/doc/rfc1950.txt

-630

		--- a/compat/zlib/doc/rfc1950.txt
		+++ b/compat/zlib/doc/rfc1950.txt
		@@ -1,630 +0,0 @@
1		-
2		-
3		-
4		-
5		-
6		-
7		-Network Working Group P. Deutsch
8		-Request for Comments: 1950 Aladdin Enterprises
9		-Category: Informational J-L. Gailly
10		- Info-ZIP
11		- May 1996
12		-
13		-
14		- ZLIB Compressed Data Format Specification version 3.3
15		-
16		-Status of This Memo
17		-
18		- This memo provides information for the Internet community. This memo
19		- does not specify an Internet standard of any kind. Distribution of
20		- this memo is unlimited.
21		-
22		-IESG Note:
23		-
24		- The IESG takes no position on the validity of any Intellectual
25		- Property Rights statements contained in this document.
26		-
27		-Notices
28		-
29		- Copyright (c) 1996 L. Peter Deutsch and Jean-Loup Gailly
30		-
31		- Permission is granted to copy and distribute this document for any
32		- purpose and without charge, including translations into other
33		- languages and incorporation into compilations, provided that the
34		- copyright notice and this notice are preserved, and that any
35		- substantive changes or deletions from the original are clearly
36		- marked.
37		-
38		- A pointer to the latest version of this and related documentation in
39		- HTML format can be found at the URL
40		- <ftp://ftp.uu.net/graphics/png/documents/zlib/zdoc-index.html>.
41		-
42		-Abstract
43		-
44		- This specification defines a lossless compressed data format. The
45		- data can be produced or consumed, even for an arbitrarily long
46		- sequentially presented input data stream, using only an a priori
47		- bounded amount of intermediate storage. The format presently uses
48		- the DEFLATE compression method but can be easily extended to use
49		- other compression methods. It can be implemented readily in a manner
50		- not covered by patents. This specification also defines the ADLER-32
51		- checksum (an extension and improvement of the Fletcher checksum),
52		- used for detection of data corruption, and provides an algorithm for
53		- computing it.
54		-
55		-
56		-
57		-
58		-Deutsch & Gailly Informational [Page 1]
59		-
60		-
61		-RFC 1950 ZLIB Compressed Data Format Specification May 1996
62		-
63		-
64		-Table of Contents
65		-
66		- 1. Introduction ................................................... 2
67		- 1.1. Purpose ................................................... 2
68		- 1.2. Intended audience ......................................... 3
69		- 1.3. Scope ..................................................... 3
70		- 1.4. Compliance ................................................ 3
71		- 1.5. Definitions of terms and conventions used ................ 3
72		- 1.6. Changes from previous versions ............................ 3
73		- 2. Detailed specification ......................................... 3
74		- 2.1. Overall conventions ....................................... 3
75		- 2.2. Data format ............................................... 4
76		- 2.3. Compliance ................................................ 7
77		- 3. References ..................................................... 7
78		- 4. Source code .................................................... 8
79		- 5. Security Considerations ........................................ 8
80		- 6. Acknowledgements ............................................... 8
81		- 7. Authors' Addresses ............................................. 8
82		- 8. Appendix: Rationale ............................................ 9
83		- 9. Appendix: Sample code ..........................................10
84		-
85		-1. Introduction
86		-
87		- 1.1. Purpose
88		-
89		- The purpose of this specification is to define a lossless
90		- compressed data format that:
91		-
92		- * Is independent of CPU type, operating system, file system,
93		- and character set, and hence can be used for interchange;
94		-
95		- * Can be produced or consumed, even for an arbitrarily long
96		- sequentially presented input data stream, using only an a
97		- priori bounded amount of intermediate storage, and hence can
98		- be used in data communications or similar structures such as
99		- Unix filters;
100		-
101		- * Can use a number of different compression methods;
102		-
103		- * Can be implemented readily in a manner not covered by
104		- patents, and hence can be practiced freely.
105		-
106		- The data format defined by this specification does not attempt to
107		- allow random access to compressed data.
108		-
109		-
110		-
111		-
112		-
113		-
114		-
115		-Deutsch & Gailly Informational [Page 2]
116		-
117		-
118		-RFC 1950 ZLIB Compressed Data Format Specification May 1996
119		-
120		-
121		- 1.2. Intended audience
122		-
123		- This specification is intended for use by implementors of software
124		- to compress data into zlib format and/or decompress data from zlib
125		- format.
126		-
127		- The text of the specification assumes a basic background in
128		- programming at the level of bits and other primitive data
129		- representations.
130		-
131		- 1.3. Scope
132		-
133		- The specification specifies a compressed data format that can be
134		- used for in-memory compression of a sequence of arbitrary bytes.
135		-
136		- 1.4. Compliance
137		-
138		- Unless otherwise indicated below, a compliant decompressor must be
139		- able to accept and decompress any data set that conforms to all
140		- the specifications presented here; a compliant compressor must
141		- produce data sets that conform to all the specifications presented
142		- here.
143		-
144		- 1.5. Definitions of terms and conventions used
145		-
146		- byte: 8 bits stored or transmitted as a unit (same as an octet).
147		- (For this specification, a byte is exactly 8 bits, even on
148		- machines which store a character on a number of bits different
149		- from 8.) See below, for the numbering of bits within a byte.
150		-
151		- 1.6. Changes from previous versions
152		-
153		- Version 3.1 was the first public release of this specification.
154		- In version 3.2, some terminology was changed and the Adler-32
155		- sample code was rewritten for clarity. In version 3.3, the
156		- support for a preset dictionary was introduced, and the
157		- specification was converted to RFC style.
158		-
159		-2. Detailed specification
160		-
161		- 2.1. Overall conventions
162		-
163		- In the diagrams below, a box like this:
164		-
165		- +---+
166		- \| \| <-- the vertical bars might be missing
167		- +---+
168		-
169		-
170		-
171		-
172		-Deutsch & Gailly Informational [Page 3]
173		-
174		-
175		-RFC 1950 ZLIB Compressed Data Format Specification May 1996
176		-
177		-
178		- represents one byte; a box like this:
179		-
180		- +==============+
181		- \| \|
182		- +==============+
183		-
184		- represents a variable number of bytes.
185		-
186		- Bytes stored within a computer do not have a "bit order", since
187		- they are always treated as a unit. However, a byte considered as
188		- an integer between 0 and 255 does have a most- and least-
189		- significant bit, and since we write numbers with the most-
190		- significant digit on the left, we also write bytes with the most-
191		- significant bit on the left. In the diagrams below, we number the
192		- bits of a byte so that bit 0 is the least-significant bit, i.e.,
193		- the bits are numbered:
194		-
195		- +--------+
196		- \|76543210\|
197		- +--------+
198		-
199		- Within a computer, a number may occupy multiple bytes. All
200		- multi-byte numbers in the format described here are stored with
201		- the MOST-significant byte first (at the lower memory address).
202		- For example, the decimal number 520 is stored as:
203		-
204		- 0 1
205		- +--------+--------+
206		- \|00000010\|00001000\|
207		- +--------+--------+
208		- ^ ^
209		- \| \|
210		- \| + less significant byte = 8
211		- + more significant byte = 2 x 256
212		-
213		- 2.2. Data format
214		-
215		- A zlib stream has the following structure:
216		-
217		- 0 1
218		- +---+---+
219		- \|CMF\|FLG\| (more-->)
220		- +---+---+
221		-
222		-
223		-
224		-
225		-
226		-
227		-
228		-
229		-Deutsch & Gailly Informational [Page 4]
230		-
231		-
232		-RFC 1950 ZLIB Compressed Data Format Specification May 1996
233		-
234		-
235		- (if FLG.FDICT set)
236		-
237		- 0 1 2 3
238		- +---+---+---+---+
239		- \| DICTID \| (more-->)
240		- +---+---+---+---+
241		-
242		- +=====================+---+---+---+---+
243		- \|...compressed data...\| ADLER32 \|
244		- +=====================+---+---+---+---+
245		-
246		- Any data which may appear after ADLER32 are not part of the zlib
247		- stream.
248		-
249		- CMF (Compression Method and flags)
250		- This byte is divided into a 4-bit compression method and a 4-
251		- bit information field depending on the compression method.
252		-
253		- bits 0 to 3 CM Compression method
254		- bits 4 to 7 CINFO Compression info
255		-
256		- CM (Compression method)
257		- This identifies the compression method used in the file. CM = 8
258		- denotes the "deflate" compression method with a window size up
259		- to 32K. This is the method used by gzip and PNG (see
260		- references [1] and [2] in Chapter 3, below, for the reference
261		- documents). CM = 15 is reserved. It might be used in a future
262		- version of this specification to indicate the presence of an
263		- extra field before the compressed data.
264		-
265		- CINFO (Compression info)
266		- For CM = 8, CINFO is the base-2 logarithm of the LZ77 window
267		- size, minus eight (CINFO=7 indicates a 32K window size). Values
268		- of CINFO above 7 are not allowed in this version of the
269		- specification. CINFO is not defined in this specification for
270		- CM not equal to 8.
271		-
272		- FLG (FLaGs)
273		- This flag byte is divided as follows:
274		-
275		- bits 0 to 4 FCHECK (check bits for CMF and FLG)
276		- bit 5 FDICT (preset dictionary)
277		- bits 6 to 7 FLEVEL (compression level)
278		-
279		- The FCHECK value must be such that CMF and FLG, when viewed as
280		- a 16-bit unsigned integer stored in MSB order (CMF*256 + FLG),
281		- is a multiple of 31.
282		-
283		-
284		-
285		-
286		-Deutsch & Gailly Informational [Page 5]
287		-
288		-
289		-RFC 1950 ZLIB Compressed Data Format Specification May 1996
290		-
291		-
292		- FDICT (Preset dictionary)
293		- If FDICT is set, a DICT dictionary identifier is present
294		- immediately after the FLG byte. The dictionary is a sequence of
295		- bytes which are initially fed to the compressor without
296		- producing any compressed output. DICT is the Adler-32 checksum
297		- of this sequence of bytes (see the definition of ADLER32
298		- below). The decompressor can use this identifier to determine
299		- which dictionary has been used by the compressor.
300		-
301		- FLEVEL (Compression level)
302		- These flags are available for use by specific compression
303		- methods. The "deflate" method (CM = 8) sets these flags as
304		- follows:
305		-
306		- 0 - compressor used fastest algorithm
307		- 1 - compressor used fast algorithm
308		- 2 - compressor used default algorithm
309		- 3 - compressor used maximum compression, slowest algorithm
310		-
311		- The information in FLEVEL is not needed for decompression; it
312		- is there to indicate if recompression might be worthwhile.
313		-
314		- compressed data
315		- For compression method 8, the compressed data is stored in the
316		- deflate compressed data format as described in the document
317		- "DEFLATE Compressed Data Format Specification" by L. Peter
318		- Deutsch. (See reference [3] in Chapter 3, below)
319		-
320		- Other compressed data formats are not specified in this version
321		- of the zlib specification.
322		-
323		- ADLER32 (Adler-32 checksum)
324		- This contains a checksum value of the uncompressed data
325		- (excluding any dictionary data) computed according to Adler-32
326		- algorithm. This algorithm is a 32-bit extension and improvement
327		- of the Fletcher algorithm, used in the ITU-T X.224 / ISO 8073
328		- standard. See references [4] and [5] in Chapter 3, below)
329		-
330		- Adler-32 is composed of two sums accumulated per byte: s1 is
331		- the sum of all bytes, s2 is the sum of all s1 values. Both sums
332		- are done modulo 65521. s1 is initialized to 1, s2 to zero. The
333		- Adler-32 checksum is stored as s2*65536 + s1 in most-
334		- significant-byte first (network) order.
335		-
336		-
337		-
338		-
339		-
340		-
341		-
342		-
343		-Deutsch & Gailly Informational [Page 6]
344		-
345		-
346		-RFC 1950 ZLIB Compressed Data Format Specification May 1996
347		-
348		-
349		- 2.3. Compliance
350		-
351		- A compliant compressor must produce streams with correct CMF, FLG
352		- and ADLER32, but need not support preset dictionaries. When the
353		- zlib data format is used as part of another standard data format,
354		- the compressor may use only preset dictionaries that are specified
355		- by this other data format. If this other format does not use the
356		- preset dictionary feature, the compressor must not set the FDICT
357		- flag.
358		-
359		- A compliant decompressor must check CMF, FLG, and ADLER32, and
360		- provide an error indication if any of these have incorrect values.
361		- A compliant decompressor must give an error indication if CM is
362		- not one of the values defined in this specification (only the
363		- value 8 is permitted in this version), since another value could
364		- indicate the presence of new features that would cause subsequent
365		- data to be interpreted incorrectly. A compliant decompressor must
366		- give an error indication if FDICT is set and DICTID is not the
367		- identifier of a known preset dictionary. A decompressor may
368		- ignore FLEVEL and still be compliant. When the zlib data format
369		- is being used as a part of another standard format, a compliant
370		- decompressor must support all the preset dictionaries specified by
371		- the other format. When the other format does not use the preset
372		- dictionary feature, a compliant decompressor must reject any
373		- stream in which the FDICT flag is set.
374		-
375		-3. References
376		-
377		- [1] Deutsch, L.P.,"GZIP Compressed Data Format Specification",
378		- available in ftp://ftp.uu.net/pub/archiving/zip/doc/
379		-
380		- [2] Thomas Boutell, "PNG (Portable Network Graphics) specification",
381		- available in ftp://ftp.uu.net/graphics/png/documents/
382		-
383		- [3] Deutsch, L.P.,"DEFLATE Compressed Data Format Specification",
384		- available in ftp://ftp.uu.net/pub/archiving/zip/doc/
385		-
386		- [4] Fletcher, J. G., "An Arithmetic Checksum for Serial
387		- Transmissions," IEEE Transactions on Communications, Vol. COM-30,
388		- No. 1, January 1982, pp. 247-252.
389		-
390		- [5] ITU-T Recommendation X.224, Annex D, "Checksum Algorithms,"
391		- November, 1993, pp. 144, 145. (Available from
392		- gopher://info.itu.ch). ITU-T X.244 is also the same as ISO 8073.
393		-
394		-
395		-
396		-
397		-
398		-
399		-
400		-Deutsch & Gailly Informational [Page 7]
401		-
402		-
403		-RFC 1950 ZLIB Compressed Data Format Specification May 1996
404		-
405		-
406		-4. Source code
407		-
408		- Source code for a C language implementation of a "zlib" compliant
409		- library is available at ftp://ftp.uu.net/pub/archiving/zip/zlib/.
410		-
411		-5. Security Considerations
412		-
413		- A decoder that fails to check the ADLER32 checksum value may be
414		- subject to undetected data corruption.
415		-
416		-6. Acknowledgements
417		-
418		- Trademarks cited in this document are the property of their
419		- respective owners.
420		-
421		- Jean-Loup Gailly and Mark Adler designed the zlib format and wrote
422		- the related software described in this specification. Glenn
423		- Randers-Pehrson converted this document to RFC and HTML format.
424		-
425		-7. Authors' Addresses
426		-
427		- L. Peter Deutsch
428		- Aladdin Enterprises
429		- 203 Santa Margarita Ave.
430		- Menlo Park, CA 94025
431		-
432		- Phone: (415) 322-0103 (AM only)
433		- FAX: (415) 322-1734
434		- EMail: <[email protected]>
435		-
436		-
437		- Jean-Loup Gailly
438		-
439		- EMail: <[email protected]>
440		-
441		- Questions about the technical content of this specification can be
442		- sent by email to
443		-
444		- Jean-Loup Gailly <[email protected]> and
445		- Mark Adler <[email protected]>
446		-
447		- Editorial comments on this specification can be sent by email to
448		-
449		- L. Peter Deutsch <[email protected]> and
450		- Glenn Randers-Pehrson <[email protected]>
451		-
452		-
453		-
454		-
455		-
456		-
457		-Deutsch & Gailly Informational [Page 8]
458		-
459		-
460		-RFC 1950 ZLIB Compressed Data Format Specification May 1996
461		-
462		-
463		-8. Appendix: Rationale
464		-
465		- 8.1. Preset dictionaries
466		-
467		- A preset dictionary is specially useful to compress short input
468		- sequences. The compressor can take advantage of the dictionary
469		- context to encode the input in a more compact manner. The
470		- decompressor can be initialized with the appropriate context by
471		- virtually decompressing a compressed version of the dictionary
472		- without producing any output. However for certain compression
473		- algorithms such as the deflate algorithm this operation can be
474		- achieved without actually performing any decompression.
475		-
476		- The compressor and the decompressor must use exactly the same
477		- dictionary. The dictionary may be fixed or may be chosen among a
478		- certain number of predefined dictionaries, according to the kind
479		- of input data. The decompressor can determine which dictionary has
480		- been chosen by the compressor by checking the dictionary
481		- identifier. This document does not specify the contents of
482		- predefined dictionaries, since the optimal dictionaries are
483		- application specific. Standard data formats using this feature of
484		- the zlib specification must precisely define the allowed
485		- dictionaries.
486		-
487		- 8.2. The Adler-32 algorithm
488		-
489		- The Adler-32 algorithm is much faster than the CRC32 algorithm yet
490		- still provides an extremely low probability of undetected errors.
491		-
492		- The modulo on unsigned long accumulators can be delayed for 5552
493		- bytes, so the modulo operation time is negligible. If the bytes
494		- are a, b, c, the second sum is 3a + 2b + c + 3, and so is position
495		- and order sensitive, unlike the first sum, which is just a
496		- checksum. That 65521 is prime is important to avoid a possible
497		- large class of two-byte errors that leave the check unchanged.
498		- (The Fletcher checksum uses 255, which is not prime and which also
499		- makes the Fletcher check insensitive to single byte changes 0 <->
500		- 255.)
501		-
502		- The sum s1 is initialized to 1 instead of zero to make the length
503		- of the sequence part of s2, so that the length does not have to be
504		- checked separately. (Any sequence of zeroes has a Fletcher
505		- checksum of zero.)
506		-
507		-
508		-
509		-
510		-
511		-
512		-
513		-
514		-Deutsch & Gailly Informational [Page 9]
515		-
516		-
517		-RFC 1950 ZLIB Compressed Data Format Specification May 1996
518		-
519		-
520		-9. Appendix: Sample code
521		-
522		- The following C code computes the Adler-32 checksum of a data buffer.
523		- It is written for clarity, not for speed. The sample code is in the
524		- ANSI C programming language. Non C users may find it easier to read
525		- with these hints:
526		-
527		- & Bitwise AND operator.
528		- >> Bitwise right shift operator. When applied to an
529		- unsigned quantity, as here, right shift inserts zero bit(s)
530		- at the left.
531		- << Bitwise left shift operator. Left shift inserts zero
532		- bit(s) at the right.
533		- ++ "n++" increments the variable n.
534		- % modulo operator: a % b is the remainder of a divided by b.
535		-
536		- #define BASE 65521 /* largest prime smaller than 65536 */
537		-
538		- /*
539		- Update a running Adler-32 checksum with the bytes buf[0..len-1]
540		- and return the updated checksum. The Adler-32 checksum should be
541		- initialized to 1.
542		-
543		- Usage example:
544		-
545		- unsigned long adler = 1L;
546		-
547		- while (read_buffer(buffer, length) != EOF) {
548		- adler = update_adler32(adler, buffer, length);
549		- }
550		- if (adler != original_adler) error();
551		- */
552		- unsigned long update_adler32(unsigned long adler,
553		- unsigned char *buf, int len)
554		- {
555		- unsigned long s1 = adler & 0xffff;
556		- unsigned long s2 = (adler >> 16) & 0xffff;
557		- int n;
558		-
559		- for (n = 0; n < len; n++) {
560		- s1 = (s1 + buf[n]) % BASE;
561		- s2 = (s2 + s1) % BASE;
562		- }
563		- return (s2 << 16) + s1;
564		- }
565		-
566		- /* Return the adler32 of the bytes buf[0..len-1] */
567		-
568		-
569		-
570		-
571		-Deutsch & Gailly Informational [Page 10]
572		-
573		-
574		-RFC 1950 ZLIB Compressed Data Format Specification May 1996
575		-
576		-
577		- unsigned long adler32(unsigned char *buf, int len)
578		- {
579		- return update_adler32(1L, buf, len);
580		- }
581		-
582		-
583		-
584		-
585		-
586		-
587		-
588		-
589		-
590		-
591		-
592		-
593		-
594		-
595		-
596		-
597		-
598		-
599		-
600		-
601		-
602		-
603		-
604		-
605		-
606		-
607		-
608		-
609		-
610		-
611		-
612		-
613		-
614		-
615		-
616		-
617		-
618		-
619		-
620		-
621		-
622		-
623		-
624		-
625		-
626		-
627		-
628		-Deutsch & Gailly Informational [Page 11]
629		-
630		-

	--- a/compat/zlib/doc/rfc1950.txt
	+++ b/compat/zlib/doc/rfc1950.txt
	@@ -1,630 +0,0 @@
1
2
3
4
5
6
7	Network Working Group P. Deutsch
8	Request for Comments: 1950 Aladdin Enterprises
9	Category: Informational J-L. Gailly
10	Info-ZIP
11	May 1996
12
13
14	ZLIB Compressed Data Format Specification version 3.3
15
16	Status of This Memo
17
18	This memo provides information for the Internet community. This memo
19	does not specify an Internet standard of any kind. Distribution of
20	this memo is unlimited.
21
22	IESG Note:
23
24	The IESG takes no position on the validity of any Intellectual
25	Property Rights statements contained in this document.
26
27	Notices
28
29	Copyright (c) 1996 L. Peter Deutsch and Jean-Loup Gailly
30
31	Permission is granted to copy and distribute this document for any
32	purpose and without charge, including translations into other
33	languages and incorporation into compilations, provided that the
34	copyright notice and this notice are preserved, and that any
35	substantive changes or deletions from the original are clearly
36	marked.
37
38	A pointer to the latest version of this and related documentation in
39	HTML format can be found at the URL
40	<ftp://ftp.uu.net/graphics/png/documents/zlib/zdoc-index.html>.
41
42	Abstract
43
44	This specification defines a lossless compressed data format. The
45	data can be produced or consumed, even for an arbitrarily long
46	sequentially presented input data stream, using only an a priori
47	bounded amount of intermediate storage. The format presently uses
48	the DEFLATE compression method but can be easily extended to use
49	other compression methods. It can be implemented readily in a manner
50	not covered by patents. This specification also defines the ADLER-32
51	checksum (an extension and improvement of the Fletcher checksum),
52	used for detection of data corruption, and provides an algorithm for
53	computing it.
54
55
56
57
58	Deutsch & Gailly Informational [Page 1]
59
60
61	RFC 1950 ZLIB Compressed Data Format Specification May 1996
62
63
64	Table of Contents
65
66	1. Introduction ................................................... 2
67	1.1. Purpose ................................................... 2
68	1.2. Intended audience ......................................... 3
69	1.3. Scope ..................................................... 3
70	1.4. Compliance ................................................ 3
71	1.5. Definitions of terms and conventions used ................ 3
72	1.6. Changes from previous versions ............................ 3
73	2. Detailed specification ......................................... 3
74	2.1. Overall conventions ....................................... 3
75	2.2. Data format ............................................... 4
76	2.3. Compliance ................................................ 7
77	3. References ..................................................... 7
78	4. Source code .................................................... 8
79	5. Security Considerations ........................................ 8
80	6. Acknowledgements ............................................... 8
81	7. Authors' Addresses ............................................. 8
82	8. Appendix: Rationale ............................................ 9
83	9. Appendix: Sample code ..........................................10
84
85	1. Introduction
86
87	1.1. Purpose
88
89	The purpose of this specification is to define a lossless
90	compressed data format that:
91
92	* Is independent of CPU type, operating system, file system,
93	and character set, and hence can be used for interchange;
94
95	* Can be produced or consumed, even for an arbitrarily long
96	sequentially presented input data stream, using only an a
97	priori bounded amount of intermediate storage, and hence can
98	be used in data communications or similar structures such as
99	Unix filters;
100
101	* Can use a number of different compression methods;
102
103	* Can be implemented readily in a manner not covered by
104	patents, and hence can be practiced freely.
105
106	The data format defined by this specification does not attempt to
107	allow random access to compressed data.
108
109
110
111
112
113
114
115	Deutsch & Gailly Informational [Page 2]
116
117
118	RFC 1950 ZLIB Compressed Data Format Specification May 1996
119
120
121	1.2. Intended audience
122
123	This specification is intended for use by implementors of software
124	to compress data into zlib format and/or decompress data from zlib
125	format.
126
127	The text of the specification assumes a basic background in
128	programming at the level of bits and other primitive data
129	representations.
130
131	1.3. Scope
132
133	The specification specifies a compressed data format that can be
134	used for in-memory compression of a sequence of arbitrary bytes.
135
136	1.4. Compliance
137
138	Unless otherwise indicated below, a compliant decompressor must be
139	able to accept and decompress any data set that conforms to all
140	the specifications presented here; a compliant compressor must
141	produce data sets that conform to all the specifications presented
142	here.
143
144	1.5. Definitions of terms and conventions used
145
146	byte: 8 bits stored or transmitted as a unit (same as an octet).
147	(For this specification, a byte is exactly 8 bits, even on
148	machines which store a character on a number of bits different
149	from 8.) See below, for the numbering of bits within a byte.
150
151	1.6. Changes from previous versions
152
153	Version 3.1 was the first public release of this specification.
154	In version 3.2, some terminology was changed and the Adler-32
155	sample code was rewritten for clarity. In version 3.3, the
156	support for a preset dictionary was introduced, and the
157	specification was converted to RFC style.
158
159	2. Detailed specification
160
161	2.1. Overall conventions
162
163	In the diagrams below, a box like this:
164
165	+---+
166	\| \| <-- the vertical bars might be missing
167	+---+
168
169
170
171
172	Deutsch & Gailly Informational [Page 3]
173
174
175	RFC 1950 ZLIB Compressed Data Format Specification May 1996
176
177
178	represents one byte; a box like this:
179
180	+==============+
181	\| \|
182	+==============+
183
184	represents a variable number of bytes.
185
186	Bytes stored within a computer do not have a "bit order", since
187	they are always treated as a unit. However, a byte considered as
188	an integer between 0 and 255 does have a most- and least-
189	significant bit, and since we write numbers with the most-
190	significant digit on the left, we also write bytes with the most-
191	significant bit on the left. In the diagrams below, we number the
192	bits of a byte so that bit 0 is the least-significant bit, i.e.,
193	the bits are numbered:
194
195	+--------+
196	\|76543210\|
197	+--------+
198
199	Within a computer, a number may occupy multiple bytes. All
200	multi-byte numbers in the format described here are stored with
201	the MOST-significant byte first (at the lower memory address).
202	For example, the decimal number 520 is stored as:
203
204	0 1
205	+--------+--------+
206	\|00000010\|00001000\|
207	+--------+--------+
208	^ ^
209	\| \|
210	\| + less significant byte = 8
211	+ more significant byte = 2 x 256
212
213	2.2. Data format
214
215	A zlib stream has the following structure:
216
217	0 1
218	+---+---+
219	\|CMF\|FLG\| (more-->)
220	+---+---+
221
222
223
224
225
226
227
228
229	Deutsch & Gailly Informational [Page 4]
230
231
232	RFC 1950 ZLIB Compressed Data Format Specification May 1996
233
234
235	(if FLG.FDICT set)
236
237	0 1 2 3
238	+---+---+---+---+
239	\| DICTID \| (more-->)
240	+---+---+---+---+
241
242	+=====================+---+---+---+---+
243	\|...compressed data...\| ADLER32 \|
244	+=====================+---+---+---+---+
245
246	Any data which may appear after ADLER32 are not part of the zlib
247	stream.
248
249	CMF (Compression Method and flags)
250	This byte is divided into a 4-bit compression method and a 4-
251	bit information field depending on the compression method.
252
253	bits 0 to 3 CM Compression method
254	bits 4 to 7 CINFO Compression info
255
256	CM (Compression method)
257	This identifies the compression method used in the file. CM = 8
258	denotes the "deflate" compression method with a window size up
259	to 32K. This is the method used by gzip and PNG (see
260	references [1] and [2] in Chapter 3, below, for the reference
261	documents). CM = 15 is reserved. It might be used in a future
262	version of this specification to indicate the presence of an
263	extra field before the compressed data.
264
265	CINFO (Compression info)
266	For CM = 8, CINFO is the base-2 logarithm of the LZ77 window
267	size, minus eight (CINFO=7 indicates a 32K window size). Values
268	of CINFO above 7 are not allowed in this version of the
269	specification. CINFO is not defined in this specification for
270	CM not equal to 8.
271
272	FLG (FLaGs)
273	This flag byte is divided as follows:
274
275	bits 0 to 4 FCHECK (check bits for CMF and FLG)
276	bit 5 FDICT (preset dictionary)
277	bits 6 to 7 FLEVEL (compression level)
278
279	The FCHECK value must be such that CMF and FLG, when viewed as
280	a 16-bit unsigned integer stored in MSB order (CMF*256 + FLG),
281	is a multiple of 31.
282
283
284
285
286	Deutsch & Gailly Informational [Page 5]
287
288
289	RFC 1950 ZLIB Compressed Data Format Specification May 1996
290
291
292	FDICT (Preset dictionary)
293	If FDICT is set, a DICT dictionary identifier is present
294	immediately after the FLG byte. The dictionary is a sequence of
295	bytes which are initially fed to the compressor without
296	producing any compressed output. DICT is the Adler-32 checksum
297	of this sequence of bytes (see the definition of ADLER32
298	below). The decompressor can use this identifier to determine
299	which dictionary has been used by the compressor.
300
301	FLEVEL (Compression level)
302	These flags are available for use by specific compression
303	methods. The "deflate" method (CM = 8) sets these flags as
304	follows:
305
306	0 - compressor used fastest algorithm
307	1 - compressor used fast algorithm
308	2 - compressor used default algorithm
309	3 - compressor used maximum compression, slowest algorithm
310
311	The information in FLEVEL is not needed for decompression; it
312	is there to indicate if recompression might be worthwhile.
313
314	compressed data
315	For compression method 8, the compressed data is stored in the
316	deflate compressed data format as described in the document
317	"DEFLATE Compressed Data Format Specification" by L. Peter
318	Deutsch. (See reference [3] in Chapter 3, below)
319
320	Other compressed data formats are not specified in this version
321	of the zlib specification.
322
323	ADLER32 (Adler-32 checksum)
324	This contains a checksum value of the uncompressed data
325	(excluding any dictionary data) computed according to Adler-32
326	algorithm. This algorithm is a 32-bit extension and improvement
327	of the Fletcher algorithm, used in the ITU-T X.224 / ISO 8073
328	standard. See references [4] and [5] in Chapter 3, below)
329
330	Adler-32 is composed of two sums accumulated per byte: s1 is
331	the sum of all bytes, s2 is the sum of all s1 values. Both sums
332	are done modulo 65521. s1 is initialized to 1, s2 to zero. The
333	Adler-32 checksum is stored as s2*65536 + s1 in most-
334	significant-byte first (network) order.
335
336
337
338
339
340
341
342
343	Deutsch & Gailly Informational [Page 6]
344
345
346	RFC 1950 ZLIB Compressed Data Format Specification May 1996
347
348
349	2.3. Compliance
350
351	A compliant compressor must produce streams with correct CMF, FLG
352	and ADLER32, but need not support preset dictionaries. When the
353	zlib data format is used as part of another standard data format,
354	the compressor may use only preset dictionaries that are specified
355	by this other data format. If this other format does not use the
356	preset dictionary feature, the compressor must not set the FDICT
357	flag.
358
359	A compliant decompressor must check CMF, FLG, and ADLER32, and
360	provide an error indication if any of these have incorrect values.
361	A compliant decompressor must give an error indication if CM is
362	not one of the values defined in this specification (only the
363	value 8 is permitted in this version), since another value could
364	indicate the presence of new features that would cause subsequent
365	data to be interpreted incorrectly. A compliant decompressor must
366	give an error indication if FDICT is set and DICTID is not the
367	identifier of a known preset dictionary. A decompressor may
368	ignore FLEVEL and still be compliant. When the zlib data format
369	is being used as a part of another standard format, a compliant
370	decompressor must support all the preset dictionaries specified by
371	the other format. When the other format does not use the preset
372	dictionary feature, a compliant decompressor must reject any
373	stream in which the FDICT flag is set.
374
375	3. References
376
377	[1] Deutsch, L.P.,"GZIP Compressed Data Format Specification",
378	available in ftp://ftp.uu.net/pub/archiving/zip/doc/
379
380	[2] Thomas Boutell, "PNG (Portable Network Graphics) specification",
381	available in ftp://ftp.uu.net/graphics/png/documents/
382
383	[3] Deutsch, L.P.,"DEFLATE Compressed Data Format Specification",
384	available in ftp://ftp.uu.net/pub/archiving/zip/doc/
385
386	[4] Fletcher, J. G., "An Arithmetic Checksum for Serial
387	Transmissions," IEEE Transactions on Communications, Vol. COM-30,
388	No. 1, January 1982, pp. 247-252.
389
390	[5] ITU-T Recommendation X.224, Annex D, "Checksum Algorithms,"
391	November, 1993, pp. 144, 145. (Available from
392	gopher://info.itu.ch). ITU-T X.244 is also the same as ISO 8073.
393
394
395
396
397
398
399
400	Deutsch & Gailly Informational [Page 7]
401
402
403	RFC 1950 ZLIB Compressed Data Format Specification May 1996
404
405
406	4. Source code
407
408	Source code for a C language implementation of a "zlib" compliant
409	library is available at ftp://ftp.uu.net/pub/archiving/zip/zlib/.
410
411	5. Security Considerations
412
413	A decoder that fails to check the ADLER32 checksum value may be
414	subject to undetected data corruption.
415
416	6. Acknowledgements
417
418	Trademarks cited in this document are the property of their
419	respective owners.
420
421	Jean-Loup Gailly and Mark Adler designed the zlib format and wrote
422	the related software described in this specification. Glenn
423	Randers-Pehrson converted this document to RFC and HTML format.
424
425	7. Authors' Addresses
426
427	L. Peter Deutsch
428	Aladdin Enterprises
429	203 Santa Margarita Ave.
430	Menlo Park, CA 94025
431
432	Phone: (415) 322-0103 (AM only)
433	FAX: (415) 322-1734
434	EMail: <[email protected]>
435
436
437	Jean-Loup Gailly
438
439	EMail: <[email protected]>
440
441	Questions about the technical content of this specification can be
442	sent by email to
443
444	Jean-Loup Gailly <[email protected]> and
445	Mark Adler <[email protected]>
446
447	Editorial comments on this specification can be sent by email to
448
449	L. Peter Deutsch <[email protected]> and
450	Glenn Randers-Pehrson <[email protected]>
451
452
453
454
455
456
457	Deutsch & Gailly Informational [Page 8]
458
459
460	RFC 1950 ZLIB Compressed Data Format Specification May 1996
461
462
463	8. Appendix: Rationale
464
465	8.1. Preset dictionaries
466
467	A preset dictionary is specially useful to compress short input
468	sequences. The compressor can take advantage of the dictionary
469	context to encode the input in a more compact manner. The
470	decompressor can be initialized with the appropriate context by
471	virtually decompressing a compressed version of the dictionary
472	without producing any output. However for certain compression
473	algorithms such as the deflate algorithm this operation can be
474	achieved without actually performing any decompression.
475
476	The compressor and the decompressor must use exactly the same
477	dictionary. The dictionary may be fixed or may be chosen among a
478	certain number of predefined dictionaries, according to the kind
479	of input data. The decompressor can determine which dictionary has
480	been chosen by the compressor by checking the dictionary
481	identifier. This document does not specify the contents of
482	predefined dictionaries, since the optimal dictionaries are
483	application specific. Standard data formats using this feature of
484	the zlib specification must precisely define the allowed
485	dictionaries.
486
487	8.2. The Adler-32 algorithm
488
489	The Adler-32 algorithm is much faster than the CRC32 algorithm yet
490	still provides an extremely low probability of undetected errors.
491
492	The modulo on unsigned long accumulators can be delayed for 5552
493	bytes, so the modulo operation time is negligible. If the bytes
494	are a, b, c, the second sum is 3a + 2b + c + 3, and so is position
495	and order sensitive, unlike the first sum, which is just a
496	checksum. That 65521 is prime is important to avoid a possible
497	large class of two-byte errors that leave the check unchanged.
498	(The Fletcher checksum uses 255, which is not prime and which also
499	makes the Fletcher check insensitive to single byte changes 0 <->
500	255.)
501
502	The sum s1 is initialized to 1 instead of zero to make the length
503	of the sequence part of s2, so that the length does not have to be
504	checked separately. (Any sequence of zeroes has a Fletcher
505	checksum of zero.)
506
507
508
509
510
511
512
513
514	Deutsch & Gailly Informational [Page 9]
515
516
517	RFC 1950 ZLIB Compressed Data Format Specification May 1996
518
519
520	9. Appendix: Sample code
521
522	The following C code computes the Adler-32 checksum of a data buffer.
523	It is written for clarity, not for speed. The sample code is in the
524	ANSI C programming language. Non C users may find it easier to read
525	with these hints:
526
527	& Bitwise AND operator.
528	>> Bitwise right shift operator. When applied to an
529	unsigned quantity, as here, right shift inserts zero bit(s)
530	at the left.
531	<< Bitwise left shift operator. Left shift inserts zero
532	bit(s) at the right.
533	++ "n++" increments the variable n.
534	% modulo operator: a % b is the remainder of a divided by b.
535
536	#define BASE 65521 /* largest prime smaller than 65536 */
537
538	/*
539	Update a running Adler-32 checksum with the bytes buf[0..len-1]
540	and return the updated checksum. The Adler-32 checksum should be
541	initialized to 1.
542
543	Usage example:
544
545	unsigned long adler = 1L;
546
547	while (read_buffer(buffer, length) != EOF) {
548	adler = update_adler32(adler, buffer, length);
549	}
550	if (adler != original_adler) error();
551	*/
552	unsigned long update_adler32(unsigned long adler,
553	unsigned char *buf, int len)
554	{
555	unsigned long s1 = adler & 0xffff;
556	unsigned long s2 = (adler >> 16) & 0xffff;
557	int n;
558
559	for (n = 0; n < len; n++) {
560	s1 = (s1 + buf[n]) % BASE;
561	s2 = (s2 + s1) % BASE;
562	}
563	return (s2 << 16) + s1;
564	}
565
566	/* Return the adler32 of the bytes buf[0..len-1] */
567
568
569
570
571	Deutsch & Gailly Informational [Page 10]
572
573
574	RFC 1950 ZLIB Compressed Data Format Specification May 1996
575
576
577	unsigned long adler32(unsigned char *buf, int len)
578	{
579	return update_adler32(1L, buf, len);
580	}
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628	Deutsch & Gailly Informational [Page 11]
629
630

	--- a/compat/zlib/doc/rfc1950.txt
	+++ b/compat/zlib/doc/rfc1950.txt
	@@ -1,630 +0,0 @@

D compat/zlib/doc/rfc1951.txt

-972

		--- a/compat/zlib/doc/rfc1951.txt
		+++ b/compat/zlib/doc/rfc1951.txt
		@@ -1,972 +0,0 @@
1		-
2		-
3		-
4		-
5		-
6		-
7		-Network Working Group P. Deutsch
8		-Request for Comments: 1951 Aladdin Enterprises
9		-Category: Informational May 1996
10		-
11		-
12		- DEFLATE Compressed Data Format Specification version 1.3
13		-
14		-Status of This Memo
15		-
16		- This memo provides information for the Internet community. This memo
17		- does not specify an Internet standard of any kind. Distribution of
18		- this memo is unlimited.
19		-
20		-IESG Note:
21		-
22		- The IESG takes no position on the validity of any Intellectual
23		- Property Rights statements contained in this document.
24		-
25		-Notices
26		-
27		- Copyright (c) 1996 L. Peter Deutsch
28		-
29		- Permission is granted to copy and distribute this document for any
30		- purpose and without charge, including translations into other
31		- languages and incorporation into compilations, provided that the
32		- copyright notice and this notice are preserved, and that any
33		- substantive changes or deletions from the original are clearly
34		- marked.
35		-
36		- A pointer to the latest version of this and related documentation in
37		- HTML format can be found at the URL
38		- <ftp://ftp.uu.net/graphics/png/documents/zlib/zdoc-index.html>.
39		-
40		-Abstract
41		-
42		- This specification defines a lossless compressed data format that
43		- compresses data using a combination of the LZ77 algorithm and Huffman
44		- coding, with efficiency comparable to the best currently available
45		- general-purpose compression methods. The data can be produced or
46		- consumed, even for an arbitrarily long sequentially presented input
47		- data stream, using only an a priori bounded amount of intermediate
48		- storage. The format can be implemented readily in a manner not
49		- covered by patents.
50		-
51		-
52		-
53		-
54		-
55		-
56		-
57		-
58		-Deutsch Informational [Page 1]
59		-
60		-
61		-RFC 1951 DEFLATE Compressed Data Format Specification May 1996
62		-
63		-
64		-Table of Contents
65		-
66		- 1. Introduction ................................................... 2
67		- 1.1. Purpose ................................................... 2
68		- 1.2. Intended audience ......................................... 3
69		- 1.3. Scope ..................................................... 3
70		- 1.4. Compliance ................................................ 3
71		- 1.5. Definitions of terms and conventions used ................ 3
72		- 1.6. Changes from previous versions ............................ 4
73		- 2. Compressed representation overview ............................. 4
74		- 3. Detailed specification ......................................... 5
75		- 3.1. Overall conventions ....................................... 5
76		- 3.1.1. Packing into bytes .................................. 5
77		- 3.2. Compressed block format ................................... 6
78		- 3.2.1. Synopsis of prefix and Huffman coding ............... 6
79		- 3.2.2. Use of Huffman coding in the "deflate" format ....... 7
80		- 3.2.3. Details of block format ............................. 9
81		- 3.2.4. Non-compressed blocks (BTYPE=00) ................... 11
82		- 3.2.5. Compressed blocks (length and distance codes) ...... 11
83		- 3.2.6. Compression with fixed Huffman codes (BTYPE=01) .... 12
84		- 3.2.7. Compression with dynamic Huffman codes (BTYPE=10) .. 13
85		- 3.3. Compliance ............................................... 14
86		- 4. Compression algorithm details ................................. 14
87		- 5. References .................................................... 16
88		- 6. Security Considerations ....................................... 16
89		- 7. Source code ................................................... 16
90		- 8. Acknowledgements .............................................. 16
91		- 9. Author's Address .............................................. 17
92		-
93		-1. Introduction
94		-
95		- 1.1. Purpose
96		-
97		- The purpose of this specification is to define a lossless
98		- compressed data format that:
99		- * Is independent of CPU type, operating system, file system,
100		- and character set, and hence can be used for interchange;
101		- * Can be produced or consumed, even for an arbitrarily long
102		- sequentially presented input data stream, using only an a
103		- priori bounded amount of intermediate storage, and hence
104		- can be used in data communications or similar structures
105		- such as Unix filters;
106		- * Compresses data with efficiency comparable to the best
107		- currently available general-purpose compression methods,
108		- and in particular considerably better than the "compress"
109		- program;
110		- * Can be implemented readily in a manner not covered by
111		- patents, and hence can be practiced freely;
112		-
113		-
114		-
115		-Deutsch Informational [Page 2]
116		-
117		-
118		-RFC 1951 DEFLATE Compressed Data Format Specification May 1996
119		-
120		-
121		- * Is compatible with the file format produced by the current
122		- widely used gzip utility, in that conforming decompressors
123		- will be able to read data produced by the existing gzip
124		- compressor.
125		-
126		- The data format defined by this specification does not attempt to:
127		-
128		- * Allow random access to compressed data;
129		- * Compress specialized data (e.g., raster graphics) as well
130		- as the best currently available specialized algorithms.
131		-
132		- A simple counting argument shows that no lossless compression
133		- algorithm can compress every possible input data set. For the
134		- format defined here, the worst case expansion is 5 bytes per 32K-
135		- byte block, i.e., a size increase of 0.015% for large data sets.
136		- English text usually compresses by a factor of 2.5 to 3;
137		- executable files usually compress somewhat less; graphical data
138		- such as raster images may compress much more.
139		-
140		- 1.2. Intended audience
141		-
142		- This specification is intended for use by implementors of software
143		- to compress data into "deflate" format and/or decompress data from
144		- "deflate" format.
145		-
146		- The text of the specification assumes a basic background in
147		- programming at the level of bits and other primitive data
148		- representations. Familiarity with the technique of Huffman coding
149		- is helpful but not required.
150		-
151		- 1.3. Scope
152		-
153		- The specification specifies a method for representing a sequence
154		- of bytes as a (usually shorter) sequence of bits, and a method for
155		- packing the latter bit sequence into bytes.
156		-
157		- 1.4. Compliance
158		-
159		- Unless otherwise indicated below, a compliant decompressor must be
160		- able to accept and decompress any data set that conforms to all
161		- the specifications presented here; a compliant compressor must
162		- produce data sets that conform to all the specifications presented
163		- here.
164		-
165		- 1.5. Definitions of terms and conventions used
166		-
167		- Byte: 8 bits stored or transmitted as a unit (same as an octet).
168		- For this specification, a byte is exactly 8 bits, even on machines
169		-
170		-
171		-
172		-Deutsch Informational [Page 3]
173		-
174		-
175		-RFC 1951 DEFLATE Compressed Data Format Specification May 1996
176		-
177		-
178		- which store a character on a number of bits different from eight.
179		- See below, for the numbering of bits within a byte.
180		-
181		- String: a sequence of arbitrary bytes.
182		-
183		- 1.6. Changes from previous versions
184		-
185		- There have been no technical changes to the deflate format since
186		- version 1.1 of this specification. In version 1.2, some
187		- terminology was changed. Version 1.3 is a conversion of the
188		- specification to RFC style.
189		-
190		-2. Compressed representation overview
191		-
192		- A compressed data set consists of a series of blocks, corresponding
193		- to successive blocks of input data. The block sizes are arbitrary,
194		- except that non-compressible blocks are limited to 65,535 bytes.
195		-
196		- Each block is compressed using a combination of the LZ77 algorithm
197		- and Huffman coding. The Huffman trees for each block are independent
198		- of those for previous or subsequent blocks; the LZ77 algorithm may
199		- use a reference to a duplicated string occurring in a previous block,
200		- up to 32K input bytes before.
201		-
202		- Each block consists of two parts: a pair of Huffman code trees that
203		- describe the representation of the compressed data part, and a
204		- compressed data part. (The Huffman trees themselves are compressed
205		- using Huffman encoding.) The compressed data consists of a series of
206		- elements of two types: literal bytes (of strings that have not been
207		- detected as duplicated within the previous 32K input bytes), and
208		- pointers to duplicated strings, where a pointer is represented as a
209		- pair <length, backward distance>. The representation used in the
210		- "deflate" format limits distances to 32K bytes and lengths to 258
211		- bytes, but does not limit the size of a block, except for
212		- uncompressible blocks, which are limited as noted above.
213		-
214		- Each type of value (literals, distances, and lengths) in the
215		- compressed data is represented using a Huffman code, using one code
216		- tree for literals and lengths and a separate code tree for distances.
217		- The code trees for each block appear in a compact form just before
218		- the compressed data for that block.
219		-
220		-
221		-
222		-
223		-
224		-
225		-
226		-
227		-
228		-
229		-Deutsch Informational [Page 4]
230		-
231		-
232		-RFC 1951 DEFLATE Compressed Data Format Specification May 1996
233		-
234		-
235		-3. Detailed specification
236		-
237		- 3.1. Overall conventions In the diagrams below, a box like this:
238		-
239		- +---+
240		- \| \| <-- the vertical bars might be missing
241		- +---+
242		-
243		- represents one byte; a box like this:
244		-
245		- +==============+
246		- \| \|
247		- +==============+
248		-
249		- represents a variable number of bytes.
250		-
251		- Bytes stored within a computer do not have a "bit order", since
252		- they are always treated as a unit. However, a byte considered as
253		- an integer between 0 and 255 does have a most- and least-
254		- significant bit, and since we write numbers with the most-
255		- significant digit on the left, we also write bytes with the most-
256		- significant bit on the left. In the diagrams below, we number the
257		- bits of a byte so that bit 0 is the least-significant bit, i.e.,
258		- the bits are numbered:
259		-
260		- +--------+
261		- \|76543210\|
262		- +--------+
263		-
264		- Within a computer, a number may occupy multiple bytes. All
265		- multi-byte numbers in the format described here are stored with
266		- the least-significant byte first (at the lower memory address).
267		- For example, the decimal number 520 is stored as:
268		-
269		- 0 1
270		- +--------+--------+
271		- \|00001000\|00000010\|
272		- +--------+--------+
273		- ^ ^
274		- \| \|
275		- \| + more significant byte = 2 x 256
276		- + less significant byte = 8
277		-
278		- 3.1.1. Packing into bytes
279		-
280		- This document does not address the issue of the order in which
281		- bits of a byte are transmitted on a bit-sequential medium,
282		- since the final data format described here is byte- rather than
283		-
284		-
285		-
286		-Deutsch Informational [Page 5]
287		-
288		-
289		-RFC 1951 DEFLATE Compressed Data Format Specification May 1996
290		-
291		-
292		- bit-oriented. However, we describe the compressed block format
293		- in below, as a sequence of data elements of various bit
294		- lengths, not a sequence of bytes. We must therefore specify
295		- how to pack these data elements into bytes to form the final
296		- compressed byte sequence:
297		-
298		- * Data elements are packed into bytes in order of
299		- increasing bit number within the byte, i.e., starting
300		- with the least-significant bit of the byte.
301		- * Data elements other than Huffman codes are packed
302		- starting with the least-significant bit of the data
303		- element.
304		- * Huffman codes are packed starting with the most-
305		- significant bit of the code.
306		-
307		- In other words, if one were to print out the compressed data as
308		- a sequence of bytes, starting with the first byte at the
309		- right margin and proceeding to the left, with the most-
310		- significant bit of each byte on the left as usual, one would be
311		- able to parse the result from right to left, with fixed-width
312		- elements in the correct MSB-to-LSB order and Huffman codes in
313		- bit-reversed order (i.e., with the first bit of the code in the
314		- relative LSB position).
315		-
316		- 3.2. Compressed block format
317		-
318		- 3.2.1. Synopsis of prefix and Huffman coding
319		-
320		- Prefix coding represents symbols from an a priori known
321		- alphabet by bit sequences (codes), one code for each symbol, in
322		- a manner such that different symbols may be represented by bit
323		- sequences of different lengths, but a parser can always parse
324		- an encoded string unambiguously symbol-by-symbol.
325		-
326		- We define a prefix code in terms of a binary tree in which the
327		- two edges descending from each non-leaf node are labeled 0 and
328		- 1 and in which the leaf nodes correspond one-for-one with (are
329		- labeled with) the symbols of the alphabet; then the code for a
330		- symbol is the sequence of 0's and 1's on the edges leading from
331		- the root to the leaf labeled with that symbol. For example:
332		-
333		-
334		-
335		-
336		-
337		-
338		-
339		-
340		-
341		-
342		-
343		-Deutsch Informational [Page 6]
344		-
345		-
346		-RFC 1951 DEFLATE Compressed Data Format Specification May 1996
347		-
348		-
349		- /\ Symbol Code
350		- 0 1 ------ ----
351		- / \ A 00
352		- /\ B B 1
353		- 0 1 C 011
354		- / \ D 010
355		- A /\
356		- 0 1
357		- / \
358		- D C
359		-
360		- A parser can decode the next symbol from an encoded input
361		- stream by walking down the tree from the root, at each step
362		- choosing the edge corresponding to the next input bit.
363		-
364		- Given an alphabet with known symbol frequencies, the Huffman
365		- algorithm allows the construction of an optimal prefix code
366		- (one which represents strings with those symbol frequencies
367		- using the fewest bits of any possible prefix codes for that
368		- alphabet). Such a code is called a Huffman code. (See
369		- reference [1] in Chapter 5, references for additional
370		- information on Huffman codes.)
371		-
372		- Note that in the "deflate" format, the Huffman codes for the
373		- various alphabets must not exceed certain maximum code lengths.
374		- This constraint complicates the algorithm for computing code
375		- lengths from symbol frequencies. Again, see Chapter 5,
376		- references for details.
377		-
378		- 3.2.2. Use of Huffman coding in the "deflate" format
379		-
380		- The Huffman codes used for each alphabet in the "deflate"
381		- format have two additional rules:
382		-
383		- * All codes of a given bit length have lexicographically
384		- consecutive values, in the same order as the symbols
385		- they represent;
386		-
387		- * Shorter codes lexicographically precede longer codes.
388		-
389		-
390		-
391		-
392		-
393		-
394		-
395		-
396		-
397		-
398		-
399		-
400		-Deutsch Informational [Page 7]
401		-
402		-
403		-RFC 1951 DEFLATE Compressed Data Format Specification May 1996
404		-
405		-
406		- We could recode the example above to follow this rule as
407		- follows, assuming that the order of the alphabet is ABCD:
408		-
409		- Symbol Code
410		- ------ ----
411		- A 10
412		- B 0
413		- C 110
414		- D 111
415		-
416		- I.e., 0 precedes 10 which precedes 11x, and 110 and 111 are
417		- lexicographically consecutive.
418		-
419		- Given this rule, we can define the Huffman code for an alphabet
420		- just by giving the bit lengths of the codes for each symbol of
421		- the alphabet in order; this is sufficient to determine the
422		- actual codes. In our example, the code is completely defined
423		- by the sequence of bit lengths (2, 1, 3, 3). The following
424		- algorithm generates the codes as integers, intended to be read
425		- from most- to least-significant bit. The code lengths are
426		- initially in tree[I].Len; the codes are produced in
427		- tree[I].Code.
428		-
429		- 1) Count the number of codes for each code length. Let
430		- bl_count[N] be the number of codes of length N, N >= 1.
431		-
432		- 2) Find the numerical value of the smallest code for each
433		- code length:
434		-
435		- code = 0;
436		- bl_count[0] = 0;
437		- for (bits = 1; bits <= MAX_BITS; bits++) {
438		- code = (code + bl_count[bits-1]) << 1;
439		- next_code[bits] = code;
440		- }
441		-
442		- 3) Assign numerical values to all codes, using consecutive
443		- values for all codes of the same length with the base
444		- values determined at step 2. Codes that are never used
445		- (which have a bit length of zero) must not be assigned a
446		- value.
447		-
448		- for (n = 0; n <= max_code; n++) {
449		- len = tree[n].Len;
450		- if (len != 0) {
451		- tree[n].Code = next_code[len];
452		- next_code[len]++;
453		- }
454		-
455		-
456		-
457		-Deutsch Informational [Page 8]
458		-
459		-
460		-RFC 1951 DEFLATE Compressed Data Format Specification May 1996
461		-
462		-
463		- }
464		-
465		- Example:
466		-
467		- Consider the alphabet ABCDEFGH, with bit lengths (3, 3, 3, 3,
468		- 3, 2, 4, 4). After step 1, we have:
469		-
470		- N bl_count[N]
471		- - -----------
472		- 2 1
473		- 3 5
474		- 4 2
475		-
476		- Step 2 computes the following next_code values:
477		-
478		- N next_code[N]
479		- - ------------
480		- 1 0
481		- 2 0
482		- 3 2
483		- 4 14
484		-
485		- Step 3 produces the following code values:
486		-
487		- Symbol Length Code
488		- ------ ------ ----
489		- A 3 010
490		- B 3 011
491		- C 3 100
492		- D 3 101
493		- E 3 110
494		- F 2 00
495		- G 4 1110
496		- H 4 1111
497		-
498		- 3.2.3. Details of block format
499		-
500		- Each block of compressed data begins with 3 header bits
501		- containing the following data:
502		-
503		- first bit BFINAL
504		- next 2 bits BTYPE
505		-
506		- Note that the header bits do not necessarily begin on a byte
507		- boundary, since a block does not necessarily occupy an integral
508		- number of bytes.
509		-
510		-
511		-
512		-
513		-
514		-Deutsch Informational [Page 9]
515		-
516		-
517		-RFC 1951 DEFLATE Compressed Data Format Specification May 1996
518		-
519		-
520		- BFINAL is set if and only if this is the last block of the data
521		- set.
522		-
523		- BTYPE specifies how the data are compressed, as follows:
524		-
525		- 00 - no compression
526		- 01 - compressed with fixed Huffman codes
527		- 10 - compressed with dynamic Huffman codes
528		- 11 - reserved (error)
529		-
530		- The only difference between the two compressed cases is how the
531		- Huffman codes for the literal/length and distance alphabets are
532		- defined.
533		-
534		- In all cases, the decoding algorithm for the actual data is as
535		- follows:
536		-
537		- do
538		- read block header from input stream.
539		- if stored with no compression
540		- skip any remaining bits in current partially
541		- processed byte
542		- read LEN and NLEN (see next section)
543		- copy LEN bytes of data to output
544		- otherwise
545		- if compressed with dynamic Huffman codes
546		- read representation of code trees (see
547		- subsection below)
548		- loop (until end of block code recognized)
549		- decode literal/length value from input stream
550		- if value < 256
551		- copy value (literal byte) to output stream
552		- otherwise
553		- if value = end of block (256)
554		- break from loop
555		- otherwise (value = 257..285)
556		- decode distance from input stream
557		-
558		- move backwards distance bytes in the output
559		- stream, and copy length bytes from this
560		- position to the output stream.
561		- end loop
562		- while not last block
563		-
564		- Note that a duplicated string reference may refer to a string
565		- in a previous block; i.e., the backward distance may cross one
566		- or more block boundaries. However a distance cannot refer past
567		- the beginning of the output stream. (An application using a
568		-
569		-
570		-
571		-Deutsch Informational [Page 10]
572		-
573		-
574		-RFC 1951 DEFLATE Compressed Data Format Specification May 1996
575		-
576		-
577		- preset dictionary might discard part of the output stream; a
578		- distance can refer to that part of the output stream anyway)
579		- Note also that the referenced string may overlap the current
580		- position; for example, if the last 2 bytes decoded have values
581		- X and Y, a string reference with <length = 5, distance = 2>
582		- adds X,Y,X,Y,X to the output stream.
583		-
584		- We now specify each compression method in turn.
585		-
586		- 3.2.4. Non-compressed blocks (BTYPE=00)
587		-
588		- Any bits of input up to the next byte boundary are ignored.
589		- The rest of the block consists of the following information:
590		-
591		- 0 1 2 3 4...
592		- +---+---+---+---+================================+
593		- \| LEN \| NLEN \|... LEN bytes of literal data...\|
594		- +---+---+---+---+================================+
595		-
596		- LEN is the number of data bytes in the block. NLEN is the
597		- one's complement of LEN.
598		-
599		- 3.2.5. Compressed blocks (length and distance codes)
600		-
601		- As noted above, encoded data blocks in the "deflate" format
602		- consist of sequences of symbols drawn from three conceptually
603		- distinct alphabets: either literal bytes, from the alphabet of
604		- byte values (0..255), or <length, backward distance> pairs,
605		- where the length is drawn from (3..258) and the distance is
606		- drawn from (1..32,768). In fact, the literal and length
607		- alphabets are merged into a single alphabet (0..285), where
608		- values 0..255 represent literal bytes, the value 256 indicates
609		- end-of-block, and values 257..285 represent length codes
610		- (possibly in conjunction with extra bits following the symbol
611		- code) as follows:
612		-
613		-
614		-
615		-
616		-
617		-
618		-
619		-
620		-
621		-
622		-
623		-
624		-
625		-
626		-
627		-
628		-Deutsch Informational [Page 11]
629		-
630		-
631		-RFC 1951 DEFLATE Compressed Data Format Specification May 1996
632		-
633		-
634		- Extra Extra Extra
635		- Code Bits Length(s) Code Bits Lengths Code Bits Length(s)
636		- ---- ---- ------ ---- ---- ------- ---- ---- -------
637		- 257 0 3 267 1 15,16 277 4 67-82
638		- 258 0 4 268 1 17,18 278 4 83-98
639		- 259 0 5 269 2 19-22 279 4 99-114
640		- 260 0 6 270 2 23-26 280 4 115-130
641		- 261 0 7 271 2 27-30 281 5 131-162
642		- 262 0 8 272 2 31-34 282 5 163-194
643		- 263 0 9 273 3 35-42 283 5 195-226
644		- 264 0 10 274 3 43-50 284 5 227-257
645		- 265 1 11,12 275 3 51-58 285 0 258
646		- 266 1 13,14 276 3 59-66
647		-
648		- The extra bits should be interpreted as a machine integer
649		- stored with the most-significant bit first, e.g., bits 1110
650		- represent the value 14.
651		-
652		- Extra Extra Extra
653		- Code Bits Dist Code Bits Dist Code Bits Distance
654		- ---- ---- ---- ---- ---- ------ ---- ---- --------
655		- 0 0 1 10 4 33-48 20 9 1025-1536
656		- 1 0 2 11 4 49-64 21 9 1537-2048
657		- 2 0 3 12 5 65-96 22 10 2049-3072
658		- 3 0 4 13 5 97-128 23 10 3073-4096
659		- 4 1 5,6 14 6 129-192 24 11 4097-6144
660		- 5 1 7,8 15 6 193-256 25 11 6145-8192
661		- 6 2 9-12 16 7 257-384 26 12 8193-12288
662		- 7 2 13-16 17 7 385-512 27 12 12289-16384
663		- 8 3 17-24 18 8 513-768 28 13 16385-24576
664		- 9 3 25-32 19 8 769-1024 29 13 24577-32768
665		-
666		- 3.2.6. Compression with fixed Huffman codes (BTYPE=01)
667		-
668		- The Huffman codes for the two alphabets are fixed, and are not
669		- represented explicitly in the data. The Huffman code lengths
670		- for the literal/length alphabet are:
671		-
672		- Lit Value Bits Codes
673		- --------- ---- -----
674		- 0 - 143 8 00110000 through
675		- 10111111
676		- 144 - 255 9 110010000 through
677		- 111111111
678		- 256 - 279 7 0000000 through
679		- 0010111
680		- 280 - 287 8 11000000 through
681		- 11000111
682		-
683		-
684		-
685		-Deutsch Informational [Page 12]
686		-
687		-
688		-RFC 1951 DEFLATE Compressed Data Format Specification May 1996
689		-
690		-
691		- The code lengths are sufficient to generate the actual codes,
692		- as described above; we show the codes in the table for added
693		- clarity. Literal/length values 286-287 will never actually
694		- occur in the compressed data, but participate in the code
695		- construction.
696		-
697		- Distance codes 0-31 are represented by (fixed-length) 5-bit
698		- codes, with possible additional bits as shown in the table
699		- shown in Paragraph 3.2.5, above. Note that distance codes 30-
700		- 31 will never actually occur in the compressed data.
701		-
702		- 3.2.7. Compression with dynamic Huffman codes (BTYPE=10)
703		-
704		- The Huffman codes for the two alphabets appear in the block
705		- immediately after the header bits and before the actual
706		- compressed data, first the literal/length code and then the
707		- distance code. Each code is defined by a sequence of code
708		- lengths, as discussed in Paragraph 3.2.2, above. For even
709		- greater compactness, the code length sequences themselves are
710		- compressed using a Huffman code. The alphabet for code lengths
711		- is as follows:
712		-
713		- 0 - 15: Represent code lengths of 0 - 15
714		- 16: Copy the previous code length 3 - 6 times.
715		- The next 2 bits indicate repeat length
716		- (0 = 3, ... , 3 = 6)
717		- Example: Codes 8, 16 (+2 bits 11),
718		- 16 (+2 bits 10) will expand to
719		- 12 code lengths of 8 (1 + 6 + 5)
720		- 17: Repeat a code length of 0 for 3 - 10 times.
721		- (3 bits of length)
722		- 18: Repeat a code length of 0 for 11 - 138 times
723		- (7 bits of length)
724		-
725		- A code length of 0 indicates that the corresponding symbol in
726		- the literal/length or distance alphabet will not occur in the
727		- block, and should not participate in the Huffman code
728		- construction algorithm given earlier. If only one distance
729		- code is used, it is encoded using one bit, not zero bits; in
730		- this case there is a single code length of one, with one unused
731		- code. One distance code of zero bits means that there are no
732		- distance codes used at all (the data is all literals).
733		-
734		- We can now define the format of the block:
735		-
736		- 5 Bits: HLIT, # of Literal/Length codes - 257 (257 - 286)
737		- 5 Bits: HDIST, # of Distance codes - 1 (1 - 32)
738		- 4 Bits: HCLEN, # of Code Length codes - 4 (4 - 19)
739		-
740		-
741		-
742		-Deutsch Informational [Page 13]
743		-
744		-
745		-RFC 1951 DEFLATE Compressed Data Format Specification May 1996
746		-
747		-
748		- (HCLEN + 4) x 3 bits: code lengths for the code length
749		- alphabet given just above, in the order: 16, 17, 18,
750		- 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15
751		-
752		- These code lengths are interpreted as 3-bit integers
753		- (0-7); as above, a code length of 0 means the
754		- corresponding symbol (literal/length or distance code
755		- length) is not used.
756		-
757		- HLIT + 257 code lengths for the literal/length alphabet,
758		- encoded using the code length Huffman code
759		-
760		- HDIST + 1 code lengths for the distance alphabet,
761		- encoded using the code length Huffman code
762		-
763		- The actual compressed data of the block,
764		- encoded using the literal/length and distance Huffman
765		- codes
766		-
767		- The literal/length symbol 256 (end of data),
768		- encoded using the literal/length Huffman code
769		-
770		- The code length repeat codes can cross from HLIT + 257 to the
771		- HDIST + 1 code lengths. In other words, all code lengths form
772		- a single sequence of HLIT + HDIST + 258 values.
773		-
774		- 3.3. Compliance
775		-
776		- A compressor may limit further the ranges of values specified in
777		- the previous section and still be compliant; for example, it may
778		- limit the range of backward pointers to some value smaller than
779		- 32K. Similarly, a compressor may limit the size of blocks so that
780		- a compressible block fits in memory.
781		-
782		- A compliant decompressor must accept the full range of possible
783		- values defined in the previous section, and must accept blocks of
784		- arbitrary size.
785		-
786		-4. Compression algorithm details
787		-
788		- While it is the intent of this document to define the "deflate"
789		- compressed data format without reference to any particular
790		- compression algorithm, the format is related to the compressed
791		- formats produced by LZ77 (Lempel-Ziv 1977, see reference [2] below);
792		- since many variations of LZ77 are patented, it is strongly
793		- recommended that the implementor of a compressor follow the general
794		- algorithm presented here, which is known not to be patented per se.
795		- The material in this section is not part of the definition of the
796		-
797		-
798		-
799		-Deutsch Informational [Page 14]
800		-
801		-
802		-RFC 1951 DEFLATE Compressed Data Format Specification May 1996
803		-
804		-
805		- specification per se, and a compressor need not follow it in order to
806		- be compliant.
807		-
808		- The compressor terminates a block when it determines that starting a
809		- new block with fresh trees would be useful, or when the block size
810		- fills up the compressor's block buffer.
811		-
812		- The compressor uses a chained hash table to find duplicated strings,
813		- using a hash function that operates on 3-byte sequences. At any
814		- given point during compression, let XYZ be the next 3 input bytes to
815		- be examined (not necessarily all different, of course). First, the
816		- compressor examines the hash chain for XYZ. If the chain is empty,
817		- the compressor simply writes out X as a literal byte and advances one
818		- byte in the input. If the hash chain is not empty, indicating that
819		- the sequence XYZ (or, if we are unlucky, some other 3 bytes with the
820		- same hash function value) has occurred recently, the compressor
821		- compares all strings on the XYZ hash chain with the actual input data
822		- sequence starting at the current point, and selects the longest
823		- match.
824		-
825		- The compressor searches the hash chains starting with the most recent
826		- strings, to favor small distances and thus take advantage of the
827		- Huffman encoding. The hash chains are singly linked. There are no
828		- deletions from the hash chains; the algorithm simply discards matches
829		- that are too old. To avoid a worst-case situation, very long hash
830		- chains are arbitrarily truncated at a certain length, determined by a
831		- run-time parameter.
832		-
833		- To improve overall compression, the compressor optionally defers the
834		- selection of matches ("lazy matching"): after a match of length N has
835		- been found, the compressor searches for a longer match starting at
836		- the next input byte. If it finds a longer match, it truncates the
837		- previous match to a length of one (thus producing a single literal
838		- byte) and then emits the longer match. Otherwise, it emits the
839		- original match, and, as described above, advances N bytes before
840		- continuing.
841		-
842		- Run-time parameters also control this "lazy match" procedure. If
843		- compression ratio is most important, the compressor attempts a
844		- complete second search regardless of the length of the first match.
845		- In the normal case, if the current match is "long enough", the
846		- compressor reduces the search for a longer match, thus speeding up
847		- the process. If speed is most important, the compressor inserts new
848		- strings in the hash table only when no match was found, or when the
849		- match is not "too long". This degrades the compression ratio but
850		- saves time since there are both fewer insertions and fewer searches.
851		-
852		-
853		-
854		-
855		-
856		-Deutsch Informational [Page 15]
857		-
858		-
859		-RFC 1951 DEFLATE Compressed Data Format Specification May 1996
860		-
861		-
862		-5. References
863		-
864		- [1] Huffman, D. A., "A Method for the Construction of Minimum
865		- Redundancy Codes", Proceedings of the Institute of Radio
866		- Engineers, September 1952, Volume 40, Number 9, pp. 1098-1101.
867		-
868		- [2] Ziv J., Lempel A., "A Universal Algorithm for Sequential Data
869		- Compression", IEEE Transactions on Information Theory, Vol. 23,
870		- No. 3, pp. 337-343.
871		-
872		- [3] Gailly, J.-L., and Adler, M., ZLIB documentation and sources,
873		- available in ftp://ftp.uu.net/pub/archiving/zip/doc/
874		-
875		- [4] Gailly, J.-L., and Adler, M., GZIP documentation and sources,
876		- available as gzip-*.tar in ftp://prep.ai.mit.edu/pub/gnu/
877		-
878		- [5] Schwartz, E. S., and Kallick, B. "Generating a canonical prefix
879		- encoding." Comm. ACM, 7,3 (Mar. 1964), pp. 166-169.
880		-
881		- [6] Hirschberg and Lelewer, "Efficient decoding of prefix codes,"
882		- Comm. ACM, 33,4, April 1990, pp. 449-459.
883		-
884		-6. Security Considerations
885		-
886		- Any data compression method involves the reduction of redundancy in
887		- the data. Consequently, any corruption of the data is likely to have
888		- severe effects and be difficult to correct. Uncompressed text, on
889		- the other hand, will probably still be readable despite the presence
890		- of some corrupted bytes.
891		-
892		- It is recommended that systems using this data format provide some
893		- means of validating the integrity of the compressed data. See
894		- reference [3], for example.
895		-
896		-7. Source code
897		-
898		- Source code for a C language implementation of a "deflate" compliant
899		- compressor and decompressor is available within the zlib package at
900		- ftp://ftp.uu.net/pub/archiving/zip/zlib/.
901		-
902		-8. Acknowledgements
903		-
904		- Trademarks cited in this document are the property of their
905		- respective owners.
906		-
907		- Phil Katz designed the deflate format. Jean-Loup Gailly and Mark
908		- Adler wrote the related software described in this specification.
909		- Glenn Randers-Pehrson converted this document to RFC and HTML format.
910		-
911		-
912		-
913		-Deutsch Informational [Page 16]
914		-
915		-
916		-RFC 1951 DEFLATE Compressed Data Format Specification May 1996
917		-
918		-
919		-9. Author's Address
920		-
921		- L. Peter Deutsch
922		- Aladdin Enterprises
923		- 203 Santa Margarita Ave.
924		- Menlo Park, CA 94025
925		-
926		- Phone: (415) 322-0103 (AM only)
927		- FAX: (415) 322-1734
928		- EMail: <[email protected]>
929		-
930		- Questions about the technical content of this specification can be
931		- sent by email to:
932		-
933		- Jean-Loup Gailly <[email protected]> and
934		- Mark Adler <[email protected]>
935		-
936		- Editorial comments on this specification can be sent by email to:
937		-
938		- L. Peter Deutsch <[email protected]> and
939		- Glenn Randers-Pehrson <[email protected]>
940		-
941		-
942		-
943		-
944		-
945		-
946		-
947		-
948		-
949		-
950		-
951		-
952		-
953		-
954		-
955		-
956		-
957		-
958		-
959		-
960		-
961		-
962		-
963		-
964		-
965		-
966		-
967		-
968		-
969		-
970		-Deutsch Informational [Page 17]
971		-
972		-

	--- a/compat/zlib/doc/rfc1951.txt
	+++ b/compat/zlib/doc/rfc1951.txt
	@@ -1,972 +0,0 @@
1
2
3
4
5
6
7	Network Working Group P. Deutsch
8	Request for Comments: 1951 Aladdin Enterprises
9	Category: Informational May 1996
10
11
12	DEFLATE Compressed Data Format Specification version 1.3
13
14	Status of This Memo
15
16	This memo provides information for the Internet community. This memo
17	does not specify an Internet standard of any kind. Distribution of
18	this memo is unlimited.
19
20	IESG Note:
21
22	The IESG takes no position on the validity of any Intellectual
23	Property Rights statements contained in this document.
24
25	Notices
26
27	Copyright (c) 1996 L. Peter Deutsch
28
29	Permission is granted to copy and distribute this document for any
30	purpose and without charge, including translations into other
31	languages and incorporation into compilations, provided that the
32	copyright notice and this notice are preserved, and that any
33	substantive changes or deletions from the original are clearly
34	marked.
35
36	A pointer to the latest version of this and related documentation in
37	HTML format can be found at the URL
38	<ftp://ftp.uu.net/graphics/png/documents/zlib/zdoc-index.html>.
39
40	Abstract
41
42	This specification defines a lossless compressed data format that
43	compresses data using a combination of the LZ77 algorithm and Huffman
44	coding, with efficiency comparable to the best currently available
45	general-purpose compression methods. The data can be produced or
46	consumed, even for an arbitrarily long sequentially presented input
47	data stream, using only an a priori bounded amount of intermediate
48	storage. The format can be implemented readily in a manner not
49	covered by patents.
50
51
52
53
54
55
56
57
58	Deutsch Informational [Page 1]
59
60
61	RFC 1951 DEFLATE Compressed Data Format Specification May 1996
62
63
64	Table of Contents
65
66	1. Introduction ................................................... 2
67	1.1. Purpose ................................................... 2
68	1.2. Intended audience ......................................... 3
69	1.3. Scope ..................................................... 3
70	1.4. Compliance ................................................ 3
71	1.5. Definitions of terms and conventions used ................ 3
72	1.6. Changes from previous versions ............................ 4
73	2. Compressed representation overview ............................. 4
74	3. Detailed specification ......................................... 5
75	3.1. Overall conventions ....................................... 5
76	3.1.1. Packing into bytes .................................. 5
77	3.2. Compressed block format ................................... 6
78	3.2.1. Synopsis of prefix and Huffman coding ............... 6
79	3.2.2. Use of Huffman coding in the "deflate" format ....... 7
80	3.2.3. Details of block format ............................. 9
81	3.2.4. Non-compressed blocks (BTYPE=00) ................... 11
82	3.2.5. Compressed blocks (length and distance codes) ...... 11
83	3.2.6. Compression with fixed Huffman codes (BTYPE=01) .... 12
84	3.2.7. Compression with dynamic Huffman codes (BTYPE=10) .. 13
85	3.3. Compliance ............................................... 14
86	4. Compression algorithm details ................................. 14
87	5. References .................................................... 16
88	6. Security Considerations ....................................... 16
89	7. Source code ................................................... 16
90	8. Acknowledgements .............................................. 16
91	9. Author's Address .............................................. 17
92
93	1. Introduction
94
95	1.1. Purpose
96
97	The purpose of this specification is to define a lossless
98	compressed data format that:
99	* Is independent of CPU type, operating system, file system,
100	and character set, and hence can be used for interchange;
101	* Can be produced or consumed, even for an arbitrarily long
102	sequentially presented input data stream, using only an a
103	priori bounded amount of intermediate storage, and hence
104	can be used in data communications or similar structures
105	such as Unix filters;
106	* Compresses data with efficiency comparable to the best
107	currently available general-purpose compression methods,
108	and in particular considerably better than the "compress"
109	program;
110	* Can be implemented readily in a manner not covered by
111	patents, and hence can be practiced freely;
112
113
114
115	Deutsch Informational [Page 2]
116
117
118	RFC 1951 DEFLATE Compressed Data Format Specification May 1996
119
120
121	* Is compatible with the file format produced by the current
122	widely used gzip utility, in that conforming decompressors
123	will be able to read data produced by the existing gzip
124	compressor.
125
126	The data format defined by this specification does not attempt to:
127
128	* Allow random access to compressed data;
129	* Compress specialized data (e.g., raster graphics) as well
130	as the best currently available specialized algorithms.
131
132	A simple counting argument shows that no lossless compression
133	algorithm can compress every possible input data set. For the
134	format defined here, the worst case expansion is 5 bytes per 32K-
135	byte block, i.e., a size increase of 0.015% for large data sets.
136	English text usually compresses by a factor of 2.5 to 3;
137	executable files usually compress somewhat less; graphical data
138	such as raster images may compress much more.
139
140	1.2. Intended audience
141
142	This specification is intended for use by implementors of software
143	to compress data into "deflate" format and/or decompress data from
144	"deflate" format.
145
146	The text of the specification assumes a basic background in
147	programming at the level of bits and other primitive data
148	representations. Familiarity with the technique of Huffman coding
149	is helpful but not required.
150
151	1.3. Scope
152
153	The specification specifies a method for representing a sequence
154	of bytes as a (usually shorter) sequence of bits, and a method for
155	packing the latter bit sequence into bytes.
156
157	1.4. Compliance
158
159	Unless otherwise indicated below, a compliant decompressor must be
160	able to accept and decompress any data set that conforms to all
161	the specifications presented here; a compliant compressor must
162	produce data sets that conform to all the specifications presented
163	here.
164
165	1.5. Definitions of terms and conventions used
166
167	Byte: 8 bits stored or transmitted as a unit (same as an octet).
168	For this specification, a byte is exactly 8 bits, even on machines
169
170
171
172	Deutsch Informational [Page 3]
173
174
175	RFC 1951 DEFLATE Compressed Data Format Specification May 1996
176
177
178	which store a character on a number of bits different from eight.
179	See below, for the numbering of bits within a byte.
180
181	String: a sequence of arbitrary bytes.
182
183	1.6. Changes from previous versions
184
185	There have been no technical changes to the deflate format since
186	version 1.1 of this specification. In version 1.2, some
187	terminology was changed. Version 1.3 is a conversion of the
188	specification to RFC style.
189
190	2. Compressed representation overview
191
192	A compressed data set consists of a series of blocks, corresponding
193	to successive blocks of input data. The block sizes are arbitrary,
194	except that non-compressible blocks are limited to 65,535 bytes.
195
196	Each block is compressed using a combination of the LZ77 algorithm
197	and Huffman coding. The Huffman trees for each block are independent
198	of those for previous or subsequent blocks; the LZ77 algorithm may
199	use a reference to a duplicated string occurring in a previous block,
200	up to 32K input bytes before.
201
202	Each block consists of two parts: a pair of Huffman code trees that
203	describe the representation of the compressed data part, and a
204	compressed data part. (The Huffman trees themselves are compressed
205	using Huffman encoding.) The compressed data consists of a series of
206	elements of two types: literal bytes (of strings that have not been
207	detected as duplicated within the previous 32K input bytes), and
208	pointers to duplicated strings, where a pointer is represented as a
209	pair <length, backward distance>. The representation used in the
210	"deflate" format limits distances to 32K bytes and lengths to 258
211	bytes, but does not limit the size of a block, except for
212	uncompressible blocks, which are limited as noted above.
213
214	Each type of value (literals, distances, and lengths) in the
215	compressed data is represented using a Huffman code, using one code
216	tree for literals and lengths and a separate code tree for distances.
217	The code trees for each block appear in a compact form just before
218	the compressed data for that block.
219
220
221
222
223
224
225
226
227
228
229	Deutsch Informational [Page 4]
230
231
232	RFC 1951 DEFLATE Compressed Data Format Specification May 1996
233
234
235	3. Detailed specification
236
237	3.1. Overall conventions In the diagrams below, a box like this:
238
239	+---+
240	\| \| <-- the vertical bars might be missing
241	+---+
242
243	represents one byte; a box like this:
244
245	+==============+
246	\| \|
247	+==============+
248
249	represents a variable number of bytes.
250
251	Bytes stored within a computer do not have a "bit order", since
252	they are always treated as a unit. However, a byte considered as
253	an integer between 0 and 255 does have a most- and least-
254	significant bit, and since we write numbers with the most-
255	significant digit on the left, we also write bytes with the most-
256	significant bit on the left. In the diagrams below, we number the
257	bits of a byte so that bit 0 is the least-significant bit, i.e.,
258	the bits are numbered:
259
260	+--------+
261	\|76543210\|
262	+--------+
263
264	Within a computer, a number may occupy multiple bytes. All
265	multi-byte numbers in the format described here are stored with
266	the least-significant byte first (at the lower memory address).
267	For example, the decimal number 520 is stored as:
268
269	0 1
270	+--------+--------+
271	\|00001000\|00000010\|
272	+--------+--------+
273	^ ^
274	\| \|
275	\| + more significant byte = 2 x 256
276	+ less significant byte = 8
277
278	3.1.1. Packing into bytes
279
280	This document does not address the issue of the order in which
281	bits of a byte are transmitted on a bit-sequential medium,
282	since the final data format described here is byte- rather than
283
284
285
286	Deutsch Informational [Page 5]
287
288
289	RFC 1951 DEFLATE Compressed Data Format Specification May 1996
290
291
292	bit-oriented. However, we describe the compressed block format
293	in below, as a sequence of data elements of various bit
294	lengths, not a sequence of bytes. We must therefore specify
295	how to pack these data elements into bytes to form the final
296	compressed byte sequence:
297
298	* Data elements are packed into bytes in order of
299	increasing bit number within the byte, i.e., starting
300	with the least-significant bit of the byte.
301	* Data elements other than Huffman codes are packed
302	starting with the least-significant bit of the data
303	element.
304	* Huffman codes are packed starting with the most-
305	significant bit of the code.
306
307	In other words, if one were to print out the compressed data as
308	a sequence of bytes, starting with the first byte at the
309	right margin and proceeding to the left, with the most-
310	significant bit of each byte on the left as usual, one would be
311	able to parse the result from right to left, with fixed-width
312	elements in the correct MSB-to-LSB order and Huffman codes in
313	bit-reversed order (i.e., with the first bit of the code in the
314	relative LSB position).
315
316	3.2. Compressed block format
317
318	3.2.1. Synopsis of prefix and Huffman coding
319
320	Prefix coding represents symbols from an a priori known
321	alphabet by bit sequences (codes), one code for each symbol, in
322	a manner such that different symbols may be represented by bit
323	sequences of different lengths, but a parser can always parse
324	an encoded string unambiguously symbol-by-symbol.
325
326	We define a prefix code in terms of a binary tree in which the
327	two edges descending from each non-leaf node are labeled 0 and
328	1 and in which the leaf nodes correspond one-for-one with (are
329	labeled with) the symbols of the alphabet; then the code for a
330	symbol is the sequence of 0's and 1's on the edges leading from
331	the root to the leaf labeled with that symbol. For example:
332
333
334
335
336
337
338
339
340
341
342
343	Deutsch Informational [Page 6]
344
345
346	RFC 1951 DEFLATE Compressed Data Format Specification May 1996
347
348
349	/\ Symbol Code
350	0 1 ------ ----
351	/ \ A 00
352	/\ B B 1
353	0 1 C 011
354	/ \ D 010
355	A /\
356	0 1
357	/ \
358	D C
359
360	A parser can decode the next symbol from an encoded input
361	stream by walking down the tree from the root, at each step
362	choosing the edge corresponding to the next input bit.
363
364	Given an alphabet with known symbol frequencies, the Huffman
365	algorithm allows the construction of an optimal prefix code
366	(one which represents strings with those symbol frequencies
367	using the fewest bits of any possible prefix codes for that
368	alphabet). Such a code is called a Huffman code. (See
369	reference [1] in Chapter 5, references for additional
370	information on Huffman codes.)
371
372	Note that in the "deflate" format, the Huffman codes for the
373	various alphabets must not exceed certain maximum code lengths.
374	This constraint complicates the algorithm for computing code
375	lengths from symbol frequencies. Again, see Chapter 5,
376	references for details.
377
378	3.2.2. Use of Huffman coding in the "deflate" format
379
380	The Huffman codes used for each alphabet in the "deflate"
381	format have two additional rules:
382
383	* All codes of a given bit length have lexicographically
384	consecutive values, in the same order as the symbols
385	they represent;
386
387	* Shorter codes lexicographically precede longer codes.
388
389
390
391
392
393
394
395
396
397
398
399
400	Deutsch Informational [Page 7]
401
402
403	RFC 1951 DEFLATE Compressed Data Format Specification May 1996
404
405
406	We could recode the example above to follow this rule as
407	follows, assuming that the order of the alphabet is ABCD:
408
409	Symbol Code
410	------ ----
411	A 10
412	B 0
413	C 110
414	D 111
415
416	I.e., 0 precedes 10 which precedes 11x, and 110 and 111 are
417	lexicographically consecutive.
418
419	Given this rule, we can define the Huffman code for an alphabet
420	just by giving the bit lengths of the codes for each symbol of
421	the alphabet in order; this is sufficient to determine the
422	actual codes. In our example, the code is completely defined
423	by the sequence of bit lengths (2, 1, 3, 3). The following
424	algorithm generates the codes as integers, intended to be read
425	from most- to least-significant bit. The code lengths are
426	initially in tree[I].Len; the codes are produced in
427	tree[I].Code.
428
429	1) Count the number of codes for each code length. Let
430	bl_count[N] be the number of codes of length N, N >= 1.
431
432	2) Find the numerical value of the smallest code for each
433	code length:
434
435	code = 0;
436	bl_count[0] = 0;
437	for (bits = 1; bits <= MAX_BITS; bits++) {
438	code = (code + bl_count[bits-1]) << 1;
439	next_code[bits] = code;
440	}
441
442	3) Assign numerical values to all codes, using consecutive
443	values for all codes of the same length with the base
444	values determined at step 2. Codes that are never used
445	(which have a bit length of zero) must not be assigned a
446	value.
447
448	for (n = 0; n <= max_code; n++) {
449	len = tree[n].Len;
450	if (len != 0) {
451	tree[n].Code = next_code[len];
452	next_code[len]++;
453	}
454
455
456
457	Deutsch Informational [Page 8]
458
459
460	RFC 1951 DEFLATE Compressed Data Format Specification May 1996
461
462
463	}
464
465	Example:
466
467	Consider the alphabet ABCDEFGH, with bit lengths (3, 3, 3, 3,
468	3, 2, 4, 4). After step 1, we have:
469
470	N bl_count[N]
471	- -----------
472	2 1
473	3 5
474	4 2
475
476	Step 2 computes the following next_code values:
477
478	N next_code[N]
479	- ------------
480	1 0
481	2 0
482	3 2
483	4 14
484
485	Step 3 produces the following code values:
486
487	Symbol Length Code
488	------ ------ ----
489	A 3 010
490	B 3 011
491	C 3 100
492	D 3 101
493	E 3 110
494	F 2 00
495	G 4 1110
496	H 4 1111
497
498	3.2.3. Details of block format
499
500	Each block of compressed data begins with 3 header bits
501	containing the following data:
502
503	first bit BFINAL
504	next 2 bits BTYPE
505
506	Note that the header bits do not necessarily begin on a byte
507	boundary, since a block does not necessarily occupy an integral
508	number of bytes.
509
510
511
512
513
514	Deutsch Informational [Page 9]
515
516
517	RFC 1951 DEFLATE Compressed Data Format Specification May 1996
518
519
520	BFINAL is set if and only if this is the last block of the data
521	set.
522
523	BTYPE specifies how the data are compressed, as follows:
524
525	00 - no compression
526	01 - compressed with fixed Huffman codes
527	10 - compressed with dynamic Huffman codes
528	11 - reserved (error)
529
530	The only difference between the two compressed cases is how the
531	Huffman codes for the literal/length and distance alphabets are
532	defined.
533
534	In all cases, the decoding algorithm for the actual data is as
535	follows:
536
537	do
538	read block header from input stream.
539	if stored with no compression
540	skip any remaining bits in current partially
541	processed byte
542	read LEN and NLEN (see next section)
543	copy LEN bytes of data to output
544	otherwise
545	if compressed with dynamic Huffman codes
546	read representation of code trees (see
547	subsection below)
548	loop (until end of block code recognized)
549	decode literal/length value from input stream
550	if value < 256
551	copy value (literal byte) to output stream
552	otherwise
553	if value = end of block (256)
554	break from loop
555	otherwise (value = 257..285)
556	decode distance from input stream
557
558	move backwards distance bytes in the output
559	stream, and copy length bytes from this
560	position to the output stream.
561	end loop
562	while not last block
563
564	Note that a duplicated string reference may refer to a string
565	in a previous block; i.e., the backward distance may cross one
566	or more block boundaries. However a distance cannot refer past
567	the beginning of the output stream. (An application using a
568
569
570
571	Deutsch Informational [Page 10]
572
573
574	RFC 1951 DEFLATE Compressed Data Format Specification May 1996
575
576
577	preset dictionary might discard part of the output stream; a
578	distance can refer to that part of the output stream anyway)
579	Note also that the referenced string may overlap the current
580	position; for example, if the last 2 bytes decoded have values
581	X and Y, a string reference with <length = 5, distance = 2>
582	adds X,Y,X,Y,X to the output stream.
583
584	We now specify each compression method in turn.
585
586	3.2.4. Non-compressed blocks (BTYPE=00)
587
588	Any bits of input up to the next byte boundary are ignored.
589	The rest of the block consists of the following information:
590
591	0 1 2 3 4...
592	+---+---+---+---+================================+
593	\| LEN \| NLEN \|... LEN bytes of literal data...\|
594	+---+---+---+---+================================+
595
596	LEN is the number of data bytes in the block. NLEN is the
597	one's complement of LEN.
598
599	3.2.5. Compressed blocks (length and distance codes)
600
601	As noted above, encoded data blocks in the "deflate" format
602	consist of sequences of symbols drawn from three conceptually
603	distinct alphabets: either literal bytes, from the alphabet of
604	byte values (0..255), or <length, backward distance> pairs,
605	where the length is drawn from (3..258) and the distance is
606	drawn from (1..32,768). In fact, the literal and length
607	alphabets are merged into a single alphabet (0..285), where
608	values 0..255 represent literal bytes, the value 256 indicates
609	end-of-block, and values 257..285 represent length codes
610	(possibly in conjunction with extra bits following the symbol
611	code) as follows:
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628	Deutsch Informational [Page 11]
629
630
631	RFC 1951 DEFLATE Compressed Data Format Specification May 1996
632
633
634	Extra Extra Extra
635	Code Bits Length(s) Code Bits Lengths Code Bits Length(s)
636	---- ---- ------ ---- ---- ------- ---- ---- -------
637	257 0 3 267 1 15,16 277 4 67-82
638	258 0 4 268 1 17,18 278 4 83-98
639	259 0 5 269 2 19-22 279 4 99-114
640	260 0 6 270 2 23-26 280 4 115-130
641	261 0 7 271 2 27-30 281 5 131-162
642	262 0 8 272 2 31-34 282 5 163-194
643	263 0 9 273 3 35-42 283 5 195-226
644	264 0 10 274 3 43-50 284 5 227-257
645	265 1 11,12 275 3 51-58 285 0 258
646	266 1 13,14 276 3 59-66
647
648	The extra bits should be interpreted as a machine integer
649	stored with the most-significant bit first, e.g., bits 1110
650	represent the value 14.
651
652	Extra Extra Extra
653	Code Bits Dist Code Bits Dist Code Bits Distance
654	---- ---- ---- ---- ---- ------ ---- ---- --------
655	0 0 1 10 4 33-48 20 9 1025-1536
656	1 0 2 11 4 49-64 21 9 1537-2048
657	2 0 3 12 5 65-96 22 10 2049-3072
658	3 0 4 13 5 97-128 23 10 3073-4096
659	4 1 5,6 14 6 129-192 24 11 4097-6144
660	5 1 7,8 15 6 193-256 25 11 6145-8192
661	6 2 9-12 16 7 257-384 26 12 8193-12288
662	7 2 13-16 17 7 385-512 27 12 12289-16384
663	8 3 17-24 18 8 513-768 28 13 16385-24576
664	9 3 25-32 19 8 769-1024 29 13 24577-32768
665
666	3.2.6. Compression with fixed Huffman codes (BTYPE=01)
667
668	The Huffman codes for the two alphabets are fixed, and are not
669	represented explicitly in the data. The Huffman code lengths
670	for the literal/length alphabet are:
671
672	Lit Value Bits Codes
673	--------- ---- -----
674	0 - 143 8 00110000 through
675	10111111
676	144 - 255 9 110010000 through
677	111111111
678	256 - 279 7 0000000 through
679	0010111
680	280 - 287 8 11000000 through
681	11000111
682
683
684
685	Deutsch Informational [Page 12]
686
687
688	RFC 1951 DEFLATE Compressed Data Format Specification May 1996
689
690
691	The code lengths are sufficient to generate the actual codes,
692	as described above; we show the codes in the table for added
693	clarity. Literal/length values 286-287 will never actually
694	occur in the compressed data, but participate in the code
695	construction.
696
697	Distance codes 0-31 are represented by (fixed-length) 5-bit
698	codes, with possible additional bits as shown in the table
699	shown in Paragraph 3.2.5, above. Note that distance codes 30-
700	31 will never actually occur in the compressed data.
701
702	3.2.7. Compression with dynamic Huffman codes (BTYPE=10)
703
704	The Huffman codes for the two alphabets appear in the block
705	immediately after the header bits and before the actual
706	compressed data, first the literal/length code and then the
707	distance code. Each code is defined by a sequence of code
708	lengths, as discussed in Paragraph 3.2.2, above. For even
709	greater compactness, the code length sequences themselves are
710	compressed using a Huffman code. The alphabet for code lengths
711	is as follows:
712
713	0 - 15: Represent code lengths of 0 - 15
714	16: Copy the previous code length 3 - 6 times.
715	The next 2 bits indicate repeat length
716	(0 = 3, ... , 3 = 6)
717	Example: Codes 8, 16 (+2 bits 11),
718	16 (+2 bits 10) will expand to
719	12 code lengths of 8 (1 + 6 + 5)
720	17: Repeat a code length of 0 for 3 - 10 times.
721	(3 bits of length)
722	18: Repeat a code length of 0 for 11 - 138 times
723	(7 bits of length)
724
725	A code length of 0 indicates that the corresponding symbol in
726	the literal/length or distance alphabet will not occur in the
727	block, and should not participate in the Huffman code
728	construction algorithm given earlier. If only one distance
729	code is used, it is encoded using one bit, not zero bits; in
730	this case there is a single code length of one, with one unused
731	code. One distance code of zero bits means that there are no
732	distance codes used at all (the data is all literals).
733
734	We can now define the format of the block:
735
736	5 Bits: HLIT, # of Literal/Length codes - 257 (257 - 286)
737	5 Bits: HDIST, # of Distance codes - 1 (1 - 32)
738	4 Bits: HCLEN, # of Code Length codes - 4 (4 - 19)
739
740
741
742	Deutsch Informational [Page 13]
743
744
745	RFC 1951 DEFLATE Compressed Data Format Specification May 1996
746
747
748	(HCLEN + 4) x 3 bits: code lengths for the code length
749	alphabet given just above, in the order: 16, 17, 18,
750	0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15
751
752	These code lengths are interpreted as 3-bit integers
753	(0-7); as above, a code length of 0 means the
754	corresponding symbol (literal/length or distance code
755	length) is not used.
756
757	HLIT + 257 code lengths for the literal/length alphabet,
758	encoded using the code length Huffman code
759
760	HDIST + 1 code lengths for the distance alphabet,
761	encoded using the code length Huffman code
762
763	The actual compressed data of the block,
764	encoded using the literal/length and distance Huffman
765	codes
766
767	The literal/length symbol 256 (end of data),
768	encoded using the literal/length Huffman code
769
770	The code length repeat codes can cross from HLIT + 257 to the
771	HDIST + 1 code lengths. In other words, all code lengths form
772	a single sequence of HLIT + HDIST + 258 values.
773
774	3.3. Compliance
775
776	A compressor may limit further the ranges of values specified in
777	the previous section and still be compliant; for example, it may
778	limit the range of backward pointers to some value smaller than
779	32K. Similarly, a compressor may limit the size of blocks so that
780	a compressible block fits in memory.
781
782	A compliant decompressor must accept the full range of possible
783	values defined in the previous section, and must accept blocks of
784	arbitrary size.
785
786	4. Compression algorithm details
787
788	While it is the intent of this document to define the "deflate"
789	compressed data format without reference to any particular
790	compression algorithm, the format is related to the compressed
791	formats produced by LZ77 (Lempel-Ziv 1977, see reference [2] below);
792	since many variations of LZ77 are patented, it is strongly
793	recommended that the implementor of a compressor follow the general
794	algorithm presented here, which is known not to be patented per se.
795	The material in this section is not part of the definition of the
796
797
798
799	Deutsch Informational [Page 14]
800
801
802	RFC 1951 DEFLATE Compressed Data Format Specification May 1996
803
804
805	specification per se, and a compressor need not follow it in order to
806	be compliant.
807
808	The compressor terminates a block when it determines that starting a
809	new block with fresh trees would be useful, or when the block size
810	fills up the compressor's block buffer.
811
812	The compressor uses a chained hash table to find duplicated strings,
813	using a hash function that operates on 3-byte sequences. At any
814	given point during compression, let XYZ be the next 3 input bytes to
815	be examined (not necessarily all different, of course). First, the
816	compressor examines the hash chain for XYZ. If the chain is empty,
817	the compressor simply writes out X as a literal byte and advances one
818	byte in the input. If the hash chain is not empty, indicating that
819	the sequence XYZ (or, if we are unlucky, some other 3 bytes with the
820	same hash function value) has occurred recently, the compressor
821	compares all strings on the XYZ hash chain with the actual input data
822	sequence starting at the current point, and selects the longest
823	match.
824
825	The compressor searches the hash chains starting with the most recent
826	strings, to favor small distances and thus take advantage of the
827	Huffman encoding. The hash chains are singly linked. There are no
828	deletions from the hash chains; the algorithm simply discards matches
829	that are too old. To avoid a worst-case situation, very long hash
830	chains are arbitrarily truncated at a certain length, determined by a
831	run-time parameter.
832
833	To improve overall compression, the compressor optionally defers the
834	selection of matches ("lazy matching"): after a match of length N has
835	been found, the compressor searches for a longer match starting at
836	the next input byte. If it finds a longer match, it truncates the
837	previous match to a length of one (thus producing a single literal
838	byte) and then emits the longer match. Otherwise, it emits the
839	original match, and, as described above, advances N bytes before
840	continuing.
841
842	Run-time parameters also control this "lazy match" procedure. If
843	compression ratio is most important, the compressor attempts a
844	complete second search regardless of the length of the first match.
845	In the normal case, if the current match is "long enough", the
846	compressor reduces the search for a longer match, thus speeding up
847	the process. If speed is most important, the compressor inserts new
848	strings in the hash table only when no match was found, or when the
849	match is not "too long". This degrades the compression ratio but
850	saves time since there are both fewer insertions and fewer searches.
851
852
853
854
855
856	Deutsch Informational [Page 15]
857
858
859	RFC 1951 DEFLATE Compressed Data Format Specification May 1996
860
861
862	5. References
863
864	[1] Huffman, D. A., "A Method for the Construction of Minimum
865	Redundancy Codes", Proceedings of the Institute of Radio
866	Engineers, September 1952, Volume 40, Number 9, pp. 1098-1101.
867
868	[2] Ziv J., Lempel A., "A Universal Algorithm for Sequential Data
869	Compression", IEEE Transactions on Information Theory, Vol. 23,
870	No. 3, pp. 337-343.
871
872	[3] Gailly, J.-L., and Adler, M., ZLIB documentation and sources,
873	available in ftp://ftp.uu.net/pub/archiving/zip/doc/
874
875	[4] Gailly, J.-L., and Adler, M., GZIP documentation and sources,
876	available as gzip-*.tar in ftp://prep.ai.mit.edu/pub/gnu/
877
878	[5] Schwartz, E. S., and Kallick, B. "Generating a canonical prefix
879	encoding." Comm. ACM, 7,3 (Mar. 1964), pp. 166-169.
880
881	[6] Hirschberg and Lelewer, "Efficient decoding of prefix codes,"
882	Comm. ACM, 33,4, April 1990, pp. 449-459.
883
884	6. Security Considerations
885
886	Any data compression method involves the reduction of redundancy in
887	the data. Consequently, any corruption of the data is likely to have
888	severe effects and be difficult to correct. Uncompressed text, on
889	the other hand, will probably still be readable despite the presence
890	of some corrupted bytes.
891
892	It is recommended that systems using this data format provide some
893	means of validating the integrity of the compressed data. See
894	reference [3], for example.
895
896	7. Source code
897
898	Source code for a C language implementation of a "deflate" compliant
899	compressor and decompressor is available within the zlib package at
900	ftp://ftp.uu.net/pub/archiving/zip/zlib/.
901
902	8. Acknowledgements
903
904	Trademarks cited in this document are the property of their
905	respective owners.
906
907	Phil Katz designed the deflate format. Jean-Loup Gailly and Mark
908	Adler wrote the related software described in this specification.
909	Glenn Randers-Pehrson converted this document to RFC and HTML format.
910
911
912
913	Deutsch Informational [Page 16]
914
915
916	RFC 1951 DEFLATE Compressed Data Format Specification May 1996
917
918
919	9. Author's Address
920
921	L. Peter Deutsch
922	Aladdin Enterprises
923	203 Santa Margarita Ave.
924	Menlo Park, CA 94025
925
926	Phone: (415) 322-0103 (AM only)
927	FAX: (415) 322-1734
928	EMail: <[email protected]>
929
930	Questions about the technical content of this specification can be
931	sent by email to:
932
933	Jean-Loup Gailly <[email protected]> and
934	Mark Adler <[email protected]>
935
936	Editorial comments on this specification can be sent by email to:
937
938	L. Peter Deutsch <[email protected]> and
939	Glenn Randers-Pehrson <[email protected]>
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970	Deutsch Informational [Page 17]
971
972

	--- a/compat/zlib/doc/rfc1951.txt
	+++ b/compat/zlib/doc/rfc1951.txt
	@@ -1,972 +0,0 @@

D compat/zlib/doc/rfc1952.txt

-687

		--- a/compat/zlib/doc/rfc1952.txt
		+++ b/compat/zlib/doc/rfc1952.txt
		@@ -1,687 +0,0 @@
1		-
2		-
3		-
4		-
5		-
6		-
7		-Network Working Group P. Deutsch
8		-Request for Comments: 1952 Aladdin Enterprises
9		-Category: Informational May 1996
10		-
11		-
12		- GZIP file format specification version 4.3
13		-
14		-Status of This Memo
15		-
16		- This memo provides information for the Internet community. This memo
17		- does not specify an Internet standard of any kind. Distribution of
18		- this memo is unlimited.
19		-
20		-IESG Note:
21		-
22		- The IESG takes no position on the validity of any Intellectual
23		- Property Rights statements contained in this document.
24		-
25		-Notices
26		-
27		- Copyright (c) 1996 L. Peter Deutsch
28		-
29		- Permission is granted to copy and distribute this document for any
30		- purpose and without charge, including translations into other
31		- languages and incorporation into compilations, provided that the
32		- copyright notice and this notice are preserved, and that any
33		- substantive changes or deletions from the original are clearly
34		- marked.
35		-
36		- A pointer to the latest version of this and related documentation in
37		- HTML format can be found at the URL
38		- <ftp://ftp.uu.net/graphics/png/documents/zlib/zdoc-index.html>.
39		-
40		-Abstract
41		-
42		- This specification defines a lossless compressed data format that is
43		- compatible with the widely used GZIP utility. The format includes a
44		- cyclic redundancy check value for detecting data corruption. The
45		- format presently uses the DEFLATE method of compression but can be
46		- easily extended to use other compression methods. The format can be
47		- implemented readily in a manner not covered by patents.
48		-
49		-
50		-
51		-
52		-
53		-
54		-
55		-
56		-
57		-
58		-Deutsch Informational [Page 1]
59		-
60		-
61		-RFC 1952 GZIP File Format Specification May 1996
62		-
63		-
64		-Table of Contents
65		-
66		- 1. Introduction ................................................... 2
67		- 1.1. Purpose ................................................... 2
68		- 1.2. Intended audience ......................................... 3
69		- 1.3. Scope ..................................................... 3
70		- 1.4. Compliance ................................................ 3
71		- 1.5. Definitions of terms and conventions used ................. 3
72		- 1.6. Changes from previous versions ............................ 3
73		- 2. Detailed specification ......................................... 4
74		- 2.1. Overall conventions ....................................... 4
75		- 2.2. File format ............................................... 5
76		- 2.3. Member format ............................................. 5
77		- 2.3.1. Member header and trailer ........................... 6
78		- 2.3.1.1. Extra field ................................... 8
79		- 2.3.1.2. Compliance .................................... 9
80		- 3. References .................................................. 9
81		- 4. Security Considerations .................................... 10
82		- 5. Acknowledgements ........................................... 10
83		- 6. Author's Address ........................................... 10
84		- 7. Appendix: Jean-Loup Gailly's gzip utility .................. 11
85		- 8. Appendix: Sample CRC Code .................................. 11
86		-
87		-1. Introduction
88		-
89		- 1.1. Purpose
90		-
91		- The purpose of this specification is to define a lossless
92		- compressed data format that:
93		-
94		- * Is independent of CPU type, operating system, file system,
95		- and character set, and hence can be used for interchange;
96		- * Can compress or decompress a data stream (as opposed to a
97		- randomly accessible file) to produce another data stream,
98		- using only an a priori bounded amount of intermediate
99		- storage, and hence can be used in data communications or
100		- similar structures such as Unix filters;
101		- * Compresses data with efficiency comparable to the best
102		- currently available general-purpose compression methods,
103		- and in particular considerably better than the "compress"
104		- program;
105		- * Can be implemented readily in a manner not covered by
106		- patents, and hence can be practiced freely;
107		- * Is compatible with the file format produced by the current
108		- widely used gzip utility, in that conforming decompressors
109		- will be able to read data produced by the existing gzip
110		- compressor.
111		-
112		-
113		-
114		-
115		-Deutsch Informational [Page 2]
116		-
117		-
118		-RFC 1952 GZIP File Format Specification May 1996
119		-
120		-
121		- The data format defined by this specification does not attempt to:
122		-
123		- * Provide random access to compressed data;
124		- * Compress specialized data (e.g., raster graphics) as well as
125		- the best currently available specialized algorithms.
126		-
127		- 1.2. Intended audience
128		-
129		- This specification is intended for use by implementors of software
130		- to compress data into gzip format and/or decompress data from gzip
131		- format.
132		-
133		- The text of the specification assumes a basic background in
134		- programming at the level of bits and other primitive data
135		- representations.
136		-
137		- 1.3. Scope
138		-
139		- The specification specifies a compression method and a file format
140		- (the latter assuming only that a file can store a sequence of
141		- arbitrary bytes). It does not specify any particular interface to
142		- a file system or anything about character sets or encodings
143		- (except for file names and comments, which are optional).
144		-
145		- 1.4. Compliance
146		-
147		- Unless otherwise indicated below, a compliant decompressor must be
148		- able to accept and decompress any file that conforms to all the
149		- specifications presented here; a compliant compressor must produce
150		- files that conform to all the specifications presented here. The
151		- material in the appendices is not part of the specification per se
152		- and is not relevant to compliance.
153		-
154		- 1.5. Definitions of terms and conventions used
155		-
156		- byte: 8 bits stored or transmitted as a unit (same as an octet).
157		- (For this specification, a byte is exactly 8 bits, even on
158		- machines which store a character on a number of bits different
159		- from 8.) See below for the numbering of bits within a byte.
160		-
161		- 1.6. Changes from previous versions
162		-
163		- There have been no technical changes to the gzip format since
164		- version 4.1 of this specification. In version 4.2, some
165		- terminology was changed, and the sample CRC code was rewritten for
166		- clarity and to eliminate the requirement for the caller to do pre-
167		- and post-conditioning. Version 4.3 is a conversion of the
168		- specification to RFC style.
169		-
170		-
171		-
172		-Deutsch Informational [Page 3]
173		-
174		-
175		-RFC 1952 GZIP File Format Specification May 1996
176		-
177		-
178		-2. Detailed specification
179		-
180		- 2.1. Overall conventions
181		-
182		- In the diagrams below, a box like this:
183		-
184		- +---+
185		- \| \| <-- the vertical bars might be missing
186		- +---+
187		-
188		- represents one byte; a box like this:
189		-
190		- +==============+
191		- \| \|
192		- +==============+
193		-
194		- represents a variable number of bytes.
195		-
196		- Bytes stored within a computer do not have a "bit order", since
197		- they are always treated as a unit. However, a byte considered as
198		- an integer between 0 and 255 does have a most- and least-
199		- significant bit, and since we write numbers with the most-
200		- significant digit on the left, we also write bytes with the most-
201		- significant bit on the left. In the diagrams below, we number the
202		- bits of a byte so that bit 0 is the least-significant bit, i.e.,
203		- the bits are numbered:
204		-
205		- +--------+
206		- \|76543210\|
207		- +--------+
208		-
209		- This document does not address the issue of the order in which
210		- bits of a byte are transmitted on a bit-sequential medium, since
211		- the data format described here is byte- rather than bit-oriented.
212		-
213		- Within a computer, a number may occupy multiple bytes. All
214		- multi-byte numbers in the format described here are stored with
215		- the least-significant byte first (at the lower memory address).
216		- For example, the decimal number 520 is stored as:
217		-
218		- 0 1
219		- +--------+--------+
220		- \|00001000\|00000010\|
221		- +--------+--------+
222		- ^ ^
223		- \| \|
224		- \| + more significant byte = 2 x 256
225		- + less significant byte = 8
226		-
227		-
228		-
229		-Deutsch Informational [Page 4]
230		-
231		-
232		-RFC 1952 GZIP File Format Specification May 1996
233		-
234		-
235		- 2.2. File format
236		-
237		- A gzip file consists of a series of "members" (compressed data
238		- sets). The format of each member is specified in the following
239		- section. The members simply appear one after another in the file,
240		- with no additional information before, between, or after them.
241		-
242		- 2.3. Member format
243		-
244		- Each member has the following structure:
245		-
246		- +---+---+---+---+---+---+---+---+---+---+
247		- \|ID1\|ID2\|CM \|FLG\| MTIME \|XFL\|OS \| (more-->)
248		- +---+---+---+---+---+---+---+---+---+---+
249		-
250		- (if FLG.FEXTRA set)
251		-
252		- +---+---+=================================+
253		- \| XLEN \|...XLEN bytes of "extra field"...\| (more-->)
254		- +---+---+=================================+
255		-
256		- (if FLG.FNAME set)
257		-
258		- +=========================================+
259		- \|...original file name, zero-terminated...\| (more-->)
260		- +=========================================+
261		-
262		- (if FLG.FCOMMENT set)
263		-
264		- +===================================+
265		- \|...file comment, zero-terminated...\| (more-->)
266		- +===================================+
267		-
268		- (if FLG.FHCRC set)
269		-
270		- +---+---+
271		- \| CRC16 \|
272		- +---+---+
273		-
274		- +=======================+
275		- \|...compressed blocks...\| (more-->)
276		- +=======================+
277		-
278		- 0 1 2 3 4 5 6 7
279		- +---+---+---+---+---+---+---+---+
280		- \| CRC32 \| ISIZE \|
281		- +---+---+---+---+---+---+---+---+
282		-
283		-
284		-
285		-
286		-Deutsch Informational [Page 5]
287		-
288		-
289		-RFC 1952 GZIP File Format Specification May 1996
290		-
291		-
292		- 2.3.1. Member header and trailer
293		-
294		- ID1 (IDentification 1)
295		- ID2 (IDentification 2)
296		- These have the fixed values ID1 = 31 (0x1f, \037), ID2 = 139
297		- (0x8b, \213), to identify the file as being in gzip format.
298		-
299		- CM (Compression Method)
300		- This identifies the compression method used in the file. CM
301		- = 0-7 are reserved. CM = 8 denotes the "deflate"
302		- compression method, which is the one customarily used by
303		- gzip and which is documented elsewhere.
304		-
305		- FLG (FLaGs)
306		- This flag byte is divided into individual bits as follows:
307		-
308		- bit 0 FTEXT
309		- bit 1 FHCRC
310		- bit 2 FEXTRA
311		- bit 3 FNAME
312		- bit 4 FCOMMENT
313		- bit 5 reserved
314		- bit 6 reserved
315		- bit 7 reserved
316		-
317		- If FTEXT is set, the file is probably ASCII text. This is
318		- an optional indication, which the compressor may set by
319		- checking a small amount of the input data to see whether any
320		- non-ASCII characters are present. In case of doubt, FTEXT
321		- is cleared, indicating binary data. For systems which have
322		- different file formats for ascii text and binary data, the
323		- decompressor can use FTEXT to choose the appropriate format.
324		- We deliberately do not specify the algorithm used to set
325		- this bit, since a compressor always has the option of
326		- leaving it cleared and a decompressor always has the option
327		- of ignoring it and letting some other program handle issues
328		- of data conversion.
329		-
330		- If FHCRC is set, a CRC16 for the gzip header is present,
331		- immediately before the compressed data. The CRC16 consists
332		- of the two least significant bytes of the CRC32 for all
333		- bytes of the gzip header up to and not including the CRC16.
334		- [The FHCRC bit was never set by versions of gzip up to
335		- 1.2.4, even though it was documented with a different
336		- meaning in gzip 1.2.4.]
337		-
338		- If FEXTRA is set, optional extra fields are present, as
339		- described in a following section.
340		-
341		-
342		-
343		-Deutsch Informational [Page 6]
344		-
345		-
346		-RFC 1952 GZIP File Format Specification May 1996
347		-
348		-
349		- If FNAME is set, an original file name is present,
350		- terminated by a zero byte. The name must consist of ISO
351		- 8859-1 (LATIN-1) characters; on operating systems using
352		- EBCDIC or any other character set for file names, the name
353		- must be translated to the ISO LATIN-1 character set. This
354		- is the original name of the file being compressed, with any
355		- directory components removed, and, if the file being
356		- compressed is on a file system with case insensitive names,
357		- forced to lower case. There is no original file name if the
358		- data was compressed from a source other than a named file;
359		- for example, if the source was stdin on a Unix system, there
360		- is no file name.
361		-
362		- If FCOMMENT is set, a zero-terminated file comment is
363		- present. This comment is not interpreted; it is only
364		- intended for human consumption. The comment must consist of
365		- ISO 8859-1 (LATIN-1) characters. Line breaks should be
366		- denoted by a single line feed character (10 decimal).
367		-
368		- Reserved FLG bits must be zero.
369		-
370		- MTIME (Modification TIME)
371		- This gives the most recent modification time of the original
372		- file being compressed. The time is in Unix format, i.e.,
373		- seconds since 00:00:00 GMT, Jan. 1, 1970. (Note that this
374		- may cause problems for MS-DOS and other systems that use
375		- local rather than Universal time.) If the compressed data
376		- did not come from a file, MTIME is set to the time at which
377		- compression started. MTIME = 0 means no time stamp is
378		- available.
379		-
380		- XFL (eXtra FLags)
381		- These flags are available for use by specific compression
382		- methods. The "deflate" method (CM = 8) sets these flags as
383		- follows:
384		-
385		- XFL = 2 - compressor used maximum compression,
386		- slowest algorithm
387		- XFL = 4 - compressor used fastest algorithm
388		-
389		- OS (Operating System)
390		- This identifies the type of file system on which compression
391		- took place. This may be useful in determining end-of-line
392		- convention for text files. The currently defined values are
393		- as follows:
394		-
395		-
396		-
397		-
398		-
399		-
400		-Deutsch Informational [Page 7]
401		-
402		-
403		-RFC 1952 GZIP File Format Specification May 1996
404		-
405		-
406		- 0 - FAT filesystem (MS-DOS, OS/2, NT/Win32)
407		- 1 - Amiga
408		- 2 - VMS (or OpenVMS)
409		- 3 - Unix
410		- 4 - VM/CMS
411		- 5 - Atari TOS
412		- 6 - HPFS filesystem (OS/2, NT)
413		- 7 - Macintosh
414		- 8 - Z-System
415		- 9 - CP/M
416		- 10 - TOPS-20
417		- 11 - NTFS filesystem (NT)
418		- 12 - QDOS
419		- 13 - Acorn RISCOS
420		- 255 - unknown
421		-
422		- XLEN (eXtra LENgth)
423		- If FLG.FEXTRA is set, this gives the length of the optional
424		- extra field. See below for details.
425		-
426		- CRC32 (CRC-32)
427		- This contains a Cyclic Redundancy Check value of the
428		- uncompressed data computed according to CRC-32 algorithm
429		- used in the ISO 3309 standard and in section 8.1.1.6.2 of
430		- ITU-T recommendation V.42. (See http://www.iso.ch for
431		- ordering ISO documents. See gopher://info.itu.ch for an
432		- online version of ITU-T V.42.)
433		-
434		- ISIZE (Input SIZE)
435		- This contains the size of the original (uncompressed) input
436		- data modulo 2^32.
437		-
438		- 2.3.1.1. Extra field
439		-
440		- If the FLG.FEXTRA bit is set, an "extra field" is present in
441		- the header, with total length XLEN bytes. It consists of a
442		- series of subfields, each of the form:
443		-
444		- +---+---+---+---+==================================+
445		- \|SI1\|SI2\| LEN \|... LEN bytes of subfield data ...\|
446		- +---+---+---+---+==================================+
447		-
448		- SI1 and SI2 provide a subfield ID, typically two ASCII letters
449		- with some mnemonic value. Jean-Loup Gailly
450		- <[email protected]> is maintaining a registry of subfield
451		- IDs; please send him any subfield ID you wish to use. Subfield
452		- IDs with SI2 = 0 are reserved for future use. The following
453		- IDs are currently defined:
454		-
455		-
456		-
457		-Deutsch Informational [Page 8]
458		-
459		-
460		-RFC 1952 GZIP File Format Specification May 1996
461		-
462		-
463		- SI1 SI2 Data
464		- ---------- ---------- ----
465		- 0x41 ('A') 0x70 ('P') Apollo file type information
466		-
467		- LEN gives the length of the subfield data, excluding the 4
468		- initial bytes.
469		-
470		- 2.3.1.2. Compliance
471		-
472		- A compliant compressor must produce files with correct ID1,
473		- ID2, CM, CRC32, and ISIZE, but may set all the other fields in
474		- the fixed-length part of the header to default values (255 for
475		- OS, 0 for all others). The compressor must set all reserved
476		- bits to zero.
477		-
478		- A compliant decompressor must check ID1, ID2, and CM, and
479		- provide an error indication if any of these have incorrect
480		- values. It must examine FEXTRA/XLEN, FNAME, FCOMMENT and FHCRC
481		- at least so it can skip over the optional fields if they are
482		- present. It need not examine any other part of the header or
483		- trailer; in particular, a decompressor may ignore FTEXT and OS
484		- and always produce binary output, and still be compliant. A
485		- compliant decompressor must give an error indication if any
486		- reserved bit is non-zero, since such a bit could indicate the
487		- presence of a new field that would cause subsequent data to be
488		- interpreted incorrectly.
489		-
490		-3. References
491		-
492		- [1] "Information Processing - 8-bit single-byte coded graphic
493		- character sets - Part 1: Latin alphabet No.1" (ISO 8859-1:1987).
494		- The ISO 8859-1 (Latin-1) character set is a superset of 7-bit
495		- ASCII. Files defining this character set are available as
496		- iso_8859-1.* in ftp://ftp.uu.net/graphics/png/documents/
497		-
498		- [2] ISO 3309
499		-
500		- [3] ITU-T recommendation V.42
501		-
502		- [4] Deutsch, L.P.,"DEFLATE Compressed Data Format Specification",
503		- available in ftp://ftp.uu.net/pub/archiving/zip/doc/
504		-
505		- [5] Gailly, J.-L., GZIP documentation, available as gzip-*.tar in
506		- ftp://prep.ai.mit.edu/pub/gnu/
507		-
508		- [6] Sarwate, D.V., "Computation of Cyclic Redundancy Checks via Table
509		- Look-Up", Communications of the ACM, 31(8), pp.1008-1013.
510		-
511		-
512		-
513		-
514		-Deutsch Informational [Page 9]
515		-
516		-
517		-RFC 1952 GZIP File Format Specification May 1996
518		-
519		-
520		- [7] Schwaderer, W.D., "CRC Calculation", April 85 PC Tech Journal,
521		- pp.118-133.
522		-
523		- [8] ftp://ftp.adelaide.edu.au/pub/rocksoft/papers/crc_v3.txt,
524		- describing the CRC concept.
525		-
526		-4. Security Considerations
527		-
528		- Any data compression method involves the reduction of redundancy in
529		- the data. Consequently, any corruption of the data is likely to have
530		- severe effects and be difficult to correct. Uncompressed text, on
531		- the other hand, will probably still be readable despite the presence
532		- of some corrupted bytes.
533		-
534		- It is recommended that systems using this data format provide some
535		- means of validating the integrity of the compressed data, such as by
536		- setting and checking the CRC-32 check value.
537		-
538		-5. Acknowledgements
539		-
540		- Trademarks cited in this document are the property of their
541		- respective owners.
542		-
543		- Jean-Loup Gailly designed the gzip format and wrote, with Mark Adler,
544		- the related software described in this specification. Glenn
545		- Randers-Pehrson converted this document to RFC and HTML format.
546		-
547		-6. Author's Address
548		-
549		- L. Peter Deutsch
550		- Aladdin Enterprises
551		- 203 Santa Margarita Ave.
552		- Menlo Park, CA 94025
553		-
554		- Phone: (415) 322-0103 (AM only)
555		- FAX: (415) 322-1734
556		- EMail: <[email protected]>
557		-
558		- Questions about the technical content of this specification can be
559		- sent by email to:
560		-
561		- Jean-Loup Gailly <[email protected]> and
562		- Mark Adler <[email protected]>
563		-
564		- Editorial comments on this specification can be sent by email to:
565		-
566		- L. Peter Deutsch <[email protected]> and
567		- Glenn Randers-Pehrson <[email protected]>
568		-
569		-
570		-
571		-Deutsch Informational [Page 10]
572		-
573		-
574		-RFC 1952 GZIP File Format Specification May 1996
575		-
576		-
577		-7. Appendix: Jean-Loup Gailly's gzip utility
578		-
579		- The most widely used implementation of gzip compression, and the
580		- original documentation on which this specification is based, were
581		- created by Jean-Loup Gailly <[email protected]>. Since this
582		- implementation is a de facto standard, we mention some more of its
583		- features here. Again, the material in this section is not part of
584		- the specification per se, and implementations need not follow it to
585		- be compliant.
586		-
587		- When compressing or decompressing a file, gzip preserves the
588		- protection, ownership, and modification time attributes on the local
589		- file system, since there is no provision for representing protection
590		- attributes in the gzip file format itself. Since the file format
591		- includes a modification time, the gzip decompressor provides a
592		- command line switch that assigns the modification time from the file,
593		- rather than the local modification time of the compressed input, to
594		- the decompressed output.
595		-
596		-8. Appendix: Sample CRC Code
597		-
598		- The following sample code represents a practical implementation of
599		- the CRC (Cyclic Redundancy Check). (See also ISO 3309 and ITU-T V.42
600		- for a formal specification.)
601		-
602		- The sample code is in the ANSI C programming language. Non C users
603		- may find it easier to read with these hints:
604		-
605		- & Bitwise AND operator.
606		- ^ Bitwise exclusive-OR operator.
607		- >> Bitwise right shift operator. When applied to an
608		- unsigned quantity, as here, right shift inserts zero
609		- bit(s) at the left.
610		- ! Logical NOT operator.
611		- ++ "n++" increments the variable n.
612		- 0xNNN 0x introduces a hexadecimal (base 16) constant.
613		- Suffix L indicates a long value (at least 32 bits).
614		-
615		- /* Table of CRCs of all 8-bit messages. */
616		- unsigned long crc_table[256];
617		-
618		- /* Flag: has the table been computed? Initially false. */
619		- int crc_table_computed = 0;
620		-
621		- /* Make the table for a fast CRC. */
622		- void make_crc_table(void)
623		- {
624		- unsigned long c;
625		-
626		-
627		-
628		-Deutsch Informational [Page 11]
629		-
630		-
631		-RFC 1952 GZIP File Format Specification May 1996
632		-
633		-
634		- int n, k;
635		- for (n = 0; n < 256; n++) {
636		- c = (unsigned long) n;
637		- for (k = 0; k < 8; k++) {
638		- if (c & 1) {
639		- c = 0xedb88320L ^ (c >> 1);
640		- } else {
641		- c = c >> 1;
642		- }
643		- }
644		- crc_table[n] = c;
645		- }
646		- crc_table_computed = 1;
647		- }
648		-
649		- /*
650		- Update a running crc with the bytes buf[0..len-1] and return
651		- the updated crc. The crc should be initialized to zero. Pre- and
652		- post-conditioning (one's complement) is performed within this
653		- function so it shouldn't be done by the caller. Usage example:
654		-
655		- unsigned long crc = 0L;
656		-
657		- while (read_buffer(buffer, length) != EOF) {
658		- crc = update_crc(crc, buffer, length);
659		- }
660		- if (crc != original_crc) error();
661		- */
662		- unsigned long update_crc(unsigned long crc,
663		- unsigned char *buf, int len)
664		- {
665		- unsigned long c = crc ^ 0xffffffffL;
666		- int n;
667		-
668		- if (!crc_table_computed)
669		- make_crc_table();
670		- for (n = 0; n < len; n++) {
671		- c = crc_table[(c ^ buf[n]) & 0xff] ^ (c >> 8);
672		- }
673		- return c ^ 0xffffffffL;
674		- }
675		-
676		- /* Return the CRC of the bytes buf[0..len-1]. */
677		- unsigned long crc(unsigned char *buf, int len)
678		- {
679		- return update_crc(0L, buf, len);
680		- }
681		-
682		-
683		-
684		-
685		-Deutsch Informational [Page 12]
686		-
687		-

	--- a/compat/zlib/doc/rfc1952.txt
	+++ b/compat/zlib/doc/rfc1952.txt
	@@ -1,687 +0,0 @@
1
2
3
4
5
6
7	Network Working Group P. Deutsch
8	Request for Comments: 1952 Aladdin Enterprises
9	Category: Informational May 1996
10
11
12	GZIP file format specification version 4.3
13
14	Status of This Memo
15
16	This memo provides information for the Internet community. This memo
17	does not specify an Internet standard of any kind. Distribution of
18	this memo is unlimited.
19
20	IESG Note:
21
22	The IESG takes no position on the validity of any Intellectual
23	Property Rights statements contained in this document.
24
25	Notices
26
27	Copyright (c) 1996 L. Peter Deutsch
28
29	Permission is granted to copy and distribute this document for any
30	purpose and without charge, including translations into other
31	languages and incorporation into compilations, provided that the
32	copyright notice and this notice are preserved, and that any
33	substantive changes or deletions from the original are clearly
34	marked.
35
36	A pointer to the latest version of this and related documentation in
37	HTML format can be found at the URL
38	<ftp://ftp.uu.net/graphics/png/documents/zlib/zdoc-index.html>.
39
40	Abstract
41
42	This specification defines a lossless compressed data format that is
43	compatible with the widely used GZIP utility. The format includes a
44	cyclic redundancy check value for detecting data corruption. The
45	format presently uses the DEFLATE method of compression but can be
46	easily extended to use other compression methods. The format can be
47	implemented readily in a manner not covered by patents.
48
49
50
51
52
53
54
55
56
57
58	Deutsch Informational [Page 1]
59
60
61	RFC 1952 GZIP File Format Specification May 1996
62
63
64	Table of Contents
65
66	1. Introduction ................................................... 2
67	1.1. Purpose ................................................... 2
68	1.2. Intended audience ......................................... 3
69	1.3. Scope ..................................................... 3
70	1.4. Compliance ................................................ 3
71	1.5. Definitions of terms and conventions used ................. 3
72	1.6. Changes from previous versions ............................ 3
73	2. Detailed specification ......................................... 4
74	2.1. Overall conventions ....................................... 4
75	2.2. File format ............................................... 5
76	2.3. Member format ............................................. 5
77	2.3.1. Member header and trailer ........................... 6
78	2.3.1.1. Extra field ................................... 8
79	2.3.1.2. Compliance .................................... 9
80	3. References .................................................. 9
81	4. Security Considerations .................................... 10
82	5. Acknowledgements ........................................... 10
83	6. Author's Address ........................................... 10
84	7. Appendix: Jean-Loup Gailly's gzip utility .................. 11
85	8. Appendix: Sample CRC Code .................................. 11
86
87	1. Introduction
88
89	1.1. Purpose
90
91	The purpose of this specification is to define a lossless
92	compressed data format that:
93
94	* Is independent of CPU type, operating system, file system,
95	and character set, and hence can be used for interchange;
96	* Can compress or decompress a data stream (as opposed to a
97	randomly accessible file) to produce another data stream,
98	using only an a priori bounded amount of intermediate
99	storage, and hence can be used in data communications or
100	similar structures such as Unix filters;
101	* Compresses data with efficiency comparable to the best
102	currently available general-purpose compression methods,
103	and in particular considerably better than the "compress"
104	program;
105	* Can be implemented readily in a manner not covered by
106	patents, and hence can be practiced freely;
107	* Is compatible with the file format produced by the current
108	widely used gzip utility, in that conforming decompressors
109	will be able to read data produced by the existing gzip
110	compressor.
111
112
113
114
115	Deutsch Informational [Page 2]
116
117
118	RFC 1952 GZIP File Format Specification May 1996
119
120
121	The data format defined by this specification does not attempt to:
122
123	* Provide random access to compressed data;
124	* Compress specialized data (e.g., raster graphics) as well as
125	the best currently available specialized algorithms.
126
127	1.2. Intended audience
128
129	This specification is intended for use by implementors of software
130	to compress data into gzip format and/or decompress data from gzip
131	format.
132
133	The text of the specification assumes a basic background in
134	programming at the level of bits and other primitive data
135	representations.
136
137	1.3. Scope
138
139	The specification specifies a compression method and a file format
140	(the latter assuming only that a file can store a sequence of
141	arbitrary bytes). It does not specify any particular interface to
142	a file system or anything about character sets or encodings
143	(except for file names and comments, which are optional).
144
145	1.4. Compliance
146
147	Unless otherwise indicated below, a compliant decompressor must be
148	able to accept and decompress any file that conforms to all the
149	specifications presented here; a compliant compressor must produce
150	files that conform to all the specifications presented here. The
151	material in the appendices is not part of the specification per se
152	and is not relevant to compliance.
153
154	1.5. Definitions of terms and conventions used
155
156	byte: 8 bits stored or transmitted as a unit (same as an octet).
157	(For this specification, a byte is exactly 8 bits, even on
158	machines which store a character on a number of bits different
159	from 8.) See below for the numbering of bits within a byte.
160
161	1.6. Changes from previous versions
162
163	There have been no technical changes to the gzip format since
164	version 4.1 of this specification. In version 4.2, some
165	terminology was changed, and the sample CRC code was rewritten for
166	clarity and to eliminate the requirement for the caller to do pre-
167	and post-conditioning. Version 4.3 is a conversion of the
168	specification to RFC style.
169
170
171
172	Deutsch Informational [Page 3]
173
174
175	RFC 1952 GZIP File Format Specification May 1996
176
177
178	2. Detailed specification
179
180	2.1. Overall conventions
181
182	In the diagrams below, a box like this:
183
184	+---+
185	\| \| <-- the vertical bars might be missing
186	+---+
187
188	represents one byte; a box like this:
189
190	+==============+
191	\| \|
192	+==============+
193
194	represents a variable number of bytes.
195
196	Bytes stored within a computer do not have a "bit order", since
197	they are always treated as a unit. However, a byte considered as
198	an integer between 0 and 255 does have a most- and least-
199	significant bit, and since we write numbers with the most-
200	significant digit on the left, we also write bytes with the most-
201	significant bit on the left. In the diagrams below, we number the
202	bits of a byte so that bit 0 is the least-significant bit, i.e.,
203	the bits are numbered:
204
205	+--------+
206	\|76543210\|
207	+--------+
208
209	This document does not address the issue of the order in which
210	bits of a byte are transmitted on a bit-sequential medium, since
211	the data format described here is byte- rather than bit-oriented.
212
213	Within a computer, a number may occupy multiple bytes. All
214	multi-byte numbers in the format described here are stored with
215	the least-significant byte first (at the lower memory address).
216	For example, the decimal number 520 is stored as:
217
218	0 1
219	+--------+--------+
220	\|00001000\|00000010\|
221	+--------+--------+
222	^ ^
223	\| \|
224	\| + more significant byte = 2 x 256
225	+ less significant byte = 8
226
227
228
229	Deutsch Informational [Page 4]
230
231
232	RFC 1952 GZIP File Format Specification May 1996
233
234
235	2.2. File format
236
237	A gzip file consists of a series of "members" (compressed data
238	sets). The format of each member is specified in the following
239	section. The members simply appear one after another in the file,
240	with no additional information before, between, or after them.
241
242	2.3. Member format
243
244	Each member has the following structure:
245
246	+---+---+---+---+---+---+---+---+---+---+
247	\|ID1\|ID2\|CM \|FLG\| MTIME \|XFL\|OS \| (more-->)
248	+---+---+---+---+---+---+---+---+---+---+
249
250	(if FLG.FEXTRA set)
251
252	+---+---+=================================+
253	\| XLEN \|...XLEN bytes of "extra field"...\| (more-->)
254	+---+---+=================================+
255
256	(if FLG.FNAME set)
257
258	+=========================================+
259	\|...original file name, zero-terminated...\| (more-->)
260	+=========================================+
261
262	(if FLG.FCOMMENT set)
263
264	+===================================+
265	\|...file comment, zero-terminated...\| (more-->)
266	+===================================+
267
268	(if FLG.FHCRC set)
269
270	+---+---+
271	\| CRC16 \|
272	+---+---+
273
274	+=======================+
275	\|...compressed blocks...\| (more-->)
276	+=======================+
277
278	0 1 2 3 4 5 6 7
279	+---+---+---+---+---+---+---+---+
280	\| CRC32 \| ISIZE \|
281	+---+---+---+---+---+---+---+---+
282
283
284
285
286	Deutsch Informational [Page 5]
287
288
289	RFC 1952 GZIP File Format Specification May 1996
290
291
292	2.3.1. Member header and trailer
293
294	ID1 (IDentification 1)
295	ID2 (IDentification 2)
296	These have the fixed values ID1 = 31 (0x1f, \037), ID2 = 139
297	(0x8b, \213), to identify the file as being in gzip format.
298
299	CM (Compression Method)
300	This identifies the compression method used in the file. CM
301	= 0-7 are reserved. CM = 8 denotes the "deflate"
302	compression method, which is the one customarily used by
303	gzip and which is documented elsewhere.
304
305	FLG (FLaGs)
306	This flag byte is divided into individual bits as follows:
307
308	bit 0 FTEXT
309	bit 1 FHCRC
310	bit 2 FEXTRA
311	bit 3 FNAME
312	bit 4 FCOMMENT
313	bit 5 reserved
314	bit 6 reserved
315	bit 7 reserved
316
317	If FTEXT is set, the file is probably ASCII text. This is
318	an optional indication, which the compressor may set by
319	checking a small amount of the input data to see whether any
320	non-ASCII characters are present. In case of doubt, FTEXT
321	is cleared, indicating binary data. For systems which have
322	different file formats for ascii text and binary data, the
323	decompressor can use FTEXT to choose the appropriate format.
324	We deliberately do not specify the algorithm used to set
325	this bit, since a compressor always has the option of
326	leaving it cleared and a decompressor always has the option
327	of ignoring it and letting some other program handle issues
328	of data conversion.
329
330	If FHCRC is set, a CRC16 for the gzip header is present,
331	immediately before the compressed data. The CRC16 consists
332	of the two least significant bytes of the CRC32 for all
333	bytes of the gzip header up to and not including the CRC16.
334	[The FHCRC bit was never set by versions of gzip up to
335	1.2.4, even though it was documented with a different
336	meaning in gzip 1.2.4.]
337
338	If FEXTRA is set, optional extra fields are present, as
339	described in a following section.
340
341
342
343	Deutsch Informational [Page 6]
344
345
346	RFC 1952 GZIP File Format Specification May 1996
347
348
349	If FNAME is set, an original file name is present,
350	terminated by a zero byte. The name must consist of ISO
351	8859-1 (LATIN-1) characters; on operating systems using
352	EBCDIC or any other character set for file names, the name
353	must be translated to the ISO LATIN-1 character set. This
354	is the original name of the file being compressed, with any
355	directory components removed, and, if the file being
356	compressed is on a file system with case insensitive names,
357	forced to lower case. There is no original file name if the
358	data was compressed from a source other than a named file;
359	for example, if the source was stdin on a Unix system, there
360	is no file name.
361
362	If FCOMMENT is set, a zero-terminated file comment is
363	present. This comment is not interpreted; it is only
364	intended for human consumption. The comment must consist of
365	ISO 8859-1 (LATIN-1) characters. Line breaks should be
366	denoted by a single line feed character (10 decimal).
367
368	Reserved FLG bits must be zero.
369
370	MTIME (Modification TIME)
371	This gives the most recent modification time of the original
372	file being compressed. The time is in Unix format, i.e.,
373	seconds since 00:00:00 GMT, Jan. 1, 1970. (Note that this
374	may cause problems for MS-DOS and other systems that use
375	local rather than Universal time.) If the compressed data
376	did not come from a file, MTIME is set to the time at which
377	compression started. MTIME = 0 means no time stamp is
378	available.
379
380	XFL (eXtra FLags)
381	These flags are available for use by specific compression
382	methods. The "deflate" method (CM = 8) sets these flags as
383	follows:
384
385	XFL = 2 - compressor used maximum compression,
386	slowest algorithm
387	XFL = 4 - compressor used fastest algorithm
388
389	OS (Operating System)
390	This identifies the type of file system on which compression
391	took place. This may be useful in determining end-of-line
392	convention for text files. The currently defined values are
393	as follows:
394
395
396
397
398
399
400	Deutsch Informational [Page 7]
401
402
403	RFC 1952 GZIP File Format Specification May 1996
404
405
406	0 - FAT filesystem (MS-DOS, OS/2, NT/Win32)
407	1 - Amiga
408	2 - VMS (or OpenVMS)
409	3 - Unix
410	4 - VM/CMS
411	5 - Atari TOS
412	6 - HPFS filesystem (OS/2, NT)
413	7 - Macintosh
414	8 - Z-System
415	9 - CP/M
416	10 - TOPS-20
417	11 - NTFS filesystem (NT)
418	12 - QDOS
419	13 - Acorn RISCOS
420	255 - unknown
421
422	XLEN (eXtra LENgth)
423	If FLG.FEXTRA is set, this gives the length of the optional
424	extra field. See below for details.
425
426	CRC32 (CRC-32)
427	This contains a Cyclic Redundancy Check value of the
428	uncompressed data computed according to CRC-32 algorithm
429	used in the ISO 3309 standard and in section 8.1.1.6.2 of
430	ITU-T recommendation V.42. (See http://www.iso.ch for
431	ordering ISO documents. See gopher://info.itu.ch for an
432	online version of ITU-T V.42.)
433
434	ISIZE (Input SIZE)
435	This contains the size of the original (uncompressed) input
436	data modulo 2^32.
437
438	2.3.1.1. Extra field
439
440	If the FLG.FEXTRA bit is set, an "extra field" is present in
441	the header, with total length XLEN bytes. It consists of a
442	series of subfields, each of the form:
443
444	+---+---+---+---+==================================+
445	\|SI1\|SI2\| LEN \|... LEN bytes of subfield data ...\|
446	+---+---+---+---+==================================+
447
448	SI1 and SI2 provide a subfield ID, typically two ASCII letters
449	with some mnemonic value. Jean-Loup Gailly
450	<[email protected]> is maintaining a registry of subfield
451	IDs; please send him any subfield ID you wish to use. Subfield
452	IDs with SI2 = 0 are reserved for future use. The following
453	IDs are currently defined:
454
455
456
457	Deutsch Informational [Page 8]
458
459
460	RFC 1952 GZIP File Format Specification May 1996
461
462
463	SI1 SI2 Data
464	---------- ---------- ----
465	0x41 ('A') 0x70 ('P') Apollo file type information
466
467	LEN gives the length of the subfield data, excluding the 4
468	initial bytes.
469
470	2.3.1.2. Compliance
471
472	A compliant compressor must produce files with correct ID1,
473	ID2, CM, CRC32, and ISIZE, but may set all the other fields in
474	the fixed-length part of the header to default values (255 for
475	OS, 0 for all others). The compressor must set all reserved
476	bits to zero.
477
478	A compliant decompressor must check ID1, ID2, and CM, and
479	provide an error indication if any of these have incorrect
480	values. It must examine FEXTRA/XLEN, FNAME, FCOMMENT and FHCRC
481	at least so it can skip over the optional fields if they are
482	present. It need not examine any other part of the header or
483	trailer; in particular, a decompressor may ignore FTEXT and OS
484	and always produce binary output, and still be compliant. A
485	compliant decompressor must give an error indication if any
486	reserved bit is non-zero, since such a bit could indicate the
487	presence of a new field that would cause subsequent data to be
488	interpreted incorrectly.
489
490	3. References
491
492	[1] "Information Processing - 8-bit single-byte coded graphic
493	character sets - Part 1: Latin alphabet No.1" (ISO 8859-1:1987).
494	The ISO 8859-1 (Latin-1) character set is a superset of 7-bit
495	ASCII. Files defining this character set are available as
496	iso_8859-1.* in ftp://ftp.uu.net/graphics/png/documents/
497
498	[2] ISO 3309
499
500	[3] ITU-T recommendation V.42
501
502	[4] Deutsch, L.P.,"DEFLATE Compressed Data Format Specification",
503	available in ftp://ftp.uu.net/pub/archiving/zip/doc/
504
505	[5] Gailly, J.-L., GZIP documentation, available as gzip-*.tar in
506	ftp://prep.ai.mit.edu/pub/gnu/
507
508	[6] Sarwate, D.V., "Computation of Cyclic Redundancy Checks via Table
509	Look-Up", Communications of the ACM, 31(8), pp.1008-1013.
510
511
512
513
514	Deutsch Informational [Page 9]
515
516
517	RFC 1952 GZIP File Format Specification May 1996
518
519
520	[7] Schwaderer, W.D., "CRC Calculation", April 85 PC Tech Journal,
521	pp.118-133.
522
523	[8] ftp://ftp.adelaide.edu.au/pub/rocksoft/papers/crc_v3.txt,
524	describing the CRC concept.
525
526	4. Security Considerations
527
528	Any data compression method involves the reduction of redundancy in
529	the data. Consequently, any corruption of the data is likely to have
530	severe effects and be difficult to correct. Uncompressed text, on
531	the other hand, will probably still be readable despite the presence
532	of some corrupted bytes.
533
534	It is recommended that systems using this data format provide some
535	means of validating the integrity of the compressed data, such as by
536	setting and checking the CRC-32 check value.
537
538	5. Acknowledgements
539
540	Trademarks cited in this document are the property of their
541	respective owners.
542
543	Jean-Loup Gailly designed the gzip format and wrote, with Mark Adler,
544	the related software described in this specification. Glenn
545	Randers-Pehrson converted this document to RFC and HTML format.
546
547	6. Author's Address
548
549	L. Peter Deutsch
550	Aladdin Enterprises
551	203 Santa Margarita Ave.
552	Menlo Park, CA 94025
553
554	Phone: (415) 322-0103 (AM only)
555	FAX: (415) 322-1734
556	EMail: <[email protected]>
557
558	Questions about the technical content of this specification can be
559	sent by email to:
560
561	Jean-Loup Gailly <[email protected]> and
562	Mark Adler <[email protected]>
563
564	Editorial comments on this specification can be sent by email to:
565
566	L. Peter Deutsch <[email protected]> and
567	Glenn Randers-Pehrson <[email protected]>
568
569
570
571	Deutsch Informational [Page 10]
572
573
574	RFC 1952 GZIP File Format Specification May 1996
575
576
577	7. Appendix: Jean-Loup Gailly's gzip utility
578
579	The most widely used implementation of gzip compression, and the
580	original documentation on which this specification is based, were
581	created by Jean-Loup Gailly <[email protected]>. Since this
582	implementation is a de facto standard, we mention some more of its
583	features here. Again, the material in this section is not part of
584	the specification per se, and implementations need not follow it to
585	be compliant.
586
587	When compressing or decompressing a file, gzip preserves the
588	protection, ownership, and modification time attributes on the local
589	file system, since there is no provision for representing protection
590	attributes in the gzip file format itself. Since the file format
591	includes a modification time, the gzip decompressor provides a
592	command line switch that assigns the modification time from the file,
593	rather than the local modification time of the compressed input, to
594	the decompressed output.
595
596	8. Appendix: Sample CRC Code
597
598	The following sample code represents a practical implementation of
599	the CRC (Cyclic Redundancy Check). (See also ISO 3309 and ITU-T V.42
600	for a formal specification.)
601
602	The sample code is in the ANSI C programming language. Non C users
603	may find it easier to read with these hints:
604
605	& Bitwise AND operator.
606	^ Bitwise exclusive-OR operator.
607	>> Bitwise right shift operator. When applied to an
608	unsigned quantity, as here, right shift inserts zero
609	bit(s) at the left.
610	! Logical NOT operator.
611	++ "n++" increments the variable n.
612	0xNNN 0x introduces a hexadecimal (base 16) constant.
613	Suffix L indicates a long value (at least 32 bits).
614
615	/* Table of CRCs of all 8-bit messages. */
616	unsigned long crc_table[256];
617
618	/* Flag: has the table been computed? Initially false. */
619	int crc_table_computed = 0;
620
621	/* Make the table for a fast CRC. */
622	void make_crc_table(void)
623	{
624	unsigned long c;
625
626
627
628	Deutsch Informational [Page 11]
629
630
631	RFC 1952 GZIP File Format Specification May 1996
632
633
634	int n, k;
635	for (n = 0; n < 256; n++) {
636	c = (unsigned long) n;
637	for (k = 0; k < 8; k++) {
638	if (c & 1) {
639	c = 0xedb88320L ^ (c >> 1);
640	} else {
641	c = c >> 1;
642	}
643	}
644	crc_table[n] = c;
645	}
646	crc_table_computed = 1;
647	}
648
649	/*
650	Update a running crc with the bytes buf[0..len-1] and return
651	the updated crc. The crc should be initialized to zero. Pre- and
652	post-conditioning (one's complement) is performed within this
653	function so it shouldn't be done by the caller. Usage example:
654
655	unsigned long crc = 0L;
656
657	while (read_buffer(buffer, length) != EOF) {
658	crc = update_crc(crc, buffer, length);
659	}
660	if (crc != original_crc) error();
661	*/
662	unsigned long update_crc(unsigned long crc,
663	unsigned char *buf, int len)
664	{
665	unsigned long c = crc ^ 0xffffffffL;
666	int n;
667
668	if (!crc_table_computed)
669	make_crc_table();
670	for (n = 0; n < len; n++) {
671	c = crc_table[(c ^ buf[n]) & 0xff] ^ (c >> 8);
672	}
673	return c ^ 0xffffffffL;
674	}
675
676	/* Return the CRC of the bytes buf[0..len-1]. */
677	unsigned long crc(unsigned char *buf, int len)
678	{
679	return update_crc(0L, buf, len);
680	}
681
682
683
684
685	Deutsch Informational [Page 12]
686
687

	--- a/compat/zlib/doc/rfc1952.txt
	+++ b/compat/zlib/doc/rfc1952.txt
	@@ -1,687 +0,0 @@

D compat/zlib/doc/txtvsbin.txt

-103

		--- a/compat/zlib/doc/txtvsbin.txt
		+++ b/compat/zlib/doc/txtvsbin.txt
		@@ -1,107 +0,0 @@
1		-A Fast Method for Identifying Plain Text Files
2		-==============================================
3		-
4		-
5		-Introduction
		-------------
6		-
7		-Given a file coming from an unknown source, it is sometimes desirable
8		-to find out whether the format of that file is plain text. Although
9		-this may appear like a simple task, a fully accurate detection of the
10		-file type requires heavy-duty semantic analysis on the file contents.
11		-It is, however, possible to obtain satisfactory results by employing
12		-various heuristics.
13		-
14		-Previous versions of PKZip and other zip-compatible compression tools
15		-were using a crude detection scheme: if more than 80% (4/5) of the bytes
16		-found in a certain buffer are within the range [7..127], the file is
17		-labeled as plain text, otherwise it is labeled as binary. A prominent
18		-limitation of this scheme is the restriction to Latin-based alphabets.
19		-Other alphabets, like Greek, Cyrillic or Asian, make extensive use of
20		-the bytes within the range [128..255], and texts using these alphabets
21		-are most often misidentified by this scheme; in other words, the rate
22		-of false negatives is sometimes too high, which means that the recall
23		-is low. Another weakness of this scheme is a reduced precision, due to
24		-the false positives that may occur when binary files containing large
25		-amounts of textual characters are misidentified as plain text.
26		-
27		-In this article we propose a new, simple detection scheme that features
28		-a much increased precision and a near-100% recall. This scheme is
29		-designed to work on ASCII, Unicode and other ASCII-derived alphabets,
30		-and it handles single-byte encodings (ISO-8859, MacRoman, KOI8, etc.)
31		-and variable-sized encodings (ISO-2022, UTF-8, etc.). Wider encodings
32		-(UCS-2/UTF-16 and UCS-4/UTF-32) are not handled, however.
33		-
34		-
35		-The Algorithm
		--------------
36		-
37		-The algorithm works by dividing the set of bytecodes [0..255] into three
38		-categories:
39		-- The white list of textual bytecodes:
40		- 9 (TAB), 10 (LF), 13 (CR), 32 (SPACE) to 255.
41		-- The gray list of tolerated bytecodes:
42		- 7 (BEL), 8 (BS), 11 (VT), 12 (FF), 26 (SUB), 27 (ESC).
43		-- The black list of undesired, non-textual bytecodes:
44		- 0 (NUL) to 6, 14 to 31.
45		-
46		-If a file contains at least one byte that belongs to the white list and
47		-no byte that belongs to the black list, then the file is categorized as
48		-plain text; otherwise, it is categorized as binary. (The boundary case,
49		-when the file is empty, automatically falls into the latter category.)
50		-
51		-
52		-Rationale
		----------
53		-
54		-The idea behind this algorithm relies on two observations.
55		-
56		-The first observation is that, although the full range of 7-bit codes
57		-[0..127] is properly specified by the ASCII standard, most control
58		-characters in the range [0..31] are not used in practice. The only
59		-widely-used, almost universally-portable control codes are 9 (TAB),
60		-10 (LF) and 13 (CR). There are a few more control codes that are
61		-recognized on a reduced range of platforms and text viewers/editors:
62		-7 (BEL), 8 (BS), 11 (VT), 12 (FF), 26 (SUB) and 27 (ESC); but these
63		-codes are rarely (if ever) used alone, without being accompanied by
64		-some printable text. Even the newer, portable text formats such as
65		-XML avoid using control characters outside the list mentioned here.
66		-
67		-The second observation is that most of the binary files tend to contain
68		-control characters, especially 0 (NUL). Even though the older text
69		-detection schemes observe the presence of non-ASCII codes from the range
70		-[128..255], the precision rarely has to suffer if this upper range is
71		-labeled as textual, because the files that are genuinely binary tend to
72		-contain both control characters and codes from the upper range. On the
73		-other hand, the upper range needs to be labeled as textual, because it
74		-is used by virtually all ASCII extensions. In particular, this range is
75		-used for encoding non-Latin scripts.
76		-
77		-Since there is no counting involved, other than simply observing the
78		-presence or the absence of some byte values, the algorithm produces
79		-consistent results, regardless what alphabet encoding is being used.
80		-(If counting were involved, it could be possible to obtain different
81		-results on a text encoded, say, using ISO-8859-16 versus UTF-8.)
82		-
83		-There is an extra category of plain text files that are "polluted" with
84		-one or more black-listed codes, either by mistake or by peculiar design
85		-considerations. In such cases, a scheme that tolerates a small fraction
86		-of black-listed codes would provide an increased recall (i.e. more true
87		-positives). This, however, incurs a reduced precision overall, since
88		-false positives are more likely to appear in binary files that contain
89		-large chunks of textual data. Furthermore, "polluted" plain text should
90		-be regarded as binary by general-purpose text detection schemes, because
91		-general-purpose text processing algorithms might not be applicable.
92		-Under this premise, it is safe to say that our detection method provides
93		-a near-100% recall.
94		-
95		-Experiments have been run on many files coming from various platforms
96		-and applications. We tried plain text files, system logs, source code,
97		-formatted office documents, compiled object code, etc. The results
98		-confirm the optimistic assumptions about the capabilities of this
99		-algorithm.
100		-
101		-
		---
102		-Cosmin Truta
103		-Last updated: 2006-May-28

	--- a/compat/zlib/doc/txtvsbin.txt
	+++ b/compat/zlib/doc/txtvsbin.txt
	@@ -1,107 +0,0 @@
1	A Fast Method for Identifying Plain Text Files
2	==============================================
3
4
5	Introduction
	-------------
6
7	Given a file coming from an unknown source, it is sometimes desirable
8	to find out whether the format of that file is plain text. Although
9	this may appear like a simple task, a fully accurate detection of the
10	file type requires heavy-duty semantic analysis on the file contents.
11	It is, however, possible to obtain satisfactory results by employing
12	various heuristics.
13
14	Previous versions of PKZip and other zip-compatible compression tools
15	were using a crude detection scheme: if more than 80% (4/5) of the bytes
16	found in a certain buffer are within the range [7..127], the file is
17	labeled as plain text, otherwise it is labeled as binary. A prominent
18	limitation of this scheme is the restriction to Latin-based alphabets.
19	Other alphabets, like Greek, Cyrillic or Asian, make extensive use of
20	the bytes within the range [128..255], and texts using these alphabets
21	are most often misidentified by this scheme; in other words, the rate
22	of false negatives is sometimes too high, which means that the recall
23	is low. Another weakness of this scheme is a reduced precision, due to
24	the false positives that may occur when binary files containing large
25	amounts of textual characters are misidentified as plain text.
26
27	In this article we propose a new, simple detection scheme that features
28	a much increased precision and a near-100% recall. This scheme is
29	designed to work on ASCII, Unicode and other ASCII-derived alphabets,
30	and it handles single-byte encodings (ISO-8859, MacRoman, KOI8, etc.)
31	and variable-sized encodings (ISO-2022, UTF-8, etc.). Wider encodings
32	(UCS-2/UTF-16 and UCS-4/UTF-32) are not handled, however.
33
34
35	The Algorithm
	--------------
36
37	The algorithm works by dividing the set of bytecodes [0..255] into three
38	categories:
39	- The white list of textual bytecodes:
40	9 (TAB), 10 (LF), 13 (CR), 32 (SPACE) to 255.
41	- The gray list of tolerated bytecodes:
42	7 (BEL), 8 (BS), 11 (VT), 12 (FF), 26 (SUB), 27 (ESC).
43	- The black list of undesired, non-textual bytecodes:
44	0 (NUL) to 6, 14 to 31.
45
46	If a file contains at least one byte that belongs to the white list and
47	no byte that belongs to the black list, then the file is categorized as
48	plain text; otherwise, it is categorized as binary. (The boundary case,
49	when the file is empty, automatically falls into the latter category.)
50
51
52	Rationale
	----------
53
54	The idea behind this algorithm relies on two observations.
55
56	The first observation is that, although the full range of 7-bit codes
57	[0..127] is properly specified by the ASCII standard, most control
58	characters in the range [0..31] are not used in practice. The only
59	widely-used, almost universally-portable control codes are 9 (TAB),
60	10 (LF) and 13 (CR). There are a few more control codes that are
61	recognized on a reduced range of platforms and text viewers/editors:
62	7 (BEL), 8 (BS), 11 (VT), 12 (FF), 26 (SUB) and 27 (ESC); but these
63	codes are rarely (if ever) used alone, without being accompanied by
64	some printable text. Even the newer, portable text formats such as
65	XML avoid using control characters outside the list mentioned here.
66
67	The second observation is that most of the binary files tend to contain
68	control characters, especially 0 (NUL). Even though the older text
69	detection schemes observe the presence of non-ASCII codes from the range
70	[128..255], the precision rarely has to suffer if this upper range is
71	labeled as textual, because the files that are genuinely binary tend to
72	contain both control characters and codes from the upper range. On the
73	other hand, the upper range needs to be labeled as textual, because it
74	is used by virtually all ASCII extensions. In particular, this range is
75	used for encoding non-Latin scripts.
76
77	Since there is no counting involved, other than simply observing the
78	presence or the absence of some byte values, the algorithm produces
79	consistent results, regardless what alphabet encoding is being used.
80	(If counting were involved, it could be possible to obtain different
81	results on a text encoded, say, using ISO-8859-16 versus UTF-8.)
82
83	There is an extra category of plain text files that are "polluted" with
84	one or more black-listed codes, either by mistake or by peculiar design
85	considerations. In such cases, a scheme that tolerates a small fraction
86	of black-listed codes would provide an increased recall (i.e. more true
87	positives). This, however, incurs a reduced precision overall, since
88	false positives are more likely to appear in binary files that contain
89	large chunks of textual data. Furthermore, "polluted" plain text should
90	be regarded as binary by general-purpose text detection schemes, because
91	general-purpose text processing algorithms might not be applicable.
92	Under this premise, it is safe to say that our detection method provides
93	a near-100% recall.
94
95	Experiments have been run on many files coming from various platforms
96	and applications. We tried plain text files, system logs, source code,
97	formatted office documents, compiled object code, etc. The results
98	confirm the optimistic assumptions about the capabilities of this
99	algorithm.
100
101
	---
102	Cosmin Truta
103	Last updated: 2006-May-28

	--- a/compat/zlib/doc/txtvsbin.txt
	+++ b/compat/zlib/doc/txtvsbin.txt
	@@ -1,107 +0,0 @@





	-------------






























	--------------

















	----------

















































	---

M src/checkin.c

+4 -2

		--- src/checkin.c
		+++ src/checkin.c
		@@ -464,11 +464,12 @@
464	464	{"no-merge", C_MERGE }, {"no-classify", C_CLASSIFY },
465	465	};
466	466
467	467	Blob report = BLOB_INITIALIZER;
468	468	enum {CHANGES, STATUS} command = *g.argv[1]=='s' ? STATUS : CHANGES;
469		- int useHash = find_option("hash", 0, 0)!=0;
	469	+ /* --sha1sum is an undocumented alias for --hash for backwards compatiblity */
	470	+ int useHash = find_option("hash",0,0)!=0 \|\| find_option("sha1sum",0,0)!=0;
470	471	int showHdr = command==CHANGES && find_option("header", 0, 0);
471	472	int verboseFlag = command==CHANGES && find_option("verbose", "v", 0);
472	473	const char *zIgnoreFlag = find_option("ignore", 0, 1);
473	474	unsigned scanFlags = 0;
474	475	unsigned flags = 0;
		@@ -2068,11 +2069,12 @@
2068	2069	Blob ans;
2069	2070	char cReply;
2070	2071
2071	2072	memset(&sCiInfo, 0, sizeof(sCiInfo));
2072	2073	url_proxy_options();
2073		- useHash = find_option("hash", 0, 0)!=0;
	2074	+ /* --sha1sum is an undocumented alias for --hash for backwards compatiblity */
	2075	+ useHash = find_option("hash",0,0)!=0 \|\| find_option("sha1sum",0,0)!=0;
2074	2076	noSign = find_option("nosign",0,0)!=0;
2075	2077	forceDelta = find_option("delta",0,0)!=0;
2076	2078	forceBaseline = find_option("baseline",0,0)!=0;
2077	2079	if( forceDelta && forceBaseline ){
2078	2080	fossil_fatal("cannot use --delta and --baseline together");
2079	2081

	--- src/checkin.c
	+++ src/checkin.c
	@@ -464,11 +464,12 @@
464	{"no-merge", C_MERGE }, {"no-classify", C_CLASSIFY },
465	};
466
467	Blob report = BLOB_INITIALIZER;
468	enum {CHANGES, STATUS} command = *g.argv[1]=='s' ? STATUS : CHANGES;
469	int useHash = find_option("hash", 0, 0)!=0;

470	int showHdr = command==CHANGES && find_option("header", 0, 0);
471	int verboseFlag = command==CHANGES && find_option("verbose", "v", 0);
472	const char *zIgnoreFlag = find_option("ignore", 0, 1);
473	unsigned scanFlags = 0;
474	unsigned flags = 0;
	@@ -2068,11 +2069,12 @@
2068	Blob ans;
2069	char cReply;
2070
2071	memset(&sCiInfo, 0, sizeof(sCiInfo));
2072	url_proxy_options();
2073	useHash = find_option("hash", 0, 0)!=0;

2074	noSign = find_option("nosign",0,0)!=0;
2075	forceDelta = find_option("delta",0,0)!=0;
2076	forceBaseline = find_option("baseline",0,0)!=0;
2077	if( forceDelta && forceBaseline ){
2078	fossil_fatal("cannot use --delta and --baseline together");
2079

	--- src/checkin.c
	+++ src/checkin.c
	@@ -464,11 +464,12 @@
464	{"no-merge", C_MERGE }, {"no-classify", C_CLASSIFY },
465	};
466
467	Blob report = BLOB_INITIALIZER;
468	enum {CHANGES, STATUS} command = *g.argv[1]=='s' ? STATUS : CHANGES;
469	/* --sha1sum is an undocumented alias for --hash for backwards compatiblity */
470	int useHash = find_option("hash",0,0)!=0 \|\| find_option("sha1sum",0,0)!=0;
471	int showHdr = command==CHANGES && find_option("header", 0, 0);
472	int verboseFlag = command==CHANGES && find_option("verbose", "v", 0);
473	const char *zIgnoreFlag = find_option("ignore", 0, 1);
474	unsigned scanFlags = 0;
475	unsigned flags = 0;
	@@ -2068,11 +2069,12 @@
2069	Blob ans;
2070	char cReply;
2071
2072	memset(&sCiInfo, 0, sizeof(sCiInfo));
2073	url_proxy_options();
2074	/* --sha1sum is an undocumented alias for --hash for backwards compatiblity */
2075	useHash = find_option("hash",0,0)!=0 \|\| find_option("sha1sum",0,0)!=0;
2076	noSign = find_option("nosign",0,0)!=0;
2077	forceDelta = find_option("delta",0,0)!=0;
2078	forceBaseline = find_option("baseline",0,0)!=0;
2079	if( forceDelta && forceBaseline ){
2080	fossil_fatal("cannot use --delta and --baseline together");
2081

M src/hname.c

+1 -1

		--- src/hname.c
		+++ src/hname.c
		@@ -249,11 +249,11 @@
249	249	** sha3-only Use only SHA3 artifact names. Do not reuse legacy
250	250	** SHA1 names.
251	251	**
252	252	** shun-sha1 Shun any SHA1 artifacts received by sync operations
253	253	** other than clones. Older legacy SHA1 artifacts are
254		-** are allowed during a clone.
	254	+** allowed during a clone.
255	255	**
256	256	** The default hash policy for existing repositories is "auto", which will
257	257	** immediately promote to "sha3" if the repository contains one or more
258	258	** artifacts with SHA3 names. The default hash policy for new repositories
259	259	** is "shun-sha1".
260	260

	--- src/hname.c
	+++ src/hname.c
	@@ -249,11 +249,11 @@
249	** sha3-only Use only SHA3 artifact names. Do not reuse legacy
250	** SHA1 names.
251	**
252	** shun-sha1 Shun any SHA1 artifacts received by sync operations
253	** other than clones. Older legacy SHA1 artifacts are
254	** are allowed during a clone.
255	**
256	** The default hash policy for existing repositories is "auto", which will
257	** immediately promote to "sha3" if the repository contains one or more
258	** artifacts with SHA3 names. The default hash policy for new repositories
259	** is "shun-sha1".
260

	--- src/hname.c
	+++ src/hname.c
	@@ -249,11 +249,11 @@
249	** sha3-only Use only SHA3 artifact names. Do not reuse legacy
250	** SHA1 names.
251	**
252	** shun-sha1 Shun any SHA1 artifacts received by sync operations
253	** other than clones. Older legacy SHA1 artifacts are
254	** allowed during a clone.
255	**
256	** The default hash policy for existing repositories is "auto", which will
257	** immediately promote to "sha3" if the repository contains one or more
258	** artifacts with SHA3 names. The default hash policy for new repositories
259	** is "shun-sha1".
260

M src/sha3.c

+3 -3

		--- src/sha3.c
		+++ src/sha3.c
		@@ -378,18 +378,18 @@
378	378	}
379	379
380	380	/*
381	381	** Initialize a new hash. iSize determines the size of the hash
382	382	** in bits and should be one of 224, 256, 384, or 512. Or iSize
383		-** can be zero to use the default hash size of 224 bits.
	383	+** can be zero to use the default hash size of 256 bits.
384	384	*/
385	385	static void SHA3Init(SHA3Context *p, int iSize){
386	386	memset(p, 0, sizeof(*p));
387	387	if( iSize>=128 && iSize<=512 ){
388	388	p->nRate = (1600 - ((iSize + 31)&~31)*2)/8;
389	389	}else{
390		- p->nRate = 144;
	390	+ p->nRate = (1600 - 2*256)/8;
391	391	}
392	392	#if SHA3_BYTEORDER==1234
393	393	/* Known to be little-endian at compile-time. No-op */
394	394	#elif SHA3_BYTEORDER==4321
395	395	p->ixMask = 7; /* Big-endian */
		@@ -428,11 +428,11 @@
428	428	}
429	429	}
430	430	}
431	431	#endif
432	432	for(; i<nData; i++){
433		-#if SHA1_BYTEORDER==1234
	433	+#if SHA3_BYTEORDER==1234
434	434	p->u.x[p->nLoaded] ^= aData[i];
435	435	#elif SHA3_BYTEORDER==4321
436	436	p->u.x[p->nLoaded^0x07] ^= aData[i];
437	437	#else
438	438	p->u.x[p->nLoaded^p->ixMask] ^= aData[i];
439	439

	--- src/sha3.c
	+++ src/sha3.c
	@@ -378,18 +378,18 @@
378	}
379
380	/*
381	** Initialize a new hash. iSize determines the size of the hash
382	** in bits and should be one of 224, 256, 384, or 512. Or iSize
383	** can be zero to use the default hash size of 224 bits.
384	*/
385	static void SHA3Init(SHA3Context *p, int iSize){
386	memset(p, 0, sizeof(*p));
387	if( iSize>=128 && iSize<=512 ){
388	p->nRate = (1600 - ((iSize + 31)&~31)*2)/8;
389	}else{
390	p->nRate = 144;
391	}
392	#if SHA3_BYTEORDER==1234
393	/* Known to be little-endian at compile-time. No-op */
394	#elif SHA3_BYTEORDER==4321
395	p->ixMask = 7; /* Big-endian */
	@@ -428,11 +428,11 @@
428	}
429	}
430	}
431	#endif
432	for(; i<nData; i++){
433	#if SHA1_BYTEORDER==1234
434	p->u.x[p->nLoaded] ^= aData[i];
435	#elif SHA3_BYTEORDER==4321
436	p->u.x[p->nLoaded^0x07] ^= aData[i];
437	#else
438	p->u.x[p->nLoaded^p->ixMask] ^= aData[i];
439

	--- src/sha3.c
	+++ src/sha3.c
	@@ -378,18 +378,18 @@
378	}
379
380	/*
381	** Initialize a new hash. iSize determines the size of the hash
382	** in bits and should be one of 224, 256, 384, or 512. Or iSize
383	** can be zero to use the default hash size of 256 bits.
384	*/
385	static void SHA3Init(SHA3Context *p, int iSize){
386	memset(p, 0, sizeof(*p));
387	if( iSize>=128 && iSize<=512 ){
388	p->nRate = (1600 - ((iSize + 31)&~31)*2)/8;
389	}else{
390	p->nRate = (1600 - 2*256)/8;
391	}
392	#if SHA3_BYTEORDER==1234
393	/* Known to be little-endian at compile-time. No-op */
394	#elif SHA3_BYTEORDER==4321
395	p->ixMask = 7; /* Big-endian */
	@@ -428,11 +428,11 @@
428	}
429	}
430	}
431	#endif
432	for(; i<nData; i++){
433	#if SHA3_BYTEORDER==1234
434	p->u.x[p->nLoaded] ^= aData[i];
435	#elif SHA3_BYTEORDER==4321
436	p->u.x[p->nLoaded^0x07] ^= aData[i];
437	#else
438	p->u.x[p->nLoaded^p->ixMask] ^= aData[i];
439

M src/sqlcmd.c

		--- src/sqlcmd.c
		+++ src/sqlcmd.c
		@@ -212,10 +212,13 @@
212	212	*/
213	213	void cmd_sqlite3(void){
214	214	int noRepository;
215	215	const char *zConfigDb;
216	216	extern int sqlite3_shell(int, char**);
	217	+#ifdef FOSSIL_ENABLE_TH1_HOOKS
	218	+ g.fNoThHook = 1;
	219	+#endif
217	220	noRepository = find_option("no-repository", 0, 0)!=0;
218	221	if( !noRepository ){
219	222	db_find_and_open_repository(OPEN_ANY_SCHEMA, 0);
220	223	}
221	224	db_open_config(1,0);
222	225

	--- src/sqlcmd.c
	+++ src/sqlcmd.c
	@@ -212,10 +212,13 @@
212	*/
213	void cmd_sqlite3(void){
214	int noRepository;
215	const char *zConfigDb;
216	extern int sqlite3_shell(int, char**);



217	noRepository = find_option("no-repository", 0, 0)!=0;
218	if( !noRepository ){
219	db_find_and_open_repository(OPEN_ANY_SCHEMA, 0);
220	}
221	db_open_config(1,0);
222

	--- src/sqlcmd.c
	+++ src/sqlcmd.c
	@@ -212,10 +212,13 @@
212	*/
213	void cmd_sqlite3(void){
214	int noRepository;
215	const char *zConfigDb;
216	extern int sqlite3_shell(int, char**);
217	#ifdef FOSSIL_ENABLE_TH1_HOOKS
218	g.fNoThHook = 1;
219	#endif
220	noRepository = find_option("no-repository", 0, 0)!=0;
221	if( !noRepository ){
222	db_find_and_open_repository(OPEN_ANY_SCHEMA, 0);
223	}
224	db_open_config(1,0);
225

M src/wiki.c

+1 -1

		--- src/wiki.c
		+++ src/wiki.c
		@@ -1122,11 +1122,11 @@
1122	1122	*/
1123	1123	int wiki_technote_to_rid(const char *zETime) {
1124	1124	int rid=0; /* Artifact ID of the tech note */
1125	1125	int nETime = strlen(zETime);
1126	1126	Stmt q;
1127		- if( nETime>=4 && hname_validate(zETime, nETime) ){
	1127	+ if( nETime>=4 && nETime<=HNAME_MAX && validate16(zETime, nETime) ){
1128	1128	char zUuid[HNAME_MAX+1];
1129	1129	memcpy(zUuid, zETime, nETime+1);
1130	1130	canonical16(zUuid, nETime);
1131	1131	db_prepare(&q,
1132	1132	"SELECT e.objid"
1133	1133

	--- src/wiki.c
	+++ src/wiki.c
	@@ -1122,11 +1122,11 @@
1122	*/
1123	int wiki_technote_to_rid(const char *zETime) {
1124	int rid=0; /* Artifact ID of the tech note */
1125	int nETime = strlen(zETime);
1126	Stmt q;
1127	if( nETime>=4 && hname_validate(zETime, nETime) ){
1128	char zUuid[HNAME_MAX+1];
1129	memcpy(zUuid, zETime, nETime+1);
1130	canonical16(zUuid, nETime);
1131	db_prepare(&q,
1132	"SELECT e.objid"
1133

	--- src/wiki.c
	+++ src/wiki.c
	@@ -1122,11 +1122,11 @@
1122	*/
1123	int wiki_technote_to_rid(const char *zETime) {
1124	int rid=0; /* Artifact ID of the tech note */
1125	int nETime = strlen(zETime);
1126	Stmt q;
1127	if( nETime>=4 && nETime<=HNAME_MAX && validate16(zETime, nETime) ){
1128	char zUuid[HNAME_MAX+1];
1129	memcpy(zUuid, zETime, nETime+1);
1130	canonical16(zUuid, nETime);
1131	db_prepare(&q,
1132	"SELECT e.objid"
1133

Fossil SCM

Keyboard Shortcuts