build: Index | Files | Directories

package stargz

import ""

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.


Package Files



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.

type Reader Uses

type Reader struct {
    // contains filtered or unexported fields

A Reader permits random access reads from a stargz file.

func Open Uses

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

Open opens a stargz file for reading.

func (*Reader) Lookup Uses

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 Uses

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

type TOCEntry Uses

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 Uses

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 Uses

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

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

func (*TOCEntry) ModTime Uses

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

ModTime returns the entry's modification time.

func (*TOCEntry) Stat Uses

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

Stat returns a FileInfo value representing e.

type Writer Uses

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 Uses

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 Uses

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 Uses

func (w *Writer) Close() error

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


stargzifyThe stargzify command converts a tarball into a seekable stargz tarball.

Package stargz imports 15 packages (graph) and is imported by 4 packages. Updated 2019-09-15. Refresh now. Tools for package owners.