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_OKCallback 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_ERRORVersion 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_ERRORStream, 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_ERRORState 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 ofinflateInit2_):- the heap is a library heap (
Fresh,Uniq,LibraryGlobals); versionis NULL or its first byte is readable (VersionValue);strmis NULL, or points to a readable stream record whosezallocandzfreeare each NULL or the default function (DefaultOrNull);- when
windowis not NULL andwindowBitsis 8 to 15,windowcovers2^windowBitswritable bytes (Writable).
- the heap is a library heap (
- Covered without condition. Every
windowBits, also outside 8 to 15; a NULLwindow; everystream_size; every value of the first byte ofversion; every value of the other fields of the record,stateincluded; every allocation outcome. If the record held a live decoder and the call returnsZ_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
strmthe code isZ_VERSION_ERRORorZ_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 iswindow(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.
- Returns. The call returns. With a NULL
- Not in this goal. A stream whose
zallocorzfreeis a custom function: outside every goal (deviations). Which code each refusal and the allocation failure returns, and the field values after the call: functional goalGoal.inflateBackInit_(not planned; a theorem proves it). That a valid call does returnZ_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), withstream_size112 and aversionwhose first byte is'1'; a call with another size or version byte does not returnZ_OK; - on a readable stream record whose
zallocandzfreeare each NULL or the default function, with any value in its other fields,stateincluded (BackInitArguments); - with
windowBits8 to 15 and a non-NULL window of2^windowBitswritable 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 ↗