Add deflateSetDictionary.3

1 files changed, 183 insertions, 0 deletions

diff --git a/deflateSetDictionary.3 b/deflateSetDictionary.3
new file mode 100644
index 0000000..ce59797
--- /dev/null
+++ b/deflateSetDictionary.3
@@ -0,0 +1,183 @@
+.Dd November 10, 2018
+.Dt DEFLATESETDICTIONARY 3
+.Os
+.
+.Sh NAME
+.Nm deflateSetDictionary ,
+.Nm deflateGetDictionary
+.Nd deflate sliding dictionary
+.
+.Sh LIBRARY
+.Lb libz
+.
+.Sh SYNOPSIS
+.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.