Documentation ¶
Overview ¶
proc is a low-level package that provides methods to manipulate the process we are debugging.
proc implements all core functionality including: * creating / attaching to a process * process manipulation (step, next, continue, halt) * methods to explore the memory of the process
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
- func (a *AMD64) BreakpointInstruction() []byte
- func (a *AMD64) BreakpointSize() int
- func (a *AMD64) GStructOffset() uint64
- func (a *AMD64) HardwareBreakpointUsage() []bool
- func (a *AMD64) PtrSize() int
- func (a *AMD64) SetGStructOffset(ver GoVersion, isextld bool)
- func (a *AMD64) SetHardwareBreakpointUsage(reg int, set bool)
- type Arch
- type Breakpoint
- type BreakpointExistsError
- type EvalScope
- func (scope *EvalScope) DwarfReader() *reader.Reader
- func (scope *EvalScope) EvalVariable(name string) (*Variable, error)
- func (scope *EvalScope) FunctionArguments() ([]*Variable, error)
- func (scope *EvalScope) LocalVariables() ([]*Variable, error)
- func (scope *EvalScope) PackageVariables() ([]*Variable, error)
- func (scope *EvalScope) PtrSize() int
- func (scope *EvalScope) Type(offset dwarf.Offset) (dwarf.Type, error)
- type G
- type GoVersion
- type GoroutineExitingError
- type InvalidAddressError
- type Location
- type M
- type NoBreakpointError
- type NoGError
- type NoReturnAddr
- type NullAddrError
- type OSProcessDetails
- type OSSpecificDetails
- type Process
- func (dbp *Process) ClearBreakpoint(addr uint64) (*Breakpoint, error)
- func (dbp *Process) Continue() error
- func (dbp *Process) ConvertEvalScope(gid, frame int) (*EvalScope, error)
- func (dbp *Process) CurrentBreakpoint() *Breakpoint
- func (dbp *Process) Detach(kill bool) (err error)
- func (dbp *Process) DwarfReader() *reader.Reader
- func (dbp *Process) EvalPackageVariable(name string) (*Variable, error)
- func (dbp *Process) Exited() bool
- func (dbp *Process) FindBreakpoint(pc uint64) (*Breakpoint, bool)
- func (dbp *Process) FindBreakpointByID(id int) (*Breakpoint, bool)
- func (dbp *Process) FindFileLocation(fileName string, lineno int) (uint64, error)
- func (dbp *Process) FindFunctionLocation(funcName string, firstLine bool, lineOffset int) (uint64, error)
- func (dbp *Process) FindGoroutine(gid int) (*G, error)
- func (dbp *Process) Funcs() []gosym.Func
- func (dbp *Process) GoroutineLocation(g *G) *Location
- func (dbp *Process) GoroutineStacktrace(g *G, depth int) ([]Stackframe, error)
- func (dbp *Process) GoroutinesInfo() ([]*G, error)
- func (dbp *Process) Halt() (err error)
- func (dbp *Process) Kill() (err error)
- func (dbp *Process) LoadInformation(path string) error
- func (dbp *Process) Next() error
- func (dbp *Process) PC() (uint64, error)
- func (dbp *Process) PCToLine(pc uint64) (string, int, *gosym.Func)
- func (dbp *Process) Registers() (Registers, error)
- func (dbp *Process) RequestManualStop() error
- func (dbp *Process) Running() bool
- func (dbp *Process) SetBreakpoint(addr uint64) (*Breakpoint, error)
- func (dbp *Process) SetTempBreakpoint(addr uint64) (*Breakpoint, error)
- func (dbp *Process) Sources() map[string]*gosym.Obj
- func (dbp *Process) Status() *sys.WaitStatus
- func (dbp *Process) Step() (err error)
- func (dbp *Process) SwitchGoroutine(gid int) error
- func (dbp *Process) SwitchThread(tid int) error
- type ProcessExitedError
- type Registers
- type Regs
- type Stackframe
- type Thread
- func (thread *Thread) Continue() error
- func (thread *Thread) GetG() (g *G, err error)
- func (thread *Thread) Halt() (err error)
- func (thread *Thread) Location() (*Location, error)
- func (thread *Thread) PC() (uint64, error)
- func (thread *Thread) Registers() (Registers, error)
- func (thread *Thread) ReturnAddress() (uint64, error)
- func (thread *Thread) Scope() (*EvalScope, error)
- func (thread *Thread) SetPC(pc uint64) error
- func (thread *Thread) Stacktrace(depth int) ([]Stackframe, error)
- func (thread *Thread) Step() (err error)
- func (thread *Thread) Stopped() bool
- type ThreadBlockedError
- type Variable
Constants ¶
const ( STATUS_SLEEPING = 'S' STATUS_RUNNING = 'R' STATUS_TRACE_STOP = 't' STATUS_ZOMBIE = 'Z' )
Process statuses
const ( ChanRecv = "chan receive" ChanSend = "chan send" )
const ( // G status, from: src/runtime/runtime2.go Gidle uint64 = iota // 0 Grunnable // 1 runnable and on a run queue Grunning // 2 Gsyscall // 3 Gwaiting // 4 Gmoribund_unused // 5 currently unused, but hardcoded in gdb scripts Gdead // 6 Genqueue // 7 Only the Gscanenqueue is used. Gcopystack // 8 in this state when newstack is moving the stack )
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) GStructOffset ¶
func (*AMD64) HardwareBreakpointUsage ¶
func (*AMD64) SetGStructOffset ¶
func (*AMD64) SetHardwareBreakpointUsage ¶
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). // Breakpoint information Tracepoint bool // Tracepoint flag Stacktrace int // Number of stack frames to retrieve Goroutine bool // Retrieve goroutine information Variables []string // Variables to evaluate // 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 EvalScope ¶
Scope for variable evaluation
func (*EvalScope) DwarfReader ¶
func (*EvalScope) EvalVariable ¶
Returns the value of the named variable.
func (*EvalScope) FunctionArguments ¶
FunctionArguments returns the name, value, and type of all current function arguments.
func (*EvalScope) LocalVariables ¶
LocalVariables returns all local variables from the current function scope.
func (*EvalScope) PackageVariables ¶
PackageVariables returns the name, value, and type of all package variables in the application.
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. Status uint64 // Information on goroutine location. File string Line int Func *gosym.Func // PC of entry to top-most deferred function. DeferPC uint64 // contains filtered or unexported fields }
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 GoVersion ¶
func (*GoVersion) AfterOrEqual ¶
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 Location ¶
Represents the location of a thread. Holds information on the current instruction address, the source file:line, and the function.
type M ¶
type M struct {
// contains filtered or unexported fields
}
Represents a runtime M (OS thread) structure.
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 NoReturnAddr ¶
type NoReturnAddr struct {
// contains filtered or unexported fields
}
func (NoReturnAddr) Error ¶
func (nra NoReturnAddr) Error() string
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 Process ¶
type Process struct { Pid int // Process Pid Process *os.Process // Pointer to process struct for the actual process we are debugging // Breakpoint table, hold information on software / hardware breakpoints. // Maps instruction address to Breakpoint struct. Breakpoints map[uint64]*Breakpoint // List of threads mapped as such: pid -> *Thread Threads map[int]*Thread // Active thread CurrentThread *Thread // Goroutine that will be used by default to set breakpoint, eval variables, etc... // Normally SelectedGoroutine is CurrentThread.GetG, it will not be only if SwitchGoroutine is called with a goroutine that isn't attached to a thread SelectedGoroutine *G // contains filtered or unexported fields }
Process represents all of the information the debugger is holding onto regarding the process we are debugging.
func Launch ¶
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 (*Process) ClearBreakpoint ¶
func (dbp *Process) ClearBreakpoint(addr uint64) (*Breakpoint, error)
Clears a breakpoint.
If it is a hardware assisted breakpoint, iterate through all threads and clear the debug register. Otherwise, restore original instruction.
func (*Process) ConvertEvalScope ¶
func (*Process) CurrentBreakpoint ¶
func (dbp *Process) CurrentBreakpoint() *Breakpoint
Returns the PC of the current thread.
func (*Process) DwarfReader ¶
Returns a reader for the dwarf data
func (*Process) EvalPackageVariable ¶
func (*Process) FindBreakpoint ¶
func (dbp *Process) FindBreakpoint(pc uint64) (*Breakpoint, bool)
Finds the breakpoint for the given pc.
func (*Process) FindBreakpointByID ¶
func (dbp *Process) FindBreakpointByID(id int) (*Breakpoint, bool)
Finds the breakpoint for the given ID.
func (*Process) FindFileLocation ¶
func (*Process) FindFunctionLocation ¶
func (dbp *Process) FindFunctionLocation(funcName string, firstLine bool, lineOffset int) (uint64, error)
Finds address of a function's line If firstLine == true is passed FindFunctionLocation will attempt to find the first line of the function If lineOffset is passed FindFunctionLocation will return the address of that line Pass lineOffset == 0 and firstLine == false if you want the address for the function's entry point Note that setting breakpoints at that address will cause surprising behavior: https://github.com/derekparker/delve/issues/170
func (*Process) GoroutineLocation ¶
func (*Process) GoroutineStacktrace ¶
func (dbp *Process) GoroutineStacktrace(g *G, depth int) ([]Stackframe, error)
Returns the stack trace for a goroutine. Note the locations in the array are return addresses not call addresses.
func (*Process) GoroutinesInfo ¶
Returns an array of G structures representing the information Delve cares about from the internal runtime G structure.
func (*Process) LoadInformation ¶
Finds the executable and then uses it to parse the following information: * Dwarf .debug_frame section * Dwarf .debug_line section * Go symbol table.
func (*Process) Registers ¶
Obtains register values from what Delve considers to be the current thread of the traced process.
func (*Process) RequestManualStop ¶
Sends out a request that the debugged process halt execution. Sends SIGSTOP to all threads.
func (*Process) Running ¶
Returns whether or not Delve thinks the debugged process is currently executing.
func (*Process) SetBreakpoint ¶
func (dbp *Process) SetBreakpoint(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 (*Process) SetTempBreakpoint ¶
func (dbp *Process) SetTempBreakpoint(addr uint64) (*Breakpoint, error)
Sets a temp breakpoint, for the 'next' command.
func (*Process) Status ¶
func (dbp *Process) Status() *sys.WaitStatus
Returns the status of the current main thread context.
func (*Process) SwitchGoroutine ¶
Change from current thread to the thread running the specified goroutine
func (*Process) SwitchThread ¶
Change from current thread to the thread specified by `tid`.
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 ¶
type Registers interface { PC() uint64 SP() uint64 CX() uint64 TLS() uint64 SetPC(*Thread, uint64) error String() string }
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 Stackframe ¶
type Stackframe struct { // Address the function above this one on the call stack will return to. Current Location // Address of the call instruction for the function above on the call stack. Call Location CFA int64 Ret uint64 }
func (*Stackframe) Scope ¶
func (frame *Stackframe) Scope(thread *Thread) *EvalScope
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 Process 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) Continue ¶
Continue the execution of this thread.
If we are currently at a breakpoint, we'll clear it first and then resume execution. Thread will continue until it hits a breakpoint or is signaled.
func (*Thread) GetG ¶
Returns information on the G (goroutine) that is executing on this thread.
The G structure for a thread is stored in thread local memory. Execute instructions that move the *G structure into a CPU register, and then grab the new registers and parse the G structure.
We cannot simply use the allg linked list in order to find the M that represents the given OS thread and follow its G pointer because on Darwin mach ports are not universal, so our port for this thread would not map to the `id` attribute of the M structure. Also, when linked against libc, Go prefers the libc version of clone as opposed to the runtime version. This has the consequence of not setting M.id for any thread, regardless of OS.
In order to get around all this craziness, we read the address of the G structure for the current thread from the thread local storage area.
func (*Thread) Halt ¶
Stops this thread from executing. Actual implementation is OS dependant. Look in OS thread file.
func (*Thread) Location ¶
Returns the threads location, including the file:line of the corresponding source code, the function we're in and the current instruction address.
func (*Thread) ReturnAddress ¶
Takes an offset from RSP and returns the address of the instruction the current function is going to return to.
func (*Thread) Stacktrace ¶
func (thread *Thread) Stacktrace(depth int) ([]Stackframe, error)
Returns the stack trace for thread. Note the locations in the array are return addresses not call addresses.
type ThreadBlockedError ¶
type ThreadBlockedError struct{}
func (ThreadBlockedError) Error ¶
func (tbe ThreadBlockedError) Error() string