proc

package
v0.11.0-alpha Latest Latest
Warning

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

 Go to latest Published: Jan 26, 2016 License: MIT Imports: 29 Imported by: 0

Documentation

Overview

Package 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 (
	StatusSleeping  = 'S'
	StatusRunning   = 'R'
	StatusTraceStop = 't'
	StatusZombie    = 'Z'
)

Process statuses

View Source 
const (
	Gidle           uint64 = iota // 0
	Grunnable                     // 1 runnable and on a run queue
	Grunning                      // 2
	Gsyscall                      // 3
	Gwaiting                      // 4
	GmoribundUnused               // 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
)

G status, from: src/runtime/runtime2.go

Variables

This section is empty.

Functions

func PtraceAttach 

func PtraceAttach(pid int) error

PtraceAttach executes the sys.PtraceAttach call.

func PtraceCont 

func PtraceCont(tid, sig int) error

PtraceCont executes ptrace PTRACE_CONT

func PtraceDetach 

func PtraceDetach(tid, sig int) error

PtraceDetach calls ptrace(PTRACE_DETACH).

func PtracePeekUser 

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

PtracePeekUser execute ptrace PTRACE_PEEK_USER.

func PtracePokeUser 

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

PtracePokeUser execute ptrace PTRACE_POKE_USER.

func PtraceSingleStep 

func PtraceSingleStep(tid int) error

PtraceSingleStep executes ptrace PTRACE_SINGLE_STEP.

Types

type AMD64 

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

AMD64 represents the AMD64 CPU architecture.

func AMD64Arch 

func AMD64Arch() *AMD64

AMD64Arch returns an initialized AMD64 struct.

func (*AMD64) BreakpointInstruction 

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

BreakpointInstruction returns the Breakpoint instruction for this architecture.

func (*AMD64) BreakpointSize 

func (a *AMD64) BreakpointSize() int

BreakpointSize returns the size of the breakpoint instruction on this architecture.

func (*AMD64) GStructOffset 

func (a *AMD64) GStructOffset() uint64

GStructOffset returns the offset of the G struct in thread local storage.

func (*AMD64) PtrSize 

func (a *AMD64) PtrSize() int

PtrSize returns the size of a pointer on this architecture.

func (*AMD64) SetGStructOffset 

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

SetGStructOffset sets the offset of the G struct on the AMD64 arch struct. The offset is depandant on the Go compiler Version and whether or not the target program was externally linked.

type Arch 

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

Arch defines an interface for representing a CPU architecture.

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
	HitCount      map[int]uint64 // Number of times a breakpoint has been reached in a certain goroutine
	TotalHitCount uint64         // Number of times a breakpoint has been reached

	Cond ast.Expr // When Cond is not nil the breakpoint will be triggered only if evaluating Cond returns true
}

Breakpoint represents a 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
}

BreakpointExistsError is 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
}

EvalScope is the scope for variable evaluation. Contains the thread, current location (PC), and canonical frame address.

func (*EvalScope) DwarfReader 

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

DwarfReader returns the DwarfReader containing the Dwarf information for the target process.

func (*EvalScope) EvalExpression 

func (scope *EvalScope) EvalExpression(expr string) (*Variable, error)

EvalExpression returns the value of the given expression.

func (*EvalScope) EvalVariable 

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

EvalVariable returns the value of the given expression (backwards compatibility).

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

PtrSize returns the size of a pointer.

func (*EvalScope) SetVariable 

func (scope *EvalScope) SetVariable(name, value string) error

SetVariable sets the value of the named variable

func (*EvalScope) Type 

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

Type returns the Dwarf type entry at `offset`.

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
	CurrentLoc Location

	// PC of entry to top-most deferred function.
	DeferPC uint64
	// contains filtered or unexported fields
}

G represents a runtime G (goroutine) structure (at least the fields that Delve is interested in).

func (*G) ChanRecvBlocked 

func (g *G) ChanRecvBlocked() bool

ChanRecvBlocked returns whether the goroutine is blocked on a channel read operation.

func (*G) Go 

func (g *G) Go() Location

Go returns the location of the 'go' statement that spawned this goroutine.

func (*G) UserCurrent 

func (g *G) UserCurrent() Location

UserCurrent returns the location the users code is at, or was at before entering a runtime function.

type GoVersion 

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

GoVersion represents the Go version of the Go compiler version used to compile the target binary.

func (*GoVersion) AfterOrEqual 

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

AfterOrEqual returns whether one GoVersion is after or equal to the other.

func (*GoVersion) IsDevel 

func (v *GoVersion) IsDevel() bool

