tracee

Documentation

Index

• type Argument
  • func (arg Argument) ParseValue(depth int) string
• type Attributes
• type BinaryFile
  • func OpenBinaryFile(pathToProgram string, goVersion GoVersion) (BinaryFile, error)
• type Function
  • func (f Function) IsExported() bool
• type GoRoutineInfo
• type GoVersion
  • func ParseGoVersion(raw string) GoVersion
  • func (v GoVersion) LaterThan(target GoVersion) bool
• type PanicHandler
• type Parameter
• type Process
  • func AttachProcess(pid int, attrs Attributes) (*Process, error)
  • func LaunchProcess(name string, arg []string, attrs Attributes) (*Process, error)
  • func (p *Process) ClearBreakpoint(addr uint64) error
  • func (p *Process) ContinueAndWait() (debugapi.Event, error)
  • func (p *Process) CurrentGoRoutineInfo(threadID int) (GoRoutineInfo, error)
  • func (p *Process) CurrentThreadInfo(threadID int) (ThreadInfo, error)
  • func (p *Process) Detach() error
  • func (p *Process) ExistBreakpoint(addr uint64) bool
  • func (p *Process) FindFunction(pc uint64) (*Function, error)
  • func (p *Process) ReadInstructions(f *Function) ([]x86asm.Inst, error)
  • func (p *Process) SetBreakpoint(addr uint64) error
  • func (p *Process) SingleStep(threadID int, trappedAddr uint64) error
  • func (p *Process) StackFrameAt(rsp, rip uint64) (*StackFrame, error)
• type StackFrame
• type ThreadInfo

Types

type Argument

type Argument struct {
	Name string
	Typ  dwarf.Type
	// contains filtered or unexported fields
}

Argument represents the value passed to the function.

func (Argument) ParseValue

func (arg Argument) ParseValue(depth int) string

ParseValue parses the arg value and returns string representation. The `depth` option specifies to the depth of the parsing.

type Attributes

type Attributes struct {
	ProgramPath         string
	CompiledGoVersion   string
	FirstModuleDataAddr uint64
}

Attributes specifies the set of tracee's attributes.

type BinaryFile

type BinaryFile interface {
	// FindFunction returns the function info to which the given pc specifies.
	FindFunction(pc uint64) (*Function, error)
	// Close closes the binary file.
	Close() error
	// contains filtered or unexported methods
}

BinaryFile represents the program the tracee process is executing.

func OpenBinaryFile

func OpenBinaryFile(pathToProgram string, goVersion GoVersion) (BinaryFile, error)

OpenBinaryFile opens the specified program file.

type Function

type Function struct {
	Name string
	// StartAddr is the start address of the function, inclusive.
	StartAddr uint64
	// EndAddr is the end address of the function, exclusive. 0 if unknown.
	EndAddr uint64
	// Parameters may be empty due to the lack of information.
	Parameters []Parameter
}

Function represents a function info in the debug info section.

func (Function) IsExported

func (f Function) IsExported() bool

IsExported returns true if the function is exported. See https://golang.org/ref/spec#Exported_identifiers for the spec.

type GoRoutineInfo

type GoRoutineInfo struct {
	ID                int64
	UsedStackSize     uint64
	CurrentPC         uint64
	CurrentStackAddr  uint64
	NextDeferFuncAddr uint64
	Panicking         bool
	PanicHandler      *PanicHandler
}

GoRoutineInfo describes the various info of the go routine like pc.

type GoVersion

type GoVersion struct {
	Raw                                      string
	Devel                                    bool
	MajorVersion, MinorVersion, PatchVersion int
}

GoVersion represents a go version.

func ParseGoVersion

func ParseGoVersion(raw string) GoVersion

ParseGoVersion parses the go version string such as 'go1.11.1'

func (GoVersion) LaterThan

func (v GoVersion) LaterThan(target GoVersion) bool

LaterThan returns true if the version is equal to or later than the given version.

type PanicHandler

type PanicHandler struct {
	// UsedStackSizeAtDefer and PCAtDefer are the function info which register this handler by 'defer'.
	UsedStackSizeAtDefer uint64
	PCAtDefer            uint64
}

PanicHandler holds the function info which (will) handles panic.

type Parameter

type Parameter struct {
	Name string
	Typ  dwarf.Type
	// Offset is the offset from the beginning of the parameter list.
	Offset int
	// Exist is false when the parameter is removed due to the optimization.
	Exist    bool
	IsOutput bool
}

Parameter represents a parameter given to or the returned from the function.

type Process

type Process struct {
	Binary    BinaryFile
	GoVersion GoVersion
	// contains filtered or unexported fields
}

Process represents the tracee process launched by or attached to this tracer.

func AttachProcess

func AttachProcess(pid int, attrs Attributes) (*Process, error)

AttachProcess attaches to the existing tracee process.

func LaunchProcess

func LaunchProcess(name string, arg []string, attrs Attributes) (*Process, error)

LaunchProcess launches new tracee process.

func (*Process) ClearBreakpoint

func (p *Process) ClearBreakpoint(addr uint64) error

ClearBreakpoint clears the breakpoint at the specified address.

func (*Process) ContinueAndWait

func (p *Process) ContinueAndWait() (debugapi.Event, error)

ContinueAndWait continues the execution and waits until an event happens. Note that the id of the stopped thread may be different from the id of the continued thread.

func (*Process) CurrentGoRoutineInfo

func (p *Process) CurrentGoRoutineInfo(threadID int) (GoRoutineInfo, error)

CurrentGoRoutineInfo returns the go routine info associated with the go routine which hits the breakpoint.

func (*Process) CurrentThreadInfo

func (p *Process) CurrentThreadInfo(threadID int) (ThreadInfo, error)

CurrentThreadInfo returns the thread info of the specified thread ID.

func (*Process) Detach

func (p *Process) Detach() error

Detach detaches from the tracee process. All breakpoints are cleared.

func (*Process) ExistBreakpoint

func (p *Process) ExistBreakpoint(addr uint64) bool

ExistBreakpoint returns true if the the breakpoint is already set at the specified address.

func (*Process) FindFunction

func (p *Process) FindFunction(pc uint64) (*Function, error)

FindFunction finds the function to which pc specifies.

func (*Process) ReadInstructions

func (p *Process) ReadInstructions(f *Function) ([]x86asm.Inst, error)

ReadInstructions reads the instructions of the specified function from memory.

func (*Process) SetBreakpoint

func (p *Process) SetBreakpoint(addr uint64) error

SetBreakpoint sets the breakpoint at the specified address.

func (*Process) SingleStep

func (p *Process) SingleStep(threadID int, trappedAddr uint64) error

SingleStep executes one instruction while clearing and setting breakpoints. If not all the threads are stopped, there is some possibility that another thread passes through the breakpoint while single-stepping.

func (*Process) StackFrameAt

func (p *Process) StackFrameAt(rsp, rip uint64) (*StackFrame, error)

StackFrameAt returns the stack frame to which the given rbp specified. To get the correct stack frame, it assumes: * rsp points to the return address. * rsp+8 points to the beginning of the args list.

To be accurate, we need to check the .debug_frame section to find the CFA and return address. But we omit the check here because this function is called at only the beginning or end of the tracee's function call.

type StackFrame

type StackFrame struct {
	Function        *Function
	InputArguments  []Argument
	OutputArguments []Argument
	ReturnAddress   uint64
}

StackFrame describes the data in the stack frame and its associated function.

type ThreadInfo

type ThreadInfo struct {
	ID               int
	CurrentPC        uint64
	CurrentStackAddr uint64
}

ThreadInfo describes the various info of thread.