205 lines
5.6 KiB
Groff
205 lines
5.6 KiB
Groff
.\" $OpenBSD: ktrace.1,v 1.34 2023/12/15 15:12:08 deraadt Exp $
|
|
.\"
|
|
.\" Copyright (c) 1990, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" from: @(#)ktrace.1 8.1 (Berkeley) 6/6/93
|
|
.\"
|
|
.Dd $Mdocdate: December 15 2023 $
|
|
.Dt KTRACE 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ktrace
|
|
.Nd enable kernel process tracing
|
|
.Sh SYNOPSIS
|
|
.Nm ktrace
|
|
.Op Fl aCcdi
|
|
.Op Fl f Ar trfile
|
|
.Op Fl g Ar pgid
|
|
.Op Fl p Ar pid
|
|
.Op Fl t Ar trstr
|
|
.Nm ktrace
|
|
.Op Fl aBdiT
|
|
.Op Fl f Ar trfile
|
|
.Op Fl t Ar trstr
|
|
.Ar command
|
|
.Sh DESCRIPTION
|
|
.Nm ktrace
|
|
enables kernel trace logging for the specified processes.
|
|
By default, kernel trace data is logged to the file
|
|
.Pa ktrace.out ,
|
|
unless overridden by the
|
|
.Fl f
|
|
option.
|
|
The kernel operations traced are system calls, namei translations,
|
|
signal processing and I/O.
|
|
.Pp
|
|
Once tracing is enabled on a process, trace data will be logged until
|
|
either the process exits or the trace point is cleared.
|
|
A traced process can generate enormous amounts of log data quickly;
|
|
it is strongly suggested that users memorize how to disable tracing before
|
|
attempting to trace a process.
|
|
The following command is sufficient to disable tracing on all user owned
|
|
processes and, if executed by root, all processes:
|
|
.Pp
|
|
.Dl $ ktrace -C
|
|
.Pp
|
|
The trace file is not human-readable; use
|
|
.Xr kdump 1
|
|
to decode it.
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width 9n
|
|
.It Fl a
|
|
Append to the trace file instead of recreating it.
|
|
.It Fl B
|
|
Set the
|
|
.Ev LD_BIND_NOW
|
|
environment variable to specify that the dynamic linker should process
|
|
relocations immediately instead of as they are encountered.
|
|
This eliminates the resulting
|
|
.Xr ld.so 1
|
|
relocation sequences.
|
|
.It Fl C
|
|
Disable tracing on all user owned processes and, if executed by root, all
|
|
processes in the system.
|
|
.It Fl c
|
|
Clear the trace points associated with the trace file or any specified
|
|
processes.
|
|
.It Fl d
|
|
Descendants; perform the operation for all current children of the
|
|
designated processes.
|
|
.It Fl f Ar trfile
|
|
Log trace records to
|
|
.Ar trfile
|
|
instead of
|
|
.Pa ktrace.out .
|
|
.It Fl g Ar pgid
|
|
Enable (disable) tracing on all processes in the process group (only one
|
|
.Fl g
|
|
flag is permitted).
|
|
.It Fl i
|
|
Inherit; pass the trace flags to all future children of the designated
|
|
processes.
|
|
.It Fl p Ar pid
|
|
Enable (disable) tracing on the indicated process ID (only one
|
|
.Fl p
|
|
flag is permitted).
|
|
.It Fl T
|
|
Disable userland timekeeping, making time related system calls more prevalent.
|
|
.It Fl t Ar trstr
|
|
Select which information to put into the dump file.
|
|
The argument can contain one or more of the following letters.
|
|
By default all trace points except for
|
|
.Cm X
|
|
are enabled.
|
|
.Pp
|
|
.Bl -tag -width flag -offset indent -compact
|
|
.\" Keep this list in sync with kdump(1) and ltrace(1).
|
|
.It Cm c
|
|
trace system calls
|
|
.It Cm i
|
|
trace I/O
|
|
.It Cm n
|
|
trace namei translations
|
|
.It Cm p
|
|
trace violation of
|
|
.Xr pledge 2
|
|
restrictions
|
|
.It Cm s
|
|
trace signal processing
|
|
.It Cm S
|
|
trace violation of
|
|
.Xr pinsyscalls 2
|
|
.It Cm t
|
|
trace various structures
|
|
.It Cm u
|
|
trace user data coming from
|
|
.Xr utrace 2
|
|
.It Cm x
|
|
trace argument vector in
|
|
.Xr execve 2
|
|
.It Cm X
|
|
trace environment in
|
|
.Xr execve 2
|
|
.It Cm +
|
|
trace the default points
|
|
.El
|
|
.It Ar command
|
|
Execute
|
|
.Ar command
|
|
with the specified trace flags.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fl p ,
|
|
.Fl g ,
|
|
and
|
|
.Ar command
|
|
options are mutually exclusive.
|
|
.Sh FILES
|
|
.Bl -tag -width ktrace.out -compact
|
|
.It Pa ktrace.out
|
|
default ktrace dump file
|
|
.El
|
|
.Sh EXAMPLES
|
|
Trace all kernel operations of process ID 34:
|
|
.Dl $ ktrace -p 34
|
|
.Pp
|
|
Trace all kernel operations of processes in process group 15 and
|
|
pass the trace flags to all current and future children:
|
|
.Dl $ ktrace -idg 15
|
|
.Pp
|
|
Disable all tracing of process 65:
|
|
.Dl $ ktrace -cp 65
|
|
.Pp
|
|
Disable tracing signals on process 70 and all current children:
|
|
.Dl $ ktrace -t s -cdp 70
|
|
.Pp
|
|
Enable tracing of I/O on process 67:
|
|
.Dl $ ktrace -ti -p 67
|
|
.Pp
|
|
Run the command
|
|
.Xr w 1 ,
|
|
tracing only system calls:
|
|
.Dl $ ktrace -tc w
|
|
.Pp
|
|
Disable all tracing to the file "tracedata":
|
|
.Dl $ ktrace -c -f tracedata
|
|
.Pp
|
|
Disable tracing of all processes owned by the user:
|
|
.Dl $ ktrace -C
|
|
.Sh SEE ALSO
|
|
.Xr kdump 1 ,
|
|
.Xr ktrace 2 ,
|
|
.Xr utrace 2
|
|
.Sh HISTORY
|
|
The
|
|
.Nm ktrace
|
|
command appeared in
|
|
.Bx 4.3 Reno .
|