Skip to content
REFERENCE / ZLIB × LEAN

adler32_z

Update an Adler-32 checksum with a byte range, or obtain its initial value.

Full chapter and shared rules ↗
uLong ZEXPORT adler32_z(uLong adler, const Bytef *buf, z_size_t len);

Update an Adler-32 checksum with a byte range, or obtain its initial value.

Return values and next calls

Return type. uLong — 32-bit checksum

Returns the updated Adler-32, or the initial value for a new checksum.

adler32_z()
Returned value Meaning and conditions Caller’s next step
1
Initial value
buf == NULL and len == 0, with any incoming checksum; no bytes are read. Start a new sequence at 1.
reduce(adler)
Empty range reduces the seed
buf is non-NULL and len == 0; a one-past pointer is also allowed for the empty range. reduce takes the low 32 bits and reduces each 16-bit half modulo 65521. The result equals low32(adler) when adler is a genuine Adler-32, because both halves of a genuine Adler-32 are below 65521. Keep this value for the next update.
Adler-32(A || buf)
Checksum after append
buf covers len readable bytes, len > 0, and the low 32 bits of adler are the Adler-32 of A. Use this value in later updates or compare it with the expected checksum.

Calling conditions and effects

Domain Restricted domain. Effects: read-only when buf is non-NULL.

Pre Either buf is NULL and len == 0, or it points to len readable bytes. For the checksum postcondition, the low 32 bits of adler are the Adler-32 of A. There is no setup or cleanup requirement.

Effects Preserve all memory and ownership. Read only the given range.

Forged seeds are outside this functional contract: the one-byte path need not agree with first reducing both seed halves modulo 65521. See the Adler seed note.

Proof goals.

  • Goal. Goal.adler32_z_safety (Safety/Checksums.lean); required. Theorem: ZlibF.Spec.Public.StatelessSafetyProof.adler32_z_safety (public-stateless-safety.lean).
  • Applies when. buf is NULL with len == 0, or buf points to len readable bytes (AdlerBufferBytes). For len == 0 a pointer one past the end of an object is allowed.
  • Covered without condition. Every adler, also a value that is not a checksum; every content of the bytes; every heap, with or without the library's tables.
  • Guarantees.
    • Returns. The call returns.
    • State, writes, allocations. None: the heap after the call is the heap before it.
  • Not in this goal. NULL buf with a nonzero len: outside every goal; this is narrower than zlib.h (deviations, row "Adler initialization queries"). The value returned: functional goal Goal.adler32_z (not planned; a theorem proves it).
Complete return conditions and boundaries

Post A NULL, zero-length query returns 1 for every adler, without reading bytes. Otherwise return the Adler-32 of A followed by buf[0..len-1]. A non-NULL zero-length range returns the low 32 bits of adler with each 16-bit half reduced modulo 65521 (adlerStart in Common/Checksums.lean). For a genuine Adler-32 that is the incoming checksum unchanged; a seed of 0x0000FFFF returns 0x0000000E.

Shared conditions and scope

Compute a checksum a buffer at a time, or combine the checksums of independently processed byte sequences without rereading them. The byte sequences A and B below are ordinary data; the contracts use the Adler-32 or CRC-32 of those sequences. For example, after processing A and then B, the checksum of A can be the starting value of the next update; if A and B were processed independently, the combination functions give the checksum of A followed by B.

In the update functions, buf points to this batch of input, len is its byte count, and the incoming adler or crc is the value to continue from. In the combination functions, len2 is the byte count of the second sequence B only, not the total length of the two.

Task Entries
Update Adler-32 Size-type length, 32-bit length
Combine Adler-32 Ordinary offset, explicit 64-bit offset
Update CRC-32 Size-type length, 32-bit length
Combine CRC-32 Ordinary offset, explicit 64-bit offset
Reuse a CRC combination operator Generate, generate with 64-bit length, apply
Inspect the byte table get_crc_table

The contracts follow the pinned adler32.c, crc32.c and zlib.h in the default LP64 Linux static build. No patch touches these two C files (patches). Dynamic table generation, hardware CRC hooks and generated table executables are not covered (build and platform). No checksum entry writes state, allocates, frees or performs I/O. Exceptional numeric results are ordinary values, rather than error codes. Domain and effects remain independent as explained in contract conventions. 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 (safety): each safety goal (Safety/Checksums.lean) says that the call returns and that the heap after the call is the heap before it. It says nothing about the value. 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 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 CRC goals have a premise on the model's heap: its two constant CRC tables, crc_table and x2n_table, equal the tables of the translated crc32.h (CrcGlobals). The premise is assumed of the heap the call starts on; no theorem derives it for an arbitrary heap. It is a condition on the model, not a duty of the caller (model limits). Two facts are proved about it. A library heap, which is what the stream goals start from, meets it (crc_globals_of_library). Each checksum goal returns the heap unchanged, so the premise still holds after the call.

The practical checksum contracts use actual byte sequences A and B. Each checksum is computed independently, starting at 1 for Adler-32 or 0 for CRC-32. These contracts deliberately omit functional promises for forged checksums. The functional goals in Functional/Checksums.lean also describe arbitrary seeds and exact scalar results. Both the Adler entries and their Lean goals, safety and functional, require zero length for NULL initialization queries (AdlerBufferBytes in Common/Checksums.lean). See deviations.

In this build, uLong and z_size_t are unsigned 64-bit types; uInt is unsigned 32-bit. z_off_t and z_off64_t are signed 64-bit. Input checksum bits above bit 31 are ignored; returned checksums fit in 32 bits. The explicit *64 declarations depend on the header's large-file feature macros.

Safety goal

ZlibF.Spec.Public.Goal.adler32_z_safety

State: done · Status of the results

/-- `uLong adler32_z(uLong adler, const Bytef *buf, z_size_t len)`.
**Safety of `adler32_z`**: as `Goal.adler32_safety` with a 64-bit length. -/
def Goal.adler32_z_safety : Prop :=
  ∀ (h : Heap) (seed : UInt64) (pointer : BPtr) (length : UInt64) (bytes : List UInt8),
    AdlerBufferBytes h pointer length.toNat bytes →
    ∃ value, C.run (Zlib.Adler32.adler32_z seed pointer length) h = .ok (value, h)
Related definitions and source ↗

Functional contract (beyond safety)

ZlibF.Spec.Public.Goal.adler32_z

State: done · Status of the results

/-- `uLong adler32_z(uLong adler, const Bytef *buf, z_size_t len)`.
NULL queries have zero length; nonnull readable objects cover 64-bit lengths and all seeds.
See `docs/en/deviations.md` for the query restriction. Exact value, no fault, termination,
no allocation and the complete heap frame. -/
def Goal.adler32_z : Prop := AdlerUpdate Zlib.Adler32.adler32_z
Related definitions and source ↗
ZLIB × LEAN

Contents

READING NOWadler32_z