debugger

package
v1.23.0 Latest Latest
Warning

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

 Go to latest Published: Jul 16, 2024 License: MIT Imports: 30 Imported by: 28

Documentation

Index

Constants

View Source 
const (
	ExecutingExistingFile = ExecuteKind(iota)
	ExecutingGeneratedFile
	ExecutingGeneratedTest
	ExecutingOther
)
View Source 
const NoDebugWarning string = "debuggee must not be built with 'go run' or -ldflags='-s -w', which strip debug info"

Variables

View Source 
var (
	// ErrCanNotRestart is returned when the target cannot be restarted.
	// This is returned for targets that have been attached to, or when
	// debugging core files.
	ErrCanNotRestart = errors.New("can not restart this target")

	// ErrNotRecording is returned when StopRecording is called while the
	// debugger is not recording the target.
	ErrNotRecording = errors.New("debugger is not recording")

	// ErrCoreDumpInProgress is returned when a core dump is already in progress.
	ErrCoreDumpInProgress = errors.New("core dump in progress")

	// ErrCoreDumpNotSupported is returned when core dumping is not supported
	ErrCoreDumpNotSupported = errors.New("core dumping not supported")

	// ErrNotImplementedWithMultitarget is returned for operations that are not implemented with multiple targets
	ErrNotImplementedWithMultitarget = errors.New("not implemented for multiple targets")
)

Functions

This section is empty.

Types

type Config 

type Config struct {
	// WorkingDir is working directory of the new process. This field is used
	// only when launching a new process.
	WorkingDir string

	// AttachPid is the PID of an existing process to which the debugger should
	// attach.
	AttachPid int
	// If AttachWaitFor is set the debugger will wait for a process with a name
	// starting with WaitFor and attach to it.
	AttachWaitFor string
	// AttachWaitForInterval is the time (in milliseconds) that the debugger
	// waits between checks for WaitFor.
	AttachWaitForInterval float64
	// AttachWaitForDuration is the time (in milliseconds) that the debugger
	// waits for WaitFor.
	AttachWaitForDuration float64

	// CoreFile specifies the path to the core dump to open.
	CoreFile string

	// Backend specifies the debugger backend.
	Backend string

	// Foreground lets target process access stdin.
	Foreground bool

	// DebugInfoDirectories is the list of directories to look for
	// when resolving external debug info files.
	DebugInfoDirectories []string

	// CheckGoVersion is true if the debugger should check the version of Go
	// used to compile the executable and refuse to work on incompatible
	// versions.
	CheckGoVersion bool

	// TTY is passed along to the target process on creation. Used to specify a
	// TTY for that process.
	TTY string

	// Packages contains the packages that we are debugging.
	Packages []string

	// BuildFlags contains the flags passed to the compiler.
	BuildFlags string

	// ExecuteKind contains the kind of the executed program.
	ExecuteKind ExecuteKind

	// Stdin Redirect file path for stdin
	Stdin string

	// Redirects specifies redirect rules for stdout
	Stdout proc.OutputRedirect

	// Redirects specifies redirect rules for stderr
	Stderr proc.OutputRedirect

	// DisableASLR disables ASLR
	DisableASLR bool

	RrOnProcessPid int
}

Config provides the configuration to start a Debugger.

Only one of ProcessArgs or AttachPid should be specified. If ProcessArgs is provided, a new process will be launched. Otherwise, the debugger will try to attach to an existing process with AttachPid.

type Debugger 

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

Debugger service.

Debugger provides a higher level of abstraction over proc.Process. It handles converting from internal types to the types expected by clients. It also handles functionality needed by clients, but not needed in lower lever packages such as proc.

func New 

func New(config *Config, processArgs []string) (*Debugger, error)

New creates a new Debugger. ProcessArgs specify the commandline arguments for the new process.

func (*Debugger) AmendBreakpoint 

func (d *Debugger) AmendBreakpoint(amend *api.Breakpoint) error

AmendBreakpoint will update the breakpoint with the matching ID. It also enables or disables the breakpoint.

func (*Debugger) Ancestors added in v1.3.0 

func (d *Debugger) Ancestors(goroutineID int64, numAncestors, depth int) ([]api.Ancestor, error)

