v0.9.0 Latest Latest

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

Go to latest
Published: Jul 29, 2022 License: BSD-3-Clause Imports: 17 Imported by: 30



Package strace traces Linux process events.

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



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.


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.).


func ByName added in v0.9.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.9.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 ReadString

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

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

func ReadStringVector

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

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

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

func SysCallEnter

func SysCallEnter(t Task, s *SyscallEvent) string

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

func SysCallExit

func SysCallExit(t Task, s *SyscallEvent) string

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

func Trace

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.


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

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

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

func PrintTraces

func PrintTraces(w io.Writer) EventCallback

PrintTraces prints every trace event to w.

func RecordTraces

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

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.

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

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

	// 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.

	// 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.

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

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

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

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

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

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

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

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

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

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

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

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

	// SockFamily is a socket protocol family value.

	// SockType is a socket type and flags value.

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

	// SockFlags are socket flags.

	// Timespec is a pointer to a struct timespec.

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

	// UTimeTimespec is a pointer to a struct timespec. Formatting includes

	// ItimerVal is a pointer to a struct itimerval.

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

	// ItimerSpec is a pointer to a struct itimerspec.

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

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

	// Utimbuf is a pointer to a struct utimbuf.

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

	// CloneFlags are clone(2) flags.

	// OpenFlags are open(2) flags.

	// Mode is a mode_t.

	// FutexOp is the futex(2) operation.

	// PtraceRequest is the ptrace(2) request.

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

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(t Task, 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.

type NewChildEvent

type NewChildEvent struct {
	PID int

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

type SaneUtsname

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

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

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

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

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

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

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

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

Task is a Linux process.

type TraceError

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

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.


Path Synopsis
Package abi describes the interface between a kernel and userspace.
Package abi describes the interface between a kernel and userspace.
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