debug: golang.org/x/debug Index | Files | Directories

package debug

import "golang.org/x/debug"

Package debug provides the portable interface to a program being debugged.

Index

Package Files

program.go

type Array Uses

type Array struct {
    ElementTypeID uint64
    Address       uint64
    Length        uint64 // Number of elements in the array
    StrideBits    uint64 // Number of bits between array entries
}

Array is a Value representing an array.

func (Array) Element Uses

func (a Array) Element(index uint64) Var

Element returns a Var referring to the given element of the array.

func (Array) Len Uses

func (a Array) Len() uint64

Len returns the number of elements in the array.

type Channel Uses

type Channel struct {
    ElementTypeID uint64
    Address       uint64 // Location of the channel struct in memory.
    Buffer        uint64 // Location of the buffer; zero for nil channels.
    Length        uint64 // Number of elements stored in the channel buffer.
    Capacity      uint64 // Capacity of the buffer; zero for unbuffered channels.
    Stride        uint64 // Number of bytes between buffer entries.
    BufferStart   uint64 // Index in the buffer of the element at the head of the queue.
}

Channel is a Value representing a channel.

func (Channel) Element Uses

func (m Channel) Element(index uint64) Var

Element returns a Var referring to the given element of the channel's queue. If the channel is unbuffered, nil, or if the index is too large, returns a Var with Address == 0.

type File Uses

type File interface {
    io.ReaderAt
    io.WriterAt
    io.Closer
}

The File interface provides access to file-like resources in the program. It implements only ReaderAt and WriterAt, not Reader and Writer, because random access is a far more common pattern for things like symbol tables, and because enormous address space of virtual memory makes routines like io.Copy dangerous.

type Frame Uses

type Frame struct {
    // PC is the hardware program counter.
    PC  uint64
    // SP is the hardware stack pointer.
    SP  uint64
    // File and Line are the source code location of the PC.
    File string
    Line uint64
    // Function is the name of this frame's function.
    Function string
    // FunctionStart is the starting PC of the function.
    FunctionStart uint64
    // Params contains the function's parameters.
    Params []Param
    // Vars contains the function's local variables.
    Vars []LocalVar
}

func (Frame) String Uses

func (f Frame) String() string

type Func Uses

type Func struct {
    Address uint64
}

Func is a Value representing a func.

type Goroutine Uses

type Goroutine struct {
    ID           int64
    Status       GoroutineStatus
    StatusString string // A human-readable string explaining the status in more detail.
    Function     string // Name of the goroutine function.
    Caller       string // Name of the function that created this goroutine.
    StackFrames  []Frame
}

func (*Goroutine) String Uses

func (g *Goroutine) String() string

type GoroutineStatus Uses

type GoroutineStatus byte
const (
    Running GoroutineStatus = iota
    Queued
    Blocked
)

func (GoroutineStatus) String Uses

func (g GoroutineStatus) String() string

type Interface Uses

type Interface struct{}

Interface is a Value representing an interface.

type LocalVar Uses

type LocalVar struct {
    Name string
    Var  Var
}

LocalVar is a local variable of a function.

type Map Uses

type Map struct {
    TypeID  uint64
    Address uint64
    Length  uint64 // Number of elements in the map.
}

Map is a Value representing a map.

type Param Uses

type Param struct {
    Name string
    Var  Var
}

Param is a parameter of a function.

type Pointer Uses

type Pointer struct {
    TypeID  uint64 // A type identifier, opaque to the user.
    Address uint64 // The address of the variable.
}

Pointer is a Value representing a pointer. Note that the TypeID field will be the type of the variable being pointed to, not the type of this pointer.

type Program Uses

