Skip to content
REFERENCE / ZLIB × LEAN

compress2_z

Compresses the input into one complete zlib stream at the requested level.

Full chapter and shared rules ↗
int ZEXPORT compress2_z(Bytef *dest, z_size_t *destLen, const Bytef *source,
                        z_size_t sourceLen, int level);

Compresses the input into one complete zlib stream at the requested level.

Return values and next calls

Return type. int — zlib status code; output length is written separately

The status says whether the whole buffer became a complete zlib stream. The byte count is in *destLen.

compress2_z()
Returned value Meaning and conditions Caller’s next step
Z_OK
Complete compression
The output is a complete zlib encoding; *destLen is the number of bytes written. Use exactly *destLen bytes as the compressed result.
Z_BUF_ERROR
Output capacity exhausted
Capacity was filled with an encoding prefix; a non-NULL destination with zero capacity also returns this after successful initialization. *destLen reports bytes written. For a complete retry from the original input, first restore *destLen to the destination capacity. Provide a larger destination and call again from the original input; this prefix is not a complete stream.
Z_MEM_ERROR
Allocation failed without output
After early argument checks and a valid level, initialization allocation fails. No output was written; *destLen is zero. For a complete retry from the original input, first restore *destLen to the destination capacity. Make a new complete call only when resources permit; this call produced no compressed result.
Z_STREAM_ERROR
Early argument rejection
source is NULL with sourceLen > 0, or dest is NULL with positive original capacity. destLen == NULL is also checked and rejected. Existing length values are unchanged. Correct the rejected arguments and call again with valid buffers.
Z_STREAM_ERROR
Invalid compression level
After early argument checks, level is outside -1 and 0–9; *destLen is zeroed before any allocation. Choose -1 or 0–9 and reset the output capacity for a new call.
Z_STREAM_ERROR
NULL destination with zero capacity
After early argument checks and a valid level, dest == NULL with zero capacity and initialization succeeds; *destLen is zero. Allocation failure instead returns Z_MEM_ERROR. Provide a valid destination and sufficient capacity, then make a new call.

Calling conditions and effects

Domain Restricted domain.

Pre Restricted buffer domain above. source may be NULL for zero input or checked rejection. destLen may be NULL for checked rejection. dest may be NULL for checked rejection, including the zero-capacity case below. Levels -1 and 0–9 are valid; -1 selects level 6.

Effects Stateful; common effects apply. A NULL source with nonzero input, NULL destLen, or NULL destination with nonzero capacity gives Z_STREAM_ERROR before any length write. Otherwise *destLen is cleared before initialisation. A bad level returns Z_STREAM_ERROR with length zero before any allocation. Later returns store the number of bytes written.

Proof goals.

  • Goal. Goal.compress2_z_safety (Safety/Utilities.lean; the statement is CompressorSafety in Common/Utilities.lean); required. Theorem: ZlibF.Spec.Public.Proofs.Compress.compress2_z_safety (public-compress-safe-mid.lean).
  • Applies when (CompressorSafety):
    1. the heap is a library heap (Fresh, Uniq, LibraryGlobals);
    2. the platform size bound holds (ByteObjectsFit);
    3. either the arguments are ones the call refuses (destLen is NULL, source is NULL with a nonzero sourceLen, or dest is NULL with a nonzero *destLen; compressRejected), or source points to sourceLen readable bytes, dest points to *destLen writable bytes, and the two ranges do not overlap (CompressArguments). A NULL source or dest counts as a range of zero bytes.
  • Covered without condition. A NULL destLen, which the call refuses; every level, valid or not; every content of the source bytes; every allocation outcome. The length cell *destLen is a value in the translation, not memory (common conventions): the goal says nothing about a cell that overlaps a buffer, which Pre excludes as well.
  • Guarantees.
    • Returns. The call returns. With refused arguments the code is Z_STREAM_ERROR. Z_MEM_ERROR is returned only after an allocation failed (AllocationFailed).
    • State. None is kept: no stream, state or buffer of the call exists afterwards.
    • Writes. Only bytes at dest, at most the *destLen given on entry; with refused arguments nothing, and the length value is unchanged. 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.
  • Not in this goal. Overlapping source and dest: outside every goal (deviations, row "Whole-buffer compression"). Which code is returned for accepted arguments, the bytes written and the length stored: functional goal Goal.compress2_z (not planned; not done).
Complete return conditions and boundaries

Post Z_OK means the output is a complete zlib encoding of the input and *destLen is its length. Z_BUF_ERROR means the capacity was filled with a prefix of that encoding. Z_MEM_ERROR means allocation failed and no output was written.

Edges NULL destination with zero capacity reaches initialisation: it returns Z_MEM_ERROR if allocation fails, otherwise Z_STREAM_ERROR, with length zero. A non-NULL destination with zero capacity gives Z_BUF_ERROR after successful initialisation. Empty input is valid.

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.compress2_z_safety

State: done · Status of the results

/-- Safety of `compress2_z` (`CompressorSafety`). -/
def Goal.compress2_z_safety : Prop :=
  ∀ level, CompressorSafety (fun d c s n => Zlib.Compress.compress2_z d c s n level) true
Related definitions and source ↗

Functional contract (beyond safety)

ZlibF.Spec.Public.Goal.compress2_z

State: not done, not planned · Status of the results

/-- `int compress2_z(Bytef *dest, z_size_t *destLen, const Bytef *source, z_size_t sourceLen, int level)`.
Includes null-cell rejection, unchanged capacity on argument rejection, exact stored length,
valid compressed data, buffer exhaustion, allocation failure, frame and complete cleanup. -/
def Goal.compress2_z : Prop :=
  ∀ level, CompressorContract (fun d c s n => Zlib.Compress.compress2_z d c s n level) level true
Related definitions and source ↗
ZLIB × LEAN

Contents

READING NOWcompress2_z