inflateBack
Purpose. Decode one complete raw stream through the input and output callbacks.
Full chapter and shared rules ↗int ZEXPORT inflateBack(z_streamp strm, in_func in, void FAR *in_desc,
out_func out, void FAR *out_desc);
Purpose. Decode one complete raw stream through the input and output callbacks.
Return values and next calls
Return type. int — zlib status code
The result covers callback decoding of one complete raw stream. This function never returns Z_OK, and every call starts a fresh stream.
inflateBack()| Returned value | Meaning and conditions | Caller’s next step |
|---|---|---|
Z_STREAM_ENDRaw stream and output complete |
A complete raw DEFLATE stream was decoded and every output callback returned zero. | Preserve the unread suffix in next_in/avail_in; decode another independent stream or call inflateBackEnd. |
Z_BUF_ERRORInput callback had no more data |
next_in is NULL on return; the input callback returned zero and input was exhausted. | The current decode is incomplete; end it, or prepare complete input and start a fresh decode from the beginning rather than resuming a pause. |
Z_BUF_ERROROutput callback failed |
next_in is non-NULL on return; an output callback returned nonzero. A final output failure changes an otherwise Z_STREAM_END result to this value. | Handle the caller’s output failure; end the decoder or start an independent decode from the beginning, without ordinary inflate-style continuation. |
Z_DATA_ERRORMalformed DEFLATE |
Malformed raw DEFLATE was found and msg set; output may already have been delivered, and a final output failure does not replace this error. | Call inflateBackEnd, or prepare input again for a new stream on the next inflateBack call. |
Z_STREAM_ERRORStream or state missing |
strm or state is NULL; no callbacks are invoked. | First create a valid callback decoder with inflateBackInit_; ordinary inflate state cannot be used with this interface. |
Reading the result.
- The input callback returns a byte count, with zero meaning no input.
Calling conditions and effects
Domain Restricted domain: a live callback decoder, valid separated slices and a finite, returning callback protocol. Arbitrary malformed input bytes are included.
Pre Init succeeded and end has not run. Keep the stream, state and window live.
Initialize next_in; NULL requests callback input immediately and ignores avail_in.
Otherwise initialize avail_in and provide that many readable bytes at next_in.
Initial and callback-provided input slices do not overlap the window, stream or private state.
Neither callback is NULL. Every callback returns safely and the total input supplied is bounded.
Callbacks may read only the input/output bytes supplied to them and their own valid objects.
They may update, allocate or free their own memory, but preserve the stream, private state and
window slice. An input chunk remains readable and unchanged until the next input callback or
return, including across output callbacks. Output callbacks read at most len window bytes.
Callback storage and the window may share an allocation when their used byte slices do not overlap.
No concurrent or re-entrant access to this stream is allowed.
Effects Reset decoding for a new stream, consume input, write the window and invoke callbacks.
Full windows and a final nonempty partial window are delivered to out, including on error.
Callbacks may therefore observe output before a later format or input failure.
The library allocates and frees nothing; callback allocations remain the caller's responsibility.
Proof goals.
- Goal.
Goal.inflateBack_safety(Safety/Back.lean); required. Theorem:ZlibF.Spec.Public.BackSafetyProof.inflateBack_safety(public-back-safety.lean). The goal has three clauses: the refusal of a NULL stream, the refusal of a stream record whose state is NULL, and one call on a history. The first and the third are clauses 1 and 3 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 call on a history asks:strmhas a callback-decoder history (BackSafeReachable); the premiseBackValidnames its record and its state;next_inis NULL, or coversavail_inreadable bytes (Bytes) that do not overlap the window (Separate);- the callbacks follow a protocol (
CallbackProtocol) whose invariant holds at the call: each ofinandoutreturns, changes only the callbacks' own blocks, and keeps the bytes of the window slice;inhands out a readable chunk that does not overlap the window;outkeeps the current input chunk readable (deviations lists every clause). The two callback clauses are required only on a heap in which the stream is a valid callback decoder over this window (CallbackEntry), which is the heap the library hands toinandout. That such a protocol exists, and that all six premises hold together on a concrete call:Goal.inflateBack_call_domain(Safety/Domains.lean), required (callbacks); - the protocol's total input, the first chunk included, is below
2^48bytes (inputBound); - the platform size bound holds at the call, and each callback step keeps it (
ByteObjectsFit,BackPlatform); - every input chunk lies in a heap byte block: the first one (
BackFirstChunk) and each oneinhands out (BackPlatform).
- Covered without condition. Every input byte sequence, well formed or not, and every split of it into chunks; an
inthat returns 0; anoutthat reports failure; every value ofin_descandout_desc; callbacks that allocate and free memory of their own. In the second refusal, every value of the other fields of the record. - Guarantees.
- Returns. On a NULL
strm, and on a stream record whosestateis NULL, the call returnsZ_STREAM_ERROR. On a history it returnsZ_STREAM_END,Z_DATA_ERRORorZ_BUF_ERROR. - State. On a history the stream keeps a valid callback-decoder state over the same window, with the same window size (
BackValid), and the protocol's invariant holds after the call. The stream then has a history again, and the goal of the next call applies. - Writes. In the two refusals, nothing: the heap is unchanged. On a history, only the stream record, the state record, the callbacks' own blocks and the block of the window; when that block is not one of the callbacks' own, only the window slice of it (
CallbackFrame). The blocks that hold callback input, the first chunk included, are among the callbacks' own blocks, also when the callbacks only read them: otherwise the invariant of the protocol cannot hold. For these blocks the guarantee is the invariant clause of State, not this frame: a fact about their bytes that the callbacks keep holds after the call. When the input shares the block of the window, that block is one of the callbacks' own, and the frame then does not limit the writes in it to the window slice; the invariant describes the bytes outside the slice. - Allocations. On a history, a block outside the callbacks' own is allocated after the call exactly when it was before: the library allocates and frees nothing.
- Returns. On a NULL
- Not in this goal. A stream record whose non-NULL state does not come from
inflateBackInit_, for example one frominflateInit_: no goal covers it. What reachesout, which of the three codes is returned, andnext_inandavail_inafter the call: functional goalGoal.inflateBack(not planned; not done). Conditions 4 to 6, the heap-block window and the rule for caller edits are narrower thanzlib.h: rows of deviations.
Complete return conditions and boundaries
Post Z_STREAM_END means the complete raw stream was decoded and every output call succeeded.
The concatenated chunks are its uncompressed bytes, with no preset dictionary.
next_in/avail_in identify the unread suffix of the initial or last callback chunk.
After input exhaustion they are NULL/zero; otherwise the pointer advances by the consumed bytes.
Totals, adler and data_type are unchanged; next_out/avail_out are not the output interface.
The stream retains its state and window for another independent decode or end.
Errors Z_BUF_ERROR means input exhaustion or a nonzero output result; it never returns Z_OK.
For Z_BUF_ERROR, NULL next_in identifies input exhaustion; non-NULL identifies output failure.
Z_DATA_ERROR means malformed DEFLATE and sets msg. A final output failure changes
Z_STREAM_END to Z_BUF_ERROR; it does not replace another error already selected.
NULL strm or NULL state gives Z_STREAM_ERROR without callbacks. Other invalid states are
outside this domain: a state from ordinary inflateInit_ is not a callback decoder.
After a decode error, end still releases the state; another call starts a fresh stream.
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.inflateBack_safety
State: done · Status of the results
/-- `int inflateBack(z_streamp strm, in_func in, void FAR *in_desc, out_func out, void FAR *out_desc)`.
**Safety of `inflateBack`**: a `NULL` stream, and a stream record whose state is `NULL`, are refused
with `Z_STREAM_ERROR` and nothing changed; one more call on a history of `BackSafeReachable` returns
without a fault, keeps the state valid over the same window, and changes only its frame (clauses 1
and 3 of `Goal.inflate_back_sequence_safety`). -/
def Goal.inflateBack_safety : Prop :=
(∀ h input inDesc output outDesc,
C.run (Zlib.Infback.inflateBack none input inDesc output outDesc) h = .ok (Z_STREAM_ERROR, h)) ∧
(∀ h r z input inDesc output outDesc, r.get h = some z → z.state = none →
C.run (Zlib.Infback.inflateBack (some r) input inDesc output outDesc) h = .ok (Z_STREAM_ERROR, h)) ∧
(∀ h r i window n z s input inDesc output outDesc
(protocol : CallbackProtocol r i window n input inDesc output outDesc) first,
BackSafeReachable h r i window n → BackValid h r i z s →
(if z.next_in = .null then first = [] else Bytes h z.next_in z.avail_in.toNat first) →
Separate z.next_in first.length window n →
protocol.invariant h { supplied := first, chunks := [], active := z.next_in, held := first } →
protocol.inputBound < 2 ^ 48 →
ZlibF.PlatformMemory.ByteObjectsFit h → BackPlatform protocol → BackFirstChunk z first →
∃ rc after z' s' log,
C.run (Zlib.Infback.inflateBack (some r) input inDesc output outDesc) h = .ok (rc, after) ∧
BackValid after r i z' s' ∧ s'.window = window ∧ s'.wsize = s.wsize ∧
protocol.invariant after log ∧
(rc = Z_STREAM_END ∨ rc = Z_DATA_ERROR ∨ rc = Z_BUF_ERROR) ∧
CallbackFrame protocol.own h after r i window n ∧
(∀ b, ¬ protocol.own b → (after.live b ↔ h.live b)))Related definitions and source ↗Functional contract (beyond safety)
ZlibF.Spec.Public.Goal.inflateBack
State: not done, not planned · Status of the results
/-- `int inflateBack(z_streamp strm, in_func in, void *in_desc, out_func out, void *out_desc)`.
For every finite, returning caller protocol, decode raw DEFLATE and deliver the chunks through
that actual output callback. The protocol's observation relation records the bytes delivered.
No allocation or free by the library is charged to the caller's callbacks. -/
def Goal.inflateBack : Prop :=
(∀ h input inDesc output outDesc,
C.run (Zlib.Infback.inflateBack none input inDesc output outDesc) h = .ok (Z_STREAM_ERROR, h)) ∧
(∀ h r i z s input inDesc output outDesc
(protocol : CallbackProtocol r i s.window s.wsize.toNat input inDesc output outDesc) first,
BackValid h r i z s →
(if z.next_in = .null then first = [] else Bytes h z.next_in z.avail_in.toNat first) →
Separate z.next_in first.length s.window s.wsize.toNat →
protocol.invariant h { supplied := first, chunks := [], active := z.next_in, held := first } →
∃ rc after z' s' log unused consumed,
C.run (Zlib.Infback.inflateBack (some r) input inDesc output outDesc) h = .ok (rc, after) ∧
BackValid after r i z' s' ∧ s'.window = s.window ∧ s'.wsize = s.wsize ∧
protocol.invariant after log ∧
(rc = Z_STREAM_END ∨ rc = Z_DATA_ERROR ∨ rc = Z_BUF_ERROR) ∧
consumed ++ unused = log.supplied ∧ unused.length = z'.avail_in.toNat ∧
unused <:+ log.held ∧
(log.exhausted = true → z'.next_in = .null ∧ unused = []) ∧
(log.exhausted = false → z'.next_in = advance log.active (log.held.length - unused.length)) ∧
(∀ chunk, chunk ∈ log.chunks → chunk ≠ [] ∧ chunk.length ≤ s.wsize.toNat) ∧
(rc = Z_STREAM_END → Deflate.Decodes [] consumed log.chunks.flatten ∧ log.failed = false) ∧
(rc = Z_BUF_ERROR → log.exhausted = true ∨ log.failed = true) ∧
z'.total_in = z.total_in ∧ z'.total_out = z.total_out ∧ z'.adler = z.adler ∧
CallbackFrame protocol.own h after r i s.window s.wsize.toNat ∧
(∀ b, ¬ protocol.own b → (after.live b ↔ h.live b)))Related definitions and source ↗