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