strace

package
v0.17.0 Latest Latest
Warning

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

Go to latest
Published: May 18, 2026 License: BSD-3-Clause Imports: 17 Imported by: 0

Documentation

Overview

Package strace traces Linux process events.

An straced process will emit events for syscalls, signals, exits, and new children.

Index

Constants

View Source
const (
	// ExecMaxTotalSize is the maximum length of all argv and envv entries.
	//
	// N.B. The behavior here is different than Linux. Linux provides a limit on
	// individual arguments of 32 pages, and an aggregate limit of at least 32 pages
	// but otherwise bounded by min(stack size / 4, 8 MB * 3 / 4). We don't implement
	// any behavior based on the stack size, and instead provide a fixed hard-limit of
	// 2 MB (which should work well given that 8 MB stack limits are common).
	ExecMaxTotalSize = 2 * 1024 * 1024

	// ExecMaxElemSize is the maximum length of a single argv or envv entry.
	ExecMaxElemSize = 32 * 4096
)

From gvisor:

View Source
const DefaultLogMaximumSize = 1024

DefaultLogMaximumSize is the default LogMaximumSize.

Variables

View Source
var EventMaximumSize uint

EventMaximumSize determines the maximum size for data blobs (read, write, etc.) sent over the event channel. Default is 0 because most clients cannot do anything useful with binary text dump of byte array arguments.

View Source
var LogMaximumSize uint = DefaultLogMaximumSize

LogMaximumSize determines the maximum display size for data blobs (read, write, etc.).

Functions

func ByName added in v0.17.0

func ByName(name string) (uintptr, error)

ByName returns a system call number, given a name. It uses a map that is filled in dynamically.

func ByNumber added in v0.17.0

func ByNumber(sysno uintptr) (string, error)

ByNumber returns a system call name given a number.

func CaptureAddress

func CaptureAddress(t Task, addr Addr, addrlen uint32) ([]byte, error)

CaptureAddress pulls a socket address from the process as a byte slice. It returns any errors.

func New

func New(c *exec.Cmd, secComp bool, recordCallback ...EventCallback) error

New traces `c` and any children c clones with the option to enable seccomp.

func ReadString added in v0.7.0

func ReadString(t Task, addr Addr, maximum int) (string, error)

ReadString reads a null-terminated string from the process at Addr and any errors.

func ReadStringVector added in v0.7.0

func ReadStringVector(t Task, addr Addr, maxsize, maxno int) ([]string, error)

ReadStringVector takes an address, max string size, and max number of string to read, and returns a string slice or error.

func Strace added in v0.7.0

func Strace(c *exec.Cmd, out io.Writer) error

Strace traces and prints process events for `c` and its children to `out`.

func SysCallEnter added in v0.7.0

func SysCallEnter(t Task, s *SyscallEvent) string

SysCallEnter is called each time a system call enter event happens.

func SysCallExit added in v0.7.0

func SysCallExit(t Task, s *SyscallEvent) string

SysCallExit is called each time a system call exit event happens.

func Trace added in v0.7.0

func Trace(c *exec.Cmd, recordCallback ...EventCallback) error

Trace traces `c` and any children c clones.

Only one trace can be active per process.

recordCallback is called every time a process event happens with the process in a stopped state.

Types

type Addr

type Addr uintptr

Addr is an address for use in strace I/O

type Address

type Address string

Address is a byte slice cast as a string that represents the address of a network node. Or, in the case of unix endpoints, it may represent a path.

type EventCallback added in v0.7.0

type EventCallback func(t Task, record *TraceRecord) error

EventCallback is a function called on each event while the subject process is stopped.

func PrintTraces added in v0.7.0

func PrintTraces(w io.Writer) EventCallback

PrintTraces prints every trace event to w.

func RecordTraces added in v0.7.0

func RecordTraces(c chan<- *TraceRecord) EventCallback

RecordTraces sends each event on c.

type EventType

type EventType int

EventType describes a process event.

const (
	// Unknown is for events we do not know how to interpret.
	Unknown EventType = 0x0

	// SyscallEnter is the event for a process calling a syscall.  Event
	// Args will contain the arguments sent by the userspace process.
	//
	// ptrace calls this a syscall-enter-stop.
	SyscallEnter EventType = 0x2

	// SyscallExit is the event for the kernel returning a syscall. Args
	// will contain the arguments as returned by the kernel.
	//
	// ptrace calls this a syscall-exit-stop.
	SyscallExit EventType = 0x3

	// SignalExit means the process has been terminated by a signal.
	SignalExit EventType = 0x4

	// Exit means the process has exited with an exit code.
	Exit EventType = 0x5

	// SignalStop means the process was stopped by a signal.
	//
	// ptrace calls this a signal-delivery-stop.
	SignalStop EventType = 0x6

	// NewChild means the process created a new child thread or child
	// process via fork, clone, or vfork.
	//
	// ptrace calls this a PTRACE_EVENT_(FORK|CLONE|VFORK).
	NewChild EventType = 0x7
)

