proctl

Documentation

Overview

Package proctl provides functions for attaching to and manipulating a process during the debug session.

Index

• Constants
• type BreakPoint
• type BreakPointExistsError
  • func (bpe BreakPointExistsError) Error() string
• type DebuggedProcess
  • func Attach(pid int) (*DebuggedProcess, error)
  • func Launch(cmd []string) (*DebuggedProcess, error)
  • func (dbp *DebuggedProcess) AttachThread(tid int) (*ThreadContext, error)
  • func (dbp *DebuggedProcess) Break(addr uintptr) (*BreakPoint, error)
  • func (dbp *DebuggedProcess) Clear(pc uint64) (*BreakPoint, error)
  • func (dbp *DebuggedProcess) Continue() error
  • func (dbp *DebuggedProcess) CurrentPC() (uint64, error)
  • func (dbp *DebuggedProcess) EvalSymbol(name string) (*Variable, error)
  • func (dbp *DebuggedProcess) LoadInformation() error
  • func (dbp *DebuggedProcess) Next() error
  • func (dbp *DebuggedProcess) PrintGoroutinesInfo() error
  • func (dbp *DebuggedProcess) PrintThreadInfo() error
  • func (dbp *DebuggedProcess) Registers() (*syscall.PtraceRegs, error)
  • func (dbp *DebuggedProcess) Status() *syscall.WaitStatus
  • func (dbp *DebuggedProcess) Step() (err error)
• type InvalidAddressError
  • func (iae InvalidAddressError) Error() string
• type ProcessExitedError
  • func (pe ProcessExitedError) Error() string
• type ProcessStatus
• type ThreadContext
  • func (thread *ThreadContext) Break(addr uintptr) (*BreakPoint, error)
  • func (thread *ThreadContext) Clear(pc uint64) (*BreakPoint, error)
  • func (thread *ThreadContext) Continue() error
  • func (thread *ThreadContext) CurrentPC() (uint64, error)
  • func (thread *ThreadContext) EvalSymbol(name string) (*Variable, error)
  • func (thread *ThreadContext) Next() (err error)
  • func (thread *ThreadContext) PrintInfo() error
  • func (thread *ThreadContext) Registers() (*syscall.PtraceRegs, error)
  • func (thread *ThreadContext) ReturnAddressFromOffset(offset int64) uint64
  • func (thread *ThreadContext) Step() (err error)
• type TimeoutError
  • func (err TimeoutError) Error() string
• type Variable

Constants

const (
	STATUS_SLEEPING   = 'S'
	STATUS_RUNNING    = 'R'
	STATUS_TRACE_STOP = 't'
)

Types

type BreakPoint

type BreakPoint struct {
	FunctionName string
	File         string
	Line         int
	Addr         uint64
	OriginalData []byte
	// contains filtered or unexported fields
}

Represents a single breakpoint. Stores information on the break point including the byte of data that originally was stored at that address.

type BreakPointExistsError

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

func (BreakPointExistsError) Error

func (bpe BreakPointExistsError) Error() string

type DebuggedProcess

type DebuggedProcess struct {
	Pid           int
	Process       *os.Process
	Executable    *elf.File
	Symbols       []elf.Symbol
	GoSymTable    *gosym.Table
	FrameEntries  *frame.FrameDescriptionEntries
	BreakPoints   map[uint64]*BreakPoint
	Threads       map[int]*ThreadContext
	CurrentThread *ThreadContext
}

Struct representing a debugged process. Holds onto pid, register values, process struct and process state.

func Attach

func Attach(pid int) (*DebuggedProcess, error)

func Launch

func Launch(cmd []string) (*DebuggedProcess, error)

func (*DebuggedProcess) AttachThread

func (dbp *DebuggedProcess) AttachThread(tid int) (*ThreadContext, error)

func (*DebuggedProcess) Break

func (dbp *DebuggedProcess) Break(addr uintptr) (*BreakPoint, error)

Sets a breakpoint in the current thread.

func (*DebuggedProcess) Clear

func (dbp *DebuggedProcess) Clear(pc uint64) (*BreakPoint, error)

