1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
.Dd November 10, 2018
.Dt DEFLATESETDICTIONARY 3
.Os
.
.Sh NAME
.Nm deflateSetDictionary ,
.Nm deflateGetDictionary
.Nd deflate sliding dictionary
.
.Sh LIBRARY
.Lb libz
.
.Sh SYNOPSIS
.In zlib.h
.Ft int
.Fo deflateSetDictionary
.Fa "z_streamp strm"
.Fa "const Bytef *dictionary"
.Fa "uInt dictLength"
.Fc
.
.Ft int
.Fo deflateGetDictionary
.Fa "z_streamp strm"
.Fa "Bytef *dictionary"
.Fa "uInt *dictLength"
.Fc
.
.Sh DESCRIPTION
.Fn deflateSetDictionary
initializes the compression dictionary
from the given byte sequence
without producing any compressed output.
When using the zlib format,
this function must be called immediately after
.Xr deflateInit 3 ,
.Xr deflateInit2 3 ,
or
.Xr deflateReset 3 ,
and before any call of
.Xr deflate 3 .
When doing raw deflate,
this function must be called
either before any call of
.Xr deflate 3 ,
or immediately after the completion of a deflate block,
i.e. after all input has been consumed
and all output has been delivered
when using any of the flush options
.Dv Z_BLOCK ,
.Dv Z_PARTIAL_FLUSH ,
.Dv Z_SYNC_FLUSH ,
or
.Dv Z_FULL_FLUSH .
The compressor and decompressor
must use exactly the same dictionary
.Po
see
.Xr inflateSetDictionary 3
.Pc .
.
.Pp
The dictionary should consist of strings
(byte sequences)
that are likely to be encountered later
in the data to be compressed,
with the most commonly used strings
preferably put towards the end of the dictionary.
Using a dictionary is most useful
when the data to be compressed is short
and can be predicted with good accuracy;
the data can then be compressed better than
with the default empty dictionary.
.
.Pp
Depending on the size of
the compression data structures selected by
.Xr deflateInit 3
or
.Xr deflateInit2 3 ,
a part of the dictionary may in effect be discarded,
for example if the dictionary is larger
than the window size provided in
.Xr deflateInit 3
or
.Xr deflateInit2 3 .
Thus the strings most likely to be useful
should be put at the end of the dictionary,
not at the front.
In addition,
the current implementation of deflate
will use at most the window size minus 262 bytes
of the provided dictionary.
.
.Pp
Upon return of this function,
.Fa strm->adler
is set to the Adler-32 value
of the dictionary;
the decompressor may later use this value
to determine which dictionary has been used
by the compressor.
(The Adler-32 value applies to the whole dictionary
even if only a subset of the dictionary
is actually used by the compressor.)
If a raw deflate was requested,
then the Adler-32 value is not computed and
.Fa strm->adler
is not set.
.
.Pp
.Fn deflateSetDictionary
does not perform any compression:
this will be done by
.Xr deflate 3 .
.
.Pp
.Fn deflateGetDictionary
returns the sliding dictionary
being maintained by deflate.
.Fa dictLength
is set to the number of bytes in the dictionary,
and that many bytes are copied to
.Fa dictionary .
.Fa dictionary
must have enough space,
where 32768 bytes is always enough.
If
.Fn deflateGetDictionary
is called with
.Fa dictionary
equal to
.Dv Z_NULL,
then only the dictionary length is returned,
and nothing is copied.
Similarly,
if
.Fa dictLength
is
.Dv Z_NULL ,
then it is not set.
.
.Pp
.Fn deflateGetDictionary
may return a length less than the window size,
even when more than the window size in input
has been provided.
It may return up to 258 bytes less in that case,
due to how zlib's implementation of deflate
manages the sliding window and lookahead for matches,
where matches can be up to 258 bytes long.
If the application needs the last window-size bytes of input,
then that would need to be saved by the application
outside of zlib.
.
.Sh RETURN VALUES
.Fn deflateSetDictionary
returns
.Dv Z_OK
if success,
or
.Dv Z_STREAM_ERROR
if a parameter is invalid
.Po
e.g. dictionary being
.Dv Z_NULL
.Pc
or the stream state is inconsistent
.Po
for example if
.Xr deflate 3
has already been called for this stream
or if not at a block boundary
for raw deflate
.Pc .
.
.Pp
.Fn deflateGetDictionary
returns
.Dv Z_OK
on success,
or
.Dv Z_STREAM_ERROR
if the stream state is inconsistent.
|