xref: /dragonfly/usr.bin/ktrace/ktrace.1 (revision 55f88487) 
1.\" Copyright (c) 1990, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"	@(#)ktrace.1	8.1 (Berkeley) 6/6/93
29.\" $FreeBSD: src/usr.bin/ktrace/ktrace.1,v 1.8.2.8 2002/06/21 15:27:30 charnier Exp $
30.\"
31.Dd April 4, 2023
32.Dt KTRACE 1
33.Os
34.Sh NAME
35.Nm ktrace
36.Nd enable kernel process tracing
37.Sh SYNOPSIS
38.Nm
39.Op Fl aCcdi
40.Op Fl f Ar trfile
41.Op Fl g Ar pgrp | Fl p Ar pid
42.Op Fl t Ar trstr
43.Nm
44.Op Fl adi
45.Op Fl f Ar trfile
46.Op Fl t Ar trstr
47.Ar command
48.Sh DESCRIPTION
49The
50.Nm
51utility enables kernel trace logging for the specified processes.
52By default, kernel trace data is logged to the file
53.Pa ktrace.out ,
54this may be overridden by the
55.Fl f
56option.
57The kernel operations that are traced include system calls, namei
58translations, signal processing, and I/O.
59.Pp
60Once tracing is enabled on a process, trace data will be logged until
61either the process exits or the trace point is cleared.
62A traced process can generate enormous amounts of log data quickly;
63It is strongly suggested that users memorize how to disable tracing before
64attempting to trace a process.
65The following command is sufficient to disable tracing on all user owned
66processes, and, if executed by root, all processes:
67.Pp
68.Dl \&$ ktrace -C
69.Pp
70The trace file is not human readable; use
71.Xr kdump 1
72to decode it.
73.Pp
74The options are as follows:
75.Bl -tag -width indent
76.It Fl a
77Append to the trace file instead of recreating it.
78.It Fl C
79Disable tracing on all user owned processes, and, if executed by root, all
80processes in the system.
81.It Fl c
82Clear the trace points associated with the specified file or processes.
83.It Fl d
84Descendants; perform the operation for all current children of the
85designated processes.
86.It Fl f Ar trfile
87Log trace records to
88.Ar trfile
89instead of
90.Pa ktrace.out .
91.It Fl g Ar pgid
92Enable (disable) tracing on all processes in the process group (only one
93.Fl g
94flag is permitted).
95.It Fl i
96Inherit; pass the trace flags to all future children of the designated
97processes.
98.It Fl p Ar pid
99Enable (disable) tracing on the indicated process id (only one
100.Fl p
101flag is permitted).
102.It Fl t Ar trstr
103The string argument represents the kernel trace points, one per letter.
104The following table equates the letters with the tracepoints:
105.Pp
106.Bl -tag -width flag -compact
107.It Cm c
108trace system calls
109.It Cm n
110trace namei translations
111.It Cm i
112trace I/O
113.It Cm s
114trace signal processing
115.It Cm u
116userland traces
117.It Cm w
118context switches
119.It Cm y
120trace
121.Xr sysctl 3
122requests
123.It Cm +
124trace the default set of trace points -
125.Cm c , n , i , s , u , y
126.El
127.It Ar command
128Execute
129.Ar command
130with the specified trace flags.
131.El
132.Pp
133The
134.Fl p ,
135.Fl g ,
136and
137.Ar command
138options are mutually exclusive.
139.Sh FILES
140.Bl -tag -width ktrace.out -compact
141.It Pa ktrace.out
142default ktrace dump file
143.El
144.Sh EXAMPLES
145# trace all kernel operations of process id 34
146.Dl $ ktrace -p 34
147.Pp
148# trace all kernel operations of processes in process group 15 and
149# pass the trace flags to all current and future children
150.Dl $ ktrace -idg 15
151.Pp
152# disable all tracing of process 65
153.Dl $ ktrace -cp 65
154.Pp
155# disable tracing signals on process 70 and all current children
156.Dl $ ktrace -t s -cdp 70
157.Pp
158# enable tracing of I/O
159on process 67
160.Dl $ ktrace -ti -p 67
161.Pp
162# run the command "w", tracing only system calls
163.Dl $ ktrace -tc w
164.Pp
165# disable all tracing to the file "tracedata"
166.Dl $ ktrace -c -f tracedata
167.Pp
168# disable tracing of all processes owned by the user
169.Dl $ ktrace -C
170.Sh SEE ALSO
171.Xr kdump 1 ,
172.Xr ktrace 2 ,
173.Xr utrace 2
174.Sh HISTORY
175The
176.Nm
177command appeared in
178.Bx 4.4 .
179.Sh BUGS
180Only works if
181.Ar trfile
182is a regular file.
183