Clears a breakpoint in the current thread.

func (*DebuggedProcess) Continue

func (dbp *DebuggedProcess) Continue() error

Continue process until next breakpoint.

func (*DebuggedProcess) CurrentPC

func (dbp *DebuggedProcess) CurrentPC() (uint64, error)

func (*DebuggedProcess) EvalSymbol

func (dbp *DebuggedProcess) EvalSymbol(name string) (*Variable, error)

Returns the value of the named symbol.

func (*DebuggedProcess) LoadInformation

func (dbp *DebuggedProcess) LoadInformation() error

Finds the executable from /proc/<pid>/exe and then uses that to parse the following information: * Dwarf .debug_frame section * Dwarf .debug_line section * Go symbol table.

func (*DebuggedProcess) Next

func (dbp *DebuggedProcess) Next() error

Step over function calls.

func (*DebuggedProcess) PrintGoroutinesInfo

func (dbp *DebuggedProcess) PrintGoroutinesInfo() error

func (*DebuggedProcess) PrintThreadInfo

func (dbp *DebuggedProcess) PrintThreadInfo() error

Loop through all threads, printing their information to the console.

func (*DebuggedProcess) Registers

func (dbp *DebuggedProcess) Registers() (*syscall.PtraceRegs, error)

Obtains register values from the debugged process.

func (*DebuggedProcess) Status

func (dbp *DebuggedProcess) Status() *syscall.WaitStatus

Returns the status of the current main thread context.

func (*DebuggedProcess) Step

func (dbp *DebuggedProcess) Step() (err error)

Steps through process.

type InvalidAddressError

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

func (InvalidAddressError) Error

func (iae InvalidAddressError) Error() string

type ProcessExitedError

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

func (ProcessExitedError) Error

func (pe ProcessExitedError) Error() string

type ProcessStatus

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

ProcessStatus is the result of parsing the data from the /proc/<pid>/stats psuedo file.

type ThreadContext

type ThreadContext struct {
	Id      int
	Process *DebuggedProcess
	Status  *syscall.WaitStatus
	Regs    *syscall.PtraceRegs
}

ThreadContext represents a single thread of execution in the traced program.

func (*ThreadContext) Break

func (thread *ThreadContext) Break(addr uintptr) (*BreakPoint, error)

Sets a software breakpoint at addr, and stores it in the process wide break point table. Setting a break point must be thread specific due to ptrace actions needing the thread to be in a signal-delivery-stop in order to initiate any ptrace command. Otherwise, it really doesn't matter as we're only dealing with threads.

func (*ThreadContext) Clear

func (thread *ThreadContext) Clear(pc uint64) (*BreakPoint, error)

Clears a software breakpoint, and removes it from the process level break point table.

func (*ThreadContext) Continue

func (thread *ThreadContext) Continue() error

func (*ThreadContext) CurrentPC

func (thread *ThreadContext) CurrentPC() (uint64, error)

func (*ThreadContext) EvalSymbol

func (thread *ThreadContext) EvalSymbol(name string) (*Variable, error)

Returns the value of the named symbol.

func (*ThreadContext) Next

func (thread *ThreadContext) Next() (err error)

Steps through thread of execution.

func (*ThreadContext) PrintInfo

func (thread *ThreadContext) PrintInfo() error

PrintInfo prints out the thread status including: PC, tid, file, line, and function.

func (*ThreadContext) Registers

func (thread *ThreadContext) Registers() (*syscall.PtraceRegs, error)

Obtains register values from the debugged process.

func (*ThreadContext) ReturnAddressFromOffset

func (thread *ThreadContext) ReturnAddressFromOffset(offset int64) uint64

Takes an offset from RSP and returns the address of the instruction the currect function is going to return to.

func (*ThreadContext) Step

func (thread *ThreadContext) Step() (err error)

Steps through thread of execution.

type TimeoutError

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

func (TimeoutError) Error

func (err TimeoutError) Error() string

type Variable

type Variable struct {
	Name  string
	Value string
	Type  string
}