1 .\" $NetBSD: ktrace.1,v 1.38 2007/03/02 20:45:45 wiz Exp $
3 .\" Copyright (c) 1990, 1993
4 .\" The Regents of the University of California. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" @(#)ktrace.1 8.1 (Berkeley) 6/6/93
37 .Nd enable kernel process tracing
69 enables kernel trace logging for the specified processes.
70 Kernel trace data is logged to the file
72 The kernel operations that are traced include system calls, namei
73 translations, signal processing, and
76 Once tracing is enabled on a process, trace data will be logged until
77 either the process exits or the trace point is cleared.
78 A traced process can generate enormous amounts of log data quickly;
79 It is strongly suggested that users memorize how to disable tracing before
80 attempting to trace a process.
81 The following command is sufficient to disable tracing on all user owned
82 processes, and, if executed by root, all processes:
86 The trace file is not human readable; use
91 is functionally the same as
93 except that trace output is printed
94 on standard output or to the file specified with the
98 is useful to see the kernel operations interleaved with
101 The options are as follows:
102 .Bl -tag -width indent
104 Append to the trace file instead of truncating it.
106 Disable tracing on all user owned processes, and, if executed by root, all
107 processes in the system.
109 Clear the trace points associated with the specified file or processes.
111 Descendants; perform the operation for all current children of the
112 designated processes.
119 Read the trace records from
121 and print them in a human readable format to standard out.
123 Enable (disable) tracing on all processes in the process group (only one
127 Inherit; pass the trace flags to all future children of the designated
130 Poll the trace file for new data and print it to standard out.
131 Only for use together with the
138 This is used for pointer type arguments, e.g., strings.
139 The data will be escaped in C-style unless
141 is specified when it will be output in hex and ascii.
143 Stop tracing if attempts to write to the trace file would block.
144 This option always affects
150 If this flag is not set, then the traced program will block until it can
151 write more data to the trace file descriptor.
157 will print its output in a human
158 readable format to standard out.
160 Enable (disable) tracing on the indicated process id (only one
164 Write to the trace file with synchronized I/O.
166 Display relative time stamps to output.
170 option, but use absolute timestamps instead.
172 The string argument represents the kernel trace points, one per letter.
173 The following table equates the letters with the tracepoints:
175 .Bl -tag -width flag -compact
177 trace all tracepoints
183 trace emulation changes
188 trace Mach out of line data when running Mach binaries with COMPAT_MACH
189 (currently limited to i386 and powerpc ports).
191 trace Mach messages when running Mach binaries with COMPAT_MACH
192 (currently limited to i386 and powerpc ports).
194 trace namei translations
196 trace MIB access (sysctl)
198 trace signal processing
200 .\" trace scheduler activations upcall data
204 trace exec environment
206 trace context switches
208 trace the default set of trace points (c, e, i, l, m, n, s, u)
210 do not trace following trace points
212 .It Fl e Ar emulation
213 If an emulation of a process is unknown,
214 interpret system call maps assuming the named emulation instead of
219 with the specified trace flags.
223 of the file generated.
224 Version 0 is the compatible ktrace format, and
225 version 1 is the new format with lwp IDs and nanosecond (instead of
226 microsecond) timestamps.
234 options are mutually exclusive.
239 options are also mutually exclusive.
241 # trace all kernel operations of process id 34
245 # trace all kernel operations of processes in process group 15 and
246 # pass the trace flags to all current and future children
250 # disable all tracing of process 65
253 # disable tracing signals on process 70 and all current children
254 .Dl $ ktrace -t s -cdp 70
259 .Dl $ ktrace -ti -p 67
261 # run the command "w", tracing only system calls
264 # disable all tracing to the file "tracedata"
265 .Dl $ ktrace -c -f tracedata
267 # disable tracing of all processes owned by the user
270 # run the command "w", displaying to standard output
273 # trace process 42 and log the records to "ktruss.out"
274 .Dl $ ktruss -p 42 -o ktruss.out
276 # poll ktruss.out for available records and print them
277 .Dl $ ktruss -lf ktruss.out