deflateSetDictionary
Load preset bytes as compression history without emitting them as input data.
Full chapter and shared rules ↗int ZEXPORT deflateSetDictionary(z_streamp strm, const Bytef *dictionary, uInt dictLength);
Load preset bytes as compression history without emitting them as input data.
dictLength is the byte count of the whole dictionary given, and w_size is the configured
history window in bytes. Of a dictionary that is too long, only the usable suffix is kept as
history, but the zlib dictionary identifier still covers the whole dictionary given.
Return values and next calls
Return type. int — zlib status code
The result says whether preset history was accepted; the dictionary is not emitted as ordinary compressed input.
deflateSetDictionary()| Returned value | Meaning and conditions | Caller’s next step |
|---|---|---|
Z_OKHistory loaded |
Dictionary and stream preconditions hold; history retains an available suffix of at most one window, while the zlib checksum covers the full dictionary. | Begin compression; a decoder requiring preset history must receive the same dictionary. next_in and avail_in are restored and no output is delivered. |
Z_STREAM_ERRORDictionary conditions refused |
The stream check fails, or the request uses gzip, a NULL dictionary, zlib past its initial state, nonzero lookahead, or raw input outside a completed block boundary; no stream changes occur. | Establish legal dictionary-call conditions. If an existing live stream remains, use a legal operation or deflateEnd. |
Calling conditions and effects
Domain Restricted domain. Effect: update history and dictionary checksum.
Pre live raw or zlib stream, immediately after init or deflateReset, before its first
deflate and first dictionary call. dictionary is non-NULL, covers dictLength
readable bytes and is separate from the window.
Proof goals.
- Goal.
Goal.deflateSetDictionary_safety(Safety/Streams.lean); required. Theorem:ZlibF.Spec.Public.StreamCallSafetyProof.deflateSetDictionary_safety(public-stream-call-safety.lean). The goal has two clauses: the refusal of a refused stream, and one call on a reachable stream.Goal.deflate_refusal(Safety/Refusals.lean), also required, states the same refusal. - Applies when. The refusal asks that
strmis a refused stream (RefusedDeflate). The call on a reachable stream asks (StreamCallDomain):strmis a reachable stream (StreamReachable);- the platform size bound holds (
ByteObjectsFit); dictionaryis NULL or points todictLengthreadable bytes outside the stream's own blocks (CallerRange).
- Covered without condition. Every
dictLengthand every dictionary content. Every reachable stream, in every phase: before the firstdeflate, mid-stream, while finishing, and afterZ_STREAM_END. The goal is wider than Pre:dictionarymay be NULL, the wrapper may be gzip, and the call may come at any point. The C refuses the cases listed in the return table. In the refusal: every refused stream and every value of the other arguments. - Guarantees (
StreamCallSafefor the call on a reachable stream).- Returns. On a refused stream the call returns
Z_STREAM_ERROR. On a reachable stream the call returns. - State. On a reachable stream, the stream keeps its invariant (
StreamInvariant). - Writes. On a refused stream, nothing: the heap is unchanged. On a reachable stream, only the stream record and the stream's own blocks.
- Allocations. On a reachable stream, the exact allocation account (
LiveChange).
- Returns. On a refused stream the call returns
- Not in this goal. A stream record with
zallocandzfreeset whosestateis a garbage pointer, points to a freed state, or points to an inflate state: no goal covers this call on such a record (deviations). Which code is returned and the history after the call: functional goalGoal.deflateSetDictionary(not planned; not done).
Complete return conditions and boundaries
Post return Z_OK. History retains an available suffix of the dictionary, at most
one window. The dictionary checksum for zlib covers the entire supplied dictionary.
The original next_in and avail_in are restored; total_in increases by
min(dictLength, w_size). No compressed output is delivered and no allocation occurs.
The decoder must be given the same preset dictionary when required.
Outside focused scope: gzip, NULL dictionary, zlib after its initial state, nonzero
lookahead, or raw input not at a completed block boundary returns Z_STREAM_ERROR
without changes. Raw replacement at legal boundaries and repeated zlib calls before the first
deflate are covered by the safety goal and by the functional goal. Repeated zlib calls
accumulate Adler-32 rather than restarting it.
Shared conditions and scope
Use a z_stream compressor when input arrives in pieces, output space is limited, or you
need a chosen wrapper, dictionary or flush boundary. A wrapper is the header, trailer and
integrity information added around the DEFLATE data; raw DEFLATE has none. Initialize once, call deflate with
successive buffers, and end the stream even if compression is abandoned. For a single buffer,
see compress and compress2.
| Task | Entries |
|---|---|
| Start or reuse | Init, configured init, reset, reset retaining history |
| Supply metadata or history | Dictionary, read history, gzip header |
| Compress and size output | Deflate, bound, pending output, last flush bits |
| Adjust or branch | Parameters, tuning, priming, copy |
| Release storage | End |
The contracts follow zlib.h and deflate.c of the pinned zlib with the
patches applied, in the default LP64 Linux build. Of the seven patches
only patches 0006 and 0007 touch deflate.c. Both change deflateBound_z, and with it the result
of deflateBound, which calls deflateBound_z: 0006 one condition, 0007 the length of the gzip extra
field in the wrapper size. The entry deflateBound_z states both changes. The
patches change no other function.
These are focused contracts: Pre describes ordinary correct use and is deliberately narrower than
what the function accepts. Cases outside Pre that the C still handles appear under Errors or
Outside focused scope. A call outside Pre is not thereby undefined, and it need not return an
error code. See how to read a contract for the domain and effect labels.
What is proved. Safety only: each call returns without undefined behaviour or a memory error, writes only what its goal names, and leaks nothing (safety). Each entry gives its goal under Proof goals, in the five items and with the fixed phrases that Reading a Proof goals paragraph defines: the goal and its theorem; the conditions under which it applies, in the order of the Lean statement; what it covers for every value; what it guarantees (returns, state, writes, allocations); and what it leaves to another goal. The proof assumes the conditions listed there, not the documentary Pre. Post, the return tables and the notes describe functional behaviour. They are read from the C, are to confirm where no theorem states them, and are not required for the safety results. Progress says which goals are done.
Shared conventions
Under each stated Pre, the documented behaviour is that the call terminates without a runtime fault and that Post holds. A call that leaves the stream live preserves its representation invariant. The part of this that is proved is the safety goal of the entry.
First, how data changes hands in one call. next_in points to the start of the input not yet read,
and avail_in is the number of bytes readable from there. next_out points to the next writable
position, and avail_out is the output room that remains, also in bytes. One call may consume only
part of the input and deliver only part of the output. Read the updated pointers and counts, take
the bytes delivered, then give the same stream more input or more output room.
- Live stream: a writable
z_streamwith a compressor state established by successful init or copy, preserved by legal calls, and not ended. The caller does not alter its internal state or allocator fields. Calls on one stream are sequential. - Buffers: input covers
avail_inreadable bytes; output coversavail_outwritable bytes. They do not overlap each other, the stream or its owned state. A non-NULL scalar result points to a writable cell separate from other results and stream memory. These separation conditions are assumptions of the contracts. Where a safety goal assumes one too, its Proof goals says so and deviations has a row. - Allocator: the default allocator/free pair is used, or both fields are NULL before init. Allocation may fail on any attempt. Custom allocator callbacks are outside this page's scope.
- Frame and ownership: calls change only their stream, its owned state and stated
output regions. Caller input is read-only. Caller buffers and header records remain caller-owned.
Only init and copy allocate; only their failure cleanup and
deflateEndfree memory. Other calls preserve the stream's allocation set. - Header lifetime: a retained gzip header and its optional fields remain readable and
unchanged while used. Non-NULL
nameandcommenthave a terminating zero;extracovers its stated length. The contracts on this page takeextra_len <= 65535. - Checked refusals: except for init and bounds, a failed stream check returns
Z_STREAM_ERRORbefore normal operation, without writes.deflateCopyadditionally clears a non-NULL destination state. Query output cells are untouched on this refusal. - Restricted domain means these explicit memory, lifetime and call-order conditions, plus the entry's Pre. It does not mean every representable pointer or integer is accepted. Error summaries cover stream records and states that the checks can read, not arbitrary invalid addresses.
- Reachable stream: the proof goals speak of a reachable stream where the contracts say live
stream (how to read a contract). A call that a goal covers extends the stream's
history: when it returns, with any code, the stream is reachable again and the goal of the next
call applies.
deflateEndends the history. - Result cells as values:
deflateGetDictionary,deflatePendinganddeflateUsedreport results through pointers (uInt *dictLength,unsigned *pending,int *bits). The translation does not model these cells as memory: each function takes only the fact that a pointer is NULL or not, and returns the values. So the goals say nothing about the address of a result cell, and a cell that overlaps another object cannot be expressed.
Safety goal
ZlibF.Spec.Public.Goal.deflateSetDictionary_safety
State: done · Status of the results
/-- `int deflateSetDictionary(z_streamp strm, const Bytef *dictionary, uInt dictLength)`.
**Safety of `deflateSetDictionary`**: a `NULL` or inconsistent stream (`RefusedDeflate`) is refused
with `Z_STREAM_ERROR` and nothing changed; and on every reachable deflate stream, with the caller's
arguments as `zlib.h` asks, the call is safe (`StreamCallSafe`). -/
def Goal.deflateSetDictionary_safety : Prop :=
(∀ h p dictionary dictLength, RefusedDeflate h p →
C.run (Zlib.Deflate.deflateSetDictionary p dictionary dictLength) h = .ok (Z_STREAM_ERROR, h)) ∧
(∀ h r dictionary dictLength,
StreamCallDomain .deflate h r (.deflateSetDictionary (some r) dictionary dictLength) →
StreamCallSafe .deflate h r (.deflateSetDictionary (some r) dictionary dictLength))Related definitions and source ↗Functional contract (beyond safety)
ZlibF.Spec.Public.Goal.deflateSetDictionary
State: not done, not planned · Status of the results
/-- `int deflateSetDictionary(z_streamp strm, const Bytef *dictionary, uInt dictLength)`.
The raw path checks the block boundary. Repeated zlib dictionaries accumulate their checksum.
The temporary input binding is restored, and no allocation is performed. -/
def Goal.deflateSetDictionary : Prop :=
∀ h r i z s source n xs old,
Zlib.Deflate.Spec.DGood h r i z s → LibraryGlobals h →
DeflateDictionary h s old → (source ≠ .null → Bytes h source n.toNat xs) →
Separate source n.toNat s.window s.window_size.toNat →
∃ rc after, C.run (Zlib.Deflate.deflateSetDictionary (some r) source n) h = .ok (rc, after) ∧
(if source = .null ∨ s.wrap = 2 ∨ (s.wrap = 1 ∧ s.status ≠ INIT_STATE) ∨
s.lookahead ≠ 0 ∨ (s.wrap = 0 ∧ s.strstart.toUInt64.toInt64 ≠ s.block_start) then
rc = Z_STREAM_ERROR ∧ after = h
else rc = Z_OK ∧ ∃ z' s' dict,
Zlib.Deflate.Spec.DGood after r i z' s' ∧ DeflateDictionary after s' dict ∧
z' = { z with
total_in := z.total_in + UInt64.ofNat (min xs.length s.w_size.toNat)
adler := if s.wrap = 1 then adlerValue z.adler xs else z.adler } ∧
s'.wrap = s.wrap ∧ s'.lookahead = 0 ∧ s'.block_start = s'.strstart.toUInt64.toInt64 ∧
dict <:+ old ++ xs ∧ dict.length ≤ s.w_size.toNat ∧
min (old.length + xs.length) (s.w_size.toNat - 262) ≤ dict.length) ∧
Frame h after (fun b => StreamRoot r b ∨ DeflateOwned i s b) ∧
LiveChange h after (fun _ => False) (fun _ => False) ∧ after.nalloc = h.nallocRelated definitions and source ↗