type ExitEvent added in v0.7.0

type ExitEvent struct {
	// WaitStatus is the exit status.
	WaitStatus unix.WaitStatus
}

ExitEvent is emitted when the process exits regularly using exit_group(2).

type FormatSpecifier

type FormatSpecifier int

FormatSpecifier values describe how an individual syscall argument should be formatted.

const (
	// Hex is just a hexadecimal number.
	Hex FormatSpecifier = iota

	// Oct is just an octal number.
	Oct

	// ReadBuffer is a buffer for a read-style call. The syscall return
	// value is used for the length.
	//
	// Formatted after syscall execution.
	ReadBuffer

	// WriteBuffer is a buffer for a write-style call. The following arg is
	// used for the length.
	//
	// Contents omitted after syscall execution.
	WriteBuffer

	// ReadIOVec is a pointer to a struct iovec for a writev-style call.
	// The following arg is used for the length. The return value is used
	// for the total length.
	//
	// Complete contents only formatted after syscall execution.
	ReadIOVec

	// WriteIOVec is a pointer to a struct iovec for a writev-style call.
	// The following arg is used for the length.
	//
	// Complete contents only formatted before syscall execution, omitted
	// after.
	WriteIOVec

	// IOVec is a generic pointer to a struct iovec. Contents are not dumped.
	IOVec

	// SendMsgHdr is a pointer to a struct msghdr for a sendmsg-style call.
	// Contents formatted only before syscall execution, omitted after.
	SendMsgHdr

	// RecvMsgHdr is a pointer to a struct msghdr for a recvmsg-style call.
	// Contents formatted only after syscall execution.
	RecvMsgHdr

	// Path is a pointer to a char* path.
	Path

	// PostPath is a pointer to a char* path, formatted after syscall
	// execution.
	PostPath

	// ExecveStringVector is a NULL-terminated array of strings. Enforces
	// the maximum execve array length.
	ExecveStringVector

	// PipeFDs is an array of two FDs, formatted after syscall execution.
	PipeFDs

	// Uname is a pointer to a struct uname, formatted after syscall execution.
	Uname

	// Stat is a pointer to a struct stat, formatted after syscall execution.
	Stat

	// SockAddr is a pointer to a struct sockaddr. The following arg is
	// used for length.
	SockAddr

	// PostSockAddr is a pointer to a struct sockaddr, formatted after
	// syscall execution. The following arg is a pointer to the socklen_t
	// length.
	PostSockAddr

	// SockLen is a pointer to a socklen_t, formatted before and after
	// syscall execution.
	SockLen

	// SockFamily is a socket protocol family value.
	SockFamily

	// SockType is a socket type and flags value.
	SockType

	// SockProtocol is a socket protocol value. Argument n-2 is the socket
	// protocol family.
	SockProtocol

	// SockFlags are socket flags.
	SockFlags

	// Timespec is a pointer to a struct timespec.
	Timespec

	// PostTimespec is a pointer to a struct timespec, formatted after
	// syscall execution.
	PostTimespec

	// UTimeTimespec is a pointer to a struct timespec. Formatting includes
	// UTIME_NOW and UTIME_OMIT.
	UTimeTimespec

	// ItimerVal is a pointer to a struct itimerval.
	ItimerVal

	// PostItimerVal is a pointer to a struct itimerval, formatted after
	// syscall execution.
	PostItimerVal

	// ItimerSpec is a pointer to a struct itimerspec.
	ItimerSpec

	// PostItimerSpec is a pointer to a struct itimerspec, formatted after
	// syscall execution.
	PostItimerSpec

	// Timeval is a pointer to a struct timeval, formatted before and after
	// syscall execution.
	Timeval

	// Utimbuf is a pointer to a struct utimbuf.
	Utimbuf

	// Rusage is a struct rusage, formatted after syscall execution.
	Rusage

	// CloneFlags are clone(2) flags.
	CloneFlags

	// OpenFlags are open(2) flags.
	OpenFlags

	// Mode is a mode_t.
	Mode

	// FutexOp is the futex(2) operation.
	FutexOp

	// PtraceRequest is the ptrace(2) request.
	PtraceRequest

	// ItimerType is an itimer type (ITIMER_REAL, etc).
	ItimerType
)

Valid FormatSpecifiers.

Unless otherwise specified, values are formatted before syscall execution and not updated after syscall execution (the same value is output).

type FullAddress

type FullAddress struct {
	// Addr is the network address.
	Addr Address

	// Port is the transport port.
	//
	// This may not be used by all endpoint types.
	Port uint16
}

FullAddress is the network address and port

func GetAddress

func GetAddress(addr []byte) (*FullAddress, error)

GetAddress reads an sockaddr struct from the given address and converts it to the FullAddress format. It supports AF_UNIX, AF_INET and AF_INET6 addresses.

func (*FullAddress) String added in v0.17.0

func (a *FullAddress) String() string

String implements String

type NewChildEvent added in v0.7.0

type NewChildEvent struct {
	PID int
}