type Program interface {
    // Open opens a virtual file associated with the process.
    // Names are things like "text", "mem", "fd/2".
    // Mode is one of "r", "w", "rw".
    // Return values are open File and error.
    // When the target binary is re-run, open files are
    // automatically updated to refer to the corresponding
    // file in the new process.
    Open(name string, mode string) (File, error)

    // Run abandons the current running process, if any,
    // and execs a new instance of the target binary file
    // (which may have changed underfoot).
    // Breakpoints and open files are re-established.
    // The call hangs until the program stops executing,
    // at which point it returns the program status.
    // args contains the command-line arguments for the process.
    Run(args ...string) (Status, error)

    // Stop stops execution of the current process but
    // does not kill it.
    Stop() (Status, error)

    // Resume resumes execution of a stopped process.
    // The call hangs until the program stops executing,
    // at which point it returns the program status.
    Resume() (Status, error)

    // Kill kills the current process.
    Kill() (Status, error)

    // Breakpoint sets a breakpoint at the specified address.
    Breakpoint(address uint64) (PCs []uint64, err error)

    // BreakpointAtFunction sets a breakpoint at the start of the specified function.
    BreakpointAtFunction(name string) (PCs []uint64, err error)

    // BreakpointAtLine sets a breakpoint at the specified source line.
    BreakpointAtLine(file string, line uint64) (PCs []uint64, err error)

    // DeleteBreakpoints removes the breakpoints at the specified addresses.
    // Addresses where no breakpoint is set are ignored.
    DeleteBreakpoints(pcs []uint64) error

    // Eval evaluates the expression (typically an address) and returns
    // its string representation(s). Multivalued expressions such as
    // matches for regular expressions return multiple values.
    // TODO: change this to multiple functions with more specific names.
    // Syntax:
    //	re:regexp
    //		Returns a list of symbol names that match the expression
    //	addr:symbol
    //		Returns a one-element list holding the hexadecimal
    //		("0x1234") value of the address of the symbol
    //	val:symbol
    //		Returns a one-element list holding the formatted
    //		value of the symbol
    //	0x1234, 01234, 467
    //		Returns a one-element list holding the name of the
    //		symbol ("main.foo") at that address (hex, octal, decimal).
    Eval(expr string) ([]string, error)

    // Evaluate evaluates an expression.  Accepts a subset of Go expression syntax:
    // basic literals, identifiers, parenthesized expressions, and most operators.
    // Only the len function call is available.
    //
    // The expression can refer to local variables and function parameters of the
    // function where the program is stopped.
    //
    // On success, the type of the value returned will be one of:
    // int8, int16, int32, int64, uint8, uint16, uint32, uint64, float32, float64,
    // complex64, complex128, bool, Pointer, Array, Slice, String, Map, Struct,
    // Channel, Func, or Interface.
    Evaluate(e string) (Value, error)

    // Frames returns up to count stack frames from where the program
    // is currently stopped.
    Frames(count int) ([]Frame, error)

    // VarByName returns a Var referring to a global variable with the given name.
    // TODO: local variables
    VarByName(name string) (Var, error)

    // Value gets the value of a variable by reading the program's memory.
    Value(v Var) (Value, error)

    // MapElement returns Vars for the key and value of a map element specified by
    // a 0-based index.
    MapElement(m Map, index uint64) (Var, Var, error)

    // Goroutines gets the current goroutines.
    Goroutines() ([]*Goroutine, error)
}

Program is the interface to a (possibly remote) program being debugged. The process (if any) and text file associated with it may change during the session, but many resources are associated with the Program rather than process or text file so they persist across debuggging runs.

type Slice Uses

type Slice struct {
    Array
    Capacity uint64
}

Slice is a Value representing a slice.

type Status Uses

type Status struct {
    PC, SP uint64
}

type String Uses

type String struct {
    // Length contains the length of the remote string, in bytes.
    Length uint64
    // String contains the string itself; it may be truncated to fewer bytes than the value of the Length field.
    String string
}

String is a Value representing a string. TODO: a method to access more of a truncated string.

type Struct Uses

type Struct struct {
    Fields []StructField
}

Struct is a Value representing a struct.

type StructField Uses

type StructField struct {
    Name string
    Var  Var
}

StructField represents a field in a struct object.

type Value Uses

type Value interface{}

A value read from a remote program.

type Var Uses

type Var struct {
    TypeID  uint64 // A type identifier, opaque to the user.
    Address uint64 // The address of the variable.
}

A reference to a variable in a program. TODO: handle variables stored in registers

Directories

PathSynopsis
archPackage arch contains architecture-specific definitions.
dwarfPackage dwarf provides access to DWARF debugging information loaded from executable files, as defined in the DWARF 2.0 Standard at http://dwarfstd.org/doc/dwarf-2.0.0.pdf
elfPackage elf implements access to ELF object files.
gosymPackage gosym implements access to the Go symbol and line number tables embedded in Go binaries generated by the gc compilers.
localPackage local provides access to a local program.
machoPackage macho implements access to Mach-O object files.
remotePackage remote provides remote access to a debugproxy server.
serverPackage server provides RPC access to a local program being debugged.
server/protocolPackage protocol defines the types used to represent calls to the debug server.

Package debug imports 3 packages (graph) and is imported by 7 packages. Updated 2017-05-07. Refresh now. Tools for package owners.