Version: v0.0.0-...-71d77da Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2019 License: BSD-3-Clause Imports: 17 Imported by: 1



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.



View Source
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)
View Source
const TOCTarName = "stargz.index.json"

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


This section is empty.


This section is empty.


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) ChunkEntryForOffset

func (r *Reader) ChunkEntryForOffset(name string, offset int64) (e *TOCEntry, ok bool)

ChunkEntryForOffset returns the TOCEntry containing the byte of the named file at the given offset within the file.

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", "char",
	// "block", "fifo", 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"`

	// DevMajor is the major device number for "char" and "block" types.
	DevMajor int `json:"devMajor,omitempty"`

	// DevMinor is the major device number for "char" and "block" types.
	DevMinor int `json:"devMinor,omitempty"`

	// NumLink is the number of entry names pointing to this entry.
	// Zero means one name references this entry.
	NumLink int

	// Xattrs are the extended attribute for the entry.
	Xattrs map[string][]byte `json:"xattrs,omitempty"`

	// Digest stores the OCI checksum for regular files payload.
	// It has the form "sha256:abcdef01234....".
	Digest string `json:"digest,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.
	// In serialized form, a "chunkSize" JSON field of zero means
	// that the chunk goes to the end of the file. After reading
	// from the stargz TOC, though, the ChunkSize is initialized
	// to a non-zero file for when Type is either "reg" or
	// "chunk".
	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) NextOffset

func (e *TOCEntry) NextOffset() int64

NextOffset returns the position (relative to the start of the stargz file) of the next gzip boundary after e.Offset.

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.

func (*Writer) DiffID

func (w *Writer) DiffID() string

DiffID returns the SHA-256 of the uncompressed tar bytes. It is only valid to call DiffID after Close.

Source Files


Path Synopsis
The stargzify command converts a remote container image into an equivalent image with its layers transformed into stargz files instead of gzipped tar files.
The stargzify command converts a remote container image into an equivalent image with its layers transformed into stargz files instead of gzipped tar files.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL