binary

Documentation

Overview

Package binary provides types for parsing and representing executable binaries.

Index

• Constants
• Variables
• type Architecture
  • func ParseArchitecture(s string) (Architecture, bool)
  • func (a Architecture) Matches(target Architecture) bool
  • func (a Architecture) String() string
• type Binary
• type BitWidth
  • func (b BitWidth) String() string
• type DynEntry
• type ELFBinary
  • func ParseELF(r io.ReaderAt) (*ELFBinary, error)
  • func ParseELFWithDetector(r io.ReaderAt, detector toolchain.ELFDetector) (*ELFBinary, error)
  • func (b *ELFBinary) DynString(tag elf.DynTag) string
  • func (b *ELFBinary) HasDynFlag(tag elf.DynTag, flag uint64) bool
  • func (b *ELFBinary) HasDynTag(tag elf.DynTag) bool
  • func (b *ELFBinary) HasGNUProperty(propertyType, featureFlag uint32) bool
• type Format
  • func (f Format) String() string
• type ISA
  • func ParseISA(s string) (ISA, error)
  • func (i ISA) IsAtLeast(required ISA) bool
  • func (i ISA) String() string
• type LibC
  • func (l LibC) String() string
• type Platform
  • func (p Platform) String() string

Constants

const (
	NT_GNU_PROPERTY_TYPE_0 = 5

	GNU_PROPERTY_X86_FEATURE_1_AND   = 0xc0000002
	GNU_PROPERTY_X86_FEATURE_1_IBT   = 0x1
	GNU_PROPERTY_X86_FEATURE_1_SHSTK = 0x2

	GNU_PROPERTY_AARCH64_FEATURE_1_AND = 0xc0000000
	GNU_PROPERTY_AARCH64_FEATURE_1_BTI = 0x1
	GNU_PROPERTY_AARCH64_FEATURE_1_PAC = 0x2
)

GNU property constants for feature detection.

Variables

var (
	ARM64v83 = ISA{Major: 8, Minor: 3}
	ARM64v85 = ISA{Major: 8, Minor: 5}

	AMD64v1 = ISA{Major: 1}
	AMD64v2 = ISA{Major: 2}
	AMD64v3 = ISA{Major: 3}
	AMD64v4 = ISA{Major: 4}
)

var (
	PlatformAll    = Platform{Architecture: ArchAll}
	PlatformAllX86 = Platform{Architecture: ArchAllX86}
	PlatformAllARM = Platform{Architecture: ArchAllARM}

	PlatformARM64v83 = Platform{Architecture: ArchARM64, MinISA: ARM64v83}
	PlatformARM64v85 = Platform{Architecture: ArchARM64, MinISA: ARM64v85}
)

var ErrUnsupportedFormat = errors.New("unsupported binary format")

ErrUnsupportedFormat is returned when the file is not a supported binary format.

Types

type Architecture

type Architecture uint32

Architecture identifies CPU architecture as a bitmask, allowing combinations.

const (
	ArchUnknown Architecture = 0
	ArchX86     Architecture = 1 << 0
	ArchAMD64   Architecture = 1 << 1
	ArchARM     Architecture = 1 << 2
	ArchARM64   Architecture = 1 << 3
	ArchRISCV   Architecture = 1 << 4
	ArchPPC64   Architecture = 1 << 5
	ArchMIPS    Architecture = 1 << 6
	ArchS390X   Architecture = 1 << 7

	ArchAllX86 = ArchX86 | ArchAMD64
	ArchAllARM = ArchARM | ArchARM64
	ArchAll    = ArchX86 | ArchAMD64 | ArchARM | ArchARM64 | ArchRISCV | ArchPPC64 | ArchMIPS | ArchS390X
)

func ParseArchitecture

func ParseArchitecture(s string) (Architecture, bool)

ParseArchitecture converts a string to Architecture. Returns false if unknown.

func (Architecture) Matches

func (a Architecture) Matches(target Architecture) bool

Matches reports whether a has any overlap with target.

func (Architecture) String

func (a Architecture) String() string

type Binary

type Binary struct {
	Format       Format
	Architecture Architecture
	Bits         BitWidth
	Build        toolchain.BuildInfo
	LibC         LibC
}

Binary holds common metadata for any executable format.

type BitWidth

type BitWidth int

BitWidth represents the binary's word size.

const (
	BitsUnknown BitWidth = 0
	Bits32      BitWidth = 32
	Bits64      BitWidth = 64
)

func (BitWidth) String

func (b BitWidth) String() string

type DynEntry

type DynEntry struct {
	Tag uint64
	Val uint64
}

DynEntry represents an entry in the .dynamic section.

type ELFBinary

type ELFBinary struct {
	Binary

	Type     elf.Type
	Progs    []elf.Prog
	Sections []elf.SectionHeader
	// Symbols from .symtab section, or nil if missing/stripped.
	Symbols []elf.Symbol
	// DynSymbols from .dynsym section, or nil if missing.
	DynSymbols []elf.Symbol

	// DynEntries contains parsed entries from the .dynamic section.
	// Exposed for custom rules that need direct access to dynamic tags
	// beyond what HasDynFlag, HasDynTag, and DynString provide.
	DynEntries []DynEntry
	// contains filtered or unexported fields
}

ELFBinary represents a parsed ELF executable or shared library.

func ParseELF

func ParseELF(r io.ReaderAt) (*ELFBinary, error)

ParseELF parses an ELF binary. The caller owns the io.ReaderAt and must keep it open while ELFBinary is in use.

func ParseELFWithDetector

func ParseELFWithDetector(r io.ReaderAt, detector toolchain.ELFDetector) (*ELFBinary, error)

ParseELFWithDetector parses an ELF binary using a custom compiler detector. The caller owns the io.ReaderAt and must keep it open while ELFBinary is in use.

func (*ELFBinary) DynString

func (b *ELFBinary) DynString(tag elf.DynTag) string

DynString returns the string value associated with a dynamic tag.

func (*ELFBinary) HasDynFlag

func (b *ELFBinary) HasDynFlag(tag elf.DynTag, flag uint64) bool

HasDynFlag reports whether a dynamic tag has the specified flag set.

func (*ELFBinary) HasDynTag

func (b *ELFBinary) HasDynTag(tag elf.DynTag) bool

HasDynTag reports whether a dynamic tag exists.

func (*ELFBinary) HasGNUProperty

func (b *ELFBinary) HasGNUProperty(propertyType, featureFlag uint32) bool

HasGNUProperty reports whether the binary has a GNU property with the specified flag.

type Format

type Format int

Format identifies the executable format.

const (
	FormatUnknown Format = iota
	FormatELF
)

func (Format) String

func (f Format) String() string

type ISA

type ISA struct {
	Major int
	Minor int
}

ISA represents an instruction set architecture version

func ParseISA

func ParseISA(s string) (ISA, error)

ParseISA parses a version string like "v8.3" or "8.3" into an ISA.

func (ISA) IsAtLeast

func (i ISA) IsAtLeast(required ISA) bool

IsAtLeast reports whether ISA is at least the required version.

func (ISA) String

func (i ISA) String() string

type LibC

type LibC int

LibC identifies the C library the binary is linked against.

const (
	LibCUnknown LibC = iota
	LibCGlibc
	LibCMusl
)

func (LibC) String

func (l LibC) String() string

type Platform

type Platform struct {
	Architecture Architecture
	MinISA       ISA
}

Platform combines architecture with optional minimum ISA requirement.

func (Platform) String

func (p Platform) String() string