IsDevel returns whether the GoVersion is a development version.

type GoroutineExitingError 

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

GoroutineExitingError is returned when the goroutine specified by `goid` is in the process of 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 IsNilErr 

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

IsNilErr is returned when a variable is nil.

func (*IsNilErr) Error 

func (err *IsNilErr) Error() string

type Location 

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

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
}

M represents a runtime M (OS thread) structure.

type NoBreakpointError 

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

NoBreakpointError is returned 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
}

NoReturnAddr is returned when return address could not be found during stack tracae.

func (NoReturnAddr) Error 

func (nra NoReturnAddr) Error() string

type NullAddrError 

type NullAddrError struct{}

NullAddrError is an error for a null address.

func (NullAddrError) Error 

func (n NullAddrError) Error() string

type OSProcessDetails 

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

OSProcessDetails contains Linux specific process details.

type OSSpecificDetails 

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

OSSpecificDetails hold Linux specific process details.

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, holds information on 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)

Launch creates and begins 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

New returns an initialized Process struct. Before returning, it will also launch a goroutine in order to handle ptrace(2) functions. For more information, see the documentation on `handlePtraceFuncs`.

func (*Process) ClearBreakpoint 

func (dbp *Process) ClearBreakpoint(addr uint64) (*Breakpoint, error)

ClearBreakpoint clears the breakpoint at addr.

func (*Process) Continue 

func (dbp *Process) Continue() error

Continue continues execution of the debugged process. It will continue until it hits a breakpoint or is otherwise stopped.

func (*Process) ConvertEvalScope 

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

ConvertEvalScope returns a new EvalScope in the context of the specified goroutine ID and stack frame.

func (*Process) CurrentBreakpoint 

func (dbp *Process) CurrentBreakpoint() *Breakpoint

CurrentBreakpoint returns the breakpoint the current thread is stopped at.

func (*Process) CurrentLocation 

func (dbp *Process) CurrentLocation() (*Location, error)

CurrentLocation returns the location 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

DwarfReader returns a reader for the dwarf data

func (*Process) EvalPackageVariable 

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

EvalPackageVariable will evaluate the package level variable specified by 'name'.

func (*Process) Exited 

func (dbp *Process) Exited() bool

Exited returns whether the debugged process has exited.

func (*Process) FindBreakpoint 

func (dbp *Process) FindBreakpoint(pc uint64) (*Breakpoint, bool)

FindBreakpoint finds the breakpoint for the given pc.

func (*Process) FindBreakpointByID 

func (dbp *Process) FindBreakpointByID(id int) (*Breakpoint, bool)

FindBreakpointByID finds the breakpoint for the given ID.

func (*Process) FindFileLocation 

func (dbp *Process) FindFileLocation(fileName string, lineno int) (uint64, error)

FindFileLocation returns the PC for a given file:line.

func (*Process) FindFunctionLocation 

func (dbp *Process) FindFunctionLocation(funcName string, firstLine bool, lineOffset int) (uint64, error)

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

FindGoroutine returns a G struct representing the goroutine specified by `gid`.

func (*Process) Funcs 

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

Funcs returns list of functions present in the debugged program.

func (*Process) FunctionEntryToFirstLine 

func (dbp *Process) FunctionEntryToFirstLine(entry uint64) (uint64, error)

func (*Process) GoroutineLocation 

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

GoroutineLocation returns the location of the given goroutine.

func (*Process) GoroutineStacktrace 

func (dbp *Process) GoroutineStacktrace(g *G, depth int) ([]Stackframe, error)

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

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

Halt stops all threads.

func (*Process) Kill 

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

Kill kills the target process.

func (*Process) LoadInformation 

func (dbp *Process) LoadInformation(path string) error

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

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

Next continues execution until the next source line.

func (*Process) PC 

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

PC returns the PC of the current thread.

func (*Process) PCToLine 

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

PCToLine converts an instruction address to a file/line/function.

func (*Process) Registers 

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

Registers obtains register values from the "current" thread of the traced process.

func (*Process) RequestManualStop 

func (dbp *Process) RequestManualStop() error

RequestManualStop sets the `halt` flag and sends SIGSTOP to all threads.

func (*Process) Running 

func (dbp *Process) Running() bool

Running returns whether the debugged process is currently executing.

func (*Process) SetBreakpoint 

func (dbp *Process) SetBreakpoint(addr uint64) (*Breakpoint, error)

SetBreakpoint 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.

func (*Process) SetTempBreakpoint 

func (dbp *Process) SetTempBreakpoint(addr uint64) (*Breakpoint, error)

SetTempBreakpoint sets a temp breakpoint. Used during 'next' operations.

