Documentation
¶
Overview ¶
proc is a low-level package that provides methods to manipulate the process we are debugging, and methods to read and write from the virtual memory of the process.
proc implements the core features of this debugger, including all process manipulation (step, next, continue, halt) as well as providing methods to evaluate variables and read them from the virtual memory of the process we are debugging.
Index ¶
- Constants
- func PtraceCont(tid, sig int) error
- func PtraceDetach(tid, sig int) error
- func PtracePeekUser(tid int, off uintptr) (uintptr, error)
- func PtracePokeUser(tid int, off, addr uintptr) error
- func PtraceSingleStep(tid int) error
- type AMD64
- type Arch
- type Breakpoint
- type BreakpointExistsError
- type DebuggedProcess
- func (dbp *DebuggedProcess) Break(addr uint64) (*Breakpoint, error)
- func (dbp *DebuggedProcess) BreakByLocation(loc string) (*Breakpoint, error)
- func (dbp *DebuggedProcess) BreakpointExists(addr uint64) bool
- func (dbp *DebuggedProcess) Clear(addr uint64) (*Breakpoint, error)
- func (dbp *DebuggedProcess) ClearByLocation(loc string) (*Breakpoint, error)
- func (dbp *DebuggedProcess) Continue() error
- func (dbp *DebuggedProcess) CurrentBreakpoint() *Breakpoint
- func (dbp *DebuggedProcess) Detach(kill bool) (err error)
- func (dbp *DebuggedProcess) DwarfReader() *reader.Reader
- func (dbp *DebuggedProcess) EvalVariable(name string) (*Variable, error)
- func (dbp *DebuggedProcess) Exited() bool
- func (dbp *DebuggedProcess) FindBreakpoint(pc uint64) (*Breakpoint, bool)
- func (dbp *DebuggedProcess) FindBreakpointByID(id int) (*Breakpoint, bool)
- func (dbp *DebuggedProcess) FindLocation(str string) (uint64, error)
- func (dbp *DebuggedProcess) Funcs() []gosym.Func
- func (dbp *DebuggedProcess) GoroutinesInfo() ([]*G, error)
- func (dbp *DebuggedProcess) Halt() (err error)
- func (dbp *DebuggedProcess) HardwareBreakpoints() []*Breakpoint
- func (dbp *DebuggedProcess) LoadInformation(path string) error
- func (dbp *DebuggedProcess) Next() error
- func (dbp *DebuggedProcess) PC() (uint64, error)
- func (dbp *DebuggedProcess) PCToLine(pc uint64) (string, int, *gosym.Func)
- func (dbp *DebuggedProcess) Registers() (Registers, error)
- func (dbp *DebuggedProcess) RequestManualStop() error
- func (dbp *DebuggedProcess) Running() bool
- func (dbp *DebuggedProcess) Sources() map[string]*gosym.Obj
- func (dbp *DebuggedProcess) Status() *sys.WaitStatus
- func (dbp *DebuggedProcess) Step() (err error)
- func (dbp *DebuggedProcess) SwitchThread(tid int) error
- func (dbp *DebuggedProcess) TempBreak(addr uint64) (*Breakpoint, error)
- type G
- type GoroutineExitingError
- type InvalidAddressError
- type Location
- type M
- type ManualStopError
- type NoBreakpointError
- type NoGError
- type NullAddrError
- type OSProcessDetails
- type OSSpecificDetails
- type ProcessExitedError
- type Registers
- type Regs
- type Thread
- func (thread *Thread) Break(addr uint64) (*Breakpoint, error)
- func (thread *Thread) Clear(addr uint64) (*Breakpoint, error)
- func (thread *Thread) Continue() error
- func (thread *Thread) EvalVariable(name string) (*Variable, error)
- func (thread *Thread) FunctionArguments() ([]*Variable, error)
- func (t *Thread) Halt() error
- func (thread *Thread) LocalVariables() ([]*Variable, error)
- func (thread *Thread) Location() (*Location, error)
- func (thread *Thread) PC() (uint64, error)
- func (thread *Thread) PackageVariables() ([]*Variable, error)
- func (thread *Thread) Registers() (Registers, error)
- func (thread *Thread) ReturnAddress() (uint64, error)
- func (thread *Thread) SetNextBreakpoints() (err error)
- func (thread *Thread) SetPC(pc uint64) error
- func (thread *Thread) Step() (err error)
- func (thread *Thread) TempBreak(addr uint64) (*Breakpoint, error)
- type Variable
Constants ¶
const ( STATUS_SLEEPING = 'S' STATUS_RUNNING = 'R' STATUS_TRACE_STOP = 't' )
const ( ChanRecv = "chan receive" ChanSend = "chan send" )
Variables ¶
This section is empty.
Functions ¶
func PtraceCont ¶
func PtraceDetach ¶
func PtracePokeUser ¶
func PtraceSingleStep ¶
Types ¶
type AMD64 ¶
type AMD64 struct {
// contains filtered or unexported fields
}
func (*AMD64) BreakpointInstruction ¶
func (*AMD64) BreakpointSize ¶
func (*AMD64) CurgInstructions ¶
func (*AMD64) HardwareBreakpoints ¶
func (a *AMD64) HardwareBreakpoints() []*Breakpoint
type Arch ¶
type Arch interface { PtrSize() int BreakpointInstruction() []byte BreakpointSize() int CurgInstructions() []byte HardwareBreakpoints() []*Breakpoint }
type Breakpoint ¶
type Breakpoint struct { // File & line information for printing. FunctionName string File string Line int Addr uint64 // Address breakpoint is set for. OriginalData []byte // If software breakpoint, the data we replace with breakpoint instruction. ID int // Monotonically increasing ID. Temp bool // Whether this is a temp breakpoint (for next'ing). // 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.
func (*Breakpoint) Clear ¶
func (bp *Breakpoint) Clear(thread *Thread) (*Breakpoint, error)
Clear this breakpoint appropriately depending on whether it is a hardware or software breakpoint.
func (*Breakpoint) String ¶
func (bp *Breakpoint) String() string
type BreakpointExistsError ¶
type BreakpointExistsError struct {
// contains filtered or unexported fields
}
Returned when trying to set a breakpoint at an address that already has a breakpoint set for it.
func (BreakpointExistsError) Error ¶
func (bpe BreakpointExistsError) Error() string
type DebuggedProcess ¶
type DebuggedProcess struct { Pid int // Process Pid Process *os.Process // Pointer to process struct for the actual process we are debugging // Software breakpoint table. Hardware breakpoints are stored in proc/arch.go, as they are architecture dependant. Breakpoints map[uint64]*Breakpoint // List of threads mapped as such: pid -> *Thread Threads map[int]*Thread // Active thread. This is the default thread used for setting breakpoints, evaluating variables, etc.. CurrentThread *Thread // contains filtered or unexported fields }
DebuggedProcess represents all of the information the debugger is holding onto regarding the process we are debugging.
func Attach ¶
func Attach(pid int) (*DebuggedProcess, error)
Attach to an existing process with the given PID.
func Launch ¶
func Launch(cmd []string) (*DebuggedProcess, error)
Create and begin debugging a new process. First entry in `cmd` is the program to run, and then rest are the arguments to be supplied to that process.
func New ¶
func New(pid int) *DebuggedProcess
func (*DebuggedProcess) Break ¶
func (dbp *DebuggedProcess) Break(addr uint64) (*Breakpoint, error)
Sets a 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.
Depending on hardware support, Delve will choose to either set a hardware or software breakpoint. Essentially, if the hardware supports it, and there are free debug registers, Delve will set a hardware breakpoint. Otherwise we fall back to software breakpoints, which are a bit more work for us.
func (*DebuggedProcess) BreakByLocation ¶
func (dbp *DebuggedProcess) BreakByLocation(loc string) (*Breakpoint, error)
Sets a breakpoint by location string (function, file+line, address)
func (*DebuggedProcess) BreakpointExists ¶
func (dbp *DebuggedProcess) BreakpointExists(addr uint64) bool
Returns whether or not a breakpoint has been set for the given address.
func (*DebuggedProcess) Clear ¶
func (dbp *DebuggedProcess) Clear(addr uint64) (*Breakpoint, error)
Clears a breakpoint in the current thread.
func (*DebuggedProcess) ClearByLocation ¶
func (dbp *DebuggedProcess) ClearByLocation(loc string) (*Breakpoint, error)
Clears a breakpoint by location (function, file+line, address, breakpoint id)
func (*DebuggedProcess) CurrentBreakpoint ¶
func (dbp *DebuggedProcess) CurrentBreakpoint() *Breakpoint
Returns the PC of the current thread.
func (*DebuggedProcess) Detach ¶
func (dbp *DebuggedProcess) Detach(kill bool) (err error)
func (*DebuggedProcess) DwarfReader ¶
func (dbp *DebuggedProcess) DwarfReader() *reader.Reader
Returns a reader for the dwarf data
func (*DebuggedProcess) EvalVariable ¶
func (dbp *DebuggedProcess) EvalVariable(name string) (*Variable, error)
Returns the value of the named symbol.
func (*DebuggedProcess) Exited ¶
func (dbp *DebuggedProcess) Exited() bool
Returns whether or not Delve thinks the debugged process has exited.
func (*DebuggedProcess) FindBreakpoint ¶
func (dbp *DebuggedProcess) FindBreakpoint(pc uint64) (*Breakpoint, bool)
Finds the breakpoint for the given pc.
func (*DebuggedProcess) FindBreakpointByID ¶
func (dbp *DebuggedProcess) FindBreakpointByID(id int) (*Breakpoint, bool)
Finds the breakpoint for the given ID.
func (*DebuggedProcess) FindLocation ¶
func (dbp *DebuggedProcess) FindLocation(str string) (uint64, error)
Find a location by string (file+line, function, breakpoint id, addr)
func (*DebuggedProcess) Funcs ¶
func (dbp *DebuggedProcess) Funcs() []gosym.Func
Returns list of functions present in the debugged program.
func (*DebuggedProcess) GoroutinesInfo ¶
func (dbp *DebuggedProcess) GoroutinesInfo() ([]*G, error)
Returns an array of G structures representing the information Delve cares about from the internal runtime G structure.
func (*DebuggedProcess) HardwareBreakpoints ¶
func (dbp *DebuggedProcess) HardwareBreakpoints() []*Breakpoint
func (*DebuggedProcess) LoadInformation ¶
func (dbp *DebuggedProcess) LoadInformation(path string) error
Finds the executable and then uses it to parse the following information: * Dwarf .debug_frame section * Dwarf .debug_line section * Go symbol table.
func (*DebuggedProcess) PC ¶
func (dbp *DebuggedProcess) PC() (uint64, error)
Returns the PC of the current thread.
func (*DebuggedProcess) Registers ¶
func (dbp *DebuggedProcess) Registers() (Registers, error)
Obtains register values from what Delve considers to be the current thread of the traced process.
func (*DebuggedProcess) RequestManualStop ¶
func (dbp *DebuggedProcess) RequestManualStop() error
Sends out a request that the debugged process halt execution. Sends SIGSTOP to all threads.
func (*DebuggedProcess) Running ¶
func (dbp *DebuggedProcess) Running() bool
Returns whether or not Delve thinks the debugged process is currently executing.
func (*DebuggedProcess) Sources ¶
func (dbp *DebuggedProcess) Sources() map[string]*gosym.Obj
Returns list of source files that comprise the debugged binary.
func (*DebuggedProcess) Status ¶
func (dbp *DebuggedProcess) Status() *sys.WaitStatus
Returns the status of the current main thread context.
func (*DebuggedProcess) Step ¶
func (dbp *DebuggedProcess) Step() (err error)
Single step, will execute a single instruction.
func (*DebuggedProcess) SwitchThread ¶
func (dbp *DebuggedProcess) SwitchThread(tid int) error
Change from current thread to the thread specified by `tid`.
func (*DebuggedProcess) TempBreak ¶
func (dbp *DebuggedProcess) TempBreak(addr uint64) (*Breakpoint, error)
Sets a temp breakpoint, for the 'next' command.
type G ¶
type G struct { Id int // Goroutine ID PC uint64 // PC of goroutine when it was parked. SP uint64 // SP of goroutine when it was parked. GoPC uint64 // PC of 'go' statement that created this goroutine. WaitReason string // Reason for goroutine being parked. // Information on goroutine location. File string Line int Func *gosym.Func // PC of entry to top-most deferred function. DeferPC uint64 }
Represents a runtime G (goroutine) structure (at least the fields that Delve is interested in).
func (*G) ChanRecvBlocked ¶
Returns whether the goroutine is blocked on a channel read operation.
type GoroutineExitingError ¶
type GoroutineExitingError struct {
// contains filtered or unexported fields
}
Go routine is exiting.
func (GoroutineExitingError) Error ¶
func (ge GoroutineExitingError) Error() string
type InvalidAddressError ¶
type InvalidAddressError struct {
// contains filtered or unexported fields
}
InvalidAddressError represents the result of attempting to set a breakpoint at an invalid address.
func (InvalidAddressError) Error ¶
func (iae InvalidAddressError) Error() string
type M ¶
type M struct {
// contains filtered or unexported fields
}
Represents a runtime M (OS thread) structure.
type ManualStopError ¶
type ManualStopError struct{}
A ManualStopError happens when the user triggers a manual stop via SIGERM.
func (ManualStopError) Error ¶
func (mse ManualStopError) Error() string
type NoBreakpointError ¶
type NoBreakpointError struct {
// contains filtered or unexported fields
}
Error thrown when trying to clear a breakpoint that does not exist.
func (NoBreakpointError) Error ¶
func (nbp NoBreakpointError) Error() string
type NoGError ¶
type NoGError struct {
// contains filtered or unexported fields
}
NoGError returned when a G could not be found for a specific thread.
type NullAddrError ¶
type NullAddrError struct{}
func (NullAddrError) Error ¶
func (n NullAddrError) Error() string
type OSSpecificDetails ¶
type OSSpecificDetails struct {
// contains filtered or unexported fields
}
Not actually used, but necessary to be defined.
type ProcessExitedError ¶
ProcessExitedError indicates that the process has exited and contains both process id and exit status.
func (ProcessExitedError) Error ¶
func (pe ProcessExitedError) Error() string
type Registers ¶
An interface for a generic register type. The interface encapsulates the generic values / actions we need independant of arch. The concrete register types will be different depending on OS/Arch.
type Thread ¶
type Thread struct { Id int // Thread ID or mach port Status *sys.WaitStatus // Status returned from last wait call CurrentBreakpoint *Breakpoint // Breakpoint thread is currently stopped at // contains filtered or unexported fields }
Thread represents a single thread in the traced process Id represents the thread id or port, Process holds a reference to the DebuggedProcess struct that contains info on the process as a whole, and Status represents the last result of a `wait` call on this thread.
func (*Thread) Break ¶
func (thread *Thread) Break(addr uint64) (*Breakpoint, error)
Set breakpoint using this thread.
func (*Thread) Clear ¶
func (thread *Thread) Clear(addr uint64) (*Breakpoint, error)
Clear breakpoint using this thread.
func (*Thread) Continue ¶
Continue the execution of this thread. This method takes software breakpoints into consideration and ensures that we step over any breakpoints. It will restore the instruction, step, and then restore the breakpoint and continue.
func (*Thread) EvalVariable ¶
Returns the value of the named variable.
func (*Thread) FunctionArguments ¶
FunctionArguments returns the name, value, and type of all current function arguments.
func (*Thread) LocalVariables ¶
LocalVariables returns all local variables from the current function scope.
func (*Thread) PackageVariables ¶
PackageVariables returns the name, value, and type of all package variables in the application.
func (*Thread) ReturnAddress ¶
Takes an offset from RSP and returns the address of the instruction the currect function is going to return to.
func (*Thread) SetNextBreakpoints ¶
Step to next source line.
Next will step over functions, and will follow through to the return address of a function.
This functionality is implemented by finding all possible next lines and setting a breakpoint at them. Once we've set a breakpoint at each potential line, we continue the thread.