Skip to content
REFERENCE / ZLIB × LEAN

inflateBackInit_

Purpose. Allocate decoder state and attach the caller's window. The inflateBackInit macro supplies version and stream_size.

Full chapter and shared rules ↗
int ZEXPORT inflateBackInit_(z_streamp strm, int windowBits, unsigned char FAR *window,
                             const char *version, int stream_size);

Purpose. Allocate decoder state and attach the caller's window. The inflateBackInit macro supplies version and stream_size.

Return values and next calls

Return type. int — zlib status code

The result says whether callback decoder state was created and attached to the caller’s window.

inflateBackInit_()
Returned value Meaning and conditions Caller’s next step
Z_OK
Callback decoder created
The version and stream size match, 8 <= windowBits <= 15, the window is non-NULL, and state allocation succeeded. Keep the window alive and decode with inflateBack; eventually call inflateBackEnd.
Z_VERSION_ERROR
Version or structure size mismatch
version is NULL, its major-version byte differs, or stream_size is wrong; this returns before stream access. Correct the version and structure size before initializing again; this failure needs no end call.
Z_STREAM_ERROR
Stream, window or bit count refused
strm or window is NULL, or windowBits is outside 8..15. Provide a valid inactive stream, window and bit count before initializing again; this failure needs no end call.
Z_MEM_ERROR
State allocation failed
State allocation failed; msg and default allocator fields may change, while the old state field is retained. Initialization may be tried again when resources are available; no new allocation was retained and this failure needs no inflateBackEnd.

Calling conditions and effects

Domain Restricted domain: valid caller memory, an inactive stream and default allocation.

Pre A non-NULL strm points to a writable z_stream with initialized zalloc, zfree and opaque. Use NULL or the default allocator/free pair; do not overwrite live library state. A non-NULL version has a readable first byte. On the initialization path, window provides 2^windowBits writable bytes separate from the stream. Keep that slice alive until end.

Effects May initialize allocator fields and opaque, clear msg and allocate one state. The window remains caller-owned and is not allocated, cleared or freed here.

Proof goals.

  • Goal. Goal.inflateBackInit__safety (Safety/Back.lean); required. Theorem: ZlibF.Spec.Public.BackSafetyProof.inflateBackInit__safety (public-back-safety.lean).
  • Applies when (1 to 3 are InitArguments, the conditions of inflateInit2_):
    1. the heap is a library heap (Fresh, Uniq, LibraryGlobals);
    2. version is NULL or its first byte is readable (VersionValue);
    3. strm is NULL, or points to a readable stream record whose zalloc and zfree are each NULL or the default function (DefaultOrNull);
    4. when window is not NULL and windowBits is 8 to 15, window covers 2^windowBits writable bytes (Writable).
  • Covered without condition. Every windowBits, also outside 8 to 15; a NULL window; every stream_size; every value of the first byte of version; every value of the other fields of the record, state included; every allocation outcome. If the record held a live decoder and the call returns Z_OK, the old state stays allocated and the record no longer points to it: the account records that leak, it does not exclude it.
  • Guarantees.
    • Returns. The call returns. With a NULL strm the code is Z_VERSION_ERROR or Z_STREAM_ERROR.
    • State. With Z_OK, the stream record points to a valid callback-decoder state in the new block, and that state's window is window (BackValid).
    • Writes. With a NULL strm, nothing: the heap is unchanged. Otherwise only the stream record and the block the call itself allocates (Frame).
    • Allocations. With Z_OK, exactly one block is new, the state record, and nothing is freed (LiveChange). With any other code the allocated blocks are the same as before the call.
  • Not in this goal. A stream whose zalloc or zfree is a custom function: outside every goal (deviations). Which code each refusal and the allocation failure returns, and the field values after the call: functional goal Goal.inflateBackInit_ (not planned; a theorem proves it). That a valid call does return Z_OK: Goal.inflate_back_initialisation_domain (Safety/Domains.lean), required.
Complete return conditions and boundaries

Post Z_OK attaches fresh state for inflateBack with 8 <= windowBits <= 15. Input/output pointers, availability counters, totals, adler and data_type are unchanged. Only selected state fields are initialized; use this state with the callback API.

