strace

package
v0.14.0 Latest Latest
Warning

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

 Go to latest Published: Feb 27, 2024 License: BSD-3-Clause Imports: 17 Imported by: 29

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

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 

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

func (a *FullAddress) String() string

String implements String

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.

Source Files

View all Source files

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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.