Skip to content
REFERENCE / ZLIB × LEAN

inflateSetDictionary

Install or amend the bytes available for backward matches.

Full chapter and shared rules ↗
int ZEXPORT inflateSetDictionary(z_streamp strm, const Bytef *dictionary, uInt dictLength);

Install or amend the bytes available for backward matches.

Return values and next calls

Return type. int — zlib status code

The result distinguishes successful dictionary installation, an identifier mismatch, and stream or memory errors.

inflateSetDictionary()
Returned value Meaning and conditions Caller’s next step
Z_OK
Dictionary installed
A raw stream accepted the dictionary, or a waiting zlib stream’s identifier matched; the usable window suffix is retained. Continue inflate; input/output pointers and totals have not advanced.
Z_DATA_ERROR
Zlib dictionary identifier mismatch
The supplied dictionary’s full Adler identifier differs from the required identifier; the stream is unchanged. Try another dictionary, or call inflateEnd if abandoning decoding.
Z_STREAM_ERROR
Dictionary request refused
dictionary is NULL, the stream check failed, or a wrapped stream is not awaiting a dictionary. Provide a non-NULL dictionary under the contract only for a valid raw stream or a zlib stream awaiting one.
Z_MEM_ERROR
Window allocation failed
History-window allocation failed and the stream enters memory-error mode. Reset before starting a new decode, or call inflateEnd to release state.

Calling conditions and effects

Domain Restricted domain: live zlib streams waiting after Z_NEED_DICT, or live raw streams at any call boundary.

Effects Mutates history and may allocate its window.

Pre dictionary is non-NULL and describes dictLength readable bytes, even when the length is zero. For correct output it matches the compressor's dictionary.

Proof goals.

  • Goal. Goal.inflateSetDictionary_safety (Safety/Streams.lean); required. Theorem: ZlibF.Spec.Public.StreamCallSafetyProof.inflateSetDictionary_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.inflate_refusal (Safety/Refusals.lean), also required, states the same refusal.
  • Applies when. The refusal asks that strm is a refused stream (RefusedInflate). The call on a reachable stream asks (StreamCallDomain):
    1. strm is a reachable stream (StreamReachable);
    2. the platform size bound holds (ByteObjectsFit);
    3. dictionary is NULL or points to dictLength readable bytes outside the stream's own blocks (CallerRange).
  • Covered without condition. Every dictLength and every dictionary content; every allocation outcome. Every reachable stream, in every mode: before decoding, mid-block, at stream end, and after a data or memory error. In the refusal: every refused stream and every value of the other arguments.
  • Guarantees (StreamCallSafe for 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).
  • Not in this goal. A stream record with zalloc and zfree set whose state is a garbage pointer, points to a freed state, or points to a deflate state: no goal covers this call on such a record (deviations). Which code is returned and the history after the call: functional goal Goal.inflateSetDictionary (not planned; a theorem proves it).
Complete return conditions and boundaries

Post Returns Z_OK after retaining the last window-sized suffix of old history followed by the new dictionary. The whole supplied dictionary is checked against the zlib identifier. Caller bytes are copied, not retained or freed.

Errors A wrong zlib identifier returns Z_DATA_ERROR unchanged; another dictionary can be tried. NULL dictionary, failed stream check or wrapped stream not awaiting a dictionary returns Z_STREAM_ERROR. Allocation failure returns Z_MEM_ERROR and leaves the stream in the memory-error mode, still endable.

Edges Gzip has no preset-dictionary path. Raw mode has no identifier check; a wrong dictionary can produce wrong output or a later error. Zero-length raw dictionaries are accepted. No input/output pointers or totals are advanced.

Shared conditions and scope

Use an inflate stream to decode input in pieces while controlling output space. Select zlib, gzip or raw DEFLATE at initialization, then continue with more input or room until completion, a dictionary request or an error. inflateEnd releases the decoder after any of those outcomes. For whole-buffer zlib decoding, see uncompress.

Task Entries
Start or reuse Init, configured init, reset, new configuration, keep history
Decode or provide metadata Inflate, set dictionary, read history, gzip header
Recover or inspect Sync search, sync point, mark, table use
Adjust or branch Prime bits, validation, distance option, copy
Release storage End

The contracts follow the pinned inflate.c with patch 0001 applied and zlib.h, in the default LP64 Linux build, with gzip enabled and without the optional invalid-distance or strict-distance modes. Patch 0001 changes inflateCopy only (patches). 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 Edges. A call outside Pre is not thereby undefined, and it need not return an error code. See how to read a contract for the 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.

Common conditions

The caller and the decoder keep different things. The caller supplies the input and output buffers of each call. The decoder keeps the current parsing stage, the bits not yet used, and the history that later copies may need. Giving it a different output array does not start a new decoding task.

next_in is the start of the unread input and avail_in the number of readable bytes. next_out is the next output position and avail_out the number of writable bytes that remain from there. For example, a 5-byte output array that returns with 2 bytes of room has received 3 bytes. Take those bytes first, then set the pointer and the count to the next writable region.

