ptrace

Documentation

Overview

Package ptrace provides the program traceing by ptrace syscall.

Index

• Constants
• Variables
• func Attach(pid int) (err error)
• func Cont(pid, signal int) (err error)
• func Detach(pid, sig int) (err error)
• func DumpRegs(regs *unix.PtraceRegs) string
• func GetEventMsg(pid int) (msg uintptr, err error)
• func GetFPRegs(pid int, regsout *unix.PtraceRegs) (err error)
• func GetRegs(pid int, regsout *unix.PtraceRegs) (err error)
• func Interrupt(pid int) (err error)
• func PeekData(pid int, addr uintptr, out []byte) (count int, err error)
• func PeekText(pid int, addr uintptr, out []byte) (count int, err error)
• func PeekUser(pid int, addr uintptr, out []byte) (count int, err error)
• func PokeData(pid int, addr uintptr, data []byte) (count int, err error)
• func PokeText(pid int, addr uintptr, data []byte) (count int, err error)
• func PokeUser(pid int, addr uintptr, data []byte) (count int, err error)
• func ProcessVMReadv(pid int, addr *uintptr, data []byte) (int, error)
• func ProcessVMWritev(pid int, addr *uintptr, data []byte) (int, error)
• func ReadXstate(xstateArgs []byte, readLegacy bool, regset *Xstate) error
• func RegisterLogger(logger logr.Logger)
• func Seize(pid int) (err error)
• func SetFPRegs(pid int, regs *unix.PtraceRegs) (err error)
• func SetOptions(pid, options int) (err error)
• func SetRegs(pid int, regs *unix.PtraceRegs) (err error)
• func SingleStep(pid int) (err error)
• func Syscall(pid, signal int) (err error)
• type FPRegs
• type Thread
  • func (t *Thread) GetEventMessage() (uintptr, error)
  • func (t *Thread) GetRegs(regs *unix.PtraceRegs) error
  • func (t *Thread) Wait(outcome WaitOutcome) unix.Signal
• type WaitOutcome
• type Xstate
  • func GetRegset(tid int) (regset Xstate, errno error)

Constants

const (
	X86_XSTATE_MAX_SIZE = 2688
	NT_X86_XSTATE       = 0x202

	XSAVE_HDR_OFFSET             = 512
	XSAVE_HDR_SIZE               = 64
	XSAVE_EXTENDED_REGION_OFFSET = 576
	XSAVE_SSE_REGION_LEN         = 416
)

Variables

var (
	// StubStart is the link address for our stub, and determines the
	// maximum user address. This is valid only after a call to stubInit.
	//
	// We attempt to link the stub here, and adjust downward as needed.
	StubStart uintptr = stubInitAddress

	// StubEnd is the first byte past the end of the stub, as with
	// stubStart this is valid only after a call to stubInit.
	StubEnd uintptr
)

Functions

func Attach

func Attach(pid int) (err error)

Attach attachs to the process specified in pid, making it a tracee of the calling process.

func Cont

func Cont(pid, signal int) (err error)

Cont restarts the stopped tracee process.

func Detach

func Detach(pid, sig int) (err error)

Detach restarts the stopped tracee as for PTRACE_CONT, but first detach from it.

func DumpRegs

func DumpRegs(regs *unix.PtraceRegs) string

DumpRegs dumps regs.

func GetEventMsg

func GetEventMsg(pid int) (msg uintptr, err error)

GetEventMsg retrieves a message about the ptrace event that just happened, placing it at the address data in the tracer.

func GetFPRegs

func GetFPRegs(pid int, regsout *unix.PtraceRegs) (err error)

GetFPRegs copies the tracee's floating-point registers, respectively, to the address data in the tracer.

func GetRegs

func GetRegs(pid int, regsout *unix.PtraceRegs) (err error)

GetRegs copies the tracee's general-purpose registers, respectively, to the address data in the tracer.

func Interrupt

func Interrupt(pid int) (err error)

Interrupt stops a tracee.

func PeekData

func PeekData(pid int, addr uintptr, out []byte) (count int, err error)

PeekData reads a word at the address addr in the tracee's memory, returning the word as the result of the ptrace call.

func PeekText

func PeekText(pid int, addr uintptr, out []byte) (count int, err error)

PeekText reads a word at the address addr in the tracee's memory, returning the word as the result of the ptrace call.

func PeekUser

func PeekUser(pid int, addr uintptr, out []byte) (count int, err error)

PeekUser reads a word at offset addr in the tracee's USER area, which holds the registers and other information about the process.

The word is returned as the result of the ptrace call.

func PokeData

func PokeData(pid int, addr uintptr, data []byte) (count int, err error)

PokeData copies the word data to the address addr in the tracee's memory.

