ptrace

Documentation

Overview

Package ptrace provides a ptrace-based implementation of the platform interface. This is useful for development and testing purposes primarily, and runs on stock kernels without special permissions.

In a nutshell, it works as follows:

The creation of a new address space creates a new child process with a single thread which is traced by a single goroutine.

A context is just a collection of temporary variables. Calling Switch on a context does the following:

Locks the runtime thread.

Looks up a traced subprocess thread for the current runtime thread. If
none exists, the dedicated goroutine is asked to create a new stopped
thread in the subprocess. This stopped subprocess thread is then traced
by the current thread and this information is stored for subsequent
switches.

The context is then bound with information about the subprocess thread
so that the context may be appropriately interrupted via a signal.

The requested operation is performed in the traced subprocess thread
(e.g. set registers, execute, return).

Lock order:

 subprocess.mu
	context.mu

Index

• Constants
• type PTrace
  • func New() (*PTrace, error)
  • func (*PTrace) CooperativelySchedulesAddressSpace() bool
  • func (*PTrace) MapUnit() uint64
  • func (*PTrace) MaxUserAddress() hostarch.Addr
  • func (p *PTrace) NewAddressSpace(any) (platform.AddressSpace, <-chan struct{}, error)
  • func (*PTrace) NewContext(ctx pkgcontext.Context) platform.Context
  • func (*PTrace) SupportsAddressSpaceIO() bool
  • func (*PTrace) SyscallFilters() seccomp.SyscallRules

Constants

const (
	ERESTARTSYS    = unix.Errno(512)
	ERESTARTNOINTR = unix.Errno(513)
	ERESTARTNOHAND = unix.Errno(514)
)

Linux kernel errnos which "should never be seen by user programs", but will be revealed to ptrace syscall exit tracing.

These constants are only used in subprocess.go.

Types

type PTrace

type PTrace struct {
	platform.MMapMinAddr
	platform.NoCPUPreemptionDetection
	platform.UseHostGlobalMemoryBarrier
	platform.DoesNotOwnPageTables
}

PTrace represents a collection of ptrace subprocesses.

func New

func New() (*PTrace, error)

New returns a new ptrace-based implementation of the platform interface.

func (*PTrace) CooperativelySchedulesAddressSpace

func (*PTrace) CooperativelySchedulesAddressSpace() bool

CooperativelySchedulesAddressSpace implements platform.Platform.CooperativelySchedulesAddressSpace.

func (*PTrace) MapUnit

func (*PTrace) MapUnit() uint64

MapUnit implements platform.Platform.MapUnit.

func (*PTrace) MaxUserAddress

func (*PTrace) MaxUserAddress() hostarch.Addr

MaxUserAddress returns the first address that may not be used by user applications.

func (*PTrace) NewAddressSpace

func (p *PTrace) NewAddressSpace(any) (platform.AddressSpace, <-chan struct{}, error)

NewAddressSpace returns a new subprocess.

func (*PTrace) NewContext

func (*PTrace) NewContext(ctx pkgcontext.Context) platform.Context

NewContext implements platform.Platform.NewContext.

func (*PTrace) SupportsAddressSpaceIO

func (*PTrace) SupportsAddressSpaceIO() bool

SupportsAddressSpaceIO implements platform.Platform.SupportsAddressSpaceIO.

func (*PTrace) SyscallFilters

func (*PTrace) SyscallFilters() seccomp.SyscallRules

SyscallFilters returns syscalls made exclusively by the ptrace platform.