Ancestors returns the stacktraces for the ancestors of a goroutine.

func (*Debugger) AsmInstructionText added in v1.5.1 

func (d *Debugger) AsmInstructionText(inst *proc.AsmInstruction, flavour proc.AssemblyFlavour) string

func (*Debugger) Attach added in v1.0.0 

func (d *Debugger) Attach(pid int, path string, waitFor *proc.WaitFor) (*proc.TargetGroup, error)

Attach will attach to the process specified by 'pid'.

func (*Debugger) AttachPid added in v1.9.0 

func (d *Debugger) AttachPid() int

func (*Debugger) Breakpoints 

func (d *Debugger) Breakpoints(all bool) []*api.Breakpoint

Breakpoints returns the list of current breakpoints.

func (*Debugger) BuildID added in v1.8.1 

func (d *Debugger) BuildID() string

func (*Debugger) CancelNext 

func (d *Debugger) CancelNext() error

CancelNext will clear internal breakpoints, thus cancelling the 'next', 'step' or 'stepout' operation.

func (*Debugger) ChanGoroutines added in v1.21.1 

func (d *Debugger) ChanGoroutines(goid int64, frame, deferredCall int, expr string, start, count int) ([]*proc.G, error)

ChanGoroutines returns the list of goroutines waiting on the channel specified by expr.

func (*Debugger) Checkpoint added in v1.0.0 

func (d *Debugger) Checkpoint(where string) (int, error)

Checkpoint will set a checkpoint specified by the locspec.

func (*Debugger) Checkpoints added in v1.0.0 

func (d *Debugger) Checkpoints() ([]proc.Checkpoint, error)

Checkpoints will return a list of checkpoints.

func (*Debugger) ClearBreakpoint 

func (d *Debugger) ClearBreakpoint(requestedBp *api.Breakpoint) (*api.Breakpoint, error)

ClearBreakpoint clears a breakpoint.

func (*Debugger) ClearCheckpoint added in v1.0.0 

func (d *Debugger) ClearCheckpoint(id int) error

ClearCheckpoint will clear the checkpoint of the given ID.

func (*Debugger) Command 

func (d *Debugger) Command(command *api.DebuggerCommand, resumeNotify chan struct{}, clientStatusCh chan struct{}) (state *api.DebuggerState, err error)

Command handles commands which control the debugger lifecycle

func (*Debugger) ConvertStacktrace added in v1.5.1 

func (d *Debugger) ConvertStacktrace(rawlocs []proc.Stackframe, cfg *proc.LoadConfig) ([]api.Stackframe, error)

ConvertStacktrace converts a slice of proc.Stackframe into a slice of api.Stackframe, loading local variables and arguments of each frame if cfg is not nil.

func (*Debugger) ConvertThreadBreakpoint added in v1.9.0 

func (d *Debugger) ConvertThreadBreakpoint(thread proc.Thread) *api.Breakpoint

func (*Debugger) CreateBreakpoint 

func (d *Debugger) CreateBreakpoint(requestedBp *api.Breakpoint, locExpr string, substitutePathRules [][2]string, suspended bool) (*api.Breakpoint, error)

CreateBreakpoint creates a breakpoint using information from the provided `requestedBp`. This function accepts several different ways of specifying where and how to create the breakpoint that has been requested. Any error encountered during the attempt to set the breakpoint will be returned to the caller.

The ways of specifying a breakpoint are listed below in the order they are considered by this function:

- If requestedBp.TraceReturn is true then it is expected that requestedBp.Addrs will contain the list of return addresses supplied by the caller.

- If requestedBp.File is not an empty string the breakpoint will be created on the specified file:line location

- If requestedBp.FunctionName is not an empty string the breakpoint will be created on the specified function:line location.

- If requestedBp.Addrs is filled it will create a logical breakpoint corresponding to all specified addresses.

- Otherwise the value specified by arg.Breakpoint.Addr will be used.

Note that this method will use the first successful method in order to create a breakpoint, so mixing different fields will not result is multiple breakpoints being set.

If LocExpr is specified it will be used, along with substitutePathRules, to re-enable the breakpoint after it is disabled.

If suspended is true a logical breakpoint will be created even if the location can not be found, the backend will attempt to enable the breakpoint every time a new plugin is loaded.