All contracts below have a Restricted domain. A C pointer type alone does not supply the storage, lifetime or call history required here.

  • A live stream was successfully initialised or copied, has not been ended, retains its library-owned state, and is used without concurrent calls. Use the default allocator and free function. Init takes a writable, non-live stream with allocator fields set to NULL or the default functions.
  • A readable or writable range has the stated capacity for the whole call. Caller ranges are separate from the stream and its owned storage. Input and output ranges do not overlap. Dictionary destinations, the registered header record and its destination buffers are separate from each other and from the stream. Registered header storage is also separate from input/output ranges on calls using it. These restrictions are part of Pre; each entry's Proof goals says which of them its goal assumes.
  • The caller owns its stream object and buffers. The library owns the state and optional window. A call changes only its stream, owned storage, stated output ranges and any registered header destination. It never frees caller buffers.
  • A rejected stream check returns Z_STREAM_ERROR without changes, unless a query or copy contract says otherwise. This covers NULL and safely readable records rejected by the check; it does not cover dangling or arbitrary pointers. The check requires allocators, state, the state's back-pointer and a valid mode.
  • Counters use the C unsigned widths and wrap. No contract assumes allocation succeeds. End remains available after decoding, dictionary or allocation errors.
  • 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. inflateEnd ends the history.
  • Result cells as values. inflateGetDictionary reports a length through uInt *dictLength. The translation does not model that cell as memory: the function takes the cell's old value, or the fact that the pointer is NULL, and returns the new value. So the goal says nothing about the address of the cell, and a cell that overlaps another object cannot be expressed.
flowchart LR
    I["Init"] --> F["inflate"]
    F -->|"Z_NEED_DICT"| D["SetDictionary"] --> F
    F -->|"more room or input"| F
    F -->|"end or abandon"| E["End"]
    F -->|"data error"| R["Reset or Sync"] --> F

Safety goal

ZlibF.Spec.Public.Goal.inflateSetDictionary_safety

State: done · Status of the results

/-- `int inflateSetDictionary(z_streamp strm, const Bytef *dictionary, uInt dictLength)`.
**Safety of `inflateSetDictionary`**: a `NULL` or inconsistent stream (`RefusedInflate`) is refused
with `Z_STREAM_ERROR` and nothing changed; and on every reachable inflate stream, with the caller's
arguments as `zlib.h` asks, the call is safe (`StreamCallSafe`). -/
def Goal.inflateSetDictionary_safety : Prop :=
  (∀ h p dictionary dictLength, RefusedInflate h p →
    C.run (Zlib.Inflate.inflateSetDictionary p dictionary dictLength) h = .ok (Z_STREAM_ERROR, h)) ∧
  (∀ h r dictionary dictLength,
     StreamCallDomain .inflate h r (.inflateSetDictionary (some r) dictionary dictLength) →
     StreamCallSafe .inflate h r (.inflateSetDictionary (some r) dictionary dictLength))
Related definitions and source ↗

Functional contract (beyond safety)

ZlibF.Spec.Public.Goal.inflateSetDictionary

State: done · Status of the results

/-- `int inflateSetDictionary(z_streamp strm, const Bytef *dictionary, uInt dictLength)`.
Raw streams append to their window. Wrapped streams require DICT mode and the exact Adler id. -/
def Goal.inflateSetDictionary : Prop :=
  ∀ h r i z s source n xs old,
    Zlib.Inflate.Spec.Good h r i z s → z.zalloc = .fn "zcalloc" →
    InflateDictionary h s old → (source ≠ .null → Bytes h source n.toNat xs) →
    Separate source n.toNat s.window (2 ^ s.wbits.toNat) →
    ((s.wrap = 0 ∨ s.mode = DICT) → 8 ≤ s.wbits.toNat) →
    ∃ rc after, C.run (Zlib.Inflate.inflateSetDictionary (some r) source n) h = .ok (rc, after) ∧
      (source = .null ∨ (s.wrap ≠ 0 ∧ s.mode ≠ DICT) → rc = Z_STREAM_ERROR ∧ after = h) ∧
      (source ≠ .null → (s.wrap = 0 ∨ s.mode = DICT) →
        if s.mode = DICT ∧ s.check ≠ (ZlibF.Spec.adler32 xs).toUInt64 then rc = Z_DATA_ERROR ∧ after = h
        else (rc = Z_MEM_ERROR ∧ AllocationFailed h after ∧
          ∃ s', Zlib.Inflate.Spec.Good after r i z s' ∧ s'.mode = MEM) ∨
          (rc = Z_OK ∧ ∃ s', Zlib.Inflate.Spec.Good after r i z s' ∧
            s'.havedict = 1 ∧ s'.mode = s.mode ∧
            InflateDictionary after s' ((old ++ xs).drop ((old ++ xs).length - 2 ^ s.wbits.toNat)))) ∧
      Frame h after (fun b => StreamRoot r b ∨ InflateOwned i s b) ∧
      (∃ s', h.istates i = some s ∧ after.istates i = some s' ∧
        LiveChange h after (fun b => InflateOwned i s' b ∧ ¬ h.live b) (fun _ => False))
Related definitions and source ↗
ZLIB × LEAN

Contents

READING NOWinflateSetDictionary