truss(1)

NAME

truss – trace system calls

SYNOPSIS

truss [-facedyDHS] [-o file] [-s strsize] [-t expr] -p pid

truss [-facedDHS] [-o file] [-s strsize] [-t expr] command [args]

truss -t

DESCRIPTION

The truss utility traces the system calls called by the specified process or program. Output is to the specified output file, or standard error by default. It does this by stopping and restarting the process being monitored via ptrace(2).

By default, truss enters the capability mode (see capsicum(4)) after opening the output file and creating and attaching to the target process. An error to enter the mode is not fatal, but a warning is issued to the standard error.

The options are as follows:

-f

Trace descendants of the original traced process created by fork(2), vfork(2), etc. To distinguish events between processes, the process ID (PID) of the process is included in the output of each event.

-a

Show the argument strings that are passed in each execve(2) system call.

-c

Do not display individual system calls or signals. Instead, before exiting, print a summary containing for each system call: the total system time used, the number of times the call was invoked, and the number of times the call returned with an error.

-e

Show the environment strings that are passed in each execve(2) system call.

-d

Include timestamps in the output showing the time elapsed since the trace was started.

-D

Include timestamps in the output showing the time elapsed since the last recorded event.

-H

Include the thread ID of in the output of each event.

-S

Do not display information about signals received by the process. (Normally, truss displays signal as well as system call events.)

-y

Use the ‘classic’ combination of ptrace(2) and waitpid(2) system calls to control the traced processes, instead of the process descriptors and kqueue PROCDESC filter (see pdfork(2) and kqueue(2.)) Do not try to enter capability mode.

-o file

Print the output to the specified file instead of standard error.

-s strsize

Display strings using at most strsize characters. If the buffer is larger, “...” will be displayed at the end of the string. The default strsize is 32.

-t expr

Report only the system calls selected by expr, a comma-separated list of terms. Whatever follows -t is taken to be the expr, so one must be given; the sole exception is the third form shown above, ‘truss -t’ with nothing after it, which prints the groups described below and exits. That is not the same as giving an empty expr: ‘truss -t ""’ is an expression with no terms in it, and so filters nothing.

Each term takes one of three forms:

name

The name of a system call, as truss prints it, for example ‘read’. A name may also contain the wildcards ‘*’, ‘?’ and ‘[]’ described in fnmatch(3), in which case it selects every system call whose name it matches: ‘read*’ selects read(2), readv(2) and readlink(2) alike.

number

A system call number in decimal, for example ‘3’. The number is the one the ABI of the traced process uses, so ‘3’ selects read(2) from a native process but close() from a Linux one.

@group

One of the groups of related system calls listed below, for example ‘@file’.

A term prefixed with ‘!’ excludes the system calls it matches instead of including them. The ‘!’ applies only to the term it prefixes, not to the terms that follow it.

An expression whose terms are all negated subtracts from the set of every system call; any other expression selects from an empty set. Terms are applied in the order they are given, and the last one to match a system call decides whether it is reported. Repeating -t appends to the expression rather than replacing it, so that -t a -t b and -t a,b are equivalent. An empty term is ignored, which is why an empty expr filters nothing, and why a stray comma is not an error.

The groups are:

@all

every system call

@creds

get or set process credentials

@desc

operate on a file descriptor

@file

operate on a pathname

@ipc

System V and POSIX IPC

@memory

memory mapping and locking

@net

network and socket operations

@none

no system call

@proc

process and thread lifecycle

@read

read data from a descriptor

@signal

signal delivery and handling

@time

clocks, timers and sleeping

@write

write data to a descriptor

A group is itself defined by an expression of the same form as expr, so a group may name other groups and may exclude as well as include: @desc is defined to include @read and @write, and @none is defined as ‘!*’.

A system call is matched both under the name truss displays for it and under that name with any prefix naming a compatibility layer or a non-native ABI removed, so that -t @file selects ‘compat11.stat’ and ‘linux_newstat’ as well as ‘stat’.

A name or pattern that matches no system call of any ABI that truss understands is reported with a warning, since it is almost always a typo, but it is not an error: the term is kept and simply never matches. A number is not checked against any table, as a process may issue any system call number the kernel can hold and truss reports the attempt whether or not a system call is implemented behind it; only a number too large to be one at all is rejected. An unknown group is an error.

-p pid

Follow the process specified by pid instead of a new command.

command [args]

Execute command and trace the system calls of it. (The -p and command options are mutually exclusive.)

EXAMPLES

Follow the system calls used in echoing "hello":

$ truss /bin/echo hello

Do the same, but put the output into a file:

$ truss -o /tmp/truss.out /bin/echo hello

Follow an already-running process:

$ truss -p 34

List the groups that -t understands:

$ truss -t

Show only the file and network activity of a command:

$ truss -t @file,@net fetch https://www.freebsd.org/

Show everything a command does except its memory management:

$ truss -t '!@memory' make buildworld

Show the descriptor activity of a running process apart from the data transfers themselves:

$ truss -t '@desc,!@read,!@write' -p 34

Count the readlink(2) and readlinkat(2) calls made while starting a program:

$ truss -c -t 'readlink*' /bin/ls

SEE ALSO

dtrace(1), kdump(1), ktrace(1), pdfork(2), pdtrace(2), ptrace(2), utrace(2), fnmatch(3), sysdecode(3), capsicum(4)

HISTORY

The truss command was written by Sean Eric Fagan for FreeBSD. It was modeled after similar commands available for System V Release 4 and SunOS.