func (*Debugger) CreateEBPFTracepoint added in v1.7.1 

func (d *Debugger) CreateEBPFTracepoint(fnName string) error

func (*Debugger) CreateWatchpoint added in v1.7.0 

func (d *Debugger) CreateWatchpoint(goid int64, frame, deferredCall int, expr string, wtype api.WatchType) (*api.Breakpoint, error)

CreateWatchpoint creates a watchpoint on the specified expression.

func (*Debugger) CurrentPackage added in v1.5.1 

func (d *Debugger) CurrentPackage() (string, error)

CurrentPackage returns the fully qualified name of the package corresponding to the function location of the current thread.

func (*Debugger) DebugInfoDirectories added in v1.21.0 

func (d *Debugger) DebugInfoDirectories() []string

func (*Debugger) Detach 

func (d *Debugger) Detach(kill bool) error

Detach detaches from the target process. If `kill` is true we will kill the process after detaching.

func (*Debugger) Disassemble 

func (d *Debugger) Disassemble(goroutineID int64, addr1, addr2 uint64) ([]proc.AsmInstruction, error)

Disassemble code between startPC and endPC. if endPC == 0 it will find the function containing startPC and disassemble the whole function.

func (*Debugger) DumpCancel added in v1.6.1 

func (d *Debugger) DumpCancel() error

DumpCancel cancels a dump in progress

func (*Debugger) DumpStart added in v1.6.1 

func (d *Debugger) DumpStart(dest string) error

DumpStart starts a core dump to dest.

func (*Debugger) DumpWait added in v1.6.1 

func (d *Debugger) DumpWait(wait time.Duration) *proc.DumpState

DumpWait waits for the dump to finish, or for the duration of wait. Returns the state of the dump. If wait == 0 returns immediately.

func (*Debugger) DwarfRegisterToString added in v1.5.1 

func (d *Debugger) DwarfRegisterToString(i int, reg *op.DwarfRegister) (string, bool, string)

DwarfRegisterToString returns the name and value representation of the given register.

func (*Debugger) EvalVariableInScope 

func (d *Debugger) EvalVariableInScope(goid int64, frame, deferredCall int, expr string, cfg proc.LoadConfig) (*proc.Variable, error)

EvalVariableInScope will attempt to evaluate the 'expr' in the scope corresponding to the given 'frame' on the goroutine identified by 'goid'.

func (*Debugger) ExamineMemory added in v1.4.1 

func (d *Debugger) ExamineMemory(address uint64, length int) ([]byte, error)

ExamineMemory returns the raw memory stored at the given address. The amount of data to be read is specified by length. This function will return an error if it reads less than `length` bytes.

func (*Debugger) FilterGoroutines added in v1.7.0 

func (d *Debugger) FilterGoroutines(gs []*proc.G, filters []api.ListGoroutinesFilter) []*proc.G

FilterGoroutines returns the goroutines in gs that satisfy the specified filters.

func (*Debugger) FindBreakpoint 

func (d *Debugger) FindBreakpoint(id int) *api.Breakpoint

FindBreakpoint returns the breakpoint specified by 'id'.

func (*Debugger) FindBreakpointByName 

func (d *Debugger) FindBreakpointByName(name string) *api.Breakpoint

FindBreakpointByName returns the breakpoint specified by 'name'

func (*Debugger) FindGoroutine added in v1.6.1 

func (d *Debugger) FindGoroutine(id int64) (*proc.G, error)

FindGoroutine returns the goroutine for the given 'id'.

func (*Debugger) FindLocation 

func (d *Debugger) FindLocation(goid int64, frame, deferredCall int, locStr string, includeNonExecutableLines bool, substitutePathRules [][2]string) ([]api.Location, string, error)

FindLocation will find the location specified by 'locStr'.

func (*Debugger) FindLocationSpec added in v1.6.1 

func (d *Debugger) FindLocationSpec(goid int64, frame, deferredCall int, locStr string, locSpec locspec.LocationSpec, includeNonExecutableLines bool, substitutePathRules [][2]string) ([]api.Location, error)

