blob: d27da54f38b3787d1f5f31b23ba0beb2b9320a5a [file] [log] [blame]
// Copyright 2014 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// Package program provides the portable interface to a program being debugged.
package program
import (
// 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 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)
// SetArguments sets the command-line arguments for
// the next running of the target binary, excluding the
// target's binary name. That is, while debugging the
// echo command, to prepare a run of "echo hi" call
// SetArguments("hi")
SetArguments(args ...string)
// 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 flag specifies whether to run the program (true)
// or stop it before it executes any instructions (false).
// The call hangs until the program stops executing,
// at which point it returns the program status.
Run(start bool) (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)
// TODO: Step(). Where does the granularity happen,
// on the proxy end or the debugging control end?
// Kill kills the current process.
Kill() (Status, error)
// Breakpoint sets a breakpoint at the specified address.
// When the target binary is re-run, breakpoints are
// automatically re-established in the new process by
// re-evaluating the address.
// Address syntax:
// "main.main" Start of function
// "main.go:23" Line number
// (more to follow; may want an expression grammar)
// It is OK if two breakpoints evaluate to the same PC. (TODO: verify.)
Breakpoint(address string) error
// DeleteBreakpoint removes the breakpoint at the specified
// address.
DeleteBreakpoint(address string) error
// Eval evaluates the expression (typically an address) and returns
// its string representation.
Eval(expr string) (string, error)
// 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 File interface {
type Status struct {
// TBD