xz

Documentation

Overview

Package xz implements reading and writing of XZ compressed data.

XZ is a container format that wraps LZMA2-compressed data with integrity checks and index metadata. It provides better compression than gzip and is commonly used for software distribution.

Reading

Use NewReader to decompress an XZ stream:

r, err := xz.NewReader(input)
data, _ := io.ReadAll(r)

Writing

Use NewWriter to compress data into an XZ stream:

w, err := xz.NewWriter(output)
w.Write(data)
w.Close()

Configuration

Both ReaderConfig and WriterConfig provide Verify methods and alternative constructors. The WriterConfig supports selecting the checksum type:

cfg := xz.WriterConfig{
    CheckSum: xz.SHA256,
    DictCap:  8 * 1024 * 1024,
}
w, _ := cfg.NewWriter(output)

Available checksum types (CheckSum field):

• None (0x0): no integrity check
• CRC32 (0x1): 32-bit CRC (IEEE polynomial)
• CRC64 (0x4): 64-bit CRC (ECMA polynomial, default)
• SHA256 (0xA): SHA-256 hash

Format

An XZ stream consists of:

• Stream Header (12 bytes): magic, flags, CRC32
• Block Headers and compressed data
• Index: list of block records
• Stream Footer (12 bytes): CRC32, index size, flags, magic

Multiple streams may be concatenated. The reader transparently handles stream boundaries. Set SingleStream in ReaderConfig to disable this behavior.

ValidHeader checks whether data begins with a valid XZ header:

if xz.ValidHeader(data[:12]) { ... }

Index

• Constants
• func ValidHeader(data []byte) bool
• type Reader
  • func NewReader(xz io.Reader) (r *Reader, err error)
  • func (r *Reader) Read(p []byte) (n int, err error)
• type ReaderConfig
  • func (c ReaderConfig) NewReader(xz io.Reader) (r *Reader, err error)
  • func (c *ReaderConfig) Verify() error
• type Writer
  • func NewWriter(xz io.Writer) (w *Writer, err error)
  • func (w *Writer) Close() error
  • func (w *Writer) Write(p []byte) (n int, err error)
• type WriterConfig
  • func (c WriterConfig) NewWriter(xz io.Writer) (w *Writer, err error)
  • func (c *WriterConfig) Verify() error

Constants

const (
	None   byte = 0x0
	CRC32  byte = 0x1
	CRC64  byte = 0x4
	SHA256 byte = 0xa
)

Constants for the checksum methods supported by xz.

const HeaderLen = 12

HeaderLen provides the length of the xz file header.

Functions

func ValidHeader

func ValidHeader(data []byte) bool

ValidHeader checks whether data is a correct xz file header. The length of data must be HeaderLen.

Types

type Reader

type Reader struct {
	ReaderConfig
	// contains filtered or unexported fields
}

Reader supports the reading of one or multiple xz streams.

func NewReader

func NewReader(xz io.Reader) (r *Reader, err error)

NewReader creates a new xz reader using the default parameters. The function reads and checks the header of the first XZ stream. The reader will process multiple streams including padding.

func (*Reader) Read

func (r *Reader) Read(p []byte) (n int, err error)

Read reads uncompressed data from the stream.

type ReaderConfig

type ReaderConfig struct {
	DictCap      int
	SingleStream bool
}

ReaderConfig defines the parameters for the xz reader. The SingleStream parameter requests the reader to assume that the underlying stream contains only a single stream.

func (ReaderConfig) NewReader

func (c ReaderConfig) NewReader(xz io.Reader) (r *Reader, err error)

NewReader creates an xz stream reader. The created reader will be able to process multiple streams and padding unless a SingleStream has been set in the reader configuration c.

func (*ReaderConfig) Verify

func (c *ReaderConfig) Verify() error

Verify checks the reader parameters for Validity. Zero values will be replaced by default values.

type Writer

type Writer struct {
	WriterConfig
	// contains filtered or unexported fields
}

Writer compresses data written to it. It is an io.WriteCloser.

func NewWriter

func NewWriter(xz io.Writer) (w *Writer, err error)

NewWriter creates a new xz writer using default parameters.

func (*Writer) Close

func (w *Writer) Close() error

Close closes the writer and adds the footer to the Writer. Close doesn't close the underlying writer.

func (*Writer) Write

func (w *Writer) Write(p []byte) (n int, err error)

Write compresses the uncompressed data provided.

type WriterConfig

type WriterConfig struct {
	Properties *lzma.Properties
	DictCap    int
	BufSize    int
	BlockSize  int64
	// checksum method: CRC32, CRC64 or SHA256 (default: CRC64)
	CheckSum byte
	// Forces NoChecksum (default: false)
	NoCheckSum bool
	// match algorithm
	Matcher lzma.MatchAlgorithm
}

WriterConfig describe the parameters for an xz writer.

func (WriterConfig) NewWriter

func (c WriterConfig) NewWriter(xz io.Writer) (w *Writer, err error)

NewWriter creates a new Writer using the given configuration parameters.

func (*WriterConfig) Verify

func (c *WriterConfig) Verify() error

Verify checks the configuration for errors. Zero values will be replaced by default values.