func (*Process) Sources 

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

Sources returns list of source files that comprise the debugged binary.

func (*Process) Status 

func (dbp *Process) Status() *WaitStatus

Status returns the status of the current main thread context.

func (*Process) Step 

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

Step will continue until another source line is reached. Will step into functions.

func (*Process) StepInstruction 

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

StepInstruction will continue the current thread for exactly one instruction. This method affects only the thread asssociated with the selected goroutine. All other threads will remain stopped.

func (*Process) SwitchGoroutine 

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

SwitchGoroutine changes from current thread to the thread running the specified goroutine.

func (*Process) SwitchThread 

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

SwitchThread changes 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
}

Registers is 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
}

Regs is a wrapper for sys.PtraceRegs.

func (*Regs) CX 

func (r *Regs) CX() uint64

CX returns the value of RCX register.

func (*Regs) PC 

func (r *Regs) PC() uint64

PC returns the value of RIP register.

func (*Regs) SP 

func (r *Regs) SP() uint64

SP returns the value of RSP register.

func (*Regs) SetPC 

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

SetPC sets RIP to the value specified by 'pc'.

func (*Regs) String 

func (r *Regs) String() string

func (*Regs) TLS 

func (r *Regs) TLS() uint64

TLS returns the address of the thread local storage memory segment.

type StackIterator 

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

StackIterator holds information required to iterate and walk the program stack.

func (*StackIterator) Err 

func (it *StackIterator) Err() error

Err returns the error encountered during stack iteration.

func (*StackIterator) Frame 

func (it *StackIterator) Frame() Stackframe

Frame returns the frame the iterator is pointing at.

func (*StackIterator) Next 

func (it *StackIterator) Next() bool

Next points the iterator to the next stack frame.

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
}

Stackframe represents a frame in a system stack.

func (*Stackframe) Scope 

func (frame *Stackframe) Scope(thread *Thread) *EvalScope

Scope returns a new EvalScope using this frame.

type Thread 

type Thread struct {
	ID                       int         // Thread ID or mach port
	Status                   *WaitStatus // Status returned from last wait call
	CurrentBreakpoint        *Breakpoint // Breakpoint thread is currently stopped at
	BreakpointConditionMet   bool        // Output of evaluating the breakpoint's condition
	BreakpointConditionError error       // Error evaluating the breakpoint's condition
	// 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)

GetG returns information on the G (goroutine) that is executing on this thread.

The G structure for a thread is stored in thread local storage. Here we simply calculate the address and read and parse the G struct.

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)

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

func (*Thread) Location 

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

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

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

PC returns the current PC for this thread.

func (*Thread) Registers 

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

Registers obtains register values from the debugged process.

func (*Thread) ReturnAddress 

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

ReturnAddress returns the return address of the function this thread is executing.

func (*Thread) Scope 

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

Scope returns the current EvalScope for this thread.

func (*Thread) SetCurrentBreakpoint 

func (thread *Thread) SetCurrentBreakpoint() error

SetCurrentBreakpoint sets the current breakpoint that this thread is stopped at as CurrentBreakpoint on the thread struct.

func (*Thread) SetPC 

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

SetPC sets the PC for this thread.

func (*Thread) Stacktrace 

func (t *Thread) Stacktrace(depth int) ([]Stackframe, error)

Stacktrace returns the stack trace for thread. Note the locations in the array are return addresses not call addresses.

func (*Thread) StepInstruction 

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

StepInstruction steps 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

Stopped 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{}

ThreadBlockedError is returned when the thread is blocked in the scheduler.

func (ThreadBlockedError) Error 

func (tbe ThreadBlockedError) Error() string

type Variable 

type Variable struct {
	Addr      uintptr
	OnlyAddr  bool
	Name      string
	DwarfType dwarf.Type
	RealType  dwarf.Type
	Kind      reflect.Kind

	Value constant.Value

	Len int64
	Cap int64

	// Base address of arrays, Base address of the backing array for slices (0 for nil slices)
	// Base address of the backing byte array for strings
	// address of the struct backing chan and map variables
	// address of the function entry point for function variables (0 for nil function pointers)
	Base uintptr

	Children []Variable

	Unreadable error
	// contains filtered or unexported fields
}

Variable represents a variable. It contains the address, name, type and other information parsed from both the Dwarf information and the memory of the debugged process. If OnlyAddr is true, the variables value has not been loaded.

func (*Variable) TypeString 

func (v *Variable) TypeString() string

TypeString returns the string representation of the type of this variable.

type WaitStatus 

type WaitStatus sys.WaitStatus

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.