Errors A NULL version, different major-version byte or wrong stream size gives Z_VERSION_ERROR before stream access. NULL strm/window, or bits outside 8..15, gives Z_STREAM_ERROR. Allocation failure gives Z_MEM_ERROR: msg and allocator defaults may have changed, but the old state field is retained. No state was allocated, so no end call is needed after failed init in this inactive-stream domain.

Shared conditions and scope

The callback interface lets a caller supply input chunks and receive decoded output directly from its window. Start with inflateBackInit_, decode with inflateBack, and release state with inflateBackEnd. The caller's window remains caller-owned throughout.

These focused contracts follow the pinned infback.c and zlib.h in the default LP64 Linux build. See contract conventions for domain/effect labels.

What is proved. The required goal of each function is its safety goal: no undefined behaviour, no memory error, no leak, and termination (safety). Each entry names that goal under Proof goals, with its premises. The proof assumes those premises, not the documentary Pre; where the two differ, the Lean statement counts. The return values, output bytes and state changes described here are functional behaviour. They are read from the C and are to confirm where no theorem states them. They are not required for the safety results. Progress says which goals are done.

Each function has its own required safety goal: Goal.inflateBackInit__safety, Goal.inflateBack_safety and Goal.inflateBackEnd_safety (Safety/Back.lean). The sequence goal Goal.inflate_back_sequence_safety (Safety/Sequences.lean) is required as well. It adds that every history leaves a valid decoder state; its call clause and its end clause are the ones the goals of inflateBack and inflateBackEnd repeat. The functional goals Goal.inflateBackInit_, Goal.inflateBack and Goal.inflateBackEnd (Functional/Back.lean) are not planned; each entry says whether a theorem proves its functional goal.

A callback-decoder history (BackSafeReachable) is what the goals of inflateBack and inflateBackEnd range over. It starts with a call of inflateBackInit_ that returned Z_OK:

  • on a library heap (Fresh, Uniq, LibraryGlobals), with stream_size 112 and a version whose first byte is '1'; a call with another size or version byte does not return Z_OK;
  • on a readable stream record whose zalloc and zfree are each NULL or the default function, with any value in its other fields, state included (BackInitArguments);
  • with windowBits 8 to 15 and a non-NULL window of 2^windowBits writable bytes that is a slice of a heap byte block.

It continues with any number of two kinds of step. One is an inflateBack call that met conditions 2, 3, 5 and 6 of its goal and returned. The other is a caller edit that changes only next_in, avail_in, next_out, avail_out and memory the stream does not own, and keeps the bytes of the window slice. An edit also keeps the read-only flag of every block that stays live, which no C code can change. The premises that are narrower than zlib.h are rows of deviations.

inflateBack decodes raw DEFLATE. The caller handles any zlib/gzip header, trailer and checksum. The caller owns a writable window of at least 2^windowBits bytes. It is also the output buffer. windowBits is the base-two exponent of the window size in bytes: 15 means 2^15 = 32768 bytes. Use that value for general streams; smaller windows can reject valid long distances.

flowchart LR
    I["inflateBackInit_: allocate state"] --> B["inflateBack: decode one stream"]
    B -->|another stream| B
    B -->|success or decode error| E["inflateBackEnd: free state"]
    I -->|no decode needed| E

Through the callbacks the library calls application code when it needs data. The argument in_desc of the input callback is the application's own context; buf receives the pointer to the start of the next input chunk, and the return value is the number of bytes in that chunk. out_desc of the output callback is application context as well; buf and len give the output range the callback may read in this call, with len in bytes. The library hands the callback a pointer and a length; it does not transfer ownership of the window.

The callbacks have these types:

typedef unsigned (*in_func)(void FAR *, z_const unsigned char FAR * FAR *);
typedef int (*out_func)(void FAR *, unsigned char FAR *, unsigned);

in(in_desc, &buf) returns a byte count and sets buf; zero means no input and ignores buf. out(out_desc, buf, len) receives up to one window of bytes; zero means success. Descriptors may be NULL if the callback supports that value.

