xref: /netbsd-src/external/cddl/dtracetoolkit/dist/Man/man1m/dtruss.1m (revision 2680eae4a73e801854fdb29d1afcc6b1e20a8a02)
1.\" $NetBSD: dtruss.1m,v 1.6 2020/06/26 15:45:18 wiz Exp $
2.Dd June 25, 2020
3.Dt DTRUSS 1
4.Os
5.Sh NAME
6.Nm dtruss
7.Nd process syscall details. Uses DTrace
8.Sh SYNOPSIS
9.Nm
10.Op Fl acdeflhLos
11.Op Fl t Ar syscall
12.Op Fl p Ar PID | Fl n Ar name | command
13.Sh DESCRIPTION
14.Nm
15prints details on process system calls.
16It is like a DTrace version of truss, and has been designed to be less
17intrusive than truss.
18.Pp
19Of particular interest is the elapsed times and on cpu times, which can
20identify both system calls that are slow to complete, and those which are
21consuming CPU cycles.
22.Pp
23Since this uses DTrace, only the root user or users with the dtrace_kernel
24privilege can run this command.
25.Bl -tag -width Fl
26.It Fl a
27print all details
28.It Fl b Ar bufsize
29dynamic variable buffer size.
30Increase this if you notice dynamic variable drop errors.
31The default is
32.Ql "4m"
33for 4\~megabytes per CPU.
34.It Fl c
35print system call counts
36.It Fl d
37print relative timestamps, us (microseconds)
38.It Fl e
39print elapsed times, us
40.It Fl f
41follow children as they are forked
42.It Fl L
43don't print pid/lwpid per line
44.It Fl l
45force printing of pid/lwpid per line
46.It Fl n Ar name
47examine processes with this name
48.It Fl o
49print on-cpu times, us
50.It Fl p Ar PID
51examine this PID
52.It Fl s
53print stack backtraces
54.It Fl t Ar syscall
55examine this syscall only
56.El
57.Bl -column "SYSCALL(args)"
58.It Sy Field      Ta Sy Description
59.It PID/LWPID     Ta Process ID\|/\|Lightweight Process ID
60.It RELATIVE      Ta relative timestamps to the start of the thread, us
61.It ELAPSD        Ta elapsed time for this system call, us
62.It CPU           Ta on-cpu time for this system call, us
63.It SYSCALL(args) Ta system call name, with arguments (some may be evaluated)
64.El
65.Sh EXAMPLES
66run and examine the
67.Ql df -h
68command
69.Pp
70.Dl Ic dtruss df -h
71.Pp
72examine PID 1871
73.Pp
74.Dl Ic dtruss -p 1871
75.Pp
76examine all processes called "tar"
77.Pp
78.Dl Ic dtruss -n tar
79.Pp
80run
81.Ql test.sh
82and follow children
83.Pp
84.Dl Ic dtruss -f test.sh
85.Pp
86run the
87.Ql date
88command and print elapsed and on cpu times,
89.Pp
90.Dl Ic dtruss -eo date
91.Ss STABILITY
92stable \(em needs the syscall provider.
93.Ss DOCUMENTATION
94See the DTraceToolkit for further documentation under the Docs directory.
95The DTraceToolkit docs may include full worked examples with verbose
96descriptions explaining the output.
97.Sh EXIT
98dtruss will run forever until Ctrl\-C is hit, or if a command was
99executed dtruss will finish when the command ends.
100.Sh SEE ALSO
101.Xr dtrace 1
102.\".Xr procsystime 1
103.Sh AUTHORS
104.An Brendan Gregg
105[Sydney, Australia]
106