Annotation of src/usr.bin/ktrace/ktrace.1, Revision 1.34
1.34 ! deraadt 1: .\" $OpenBSD: ktrace.1,v 1.33 2023/09/30 13:03:40 naddy 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: .\"
1.34 ! deraadt 32: .Dd $Mdocdate: September 30 2023 $
1.1 deraadt 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
1.31 tedu 40: .Op Fl aCcdi
1.1 deraadt 41: .Op Fl f Ar trfile
1.14 jmc 42: .Op Fl g Ar pgid
1.1 deraadt 43: .Op Fl p Ar pid
44: .Op Fl t Ar trstr
45: .Nm ktrace
1.31 tedu 46: .Op Fl aBdiT
1.1 deraadt 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.20 jmc 58: The kernel operations traced are system calls, namei translations,
1.28 guenther 59: signal processing and I/O.
1.1 deraadt 60: .Pp
61: Once tracing is enabled on a process, trace data will be logged until
62: either the process exits or the trace point is cleared.
63: A traced process can generate enormous amounts of log data quickly;
1.8 aaron 64: it is strongly suggested that users memorize how to disable tracing before
1.1 deraadt 65: attempting to trace a process.
66: The following command is sufficient to disable tracing on all user owned
1.25 jmc 67: processes and, if executed by root, all processes:
1.1 deraadt 68: .Pp
1.14 jmc 69: .Dl $ ktrace -C
1.1 deraadt 70: .Pp
1.6 aaron 71: The trace file is not human-readable; use
1.1 deraadt 72: .Xr kdump 1
73: to decode it.
74: .Pp
75: The options are as follows:
1.24 miod 76: .Bl -tag -width 9n
1.1 deraadt 77: .It Fl a
1.5 deraadt 78: Append to the trace file instead of recreating it.
1.23 guenther 79: .It Fl B
80: Set the
81: .Ev LD_BIND_NOW
82: environment variable to specify that the dynamic linker should process
83: relocations immediately instead of as they are encountered.
84: This eliminates the resulting
85: .Xr ld.so 1
86: relocation sequences.
1.1 deraadt 87: .It Fl C
1.25 jmc 88: Disable tracing on all user owned processes and, if executed by root, all
1.1 deraadt 89: processes in the system.
90: .It Fl c
1.20 jmc 91: Clear the trace points associated with the trace file or any specified
92: processes.
1.1 deraadt 93: .It Fl d
94: Descendants; perform the operation for all current children of the
95: designated processes.
1.17 jmc 96: .It Fl f Ar trfile
1.1 deraadt 97: Log trace records to
1.18 jmc 98: .Ar trfile
1.1 deraadt 99: instead of
100: .Pa ktrace.out .
1.7 aaron 101: .It Fl g Ar pgid
1.1 deraadt 102: Enable (disable) tracing on all processes in the process group (only one
103: .Fl g
104: flag is permitted).
105: .It Fl i
106: Inherit; pass the trace flags to all future children of the designated
107: processes.
1.7 aaron 108: .It Fl p Ar pid
1.6 aaron 109: Enable (disable) tracing on the indicated process ID (only one
1.1 deraadt 110: .Fl p
111: flag is permitted).
1.31 tedu 112: .It Fl T
113: Disable userland timekeeping, making time related system calls more prevalent.
1.7 aaron 114: .It Fl t Ar trstr
1.30 schwarze 115: Select which information to put into the dump file.
116: The argument can contain one or more of the following letters.
1.29 guenther 117: By default all trace points except for
118: .Cm X
119: are enabled.
1.1 deraadt 120: .Pp
1.14 jmc 121: .Bl -tag -width flag -offset indent -compact
1.33 naddy 122: .\" Keep this list in sync with kdump(1) and ltrace(1).
1.1 deraadt 123: .It Cm c
124: trace system calls
125: .It Cm i
1.14 jmc 126: trace I/O
1.11 deraadt 127: .It Cm n
128: trace namei translations
1.29 guenther 129: .It Cm p
130: trace violation of
131: .Xr pledge 2
132: restrictions
1.1 deraadt 133: .It Cm s
134: trace signal processing
1.34 ! deraadt 135: .It Cm S
! 136: trace violation of
! 137: .Xr pinsyscalls 2
1.21 otto 138: .It Cm t
139: trace various structures
1.24 miod 140: .It Cm u
141: trace user data coming from
142: .Xr utrace 2
1.27 guenther 143: .It Cm x
144: trace argument vector in
145: .Xr execve 2
146: .It Cm X
147: trace environment in
148: .Xr execve 2
1.20 jmc 149: .It Cm +
150: trace the default points
1.1 deraadt 151: .El
152: .It Ar command
153: Execute
154: .Ar command
155: with the specified trace flags.
156: .El
157: .Pp
158: The
159: .Fl p ,
160: .Fl g ,
161: and
162: .Ar command
163: options are mutually exclusive.
1.13 jmc 164: .Sh FILES
165: .Bl -tag -width ktrace.out -compact
166: .It Pa ktrace.out
167: default ktrace dump file
168: .El
1.1 deraadt 169: .Sh EXAMPLES
1.16 jmc 170: Trace all kernel operations of process ID 34:
1.1 deraadt 171: .Dl $ ktrace -p 34
1.16 jmc 172: .Pp
173: Trace all kernel operations of processes in process group 15 and
174: pass the trace flags to all current and future children:
1.1 deraadt 175: .Dl $ ktrace -idg 15
176: .Pp
1.16 jmc 177: Disable all tracing of process 65:
1.1 deraadt 178: .Dl $ ktrace -cp 65
179: .Pp
1.16 jmc 180: Disable tracing signals on process 70 and all current children:
1.1 deraadt 181: .Dl $ ktrace -t s -cdp 70
182: .Pp
1.16 jmc 183: Enable tracing of I/O on process 67:
1.1 deraadt 184: .Dl $ ktrace -ti -p 67
185: .Pp
1.16 jmc 186: Run the command
187: .Xr w 1 ,
188: tracing only system calls:
1.1 deraadt 189: .Dl $ ktrace -tc w
190: .Pp
1.16 jmc 191: Disable all tracing to the file "tracedata":
1.1 deraadt 192: .Dl $ ktrace -c -f tracedata
193: .Pp
1.16 jmc 194: Disable tracing of all processes owned by the user:
1.1 deraadt 195: .Dl $ ktrace -C
196: .Sh SEE ALSO
1.15 grunk 197: .Xr kdump 1 ,
1.24 miod 198: .Xr ktrace 2 ,
199: .Xr utrace 2
1.1 deraadt 200: .Sh HISTORY
201: The
202: .Nm ktrace
1.6 aaron 203: command appeared in
1.32 jsg 204: .Bx 4.3 Reno .
![[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