package core

import "golang.org/x/debug/internal/core"

The core library is used to process ELF core dump files. You can open a core dump file and read from addresses in the process that dumped core, called the "inferior". Some ancillary information about the inferior is also provided, like architecture and OS thread state.

There's nothing Go-specific about this library, it could just as easily be used to read a C++ core dump. See ../gocore for the next layer up, a Go-specific core dump reader.

The Read* operations all panic with an error (the builtin Go type) if the inferior is not readable at the address requested.

Index

Types

type Address 

type Address uint64

An Address is a location in the inferior's address space.

func (Address) Add 

func (a Address) Add(x int64) Address

Add adds x to address a.

func (Address) Align 

func (a Address) Align(x int64) Address

Align rounds a up to a multiple of x. x must be a power of 2.

func (Address) Max 

func (a Address) Max(b Address) Address

Max returns the larger of a and b.

func (Address) Min 

func (a Address) Min(b Address) Address

Min returns the smaller of a and b.

func (Address) Sub 

func (a Address) Sub(b Address) int64

Sub subtracts b from a. Requires a >= b.

type Mapping 

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

A Mapping represents a contiguous subset of the inferior's address space.

func (*Mapping) CopyOnWrite 

func (m *Mapping) CopyOnWrite() bool

CopyOnWrite reports whether the mapping is a copy-on-write region, i.e. it started as a mapped file and is now writeable. TODO: is this distinguishable from a write-back region?

func (*Mapping) Max 

func (m *Mapping) Max() Address

Max returns the virtual address of the byte just beyond the mapping.

func (*Mapping) Min 

func (m *Mapping) Min() Address

Min returns the lowest virtual address of the mapping.

func (*Mapping) OrigSource 

func (m *Mapping) OrigSource() (string, int64)

For CopyOnWrite mappings, OrigSource returns the file/offset of the original copy of the data, or "", 0 if none.

func (*Mapping) Perm 

func (m *Mapping) Perm() Perm

Perm returns the permissions on the mapping.

func (*Mapping) Size 

func (m *Mapping) Size() int64

Size returns int64(Max-Min)

func (*Mapping) Source 

func (m *Mapping) Source() (string, int64)

Source returns the backing file and offset for the mapping, or "", 0 if none.

func (Mapping) String 

func (m Mapping) String() string

type Perm 

type Perm uint8

A Perm represents the permissions allowed for a Mapping. 

const (
	Read Perm = 1 << iota
	Write
	Exec
)

func (Perm) String 

func (p Perm) String() string

type Process 

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

A Process represents the state of the process that core dumped.

func Core 

func Core(corePath, base, exePath string) (*Process, error)

Core takes the path to a core file and returns a Process that represents the state of the inferior that generated the core file.

base is the base directory from which files in the core can be found.

exePath is the path of the main executable. If "", the path will be determined from the core itself.

func (*Process) Arch 

func (p *Process) Arch() string

func (*Process) Args 

func (p *Process) Args() string

Args returns the initial part of the program arguments.

func (*Process) ByteOrder 

func (p *Process) ByteOrder() binary.ByteOrder

func (*Process) DWARF 

func (p *Process) DWARF() (*dwarf.Data, error)

func (*Process) DWARFLoc 

func (p *Process) DWARFLoc() ([]byte, error)

func (*Process) LogPtrSize 

func (p *Process) LogPtrSize() uint

func (*Process) Mappings 

func (p *Process) Mappings() []*Mapping

Mappings returns a list of virtual memory mappings for p.

func (*Process) PtrSize 

func (p *Process) PtrSize() int64

PtrSize returns the size in bytes of a pointer in the inferior.

func (*Process) ReadAt 

func (p *Process) ReadAt(b []byte, a Address)

ReadAt reads len(b) bytes at address a in the inferior and stores them in b.

func (*Process) ReadCString 

func (p *Process) ReadCString(a Address) string

ReadCString reads a null-terminated string starting at address a.

func (*Process) ReadInt 

func (p *Process) ReadInt(a Address) int64

ReadInt returns an int (of pointer size) read from address a of the inferior.

func (*Process) ReadInt16 

func (p *Process) ReadInt16(a Address) int16

ReadInt16 returns an int16 read from address a of the inferior.

func (*Process) ReadInt32 

func (p *Process) ReadInt32(a Address) int32

ReadInt32 returns an int32 read from address a of the inferior.

func (*Process) ReadInt64 

func (p *Process) ReadInt64(a Address) int64

ReadInt64 returns an int64 read from address a of the inferior.

func (*Process) ReadInt8 

func (p *Process) ReadInt8(a Address) int8

ReadInt8 returns an int8 read from address a of the inferior.

func (*Process) ReadPtr 

func (p *Process) ReadPtr(a Address) Address

ReadPtr returns a pointer loaded from address a of the inferior.

func (*Process) ReadUint16 

func (p *Process) ReadUint16(a Address) uint16

ReadUint16 returns a uint16 read from address a of the inferior.

func (*Process) ReadUint32 

func (p *Process) ReadUint32(a Address) uint32

ReadUint32 returns a uint32 read from address a of the inferior.

func (*Process) ReadUint64 

func (p *Process) ReadUint64(a Address) uint64

ReadUint64 returns a uint64 read from address a of the inferior.

func (*Process) ReadUint8 

func (p *Process) ReadUint8(a Address) uint8

ReadUint8 returns a uint8 read from address a of the inferior.

func (*Process) ReadUintptr 

func (p *Process) ReadUintptr(a Address) uint64

ReadUintptr returns a uint of pointer size read from address a of the inferior.

func (*Process) Readable 

func (p *Process) Readable(a Address) bool

Readable reports whether the address a is readable.

func (*Process) ReadableN 

func (p *Process) ReadableN(a Address, n int64) bool

ReadableN reports whether the n bytes starting at address a are readable.

func (*Process) StaticBase 

func (p *Process) StaticBase() uint64

StaticBase returns the offset at which the main executable was loaded in memory. For example, it should be used when dereferencing DWARF locations.

func (*Process) Symbols 

func (p *Process) Symbols() (map[string]Address, error)

Symbols returns a mapping from name to inferior address, along with any error encountered during reading the symbol information. (There may be both an error and some returned symbols.) Symbols might not be available with core files from stripped binaries.

func (*Process) Threads 

func (p *Process) Threads() []*Thread

Threads returns information about each OS thread in the inferior.

func (*Process) Warnings 

func (p *Process) Warnings() []string

func (*Process) Writeable 

func (p *Process) Writeable(a Address) bool

Writeable reports whether the address a was writeable (by the inferior at the time of the core dump).

type Register 

type Register struct {
	Name  string
	Value uint64
}

type Thread 

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

A Thread represents an operating system thread.

func (*Thread) PC 

func (t *Thread) PC() Address

func (*Thread) Pid 

func (t *Thread) Pid() uint64

func (*Thread) Regs 

func (t *Thread) Regs() []Register

Regs returns the set of register values for the thread. What registers go where is architecture-dependent.

func (*Thread) SP 

func (t *Thread) SP() Address

Source Files

address.go mapping.go process.go process_unix.go read.go thread.go

Version
v0.0.0-20250223200816-04bfb7cc7686 (latest)
Published
Feb 23, 2025
Platform
linux/amd64
Imports
11 packages
Last checked
1 month ago –

Tools for package owners.