FindLocationSpec will find the location specified by 'locStr' and 'locSpec'. 'locSpec' should be the result of calling 'locspec.Parse(locStr)'. 'locStr' is also passed, because it made be used to broaden the search criteria, if the parsed result did not find anything.

func (*Debugger) FindThread 

func (d *Debugger) FindThread(id int) (proc.Thread, error)

FindThread returns the thread for the given 'id'.

func (*Debugger) FindThreadReturnValues added in v1.5.1 

func (d *Debugger) FindThreadReturnValues(id int, cfg proc.LoadConfig) ([]*proc.Variable, error)

FindThreadReturnValues returns the return values of the function that the thread of the given 'id' just stepped out of.

func (*Debugger) FollowExec added in v1.21.0 

func (d *Debugger) FollowExec(enabled bool, regex string) error

FollowExec enabled or disables follow exec mode.

func (*Debugger) FollowExecEnabled added in v1.21.0 

func (d *Debugger) FollowExecEnabled() bool

FollowExecEnabled returns true if follow exec mode is enabled.

func (*Debugger) Function added in v1.6.1 

func (d *Debugger) Function(goid int64, frame, deferredCall int) (*proc.Function, error)

Function returns the current function.

func (*Debugger) FunctionArguments 

func (d *Debugger) FunctionArguments(goid int64, frame, deferredCall int, cfg proc.LoadConfig) ([]*proc.Variable, error)

FunctionArguments returns the arguments to the current function.

func (*Debugger) FunctionReturnLocations added in v1.2.0 

func (d *Debugger) FunctionReturnLocations(fnName string) ([]uint64, error)

FunctionReturnLocations returns all return locations for the given function, a list of addresses corresponding to 'ret' or 'call runtime.deferreturn'.

func (*Debugger) Functions 

func (d *Debugger) Functions(filter string, followCalls int) ([]string, error)

Functions returns a list of functions in the target process.

func (*Debugger) GetBufferedTracepoints added in v1.7.1 

func (d *Debugger) GetBufferedTracepoints() []api.TracepointResult

func (*Debugger) GetVersion added in v1.3.0 

func (d *Debugger) GetVersion(out *api.GetVersionOut) error

func (*Debugger) Goroutines 

func (d *Debugger) Goroutines(start, count int) ([]*proc.G, int, error)

Goroutines will return a list of goroutines in the target process.

func (*Debugger) GroupGoroutines added in v1.7.0 

func (d *Debugger) GroupGoroutines(gs []*proc.G, group *api.GoroutineGroupingOptions) ([]*proc.G, []api.GoroutineGroup, bool)

GroupGoroutines divides goroutines in gs into groups as specified by group.{GroupBy,GroupByKey}. A maximum of group.MaxGroupMembers are saved in each group, but the total number of goroutines in each group is recorded. If group.MaxGroups is set, then at most that many groups are returned. If some groups end up being dropped because of this limit, the tooManyGroups return value is set.

The first return value represents the goroutines that have been included in one of the returned groups (subject to the MaxGroupMembers and MaxGroups limits). The second return value represents the groups.

func (*Debugger) IsRunning added in v1.6.1 

func (d *Debugger) IsRunning() bool

func (*Debugger) LastModified 

func (d *Debugger) LastModified() time.Time

LastModified returns the time that the process' executable was last modified.

func (*Debugger) Launch added in v1.0.0 

func (d *Debugger) Launch(processArgs []string, wd string) (*proc.TargetGroup, error)

Launch will start a process with the given args and working directory.

func (*Debugger) ListDynamicLibraries added in v1.3.0 

func (d *Debugger) ListDynamicLibraries() []*proc.Image

ListDynamicLibraries returns a list of loaded dynamic libraries.

func (*Debugger) ListPackagesBuildInfo added in v1.4.0 

func (d *Debugger) ListPackagesBuildInfo(includeFiles bool) []*proc.PackageBuildInfo

ListPackagesBuildInfo returns the list of packages used by the program along with the directory where each package was compiled and optionally the list of files constituting the package.

func (*Debugger) LoadResliced added in v1.7.0 

func (d *Debugger) LoadResliced(v *proc.Variable, start int, cfg proc.LoadConfig) (*proc.Variable, error)

