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 ¶
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.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
A Reader permits random access reads from a stargz file.
func (*Reader) ChunkEntryForOffset ¶
ChunkEntryForOffset returns the TOCEntry containing the byte of the named file at the given offset within the file.
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 ¶
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 ¶
LookupChild returns the directory e's child by its base name.
func (*TOCEntry) NextOffset ¶
NextOffset returns the position (relative to the start of the stargz file) of the next gzip boundary after e.Offset.
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 ¶
NewWriter returns a new stargz writer writing to w.
The writer must be closed to write its trailing table of contents.
func (*Writer) AppendTar ¶
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.
Source Files
Directories
¶
| 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. |