stargz

Documentation

Overview

The stargz package reads & writes tar.gz ("tarball") files in a seekable, indexed format call "stargz". A stargz file is still a valid tarball, but it's slightly bigger with new gzip streams for each new file & throughout large files, and has an index in a magic file at the end.

Index

• Constants
• type Reader
  • func Open(sr *io.SectionReader) (*Reader, error)
  • func (r *Reader) Lookup(path string) (e *TOCEntry, ok bool)
  • func (r *Reader) OpenFile(name string) (*io.SectionReader, error)
• type TOCEntry
  • func (e *TOCEntry) ForeachChild(f func(baseName string, ent *TOCEntry) bool)
  • func (e *TOCEntry) LookupChild(baseName string) (child *TOCEntry, ok bool)
  • func (e *TOCEntry) ModTime() time.Time
  • func (e *TOCEntry) Stat() os.FileInfo
• type Writer
  • func NewWriter(w io.Writer) *Writer
  • func (w *Writer) AppendTar(r io.Reader) error
  • func (w *Writer) Close() error

Constants

const FooterSize = 47

FooterSize is the number of bytes in the stargz footer.

The footer is an empty gzip stream with no compression and an Extra header of the form "%016xSTARGZ", where the 64 bit hex-encoded number is the offset to the gzip stream of JSON TOC.

47 comes from:

10 byte gzip header +
2 byte (LE16) length of extra, encoding 22 (16 hex digits + len("STARGZ")) == "\x16\x00" +
22 bytes of extra (fmt.Sprintf("%016xSTARGZ", tocGzipOffset))
5 byte flate header
8 byte gzip footer (two little endian uint32s: digest, size)

const TOCTarName = "stargz.index.json"

TOCTarName is the name of the JSON file in the tar archive in the table of contents gzip stream.

Types

type Reader

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

A Reader permits random access reads from a stargz file.

func Open

func Open(sr *io.SectionReader) (*Reader, error)

Open opens a stargz file for reading.

func (*Reader) Lookup

func (r *Reader) Lookup(path string) (e *TOCEntry, ok bool)

Lookup returns the Table of Contents entry for the given path.

To get the root directory, use the empty string.

func (*Reader) OpenFile

func (r *Reader) OpenFile(name string) (*io.SectionReader, error)

type TOCEntry

type TOCEntry struct {
	// Name is the tar entry's name. It is the complete path
	// stored in the tar file, not just the base name.
	Name string `json:"name"`

	// Type is one of "dir", "reg", "symlink", "hardlink", or "chunk".
	// The "chunk" type is used for regular file data chunks past the first
	// TOCEntry; the 2nd chunk and on have only Type ("chunk"), Offset,
	// ChunkOffset, and ChunkSize populated.
	Type string `json:"type"`

	// Size, for regular files, is the logical size of the file.
	Size int64 `json:"size,omitempty"`

	// ModTime3339 is the modification time of the tar entry. Empty
	// means zero or unknown. Otherwise it's in UTC RFC3339
	// format. Use the ModTime method to access the time.Time value.
	ModTime3339 string `json:"modtime,omitempty"`

	// LinkName, for symlinks and hardlinks, is the link target.
	LinkName string `json:"linkName,omitempty"`

	// Mode is the permission and mode bits.
	Mode int64 `json:"mode,omitempty"`

	// Uid is the user ID of the owner.
	Uid int `json:"uid,omitempty"`

	// Gid is the group ID of the owner.
	Gid int `json:"gid,omitempty"`

	// Uname is the username of the owner.
	//
	// In the serialized JSON, this field may only be present for
	// the first entry with the same Uid.
	Uname string `json:"userName,omitempty"`

	// Gname is the group name of the owner.
	//
	// In the serialized JSON, this field may only be present for
	// the first entry with the same Gid.
	Gname string `json:"groupName,omitempty"`

	// Offset, for regular files, provides the offset in the
	// stargz file to the file's data bytes. See ChunkOffset and
	// ChunkSize.
	Offset int64 `json:"offset,omitempty"`

	// ChunkOffset is non-zero if this is a chunk of a large,
	// regular file. If so, the Offset is where the gzip header of
	// ChunkSize bytes at ChunkOffset in Name begin. If both
	// ChunkOffset and ChunkSize are zero, the file contents are
	// completely represented at the tar gzip stream starting at
	// Offset.
	ChunkOffset int64 `json:"chunkOffset,omitempty"`
	ChunkSize   int64 `json:"chunkSize,omitempty"`
	// contains filtered or unexported fields
}

TOCEntry is an entry in the stargz file's TOC (Table of Contents).

func (*TOCEntry) ForeachChild

func (e *TOCEntry) ForeachChild(f func(baseName string, ent *TOCEntry) bool)

ForeachChild calls f for each child item. If f returns false, iteration ends. If e is not a directory, f is not called.

func (*TOCEntry) LookupChild

func (e *TOCEntry) LookupChild(baseName string) (child *TOCEntry, ok bool)

LookupChild returns the directory e's child by its base name.

func (*TOCEntry) ModTime

func (e *TOCEntry) ModTime() time.Time

ModTime returns the entry's modification time.

func (*TOCEntry) Stat

func (e *TOCEntry) Stat() os.FileInfo

Stat returns a FileInfo value representing e.

type Writer

type Writer struct {

	// ChunkSize optionally controls the maximum number of bytes
	// of data of a regular file that can be written in one gzip
	// stream before a new gzip stream is started.
	// Zero means to use a default, currently 4 MiB.
	ChunkSize int
	// contains filtered or unexported fields
}

A Writer writes stargz files.

Use NewWriter to create a new Writer.

func NewWriter

func NewWriter(w io.Writer) *Writer

NewWriter returns a new stargz writer writing to w.

The writer must be closed to write its trailing table of contents.

func (*Writer) AppendTar

func (w *Writer) AppendTar(r io.Reader) error

AppendTar reads the tar or tar.gz file from r and appends each of its contents to w.

The input r can optionally be gzip compressed but the output will always be gzip compressed.

func (*Writer) Close

func (w *Writer) Close() error

Close writes the stargz's table of contents and flushes all the buffers, returning any error.