NewChildEvent is emitted when a clone/fork/vfork syscall is done.

type SaneUtsname added in v0.7.0

type SaneUtsname struct {
	Sysname    string
	Nodename   string
	Release    string
	Version    string
	Machine    string
	Domainname string
}

SaneUtsname is an utsname without the weird partially-filled []byte

func SaneUname added in v0.7.0

func SaneUname(u unix.Utsname) SaneUtsname

SaneUname returns a SaneUtsname, i.e. a Unix Time Sharing name without the weird partially filled []byte

type SignalEvent added in v0.7.0

type SignalEvent struct {
	// Signal is the signal number.
	Signal unix.Signal
}

SignalEvent is a signal that was delivered to the process.

type SyscallArgument

type SyscallArgument struct {
	// Prefer to use accessor methods instead of 'Value' directly.
	Value uintptr
}

SyscallArgument is an argument supplied to a syscall implementation. The methods used to access the arguments are named after the ***C type name*** and they convert to the closest Go type available. For example, Int() refers to a 32-bit signed integer argument represented in Go as an int32.

Using the accessor methods guarantees that the conversion between types is correct, taking into account size and signedness (i.e., zero-extension vs signed-extension).

func (SyscallArgument) Int

func (a SyscallArgument) Int() int32

Int returns the int32 representation of a 32-bit signed integer argument.

func (SyscallArgument) Int64

func (a SyscallArgument) Int64() int64

Int64 returns the int64 representation of a 64-bit signed integer argument.

func (SyscallArgument) ModeT

func (a SyscallArgument) ModeT() uint

ModeT returns the int representation of a mode_t argument.

func (SyscallArgument) Pointer

func (a SyscallArgument) Pointer() Addr

Pointer returns the usermem.Addr representation of a pointer argument.

func (SyscallArgument) SizeT

func (a SyscallArgument) SizeT() uint

SizeT returns the uint representation of a size_t argument.

func (SyscallArgument) Uint

func (a SyscallArgument) Uint() uint32

Uint returns the uint32 representation of a 32-bit unsigned integer argument.

func (SyscallArgument) Uint64

func (a SyscallArgument) Uint64() uint64

Uint64 returns the uint64 representation of a 64-bit unsigned integer argument.

type SyscallArguments

type SyscallArguments [6]SyscallArgument

SyscallArguments represents the set of arguments passed to a syscall.

type SyscallEvent added in v0.7.0

type SyscallEvent struct {
	// Regs are the process's registers as they were when the event was
	// recorded.
	Regs unix.PtraceRegs

	// Sysno is the syscall number.
	Sysno int

	// Args are the arguments to the syscall.
	Args SyscallArguments

	// Ret is the return value of the syscall. Only populated on
	// SyscallExit.
	Ret [2]SyscallArgument

	// Errno is an errno, if there was on in Ret. Only populated on
	// SyscallExit.
	Errno unix.Errno

	// Duration is the duration from enter to exit for this particular
	// syscall. Only populated on SyscallExit.
	Duration time.Duration
}

SyscallEvent is populated for both SyscallEnter and SyscallExit event types.

func (*SyscallEvent) FillArgs added in v0.7.0

func (s *SyscallEvent) FillArgs()

FillArgs pulls the correct registers to populate system call arguments and the system call number into a TraceRecord. Note that the system call number is not technically an argument. This is good, in a sense, since it makes the function arguments end up in "the right place" from the point of view of the caller. The performance improvement is negligible, as you can see by a look at the GNU runtime.

func (*SyscallEvent) FillRet added in v0.7.0

func (s *SyscallEvent) FillRet()

FillRet fills the TraceRecord with the result values from the registers.

type SyscallInfo

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

SyscallInfo captures the name and printing format of a syscall.

type SyscallMap

type SyscallMap map[uintptr]SyscallInfo

SyscallMap maps syscalls into names and printing formats.

type Task added in v0.7.0

type Task interface {
	// Read reads from the process at Addr to the interface{}
	// and returns a byte count and error.
	Read(addr Addr, v any) (int, error)

	// Name is a human-readable process identifier. E.g. PID or argv[0].
	Name() string
}

Task is a Linux process.

type TraceError added in v0.7.0

type TraceError struct {
	// PID is the process ID associated with the error.
	PID int
	Err error
}

TraceError is returned when something failed on a specific process.

func (*TraceError) Error added in v0.7.0

func (t *TraceError) Error() string

type TraceRecord

type TraceRecord struct {
	PID   int
	Time  time.Time
	Event EventType

	Syscall    *SyscallEvent
	SignalExit *SignalEvent
	SignalStop *SignalEvent
	Exit       *ExitEvent
	NewChild   *NewChildEvent
}

TraceRecord has information about a process event.

Directories

Path Synopsis
internal
abi
Package abi describes the interface between a kernel and userspace.
Package abi describes the interface between a kernel and userspace.
binary
Package binary translates between select fixed-sized types and a binary representation.
Package binary translates between select fixed-sized types and a binary representation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL