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