func PokeText

func PokeText(pid int, addr uintptr, data []byte) (count int, err error)

PokeText copies the word data to the address addr in the tracee's memory.

func PokeUser

func PokeUser(pid int, addr uintptr, data []byte) (count int, err error)

PokeUser copies the word data to offset addr in the tracee's USER area.

func ProcessVMReadv

func ProcessVMReadv(pid int, addr *uintptr, data []byte) (int, error)

ProcessVMReadv transfers data from the remote tid process to the local process.

func ProcessVMWritev

func ProcessVMWritev(pid int, addr *uintptr, data []byte) (int, error)

ProcessVMWritev transfers data from the local process to the remote pid process.

func ReadXstate

func ReadXstate(xstateArgs []byte, readLegacy bool, regset *Xstate) error

ReadXstate reads a byte array containing an XSAVE area into register set.

If readLegacy is true regset.PtraceFpRegs will be filled with the contents of the legacy region of the XSAVE area. See Section 13.1 (and following) of Intel® 64 and IA-32 Architectures Software Developer’s Manual, Volume 1: Basic Architecture.

func RegisterLogger

func RegisterLogger(logger logr.Logger)

RegisterLogger registers a logger on ptrace pkg.

func Seize

func Seize(pid int) (err error)

Seize attachs to the process specified in pid, making it a tracee of the calling process.

func SetFPRegs

func SetFPRegs(pid int, regs *unix.PtraceRegs) (err error)

SetFPRegs modifies the tracee's floating-point registers, respectively, from the address data in the tracer.

func SetOptions

func SetOptions(pid, options int) (err error)

SetOptions sets ptrace options from data. data is interpreted as a bit mask of options.

func SetRegs

func SetRegs(pid int, regs *unix.PtraceRegs) (err error)

SetRegs modifies the tracee's general-purpose registers, respectively, from the address data in the tracer.

func SingleStep

func SingleStep(pid int) (err error)

SingleStep restarts the stopped tracee as for PTRACE_CONT, but arrange for the tracee to be stopped at the next entry to or exit from a system call, or after execution of a single instruction, respectively.

func Syscall

func Syscall(pid, signal int) (err error)

Syscall restarts the stopped tracee as for PTRACE_CONT, but arrange for the tracee to be stopped at the next entry to or exit from a system call, or after execution of a single instruction, respectively.

Types

type FPRegs

type FPRegs struct {
	Cwd      uint16     // Control Word
	Swd      uint16     // Status Word
	Ftw      uint16     // Tag Word
	Fop      uint16     // Last Instruction Opcode
	Rip      uint64     // Instruction Pointer
	Rdp      uint64     // Data Pointer
	Mxcsr    uint32     // MXCSR Register State
	MxcrMask uint32     // MXCR Mask
	StSpace  [32]uint32 // 8*16 bytes for each FP-reg = 128 bytes
	XMMSpace [256]byte  // 16*16 bytes for each XMM-reg = 256 bytes
	// contains filtered or unexported fields
}

FPRegs represents a user_fpregs_struct in /usr/include/x86_64-linux-gnu/sys/user.h.

type Thread

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

Thread is a traced thread; it is a thread identifier.

This is a convenience type for defining ptrace operations.

func (*Thread) GetEventMessage

func (t *Thread) GetEventMessage() (uintptr, error)

GetEventMessage retrieves a message about the ptrace event that just happened.

func (*Thread) GetRegs

func (t *Thread) GetRegs(regs *unix.PtraceRegs) error

GetRegs gets the general purpose register set.

func (*Thread) Wait

func (t *Thread) Wait(outcome WaitOutcome) unix.Signal

Wait waits for a stop event.

type WaitOutcome

type WaitOutcome int

WaitOutcome is used for wait below.

const (
	// Stopped indicates that the process was Stopped.
	Stopped WaitOutcome = iota

	// Killed indicates that the process was Killed.
	Killed
)

type Xstate

type Xstate struct {
	FPRegs
	Xsave    []byte    // raw xsave area
	AVXState bool      // contains AVX state
	YMMSpace [256]byte // YMM register space
}

Xstate represents amd64 XSAVE area.

See Section 13.1 (and following) of Intel® 64 and IA-32 Architectures Software Developer’s Manual, Volume 1: Basic Architecture.

func GetRegset

func GetRegset(tid int) (regset Xstate, errno error)

GetRegset returns floating point registers of the specified thread using PTRACE.

See amd64_linux_fetch_inferior_registers in gdb/amd64-linux-nat.c.html and amd64_supply_xsave in gdb/amd64-tdep.c.html and Section 13.1 (and following) of Intel® 64 and IA-32 Architectures Software Developer’s Manual, Volume 1: Basic Architecture.