fatbin

Documentation

Overview

Package fatbin implements a simple fat binary format, and provides facilities for creating fat binaries and accessing its variants.

A fatbin binary is a base binary with a zip archive appended, containing copies of the same binary targeted to different GOOS/GOARCH combinations. The zip archive contains one entry for each supported architecture and operating system combination. At the end of a fatbin image is a footer, storing the offset of the zip archive as well as a magic constant used to identify fatbin images:

[8]offset[4]magic[8]checksum

The checksum is a 64-bit xxhash checksum of the offset and magic fields. The magic value is 0x5758ba2c.

Index

• Variables
• func Sniff(r io.ReaderAt, size int64) (goos, goarch string, offset int64, err error)
• type Info
  • func (info Info) String() string
• type Reader
  • func NewReader(r io.ReaderAt, offset, size int64, goos, goarch string) (*Reader, error)
  • func OpenFile(r io.ReaderAt, size int64) (*Reader, error)
  • func Self() (*Reader, error)
  • func (r *Reader) GOARCH() string
  • func (r *Reader) GOOS() string
  • func (r *Reader) List() []Info
  • func (r *Reader) Open(goos, goarch string) (io.ReadCloser, error)
• type Writer
  • func NewFileWriter(file *os.File) (*Writer, error)
  • func NewWriter(w io.Writer, offset int64, goos, goarch string) *Writer
  • func (w *Writer) Close() error
  • func (w *Writer) Create(goos, goarch string) (io.Writer, error)
  • func (w *Writer) Flush() error

Variables

var (
	// ErrNoSuchImage is returned when the fatbin does not contain an
	// image for the requested GOOS/GOARCH combination.
	ErrNoSuchImage = errors.New("image does not exist")
	// ErrCorruptedImage is returned when the fatbin image has been
	// corrupted.
	ErrCorruptedImage = errors.New("corrupted fatbin image")
)

Functions

func Sniff

func Sniff(r io.ReaderAt, size int64) (goos, goarch string, offset int64, err error)

Sniff sniffs a binary's goos, goarch, and fatbin offset. Sniff returns errors returned by the provided reader, or ErrCorruptedImage if the binary is identified as a fatbin image with a checksum mismatch.

Types

type Info

type Info struct {
	Goos, Goarch string
	Size         int64
}

Info provides information for an embedded binary.

func (Info) String

func (info Info) String() string

type Reader

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

Reader reads images from a fatbin.

func NewReader

func NewReader(r io.ReaderAt, offset, size int64, goos, goarch string) (*Reader, error)

NewReader returns a new fatbin reader from the provided reader. The offset should be the offset of the fatbin archive; size is the total file size. The provided goos and goarch are that of the base binary.

func OpenFile

func OpenFile(r io.ReaderAt, size int64) (*Reader, error)

OpenFile parses the provided ReaderAt with the provided size. The file's contents is parsed to determine the offset of the fatbin's archive. OpenFile returns an error if the file is not a fatbin.

func Self

func Self() (*Reader, error)

Self reads the currently executing binary image as a fatbin and returns a reader to it.

func (*Reader) GOARCH

func (r *Reader) GOARCH() string

GOARCH returns the base binary GOARCH.

func (*Reader) GOOS

func (r *Reader) GOOS() string

GOOS returns the base binary GOOS.

func (*Reader) List

func (r *Reader) List() []Info

List returns information about embedded binary images.

func (*Reader) Open

func (r *Reader) Open(goos, goarch string) (io.ReadCloser, error)

Open returns a ReadCloser from which the binary with the provided goos and goarch can be read. Open returns ErrNoSuchImage if the fatbin does not contain an image for the requested goos and goarch.

type Writer

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

A Writer is used to append fatbin images to an existing binary.

func NewFileWriter

func NewFileWriter(file *os.File) (*Writer, error)

NewFileWriter returns a writer that can be used to append fatbin images to the binary represented by the provided file. NewFileWriter removes any existing fatbin images that may be attached to the binary. It relies on content sniffing (see Sniff) to determine its offset.

func NewWriter

func NewWriter(w io.Writer, offset int64, goos, goarch string) *Writer

NewWriter returns a writer that may be used to append fatbin images to the writer w. The writer should be positioned at the end of the base binary image.

func (*Writer) Close

func (w *Writer) Close() error

Close should be called after all images have been written. No more images can be written after a call to Close.

func (*Writer) Create

func (w *Writer) Create(goos, goarch string) (io.Writer, error)

Create returns a Writer into which the image for the provided goos and goarch should be written. The image's contents must be written before the next call to Create or Close.

func (*Writer) Flush

func (w *Writer) Flush() error

Flush flushes the unwritten data to the underlying file.