proc

package
v0.9.0-alpha Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 20, 2015 License: MIT Imports: 24 Imported by: 0

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

View Source
const (
	STATUS_SLEEPING   = 'S'
	STATUS_RUNNING    = 'R'
	STATUS_TRACE_STOP = 't'
	STATUS_ZOMBIE     = 'Z'
)

Process statuses

View Source
const (
	ChanRecv = "chan receive"
	ChanSend = "chan send"
)
View Source
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 PtraceCont(tid, sig int) error

func PtraceDetach

func PtraceDetach(tid, sig int) error

func PtracePeekUser

func PtracePeekUser(tid int, off uintptr) (uintptr, error)

func PtracePokeUser

func PtracePokeUser(tid int, off, addr uintptr) error

func PtraceSingleStep

func PtraceSingleStep(tid int) error

Types

type AMD64

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

func AMD64Arch

func AMD64Arch() *AMD64

func (*AMD64) BreakpointInstruction

func (a *AMD64) BreakpointInstruction() []byte

func (*AMD64) BreakpointSize

func (a *AMD64) BreakpointSize() int

func (*AMD64) GStructOffset

func (a *AMD64) GStructOffset() uint64

func (*AMD64) HardwareBreakpointUsage

func (a *AMD64) HardwareBreakpointUsage() []bool

func (*AMD64) PtrSize

func (a *AMD64) PtrSize() int

func (*AMD64) SetGStructOffset

func (a *AMD64) SetGStructOffset(ver GoVersion, isextld bool)

func (*AMD64) SetHardwareBreakpointUsage

func (a *AMD64) SetHardwareBreakpointUsage(reg int, set bool)

type Arch

type Arch interface {
	SetGStructOffset(ver GoVersion, iscgo bool)
	PtrSize() int
	BreakpointInstruction() []byte
	BreakpointSize() int
	GStructOffset() uint64
	HardwareBreakpointUsage() []bool
	SetHardwareBreakpointUsage(int, bool)
}

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

type EvalScope struct {
	Thread *Thread
	PC     uint64
	CFA    int64
}

Scope for variable evaluation

func (*EvalScope) DwarfReader

func (scope *EvalScope) DwarfReader() *reader.Reader

func (*EvalScope) EvalVariable

func (scope *EvalScope) EvalVariable(name string) (*Variable, error)

Returns the value of the named variable.

func (*EvalScope) FunctionArguments

func (scope *EvalScope) FunctionArguments() ([]*Variable, error)

FunctionArguments returns the name, value, and type of all current function arguments.

func (*EvalScope) LocalVariables

func (scope *EvalScope) LocalVariables() ([]*Variable, error)

LocalVariables returns all local variables from the current function scope.

func (*EvalScope) PackageVariables

func (scope *EvalScope) PackageVariables() ([]*Variable, error)

PackageVariables returns the name, value, and type of all package variables in the application.

func (*EvalScope) PtrSize

func (scope *EvalScope) PtrSize() int

func (*EvalScope) Type

func (scope *EvalScope) Type(offset dwarf.Offset) (dwarf.Type, error)

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

func (g *G) ChanRecvBlocked() bool

Returns whether the goroutine is blocked on a channel read operation.

type GoVersion

type GoVersion struct {
	Major int
	Minor int
	Rev   int
	Beta  int
	RC    int
}

func (*GoVersion) AfterOrEqual

func (a *GoVersion) AfterOrEqual(b GoVersion) bool

func (*GoVersion) IsDevel

func (v *GoVersion) IsDevel() bool

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

type Location struct {
	PC   uint64
	File string
	Line int
	Fn   *gosym.Func
}

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.

func (NoGError) Error

func (ng NoGError) Error() string

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 OSProcessDetails

type OSProcessDetails interface{}

Not actually needed for Linux.

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 Attach

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

Attach to an existing process with the given PID.

func Launch

func Launch(cmd []string) (*Process, 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) *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) Continue

func (dbp *Process) Continue() error

Resume process.

func (*Process) ConvertEvalScope

func (dbp *Process) ConvertEvalScope(gid, frame int) (*EvalScope, error)

func (*Process) CurrentBreakpoint

func (dbp *Process) CurrentBreakpoint() *Breakpoint

Returns the PC of the current thread.

func (*Process) Detach

func (dbp *Process) Detach(kill bool) (err error)

Detach from the process being debugged, optionally killing it.

func (*Process) DwarfReader