LoadResliced will attempt to 'reslice' a map, array or slice so that the values up to cfg.MaxArrayValues children are loaded starting from index start.

func (*Debugger) LocalVariables 

func (d *Debugger) LocalVariables(goid int64, frame, deferredCall int, cfg proc.LoadConfig) ([]*proc.Variable, error)

LocalVariables returns a list of the local variables.

func (*Debugger) LockTarget added in v1.5.1 

func (d *Debugger) LockTarget()

LockTarget acquires the target mutex.

func (*Debugger) PackageVariables 

func (d *Debugger) PackageVariables(filter string, cfg proc.LoadConfig) ([]*proc.Variable, error)

PackageVariables returns a list of package variables for the thread, optionally regexp filtered using regexp described in 'filter'.

func (*Debugger) ProcessPid 

func (d *Debugger) ProcessPid() int

ProcessPid returns the PID of the process the debugger is debugging.

func (*Debugger) Recorded added in v1.0.0 

func (d *Debugger) Recorded() (recorded bool, tracedir string)

Recorded returns true if the target is a recording.

func (*Debugger) Restart 

func (d *Debugger) Restart(rerecord bool, pos string, resetArgs bool, newArgs []string, newRedirects [3]string, rebuild bool) ([]api.DiscardedBreakpoint, error)

Restart will restart the target process, first killing and then exec'ing it again. If the target process is a recording it will restart it from the given position. If pos starts with 'c' it's a checkpoint ID, otherwise it's an event number. If resetArgs is true, newArgs will replace the process args.

func (*Debugger) ScopeRegisters added in v1.5.1 

func (d *Debugger) ScopeRegisters(goid int64, frame, deferredCall int) (*op.DwarfRegisters, error)

ScopeRegisters returns registers for the specified scope.

func (*Debugger) SetDebugInfoDirectories added in v1.21.0 

func (d *Debugger) SetDebugInfoDirectories(v []string)

func (*Debugger) SetVariableInScope 

func (d *Debugger) SetVariableInScope(goid int64, frame, deferredCall int, symbol, value string) error

SetVariableInScope will set the value of the variable represented by 'symbol' to the value given, in the given scope.

func (*Debugger) Sources 

func (d *Debugger) Sources(filter string) ([]string, error)

Sources returns a list of the source files for target binary.

func (*Debugger) Stacktrace 

func (d *Debugger) Stacktrace(goroutineID int64, depth int, opts api.StacktraceOptions) ([]proc.Stackframe, error)

Stacktrace returns a list of Stackframes for the given goroutine. The length of the returned list will be min(stack_len, depth). If 'full' is true, then local vars, function args, etc. will be returned as well.

func (*Debugger) State 

func (d *Debugger) State(nowait bool) (*api.DebuggerState, error)

State returns the current state of the debugger.

func (*Debugger) StopReason added in v1.5.1 

func (d *Debugger) StopReason() proc.StopReason

StopReason returns the reason why the target process is stopped. A process could be stopped for multiple simultaneous reasons, in which case only one will be reported.

func (*Debugger) StopRecording added in v1.4.1 

func (d *Debugger) StopRecording() error

StopRecording stops a recording (if one is in progress)

func (*Debugger) Target added in v1.7.0 

func (d *Debugger) Target() *proc.Target

func (*Debugger) TargetGoVersion added in v1.7.0 

func (d *Debugger) TargetGoVersion() string

func (*Debugger) TargetGroup added in v1.9.1 

func (d *Debugger) TargetGroup() *proc.TargetGroup

func (*Debugger) ThreadRegisters added in v1.5.1 

func (d *Debugger) ThreadRegisters(threadID int) (*op.DwarfRegisters, error)

ThreadRegisters returns registers of the specified thread.

func (*Debugger) Threads 

func (d *Debugger) Threads() ([]proc.Thread, error)

Threads returns the threads of the target process.

func (*Debugger) Types 

func (d *Debugger) Types(filter string) ([]string, error)

Types returns all type information in the binary.

func (*Debugger) UnlockTarget added in v1.5.1 

func (d *Debugger) UnlockTarget()

UnlockTarget releases the target mutex.

type ExecuteKind added in v1.5.0 

type ExecuteKind int

Source Files

View all Source files

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.