API Reference

GZip.jl: A Julia interface for gzip functions in zlib

This module provides a wrapper for the gzip related functions of (zlib), a free, general-purpose, legally unencumbered, lossless data-compression library. These functions allow the reading and writing of gzip files.

Defaults to the zlib-ng backend for faster compression and decompression. Use backend=GZip.ZLIB to use standard zlib instead. Files are cross-compatible between backends.

Notes

• This interface is only for gzipped files, not the streaming zlib compression interface. Internally, it depends on/uses the streaming interface, but the gzip related functions are higher level functions pertaining to gzip files only.
• GZipStream is an implementation of IO and can be used virtually anywhere IO is used.
• This implementation mimics the IOStream implementation, and should be a drop-in replacement for IOStream, with some caveats:
  • seekend and truncate are not available
  • readuntil is available, but is not very efficient. (But readline works fine.)

In addition to open, gzopen, and gzdopen, the following IO/IOStream functions are supported:

• close()
• flush()
• seek()
• skip()
• position()
• eof()
• read()
• readuntil()
• readline()
• write()
• peek()
• isreadable()
• iswritable()

gzheader reads gzip header metadata without decompressing.

Due to limitations in zlib, seekend and truncate are not available.

gzopen(fname::AbstractString, [gzmode::AbstractString, buf_size::Integer]; backend=ZLIBNG)::GZipStream

Opens a file with mode (default "r"), setting internal buffer size to buf_size (default Z_DEFAULT_BUFSIZE=8192), and returns a the file as a GZipStream.

gzmode must contain one of:

In addition, gzmode may also contain

and/or a compression strategy:

Note that + is not allowed in gzmode. If an error occurs, gzopen throws a GZError.

Use backend=GZip.ZLIB to use the standard zlib backend instead of the default zlib-ng.

gzdopen(fd, [gzmode, buf_size]; backend=ZLIBNG)

Create a GZipStream object from an integer file descriptor. See gzopen for gzmode and buf_size descriptions.

open(fname::AbstractString, [gzmode, bufsize]; backend=ZLIBNG)::GZipStream

Alias for gzopen. This is not exported, and must be called using GZip.open.

gzheader(filename::AbstractString) -> GZipHeader

Read the gzip header metadata from a .gz file without decompressing. Returns a GZipHeader struct with modification time, original filename, comment, OS identifier, and extra field data.

h = gzheader("data.gz")
h.name     # original filename, or nothing
h.mtime    # modification time as Unix timestamp
h.comment  # file comment, or nothing

GZipHeader

Gzip file header metadata (RFC 1952).

Fields:

• mtime::UInt32 — modification time as Unix timestamp (0 = not set)
• os::UInt8 — operating system identifier
• xfl::UInt8 — extra flags (2 = best compression, 4 = fastest)
• name::Union{String,Nothing} — original filename
• comment::Union{String,Nothing} — file comment
• extra::Union{Vector{UInt8},Nothing} — extra field data
• is_text::Bool — hint that content is ASCII text

gzgetc(s::GZipStream)

Read a single byte from the stream. Throws EOFError at end of file.

gzgets(s::GZipStream, buf)

Read a line from the stream into buf, stopping at newline or end of file.

gzread(s::GZipStream, p::Ptr, len::Integer)

Read up to len bytes from the stream into the buffer at pointer p. Returns the number of bytes read. Uses gzfread which supports >4GB reads on 64-bit systems.

gzungetc(c::Integer, s::GZipStream)

Push a byte back onto the stream for subsequent reading.

gzputc(s::GZipStream, c::Integer)

Write a single byte to the stream.

gzwrite(s::GZipStream, p::Ptr, len::Integer)

Write len bytes from pointer p to the stream. Returns the number of bytes written. Uses gzfwrite which supports >4GB writes on 64-bit systems.

gzbuffer(backend::GZBackend, gz_file, gz_buf_size::Integer)

Set the internal buffer size for the gzip file. Must be called before any read or write.

GZipStream <: IO

GZipStream(name, gz_file, [buf_size]; backend=ZLIBNG)

Subtype of IO which wraps a gzip stream. Returned by gzopen and gzdopen. Parameterized by the backend (ZlibBackend or ZlibNGBackend).

GZBackend

Abstract type for gzip compression backends. Concrete subtypes are ZlibBackend and ZlibNGBackend.

ZlibBackend <: GZBackend

Standard zlib backend (Zlib_jll). Use backend=GZip.ZLIB to select.

ZlibNGBackend <: GZBackend

Default backend using zlib-ng (ZlibNG_jll), a high-performance fork of zlib.

ZLIB

The standard zlib backend. Pass as backend=GZip.ZLIB to gzopen/gzdopen.

ZLIBNG

The default zlib-ng backend. Pass as backend=GZip.ZLIBNG to gzopen/gzdopen.

ZFileOffset

Integer type used for file offsets in zlib, determined from the library's compile flags.

libversion(backend::GZBackend) -> String
libversion(s::GZipStream) -> String

Version string of the compression library behind backend, or behind the backend s was opened with.

julia> GZip.libversion(GZip.ZLIBNG) == GZip.GZLIBNG_VERSION
true

GZLIB_VERSION

Version string of the zlib library in use, e.g. "1.2.13".

This describes the ZLIB backend only. For the version behind the default zlib-ng backend see GZLIBNG_VERSION, or use libversion to ask a particular backend or stream.

GZLIBNG_VERSION

Version string of the zlib-ng library in use, e.g. "2.3.3".

zlib-ng carries its own version series, unrelated to zlib's; the default ZLIBNG backend is the one this describes.

ZLIB_VERSION

Version of the zlib library as a tuple of integers, e.g. (1, 2, 13), for comparisons such as ZLIB_VERSION >= (1, 2, 4).

ZLIBNG_VERSION

Version of the zlib-ng library as a tuple of integers, e.g. (2, 3, 3).

GZError <: Exception

gzip error number and string. Possible error values:

ZError <: Exception

zlib error, containing an error code and message string.