Annotation of src/usr.bin/ktrace/ktrace.1, Revision 1.13
1.13 ! jmc 1: .\" $OpenBSD: ktrace.1,v 1.12 2003/06/03 02:56:09 millert Exp $
1.9 aaron 2: .\"
1.1 deraadt 3: .\" Copyright (c) 1990, 1993
4: .\" The Regents of the University of California. All rights reserved.
5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
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.
1.12 millert 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 15: .\" may be used to endorse or promote products derived from this software
16: .\" without specific prior written permission.
17: .\"
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
28: .\" SUCH DAMAGE.
29: .\"
30: .\" from: @(#)ktrace.1 8.1 (Berkeley) 6/6/93
31: .\"
32: .Dd June 6, 1993
33: .Dt KTRACE 1
1.7 aaron 34: .Os
1.1 deraadt 35: .Sh NAME
36: .Nm ktrace
37: .Nd enable kernel process tracing
38: .Sh SYNOPSIS
39: .Nm ktrace
40: .Op Fl aCcdi
41: .Op Fl f Ar trfile
42: .Op Fl g Ar pgrp
43: .Op Fl p Ar pid
44: .Op Fl t Ar trstr
45: .Nm ktrace
46: .Op Fl adi
47: .Op Fl f Ar trfile
48: .Op Fl t Ar trstr
1.6 aaron 49: .Ar command
1.1 deraadt 50: .Sh DESCRIPTION
1.6 aaron 51: .Nm ktrace
1.1 deraadt 52: enables kernel trace logging for the specified processes.
1.8 aaron 53: By default, kernel trace data is logged to the file
54: .Pa ktrace.out ,
55: unless overridden by the
56: .Fl f
57: option.
1.1 deraadt 58: The kernel operations that are traced include system calls, namei
59: translations, signal processing, and
60: .Tn I/O .
61: .Pp
62: Once tracing is enabled on a process, trace data will be logged until
63: either the process exits or the trace point is cleared.
64: A traced process can generate enormous amounts of log data quickly;
1.8 aaron 65: it is strongly suggested that users memorize how to disable tracing before
1.1 deraadt 66: attempting to trace a process.
67: The following command is sufficient to disable tracing on all user owned
68: processes, and, if executed by root, all processes:
69: .Pp
1.3 millert 70: .Dl \&$ ktrace -C
1.1 deraadt 71: .Pp
1.6 aaron 72: The trace file is not human-readable; use
1.1 deraadt 73: .Xr kdump 1
74: to decode it.
75: .Pp
76: The options are as follows:
1.10 aaron 77: .Bl -tag -width Ds
1.1 deraadt 78: .It Fl a
1.5 deraadt 79: Append to the trace file instead of recreating it.
1.1 deraadt 80: .It Fl C
81: Disable tracing on all user owned processes, and, if executed by root, all
82: processes in the system.
83: .It Fl c
84: Clear the trace points associated with the specified file or processes.
85: .It Fl d
86: Descendants; perform the operation for all current children of the
87: designated processes.
1.7 aaron 88: .It Fl f Ar file
1.1 deraadt 89: Log trace records to
90: .Ar file
91: instead of
92: .Pa ktrace.out .
1.7 aaron 93: .It Fl g Ar pgid
1.1 deraadt 94: Enable (disable) tracing on all processes in the process group (only one
95: .Fl g
96: flag is permitted).
97: .It Fl i
98: Inherit; pass the trace flags to all future children of the designated
99: processes.
1.7 aaron 100: .It Fl p Ar pid
1.6 aaron 101: Enable (disable) tracing on the indicated process ID (only one
1.1 deraadt 102: .Fl p
103: flag is permitted).
1.7 aaron 104: .It Fl t Ar trstr
1.1 deraadt 105: The string argument represents the kernel trace points, one per letter.
1.11 deraadt 106: The default flags are
1.13 ! jmc 107: .Cm c ,
! 108: .Cm e ,
! 109: .Cm i ,
! 110: .Cm n ,
1.11 deraadt 111: and
1.13 ! jmc 112: .Cm s .
1.1 deraadt 113: The following table equates the letters with the tracepoints:
114: .Pp
115: .Bl -tag -width flag -compact
116: .It Cm c
117: trace system calls
118: .It Cm e
119: trace emulation changes
120: .It Cm i
121: trace
122: .Tn I/O
1.11 deraadt 123: .It Cm n
124: trace namei translations
1.1 deraadt 125: .It Cm s
126: trace signal processing
1.13 ! jmc 127: .It Cm w
1.11 deraadt 128: trace context switch points
1.1 deraadt 129: .El
130: .It Ar command
131: Execute
132: .Ar command
133: with the specified trace flags.
134: .El
135: .Pp
136: The
137: .Fl p ,
138: .Fl g ,
139: and
140: .Ar command
141: options are mutually exclusive.
1.13 ! jmc 142: .Sh FILES
! 143: .Bl -tag -width ktrace.out -compact
! 144: .It Pa ktrace.out
! 145: default ktrace dump file
! 146: .El
1.1 deraadt 147: .Sh EXAMPLES
148: # trace all kernel operations of process id 34
149: .Dl $ ktrace -p 34
150: .Pp
1.4 deraadt 151: .Bd -literal
1.1 deraadt 152: # trace all kernel operations of processes in process group 15 and
153: # pass the trace flags to all current and future children
1.4 deraadt 154: .Ed
1.1 deraadt 155: .Dl $ ktrace -idg 15
156: .Pp
157: # disable all tracing of process 65
158: .Dl $ ktrace -cp 65
159: .Pp
160: # disable tracing signals on process 70 and all current children
161: .Dl $ ktrace -t s -cdp 70
162: .Pp
163: # enable tracing of
164: .Tn I/O
165: on process 67
166: .Dl $ ktrace -ti -p 67
167: .Pp
168: # run the command "w", tracing only system calls
169: .Dl $ ktrace -tc w
170: .Pp
171: # disable all tracing to the file "tracedata"
172: .Dl $ ktrace -c -f tracedata
173: .Pp
174: # disable tracing of all processes owned by the user
175: .Dl $ ktrace -C
176: .Sh SEE ALSO
177: .Xr kdump 1
178: .Sh HISTORY
179: The
180: .Nm ktrace
1.6 aaron 181: command appeared in
1.1 deraadt 182: .Bx 4.4 .
![[BACK]](/icons/back.gif){kind=icon}
Return to ktrace.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / ktrace