usr.bin/truss/truss.1

.\" $MidnightBSD$
.\" $FreeBSD: stable/10/usr.bin/truss/truss.1 298427 2016-04-21 18:44:53Z jhb $
.\"
.Dd February 23, 2016
.Dt TRUSS 1
.Os
.Sh NAME
.Nm truss
.Nd trace system calls
.Sh SYNOPSIS
.Nm
.Op Fl facedDHS
.Op Fl o Ar file
.Op Fl s Ar strsize
.Fl p Ar pid
.Nm
.Op Fl facedDHS
.Op Fl o Ar file
.Op Fl s Ar strsize
.Ar command Op Ar args
.Sh DESCRIPTION
The
.Nm
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
.Xr ptrace 2 .
.Pp
The options are as follows:
.Bl -tag -width indent
.It Fl f
Trace descendants of the original traced process created by
.Xr fork 2 ,
.Xr vfork 2 ,
etc.
To distinguish events between processes,
the process ID
.Pq PID
of the process is included in the output of each event.
.It Fl a
Show the argument strings that are passed in each
.Xr execve 2
system call.
.It Fl 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.
.It Fl e
Show the environment strings that are passed in each
.Xr execve 2
system call.
.It Fl d
Include timestamps in the output showing the time elapsed
since the trace was started.
.It Fl D
Include timestamps in the output showing the time elapsed
since the last recorded event.
.It Fl H
Include the thread ID of in the output of each event.
.It Fl S
Do not display information about signals received by the process.
(Normally,
.Nm
displays signal as well as system call events.)
.It Fl o Ar file
Print the output to the specified
.Ar file
instead of standard error.
.It Fl s Ar strsize
Display strings using at most
.Ar strsize
characters.
If the buffer is larger,
.Dq Li ...
will be displayed at the end of the string.
The default
.Ar strsize
is 32.
.It Fl p Ar pid
Follow the process specified by
.Ar pid
instead of a new command.
.It Ar command Op Ar args
Execute
.Ar command
and trace the system calls of it.
(The
.Fl p
and
.Ar command
options are mutually exclusive.)
.El
.Sh EXAMPLES
# Follow the system calls used in echoing "hello"
.Dl $ truss /bin/echo hello
# Do the same, but put the output into a file
.Dl $ truss -o /tmp/truss.out /bin/echo hello
# Follow an already-running process
.Dl $ truss -p 34
.Sh SEE ALSO
.Xr kdump 1 ,
.Xr ktrace 1 ,
.Xr ptrace 2
.Sh HISTORY
The
.Nm
command was written by
.An Sean Eric Fagan
for
.Fx .
It was modeled after
similar commands available for System V Release 4 and SunOS.
Revision:	11271
Committed:	Wed Jul 4 00:01:33 2018 UTC (5 years, 10 months ago) by laffer1
File size:	2652 byte(s)
Log Message:	update truss
#	Content
1	.\" $MidnightBSD$
2	.\" $FreeBSD: stable/10/usr.bin/truss/truss.1 298427 2016-04-21 18:44:53Z jhb $
3	.\"
4	.Dd February 23, 2016
5	.Dt TRUSS 1
6	.Os
7	.Sh NAME
8	.Nm truss
9	.Nd trace system calls
10	.Sh SYNOPSIS
11	.Nm
12	.Op Fl facedDHS
13	.Op Fl o Ar file
14	.Op Fl s Ar strsize
15	.Fl p Ar pid
16	.Nm
17	.Op Fl facedDHS
18	.Op Fl o Ar file
19	.Op Fl s Ar strsize
20	.Ar command Op Ar args
21	.Sh DESCRIPTION
22	The
23	.Nm
24	utility traces the system calls called by the specified process or program.
25	Output is to the specified output file, or standard error by default.
26	It does this by stopping and restarting the process being monitored via
27	.Xr ptrace 2 .
28	.Pp
29	The options are as follows:
30	.Bl -tag -width indent
31	.It Fl f
32	Trace descendants of the original traced process created by
33	.Xr fork 2 ,
34	.Xr vfork 2 ,
35	etc.
36	To distinguish events between processes,
37	the process ID
38	.Pq PID
39	of the process is included in the output of each event.
40	.It Fl a
41	Show the argument strings that are passed in each
42	.Xr execve 2
43	system call.
44	.It Fl c
45	Do not display individual system calls or signals.
46	Instead, before exiting, print a summary containing for each system call:
47	the total system time used,
48	the number of times the call was invoked,
49	and the number of times the call returned with an error.
50	.It Fl e
51	Show the environment strings that are passed in each
52	.Xr execve 2
53	system call.
54	.It Fl d
55	Include timestamps in the output showing the time elapsed
56	since the trace was started.
57	.It Fl D
58	Include timestamps in the output showing the time elapsed
59	since the last recorded event.
60	.It Fl H
61	Include the thread ID of in the output of each event.
62	.It Fl S
63	Do not display information about signals received by the process.
64	(Normally,
65	.Nm
66	displays signal as well as system call events.)
67	.It Fl o Ar file
68	Print the output to the specified
69	.Ar file
70	instead of standard error.
71	.It Fl s Ar strsize
72	Display strings using at most
73	.Ar strsize
74	characters.
75	If the buffer is larger,
76	.Dq Li ...
77	will be displayed at the end of the string.
78	The default
79	.Ar strsize
80	is 32.
81	.It Fl p Ar pid
82	Follow the process specified by
83	.Ar pid
84	instead of a new command.
85	.It Ar command Op Ar args
86	Execute
87	.Ar command
88	and trace the system calls of it.
89	(The
90	.Fl p
91	and
92	.Ar command
93	options are mutually exclusive.)
94	.El
95	.Sh EXAMPLES
96	# Follow the system calls used in echoing "hello"
97	.Dl $ truss /bin/echo hello
98	# Do the same, but put the output into a file
99	.Dl $ truss -o /tmp/truss.out /bin/echo hello
100	# Follow an already-running process
101	.Dl $ truss -p 34
102	.Sh SEE ALSO
103	.Xr kdump 1 ,
104	.Xr ktrace 1 ,
105	.Xr ptrace 2
106	.Sh HISTORY
107	The
108	.Nm
109	command was written by
110	.An Sean Eric Fagan
111	for
112	.Fx .
113	It was modeled after
114	similar commands available for System V Release 4 and SunOS.