zError
Returns the text associated with a zlib result code.
Full chapter and shared rules ↗const char * ZEXPORT zError(int err);
Returns the text associated with a zlib result code.
Return values and next calls
Return type. const char * — Borrowed immutable error-text pointer
Maps the supplied result code to text. The function itself always returns a non-NULL string pointer.
zError()| Returned value | Meaning and conditions | Caller’s next step |
|---|---|---|
"need dictionary"need dictionary text |
err == 2. | Read the borrowed static text; do not write to or free it. |
"stream end"stream end text |
err == 1. | Read the borrowed static text; do not write to or free it. |
"file error"file error text |
err == -1. | Read the borrowed static text; do not write to or free it. |
"stream error"stream error text |
err == -2. | Read the borrowed static text; do not write to or free it. |
"data error"data error text |
err == -3. | Read the borrowed static text; do not write to or free it. |
"insufficient memory"insufficient memory text |
err == -4. | Read the borrowed static text; do not write to or free it. |
"buffer error"buffer error text |
err == -5. | Read the borrowed static text; do not write to or free it. |
"incompatible version"incompatible version text |
err == -6. | Read the borrowed static text; do not write to or free it. |
""Empty text |
err == 0, or err is outside -6–2, including the minimum and maximum int. | Read the empty string as needed; this is neither a NULL pointer nor another error code. |
Calling conditions and effects
Domain Full type domain.
Pre Full type domain: every int, including its minimum and maximum values.
Effects Read-only. The result is borrowed immutable static storage; do not write or free it. No allocation, heap change or error return occurs. Values outside -6–2 are checked before index arithmetic, so both scalar extremes safely return empty text.
Proof goals. No required goal: zlib.h declares this function under "undocumented functions (not part of the zlib API)". A goal is stated for it: functional goal Goal.zError (not planned; a theorem proves it), in Functional/Queries.lean, with the theorem ZlibF.Spec.Public.Proofs.zError (public-zerror.lean). It is called a functional goal because it fixes the returned text; it states the safety facts as well. For every heap and every err the goal states that the call returns, that the heap after the call is the heap before it (nothing is written, allocated or freed), and that the result points to read-only static storage that holds the text given under Post.
Complete return conditions and boundaries
Post Returns a non-NULL pointer to the following NUL-terminated text.
err |
Text |
|---|---|
| 2 | need dictionary |
| 1 | stream end |
| -1 | file error |
| -2 | stream error |
| -3 | data error |
| -4 | insufficient memory |
| -5 | buffer error |
| -6 | incompatible version |
| 0 or any other value | empty string |
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.
Functional contract (beyond safety)
ZlibF.Spec.Public.Goal.zError
State: done · Status of the results
/-- `const char *zError(int err)`.
Every signed argument returns the public error text as static read-only storage.
Every heap is unchanged; no allocation, leak or runtime fault is permitted. -/
def Goal.zError : Prop :=
∀ (h : Heap) (err : Int32), ∃ p,
C.run (Zlib.Zutil.zError err) h = .ok (p, h) ∧ StaticString h p (errorText err.toInt)Related definitions and source ↗