func (dbp *Process) DwarfReader() *reader.Reader

Returns a reader for the dwarf data

func (*Process) EvalPackageVariable

func (dbp *Process) EvalPackageVariable(name string) (*Variable, error)

func (*Process) Exited

func (dbp *Process) Exited() bool

Returns whether or not Delve thinks the debugged process has exited.

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 (dbp *Process) FindFileLocation(fileName string, lineno int) (uint64, error)

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) FindGoroutine

func (dbp *Process) FindGoroutine(gid int) (*G, error)

func (*Process) Funcs

func (dbp *Process) Funcs() []gosym.Func

Returns list of functions present in the debugged program.

func (*Process) GoroutineLocation

func (dbp *Process) GoroutineLocation(g *G) *Location

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

func (dbp *Process) GoroutinesInfo() ([]*G, error)

Returns an array of G structures representing the information Delve cares about from the internal runtime G structure.

func (*Process) Halt

func (dbp *Process) Halt() (err error)

Stop all threads.

func (*Process) Kill

func (dbp *Process) Kill() (err error)

func (*Process) LoadInformation

func (dbp *Process) 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 (*Process) Next

func (dbp *Process) Next() error

Step over function calls.

func (*Process) PC

func (dbp *Process) PC() (uint64, error)

Returns the PC of the current thread.

func (*Process) PCToLine

func (dbp *Process) PCToLine(pc uint64) (string, int, *gosym.Func)

Converts an instruction address to a file/line/function.

func (*Process) Registers

func (dbp *Process) Registers() (Registers, error)

Obtains register values from what Delve considers to be the current thread of the traced process.

func (*Process) RequestManualStop

func (dbp *Process) RequestManualStop() error

Sends out a request that the debugged process halt execution. Sends SIGSTOP to all threads.

func (*Process) Running

func (dbp *Process) Running() bool

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) Sources

func (dbp *Process) Sources() map[string]*gosym.Obj

Returns list of source files that comprise the debugged binary.

func (*Process) Status

func (dbp *Process) Status() *sys.WaitStatus

Returns the status of the current main thread context.

func (*Process) Step

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

Single step, will execute a single instruction.

func (*Process) SwitchGoroutine

func (dbp *Process) SwitchGoroutine(gid int) error

Change from current thread to the thread running the specified goroutine

func (*Process) SwitchThread

func (dbp *Process) SwitchThread(tid int) error

Change from current thread to the thread specified by `tid`.

type ProcessExitedError

type ProcessExitedError struct {
	Pid    int
	Status int
}

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 Regs

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

func (*Regs) CX

func (r *Regs) CX() uint64

func (*Regs) PC

func (r *Regs) PC() uint64

func (*Regs) SP

func (r *Regs) SP() uint64

func (*Regs) SetPC

func (r *Regs) SetPC(thread *Thread, pc uint64) (err error)

func (*Regs) String

func (r *Regs) String() string

func (*Regs) TLS

func (r *Regs) TLS() uint64

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

func (thread *Thread) Continue() error

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

func (thread *Thread) GetG() (g *G, err error)

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

func (thread *Thread) Halt() (err error)

Stops this thread from executing. Actual implementation is OS dependant. Look in OS thread file.

func (*Thread) Location

func (thread *Thread) Location() (*Location, error)

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) PC

func (thread *Thread) PC() (uint64, error)

Returns the current PC for this thread.

func (*Thread) Registers

func (thread *Thread) Registers() (Registers, error)

Obtains register values from the debugged process.

func (*Thread) ReturnAddress

func (thread *Thread) ReturnAddress() (uint64, error)

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

func (*Thread) Scope

func (thread *Thread) Scope() (*EvalScope, error)

func (*Thread) SetPC

func (thread *Thread) SetPC(pc uint64) error

Sets the PC for this thread.

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.

func (*Thread) Step

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

Step a single instruction.

Executes exactly one instruction and then returns. If the thread is at a breakpoint, we first clear it, execute the instruction, and then replace the breakpoint. Otherwise we simply execute the next instruction.

func (*Thread) Stopped

func (thread *Thread) Stopped() bool

Returns whether the thread is stopped at the operating system level. Actual implementation is OS dependant, look in OS thread file.

type ThreadBlockedError

type ThreadBlockedError struct{}

func (ThreadBlockedError) Error

func (tbe ThreadBlockedError) Error() string

type Variable

type Variable struct {
	Name  string
	Value string
	Type  string
}

Represents an evaluated variable.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL