inflateBackEnd
Purpose. Release the state allocated by callback init.
Full chapter and shared rules ↗int ZEXPORT inflateBackEnd(z_streamp strm);
Purpose. Release the state allocated by callback init.
Return values and next calls
Return type. int — zlib status code
The result says whether internal callback state was released; the caller always manages its window.
inflateBackEnd()| Returned value | Meaning and conditions | Caller’s next step |
|---|---|---|
Z_OKInternal state released |
The valid callback decoder’s internal state was freed and state set to NULL; the window and other fields are unchanged. | The caller’s window may now be released or reused; reinitialize before decoding again. |
Z_STREAM_ERRORNo release performed |
strm, state or zfree is NULL; no memory is freed. | Check the lifetime and matching free function; these checks do not establish that an arbitrary non-NULL state is valid. |
Calling conditions and effects
Domain Restricted domain: a live callback decoder with valid default free, plus the checked NULL-stream, NULL-state and NULL-free refusal cases.
Pre For cleanup, init succeeded, end has not run and no decode or callback is active.
The stream and attached state remain valid; retain the matching zfree and opaque.
Cleanup is permitted after successful decoding and after any decode error.
Effects Free exactly the internal state and clear state.
Proof goals.
- Goal.
Goal.inflateBackEnd_safety(Safety/Back.lean); required. Theorem:ZlibF.Spec.Public.BackSafetyProof.inflateBackEnd_safety(public-back-safety.lean). The goal has three clauses: the refusal of a NULL stream, the refusal of a stream record whosestateorzfreeis NULL, and the end of a history. The third is clause 4 of the sequence goalGoal.inflate_back_sequence_safety. - Applies when. The first refusal has no condition. The second asks that
strmpoints to a readable stream record. The end of a history asks:strmhas a callback-decoder history (BackSafeReachable).
- Covered without condition. Every history: straight after init, and after a decode that returned
Z_STREAM_END,Z_DATA_ERRORorZ_BUF_ERROR. The end clause has no platform premise. In the second refusal, every value of the other fields of the record. - Guarantees.
- Returns. On a NULL
strm, and on a stream record whosestateorzfreeis NULL, the call returnsZ_STREAM_ERROR. On a history it returnsZ_OK. - State. On a history the
statefield of the stream record is NULL after the call. The history ends. - Writes. In the two refusals, nothing: the heap is unchanged. On a history, only the stream record and the state block (
Frame). - Allocations. On a history exactly the state block is freed, and nothing is allocated (
LiveChange).
- Returns. On a NULL
- Not in this goal. A stream record whose non-NULL state does not come from
inflateBackInit_: no goal covers it. The other field values after the call: functional goalGoal.inflateBackEnd(not planned; a theorem proves it).
Complete return conditions and boundaries
Post Z_OK leaves state NULL. The caller's window and all other stream fields are unchanged.
The caller may now release or reuse its window; the library never frees it.
Errors NULL strm, NULL state or NULL zfree gives Z_STREAM_ERROR and frees nothing.
These checks do not validate an arbitrary non-NULL state or detect ownership mistakes.
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.inflateBackEnd_safety
State: done · Status of the results
/-- `int inflateBackEnd(z_streamp strm)`.
**Safety of `inflateBackEnd`**: a `NULL` stream, and a stream record whose state or `zfree` is
`NULL`, are refused with `Z_STREAM_ERROR` and nothing changed (clauses 1 and 2 of
`Goal.inflateBackEnd`); on a history of `BackSafeReachable` it returns `Z_OK`, clears the state
field, and frees exactly the state block (clause 4 of `Goal.inflate_back_sequence_safety`). -/
def Goal.inflateBackEnd_safety : Prop :=
(∀ h, C.run (Zlib.Infback.inflateBackEnd none) h = .ok (Z_STREAM_ERROR, h)) ∧
(∀ h r z, r.get h = some z → z.state = none ∨ z.zfree = .null →
C.run (Zlib.Infback.inflateBackEnd (some r)) h = .ok (Z_STREAM_ERROR, h)) ∧
∀ h r i window n, BackSafeReachable h r i window n →
∃ after z, C.run (Zlib.Infback.inflateBackEnd (some r)) h = .ok (Z_OK, after) ∧
r.get after = some z ∧ z.state = none ∧
Frame h after (fun b => StreamRoot r b ∨ b = i) ∧
LiveChange h after (fun _ => False) (fun b => b = i)Related definitions and source ↗Functional contract (beyond safety)
ZlibF.Spec.Public.Goal.inflateBackEnd
State: done · Status of the results
/-- `int inflateBackEnd(z_streamp strm)`.
Free only the state record. The caller's window is retained, even when it is a slice of another object. -/
def Goal.inflateBackEnd : Prop :=
(∀ h, C.run (Zlib.Infback.inflateBackEnd none) h = .ok (Z_STREAM_ERROR, h)) ∧
(∀ h r z, r.get h = some z → z.state = none ∨ z.zfree = .null →
C.run (Zlib.Infback.inflateBackEnd (some r)) h = .ok (Z_STREAM_ERROR, h)) ∧
(∀ h r i z s, BackValid h r i z s →
∃ after, C.run (Zlib.Infback.inflateBackEnd (some r)) h = .ok (Z_OK, after) ∧
r.get after = some { z with state := none } ∧
LiveChange h after (fun _ => False) (fun b => b = i) ∧
Frame h after (fun b => StreamRoot r b ∨ b = i) ∧
after.nalloc = h.nalloc ∧ after.nextBlk = h.nextBlk)Related definitions and source ↗