Safety goal

ZlibF.Spec.Public.Goal.inflateBackInit__safety

State: done · Status of the results

/-- `int inflateBackInit_(z_streamp strm, int windowBits, unsigned char FAR *window, const char *version, int stream_size)`.
**Safety of `inflateBackInit_`** (macro `inflateBackInit`): on `InitArguments`, for every
`windowBits`, every `stream_size` and every allocation outcome, the call returns without a fault.
zlib.h requires a window of `2^windowBits` bytes, so where the bits are in range and the window is
not `NULL` it is writable for that length. A `NULL` stream is refused with `Z_VERSION_ERROR` or
`Z_STREAM_ERROR` and the heap unchanged. Otherwise the call writes only the stream record and fresh
blocks; on `Z_OK` the stream holds a valid callback-decoder state over the caller's window, and only
the new state block is new; on any other code the live blocks are unchanged. -/
def Goal.inflateBackInit__safety : Prop :=
  ∀ h strm version size wb window, InitArguments h strm version →
    (window ≠ .null → 8 ≤ wb.toInt → wb.toInt ≤ 15 → Writable h window (2 ^ wb.toInt.toNat)) →
    ∃ rc after, C.run (Zlib.Infback.inflateBackInit_ strm wb window version size) h = .ok (rc, after) ∧
      match strm with
      | none => (rc = Z_VERSION_ERROR ∨ rc = Z_STREAM_ERROR) ∧ after = h
      | some r => Frame h after (StreamRoot r) ∧
          ((rc = Z_OK ∧ (∃ z s, BackValid after r h.nextBlk z s ∧ s.window = window) ∧
              LiveChange h after (fun b => b = h.nextBlk) (fun _ => False)) ∨
           (rc ≠ Z_OK ∧ LiveChange h after (fun _ => False) (fun _ => False)))
Related definitions and source ↗

Functional contract (beyond safety)

ZlibF.Spec.Public.Goal.inflateBackInit_

State: done · Status of the results

/-- `int inflateBackInit_(z_streamp strm, int windowBits, unsigned char *window,
const char *version, int stream_size)`.
The caller retains the window. Only the state record is allocated; its other integer fields
remain arbitrary. Refusal precedes allocation, and allocation failure retains the old state field. -/
def Goal.inflateBackInit_ : Prop :=
  (∀ h p wb window version head size, VersionValue h version head →
    (head ≠ some 49 ∨ size ≠ 112) →
    C.run (Zlib.Infback.inflateBackInit_ p wb window version size) h = .ok (Z_VERSION_ERROR, h)) ∧
  (∀ h p wb window version, VersionValue h version (some 49) →
    (p = none ∨ window = .null ∨ wb.toInt < 8 ∨ 15 < wb.toInt) →
    C.run (Zlib.Infback.inflateBackInit_ p wb window version 112) h = .ok (Z_STREAM_ERROR, h)) ∧
  (∀ h r z wb window version,
    Fresh h → Zlib.Inflate.Spec.Uniq h → LibraryGlobals h → r.get h = some z →
    DefaultOrNull z → VersionValue h version (some 49) →
    8 ≤ wb.toInt → wb.toInt ≤ 15 → window ≠ .null → Writable h window (2 ^ wb.toInt.toNat) →
    ∃ rc after,
      C.run (Zlib.Infback.inflateBackInit_ (some r) wb window version 112) h = .ok (rc, after) ∧
      after.nalloc = h.nalloc + 1 ∧
      if h.allocOk h.nalloc = false then
        rc = Z_MEM_ERROR ∧ SameObjects (r.put h (preparedStream z)) after
      else rc = Z_OK ∧
        let z' := { preparedStream z with state := some (.inflate h.nextBlk) }
        let s := backInitialState (h.garbage h.nalloc) window wb
        BackValid after r h.nextBlk z' s ∧
        Frame h after (StreamRoot r) ∧
        LiveChange h after (fun b => b = h.nextBlk) (fun _ => False))
Related definitions and source ↗
ZLIB × LEAN

Contents

READING NOWinflateBackInit_