uncompress2_z
Decodes the first zlib stream and reports both output size and input consumption.
Full chapter and shared rules ↗int ZEXPORT uncompress2_z(Bytef *dest, z_size_t *destLen, const Bytef *source, z_size_t *sourceLen);
Decodes the first zlib stream and reports both output size and input consumption.
Return values and next calls
Return type. int — zlib status code; counts are reported through length parameters
The status says whether the first zlib stream decoded completely. Length values report output and input consumption.
uncompress2_z()| Returned value | Meaning and conditions | Caller’s next step |
|---|---|---|
Z_OKComplete decoding |
The first zlib stream decoded completely and passed its checks; *destLen reports bytes written and *sourceLen reports bytes consumed. Trailing input is unused. |
Use exactly *destLen output bytes. Use *sourceLen to locate unused input. |
Z_BUF_ERROROutput full with input remaining |
Output filled the capacity and input remains; *destLen reports bytes written and *sourceLen reports bytes consumed. Already written output remains available. |
For a complete retry from the original input, first restore *destLen to the destination capacity and *sourceLen to the full original input length. For a complete result, enlarge the destination and make a new call from the original input; this utility returns no stream to resume. |
Z_DATA_ERRORData, completeness or dictionary error |
Input is malformed or incomplete, or needs a preset dictionary; raw and gzip inputs are also error cases. Empty input after successful initialization is a data error. Decoder Z_BUF_ERROR with no input remaining also maps to this code. | Do not treat partial output as a checked complete result; check the format, input completeness and dictionary requirement, then use an appropriate call. |
Z_MEM_ERRORInitialization allocation failure |
Initialization fails; existing length values are unchanged and no output is written. | For a complete retry from the original input, first restore *destLen to the destination capacity and *sourceLen to the full original input length. When resources permit, make a new complete call from the original input and supply the capacity again. |
Z_MEM_ERRORAllocation failure during decoding |
Allocation fails after successful initialization, possibly after partial output; *destLen reports bytes written and *sourceLen reports bytes consumed. |
For a complete retry from the original input, first restore *destLen to the destination capacity and *sourceLen to the full original input length. Retain written bytes if needed; they are not a fully checked result. A new call must start from the original input with capacity reset. |
Z_STREAM_ERRORArgument rejection before initialization |
NULL source for nonempty input, or NULL dest for positive capacity, or NULL destLen or NULL sourceLen is rejected before initialization; existing length values are unchanged. | Correct the rejected arguments, then make a new call. |
Calling conditions and effects
Domain Restricted domain.
Pre Restricted buffer domain above. *sourceLen is the available input and *destLen
the output capacity. Either length pointer may be NULL for checked rejection.
A NULL data pointer is allowed only with a zero corresponding length, or for checked rejection.
Malformed, truncated, raw, gzip and dictionary-dependent input are included as error cases.
Effects Stateful; common effects apply. The argument checks precede initialisation:
NULL sourceLen, nonempty NULL source, NULL destLen, or positive-capacity NULL destination
returns Z_STREAM_ERROR with both existing length cells unchanged.
Initialisation failure also preserves both lengths and writes no output.
After initialisation, every return stores bytes consumed in *sourceLen and bytes produced
in *destLen, including later memory failure. Output already written remains available.
Proof goals.
- Goal.
Goal.uncompress2_z_safe(Safety/Utilities.lean; the statement isUncompressCountedSafein Common/Utilities.lean); required. Theorem:ZlibF.Spec.Public.Proofs.Uncompress.uncompress2_z_safe(public-uncompress-safe.lean). - Applies when (
UncompressCountedSafe):- the heap is a library heap (
Fresh,Uniq,LibraryGlobals); - the platform size bound holds (
ByteObjectsFit); - a non-NULL
destLenpoints to a readable and writable 8-byte cell, and so does a non-NULLsourceLen(LengthCell); - a non-NULL
sourcepoints to*sourceLenreadable bytes; - a non-NULL
destpoints to*destLenwritable bytes; - the
destrange, thesourcerange and the two length cells do not overlap one another (UtilitySeparation).
- the heap is a library heap (
- Covered without condition. A NULL
destLenorsourceLen, which the call refuses; every content of the source bytes: a valid zlib stream, a truncated or malformed one, raw or gzip data; every allocation outcome. The memory conditions are those of Pre. - Guarantees.
- Returns. The call returns. If
sourceLenordestLenis NULL,sourceis NULL with a nonzero*sourceLen, ordestis NULL with a nonzero*destLen, the code isZ_STREAM_ERROR. Otherwise it isZ_OK,Z_BUF_ERROR,Z_DATA_ERRORorZ_MEM_ERROR, andZ_MEM_ERRORis returned only after an allocation failed (AllocationFailed). - State. None is kept: no stream, state or window of the call exists afterwards.
- Writes. With
Z_STREAM_ERRORfor the arguments just listed, nothing. Otherwise only: bytes atdest, at most the*destLengiven on entry;*sourceLen, which receives a count not above its entry value; and*destLen, which receives the number of bytes written. WithZ_MEM_ERRORit can also be that no byte is written and both cells keep their entry values. Every other object is unchanged (Store,SameObjectsUpToTableShape). - Allocations. Every block the call allocated is freed before it returns, on every path: the allocated blocks are the same as before the call.
- Returns. The call returns. If
- Not in this goal. A length cell that overlaps a buffer or the other cell, and overlapping
sourceanddest: outside every goal (deviations, row "Counted decompression"). Which code is returned for which input, and the bytes written: functional goalGoal.uncompress2_z(not planned; not done).
Complete return conditions and boundaries
Post Z_OK means a complete checked zlib stream decoded to the output.
Trailing input is unused. Z_BUF_ERROR means output filled the capacity and input remains.
Z_DATA_ERROR covers malformed or incomplete input and a required preset dictionary.
Z_MEM_ERROR means allocation failed and can follow partial output.
Edges NULL destination with zero capacity is accepted using a private output pointer;
a complete empty stream can succeed. Empty input is a data error after successful initialisation.
The exact final mapping is Z_STREAM_END to Z_OK, Z_NEED_DICT to Z_DATA_ERROR,
and Z_BUF_ERROR to Z_DATA_ERROR when no input remains. Other decoder codes are retained.
Shared conditions and scope
Use the buffer utilities when the complete input and output capacity are known at the call. They manage a temporary stream internally. Use the stream pages when you need incremental I/O, a different wrapper, a dictionary or explicit flush boundaries.
| Task | Entries |
|---|---|
| Compress a buffer | Choose a level, default level, size the destination |
| Decompress a buffer | Report input consumed, output only |
| Inspect the library | Version, compile flags, error text |
The contracts follow the pinned compress.c, uncompr.c, zutil.c and zlib.h in the default
LP64 Linux build. No patch touches these three C files (patches).
_z forms use z_size_t; plain forms use uLong. Both are 64-bit here.
See contract conventions for domain/effect labels.
These are focused contracts: Pre describes ordinary correct use and is deliberately narrower than
what the function accepts. A call outside Pre is not thereby undefined, and it need not return an
error code.
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.
The safety goals of the buffer utilities instantiate three statements
(Common/Utilities.lean): CompressorSafety for the
four compression functions, UncompressCountedSafe for uncompress2 and uncompress2_z, and
UncompressSingleSafe for uncompress and uncompress_z.
The buffer utilities create and release a local stream with the zlib wrapper and default settings.
The stream record is an automatic variable, not a heap block, so it takes no allocation attempt.
The allocation attempts of a call are those of the codec. A compress* call attempts at most
five, all in deflateInit: the state, the window, prev, head and the pending buffer; it
attempts none when it refuses its arguments or the level. An uncompress* call attempts the
decoder state in inflateInit, and the window inside inflate when decoding needs it.
First the convention for the lengths. sourceLen gives the number of readable input bytes.
*destLen is the writable capacity of the destination array before the call, and the number of
bytes written after it. For example, with a destination of 1000 bytes into which 120 bytes are
written, set *destLen = 1000 before the call and read 120 after a successful return. The length
cell is itself caller storage that stays live, readable and writable. For uncompress2_z,
*sourceLen likewise gives the available input before the call and reports the bytes consumed
after it.
The bound functions only compute a number; they do not allocate the destination array.
flowchart LR
B["compressBound"] --> C["compress / compress2"]
C --> Z["zlib stream"] --> U["uncompress / uncompress2"]
U --> D["decoded bytes"]
Common conventions
For buffer calls, the domain is restricted to valid memory: non-NULL sources cover the stated readable input; non-NULL destinations cover the stated writable capacity. Non-NULL length pointers name readable, writable scalar cells. Input, output and length cells are separate, including the two length cells when both occur. The caller keeps those objects live and does not modify them during the call. Each entry states its allowed NULL cases. Other invalid pointers are outside this scope. Decompression error handling needs no valid compressed-data assumption.
Common effects. Every in-scope call terminates without a fault. Buffer calls preserve input and memory outside the output and length cells. They write at most the original capacity. All internal allocations are released before return, including on allocation failure; the call leaves the caller no local stream and no allocation of its own. Pointer-valued queries return borrowed immutable storage. The safety goals named under Proof goals state these effects, without the claim about borrowed storage; the content of the output is functional behaviour.
Length cells in the model. For compress, compress2 and their _z forms, the translation
passes *destLen as a value: the function takes the capacity, or the fact that destLen is NULL,
and returns the length to store. The cell is not memory in the model, so the safety goals of these
four functions cannot speak about a cell that overlaps the source or the destination
(deviations, row "Whole-buffer compression"). For the uncompress family
the cells are memory, 8 readable and writable bytes each, and their separation from the buffers
is a stated condition of the goal.
Safety goal
ZlibF.Spec.Public.Goal.uncompress2_z_safe
State: done · Status of the results
/-- Safety of `int uncompress2_z(Bytef *dest, z_size_t *destLen, const Bytef *source, z_size_t *sourceLen)`. -/
def Goal.uncompress2_z_safe : Prop := UncompressCountedSafe Zlib.Uncompr.uncompress2_z trueRelated definitions and source ↗Functional contract (beyond safety)
ZlibF.Spec.Public.Goal.uncompress2_z
State: not done, not planned · Status of the results
/-- `int uncompress2_z(Bytef *dest, z_size_t *destLen, const Bytef *source, z_size_t *sourceLen)`.
Includes both nullable scalar checks, trailing input, partial output on memory failure and cleanup. -/
def Goal.uncompress2_z : Prop := UncompressCounted Zlib.Uncompr.uncompress2_z trueRelated definitions and source ↗