gzungetc
Push one byte onto a reader's uncompressed input.
Full chapter and shared rules ↗2425ced89b926581 · Source at the matching commit ↗Read the function’s preconditions and results first. Expand the shared rules below for buffer and ownership requirements used throughout this API group.
int ZEXPORT gzungetc(int c, gzFile file);
Push one byte onto a reader's uncompressed input.
Domain Restricted domain: reader; full int c range, including refusal of negatives.
Effect: stateful pushback, possible input inspection/allocation and skip.
Pre The shared reader requirements hold. Pushback is allowed immediately after open and can therefore make the logical position negative.
Post On success, stores the low eight bits of c, returns the original
nonnegative c, decreases position by one and clears past-EOF. Pushed bytes
are read in reverse push order. The physical input file is not modified.
Errors and edges: Returns -1 for NULL, a writer, negative c, lack of
pushback room or failed setup/skip. Initial inspection and a pending skip can
happen before negative c is refused. Full pushback records Z_DATA_ERROR
unless preserving a serious error. With allocated room, pushback may succeed
after a read error; it does not generally clear that error. Position -1 can
be a successful state, so tell's -1 alone is ambiguous. Seeking from this
state has a to confirm source caveat; it is not forbidden here.
Shared conditions and scope
API manual · Contract conventions · Stream compression · Stream decompression
Use a gzFile handle for buffered gzip file I/O. Open acquires a file descriptor and private
state; data operations initialize buffers and codec state as needed; close releases the
handle even if final I/O fails. Reading can also accept transparent, uncompressed input.
| Task | Entries |
|---|---|
| Open or configure | Open path, open descriptor, buffer size, compression parameters |
| Read | Bytes, items, character, pushback, line |
| Write | Bytes, items, character, string, formatted text, flush |
| Position | Seek, rewind, uncompressed position, file offset |
| Inspect or clear status | EOF, transparent mode, error, clear error |
| Close | Any mode, reader, writer |
These focused contracts follow the pinned source and zlib.h. Source readings are
to confirm by implementation proof. They do not assert full API verification or narrow
the broader registered public goals. See
progress for proof status and remaining work.
Common handle conditions
This page uses the default x86_64 Linux build. int and unsigned have
32 bits. long, z_off_t, z_off64_t and z_size_t have 64 bits.
The large-file declarations are enabled. Plain and *64 entry points have
the same offset range here. Other configurations need separate contracts.
gzopen_w is a Windows-only entry and is scoped separately below.
Restricted domain means ordinary use with these common requirements:
- A non-NULL handle is live, returned by a successful open, and not closed. It is used serially and its private state is not modified by the caller.
- A reader or writer has the access mode named by the entry. NULL and wrong-mode refusals are documented separately. A stale or arbitrary pointer is outside this domain; checking a mode field does not validate a pointer.
- Buffers cover the requested readable or writable extent. They are separate from handle-owned memory. Strings have a readable terminating NUL. The caller retains ownership of these objects.
- Position arithmetic and requested extents are representable in the stated C types. Explicit oversized-request and multiplication-overflow refusals remain part of the contracts below.
- The descriptor belongs to the handle until close. No other operation changes its data or position during a call. OS failures and allocation failures remain possible; a successful open does not guarantee that later I/O succeeds.
Every entry carries a domain label. “Full scalar range” applies only to the named scalar argument, under these pointer and lifetime requirements. Documentary restrictions do not excuse known failure paths. In particular, partial-read errors and pushback-created negative positions remain obligations of the unchanged public goals.
Effects. Read, write, open, seek, control and close operations are stateful,
including operations without a caller output buffer. Tell, offset and EOF
queries read state; gzerror may also write its optional code output.
gzdirect can read the file and allocate, so it is stateful.
stateDiagram-v2
[*] --> Fresh: successful open
Fresh --> Active: first I/O or format inspection
Active --> Active: read, write, seek, control
Fresh --> Closed: close
Active --> Closed: close, including final I/O failure
Closed --> [*]
Format and buffering. Opening does no payload I/O. Buffers and codec state are allocated lazily, with a default requested buffer size of 8192 bytes. Allocation can fail at first use or later in decompression. Closing releases owned allocations even when final I/O fails.
An ordinary reader detects gzip from a plausible four-byte header; otherwise
it returns the input unchanged. Empty input is transparent. Detection waits
when non-blocking input stalls before four bytes are available. Gzip members
are concatenated in the output. Trailing non-member data is ignored when the
attempted following member produces no output before its format error.
G requires gzip; T selects transparent output and is invalid for reading.
Read results. Reads advance the uncompressed position by bytes consumed,
including a final partial item. Buffered bytes can be returned before a
recorded error is reported. gzeof reports an attempted read beyond available
data, not simply the delivery of the final byte. gzerror distinguishes EOF,
corruption (Z_DATA_ERROR), truncation (Z_BUF_ERROR), allocation failure
(Z_MEM_ERROR) and system failure (Z_ERRNO). Zero-length reads do not consume
input or carry out a pending seek.
Write results. Success means input was accepted by the handle. It can still be buffered. Flush or close can fail later. A hard error can return failure after consuming a prefix; the return value alone is not always a retry offset. A non-blocking stall can instead return the number consumed so far.
Errors normally persist until cleared. A recorded would-block condition permits
the next data I/O call to retry. Seek and rewind still refuse that recorded
Z_ERRNO. Constructing an error message can itself fail and replace the code
with Z_MEM_ERROR. errno is meaningful for the associated system failure,
not as a general explanation of every failed API call.
The source is gzlib.c,
gzread.c, gzwrite.c,
gzclose.c and zlib.h.
The abstract contracts are in Api/Gz.lean.
Concrete goals are in GzOpen,
GzRead,
GzWrite,
GzControl and
GzClose.
The translations mirror the C names in ZlibF/Zlib/.
Formal contract
ZlibF.Spec.Public.Goal.gzungetc
Proof status: Not completed · Evidence and remaining work
/-- `int gzungetc(int c, gzFile file)`.
On success store the low byte but return the original nonnegative integer. Clear past-EOF.
The initial look and pending skip can precede rejection of a negative character. -/
def Goal.gzungetc : Prop :=
(∀ h fs c, Zlib.Gzread.gzungetc c none fs h = .ok ((-1, fs), h)) ∧
(∀ h fs i s c, GzReachable h fs i → GzValid h i s →
∃ rc fs' after s',
Zlib.Gzread.gzungetc c (some (.in_gzstate_x i)) fs h = .ok ((rc, fs'), after) ∧
GzStateFrame h after fs fs' i s s' [] ∧
(rc = -1 ∨ (rc = c ∧ 0 ≤ c.toInt ∧ s'.past = 0 ∧
∃ rest, Buffered after s' (c.toUInt32.toUInt8 :: rest))) ∧
(c.toInt < 0 ∨ s.mode ≠ GZ_READ → rc = -1) ∧
(rc ≠ -1 → s.skip = 0 → s'.x.pos.toInt = s.x.pos.toInt - 1))