zlib(n)

📦
version 9.0.2 · 5 versions
, in fedora 43, fedora 44

💖 zlib — the manual, but make it a group chat 💖

okay so real talk, the man page name is zlib(n) — that little (n) is just telling you it hangs out in the Tcl Built-In Commands section of the manual. anyway. hi bestie. buckle up. 🫶

✨ NAME ✨

zlib — compression and decompression operations. short, sweet, iconic. 💅

📜 SYNOPSIS 📜

zlib subcommand arg ...

🌸 DESCRIPTION 🌸

The zlib command is your all-access pass to the compression and check-summing facilities of the Zlib library, written by Jean-loup Gailly and Mark Adler. (legends. no cap. 👑)

It has the following subcommands. yes, all of them. let's go. 🦋

🎀 COMPRESSION SUBCOMMANDS 🎀

  • zlib compress string ?level? — Returns the zlib-format compressed binary data of the binary string in string. If level is present, it gives the compression level to use, from 0 (which is uncompressed, like, why even) to 9 (maximally compressed, go off 💅).
  • zlib decompress string ?bufferSize? — Returns the uncompressed version of the raw compressed binary data in string. If bufferSize is present, it's a hint as to what size of buffer is to be used to receive the data.
  • zlib deflate string ?level? — Returns the raw compressed binary data of the binary string in string. If level is present, it gives the compression level to use, from 0 (uncompressed) to 9 (maximally compressed).
  • zlib gunzip string ?-headerVar varName? — Returns the uncompressed contents of binary string string, which must have been in gzip format. If -headerVar is given, store a dictionary describing the contents of the gzip header in the variable called varName. The keys of the dictionary that may be present are:
    • comment — The comment field from the header, if present.
    • crc — A boolean value describing whether a CRC of the header is computed.
    • filename — The filename field from the header, if present.
    • os — The operating system type code field from the header (if not the QW unknown value). See RFC 1952 for the meaning of these codes.
    • size — The size of the uncompressed data.
    • time — The time field from the header if non-zero, expected to be time that the file named by the filename field was modified. Suitable for use with clock format.
    • type — The type of the uncompressed data (binary or text) if known.
  • zlib gzip string ?-level level? ?-header dict? — Returns the compressed contents of binary string string in gzip format. If -level is given, level gives the compression level to use, from 0 (which is uncompressed) to 9 (maximally compressed). If -header is given, dict is a dictionary containing values used for the gzip header. The following keys may be defined:
    • comment — Add the given comment to the header of the gzip-format data.
    • crc — A boolean saying whether to compute a CRC of the header. Note that if the data is to be interchanged with the gzip program, a header CRC should not be computed. (just. don't. 🙈)
    • filename — The name of the file that the data to be compressed came from.
    • os — The operating system type code, which should be one of the values described in RFC 1952.
    • time — The time that the file named in the filename key was last modified. This will be in the same as is returned by clock seconds or file mtime.
    • type — The type of the data being compressed, being binary or text.
  • zlib inflate string ?bufferSize? — Returns the uncompressed version of the raw compressed binary data in string. If bufferSize is present, it's a hint as to what size of buffer is to be used to receive the data.

🔥 CHANNEL SUBCOMMAND 🔥

  • zlib push mode channel ?options ...? — Pushes a compressing or decompressing transformation onto the channel channel. The transformation can be removed again with chan pop. The mode argument determines what type of transformation is pushed; the following are supported:
    • compress — The transformation will be a compressing transformation that produces zlib-format data on channel, which must be writable.
    • decompress — The transformation will be a decompressing transformation that reads zlib-format data from channel, which must be readable.
    • deflate — The transformation will be a compressing transformation that produces raw compressed data on channel, which must be writable.
    • gunzip — The transformation will be a decompressing transformation that reads gzip-format data from channel, which must be readable.
    • gzip — The transformation will be a compressing transformation that produces gzip-format data on channel, which must be writable.
    • inflate — The transformation will be a decompressing transformation that reads raw compressed data from channel, which must be readable.

The following options may be set when creating a transformation via the "options ..." to the zlib push command:

  • -dictionary binData — Sets the compression dictionary to use when working with compressing or decompressing the data to be binData. Not valid for transformations that work with gzip-format data. The dictionary should consist of strings (byte sequences) that are likely to be encountered later in the data to be compressed, with the most commonly used strings preferably put towards the end of the dictionary. Tcl provides no mechanism for choosing a good such dictionary for a particular data sequence. (so like… you're on your own for that one bestie 😭)
  • -header dictionary — Passes a description of the gzip header to create, in the same format that zlib gzip understands.
  • -level compressionLevel — How hard to compress the data. Must be an integer from 0 (uncompressed) to 9 (maximally compressed).
  • -limit readaheadLimit — The maximum number of bytes ahead to read when decompressing.

This option has become irrelevant. It was originally introduced to prevent Tcl from reading beyond the end of a compressed stream in multi-stream channels to ensure that the data after was left alone for further reading, at the cost of speed.

Tcl now automatically returns any bytes it has read beyond the end of a compressed stream back to the channel, making them appear as unread to further readers. (glow-up behavior fr fr ✨)

Both compressing and decompressing channel transformations add extra configuration options that may be accessed through chan configure. The options are:

  • -checksum checksum — This read-only option gets the current checksum for the uncompressed data that the compression engine has seen so far. It is valid for both compressing and decompressing transforms, but not for the raw inflate and deflate formats. The compression algorithm depends on what format is being produced or consumed.
  • -dictionary binData — This read-write options gets or sets the initial compression dictionary to use when working with compressing or decompressing the data to be binData. It is not valid for transformations that work with gzip-format data, and should not normally be set on compressing transformations other than at the point where the transformation is stacked. Note that this cannot be used to get the current active compression dictionary mid-stream, as that information is not exposed by the underlying library.
  • -flush type — This write-only operation flushes the current state of the compressor to the underlying channel. It is only valid for compressing transformations. The type must be either sync or full for a normal flush or an expensive flush respectively. Flushing degrades the compression ratio, but makes it easier for a decompressor to recover more of the file in the case of data corruption.
  • -header dictionary — This read-only option, only valid for decompressing transforms that are processing gzip-format data, returns the dictionary describing the header read off the data stream.
  • -limit readaheadLimit — This read-write option is used by decompressing channels to control the maximum number of bytes ahead to read from the underlying data source. See above for more information.

🧚 STREAMING SUBCOMMAND 🧚

  • zlib stream mode ?options? — Creates a streaming compression or decompression command based on the mode, and return the name of the command. For a description of how that command works, see STREAMING INSTANCE COMMAND below. The following modes and options are supported:
    • zlib stream compress ?-dictionary bindata? ?-level level? — The stream will be a compressing stream that produces zlib-format output, using compression level level (if specified) which will be an integer from 0 to 9, and the compression dictionary bindata (if specified).
    • zlib stream decompress ?-dictionary bindata? — The stream will be a decompressing stream that takes zlib-format input and produces uncompressed output. If bindata is supplied, it is a compression dictionary to use if required.
    • zlib stream deflate ?-dictionary bindata? ?-level level? — The stream will be a compressing stream that produces raw output, using compression level level (if specified) which will be an integer from 0 to 9, and the compression dictionary bindata (if specified). Note that the raw compressed data includes no metadata about what compression dictionary was used, if any; that is a feature of the zlib-format data.
  • zlib stream gunzip — bestie this one unzips. You feed it gzip-format input, it hands you back the raw uncompressed bytes. It's giving decompression era 💅
  • zlib stream gzip ?-header header? ?-level level? — the glow-up direction: this stream compresses, and what comes out is gzip-format output. Want to control the squeeze? -level level takes an integer from 0 to 9. And if you pass -header header, that's a header descriptor dictionary — for the keys you're gonna wanna go peek at zlib gzip. 🎀
  • zlib stream inflate ?-dictionary bindata? — decompressing stream, raw compressed input in, uncompressed output out. If you hand it bindata, that's a compression dictionary to use. But listen — there are literally no checks in place to determine whether the compression dictionary is correct. It will not warn you. It will not save you. It'll just vibe and possibly produce nonsense. 😭

✨ CHECKSUMMING SUBCOMMANDS ✨

These ones don't stream anything, they just do math on your bytes and hand you a number. Iconic.

  • zlib adler32 string ?initValue? — computes a checksum of the binary string string using the Adler-32 algorithm. If you pass initValue, that's what seeds the checksum engine. 🫶
  • zlib crc32 string ?initValue? — same deal but with the CRC-32 algorithm. Compute a checksum of binary string string; initValue, if given, initializes the checksum engine. ⭐

🌈 STREAMING INSTANCE COMMAND 🌈

okay so this is the part that lowkey changes everything. Streaming compression instance commands get produced by the zlib stream command — they're little objects you hold onto. You load data in by calling their put subcommand one or more times, and you pull the transformed data back out with their get subcommand one or more times. In-and-out. Main character energy, fr fr. 🦋

The full set of subcommands supported by a streaming instance command, stream, is as follows:

  • stream add ?option...? data — a lil short-cut, no cap. It's literally "stream put ?option...? data" followed by "stream get". One line, two vibes. ✨
  • stream checksum — returns the checksum of all the uncompressed data this stream has seen so far. 💖
  • stream close — deletes this stream and frees up all resources associated with it. Say goodbye, be responsible, periodt. 🧚
  • stream eof — returns a boolean telling you whether the end of the stream has been reached (as determined by the compressed data itself). Not all formats support detection of the end of the stream, so don't come for it if it can't tell you. 🙈
  • stream finalize — short-cut for "stream put -finalize {}".
  • stream flush — short-cut for "stream put -flush {}".
  • stream fullflush — short-cut for "stream put -fullflush {}".
  • stream get ?count? — returns up to count bytes from stream's internal buffers, with the transformation applied. Omit count and you get the entire contents of the buffers, all of it, no crumbs. 💅
  • stream header — returns the gzip header description dictionary extracted from the stream. Only supported for streams created with their mode parameter set to gunzip — anything else and it's simply not the moment. 🎀
  • stream put ?option...? data — appends the contents of the binary string data to stream's internal buffers while applying the transformation. The following options are supported (or any unambiguous prefix of them), and they change up how the transformation gets applied:
    • -dictionary binData — sets the compression dictionary used when compressing or decompressing the data to binData.
    • -finalize — marks the stream as finished, making sure all bytes have been wholly compressed or decompressed. For gzip streams this also makes sure the footer gets written to the stream. After this you'll need to reset the stream before writing more data to it — though you can still read data out of the stream with the get subcommand. 👑
This option is mutually exclusive with the -flush and -fullflush options. Pick one, bestie.
  • -flush — makes sure a decompressor consuming the bytes this (compressing) stream is producing will be able to produce all the bytes compressed so far. There's a performance penalty for this, so it's a trade, not a freebie. ✨
This option is mutually exclusive with the -finalize and -fullflush options.
  • -fullflush — the extra version: not only can a decompressor handle all the bytes produced so far (like -flush above), but it can also restart from this point if it detects the stream is partially corrupt. This incurs a substantial performance penalty. Highkey powerful, highkey expensive. 🔥
This option is mutually exclusive with the -finalize and -flush options.
  • stream reset — puts any stream back into a state where it can process more data — including streams that have been finalized or that have reached eof. Heads up though: it throws away all internally buffered data. Gone. Poof. 🫶

🌸 EXAMPLES 🌸

To compress a Tcl string, you first gotta convert it to a particular charset encoding, because the zlib command always operates on binary strings. That's the rule. 💜

set binData [encoding convertto utf-8 $string]
set compData [zlib compress $binData]

When converting back, it is also important to reverse the charset encoding:

set binData [zlib decompress $compData]
set string [encoding convertfrom utf-8 $binData]

The compression operation from above can also be done with streams — which is especially helpful when you want to accumulate the data by stages. Slay, honestly:

set strm [zlib stream compress]
$strm put [encoding convertto utf-8 $string]
# ...
$strm finalize
set compData [$strm get]
$strm close

💫 SEE ALSO 💫

binary(n), chan(n), encoding(n), Tcl_ZlibDeflate(3), RFC1950 - RFC1952

⭐ KEYWORDS ⭐

compress, decompress, deflate, gzip, inflate, zlib

and that's the whole page, bestie 🎀 this one ships as part of Tcl 8.6, filed under zlib(n) — so go forth, compress responsibly, and don't forget the dictionary check that literally does not exist. love u, bye 💖✨

📦 where this page comes from