286 lines
7.4 KiB
Groff
286 lines
7.4 KiB
Groff
.\" $NetBSD: ktrace.1,v 1.46 2020/11/18 20:00:15 wiz 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.
|
|
.\"
|
|
.\" @(#)ktrace.1 8.1 (Berkeley) 6/6/93
|
|
.\"
|
|
.Dd March 29, 2020
|
|
.Dt KTRACE 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ktrace , ktruss
|
|
.Nd enable kernel process tracing
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl aCcdins
|
|
.Op Fl f Ar trfile
|
|
.Op Fl g Ar pgrp
|
|
.Op Fl p Ar pid
|
|
.Op Fl t Ar trstr
|
|
.Nm
|
|
.Op Fl adis
|
|
.Op Fl f Ar trfile
|
|
.Op Fl t Ar trstr
|
|
.Ar command
|
|
.Nm ktruss
|
|
.Op Fl aCcdilnRT
|
|
.Op Fl e Ar emulation
|
|
.Op Fl f Ar infile
|
|
.Op Fl g Ar pgrp
|
|
.Op Fl m Ar maxdata
|
|
.Op Fl o Ar outfile
|
|
.Op Fl p Ar pid
|
|
.Op Fl t Ar trstr
|
|
.Nm ktruss
|
|
.Op Fl adinRT
|
|
.Op Fl e Ar emulation
|
|
.Op Fl m Ar maxdata
|
|
.Op Fl o Ar outfile
|
|
.Op Fl t Ar trstr
|
|
.Op Fl v Ar vers
|
|
command
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
enables kernel trace logging for the specified processes.
|
|
Kernel trace data is logged to the file
|
|
.Pa ktrace.out .
|
|
The kernel operations that are traced include system calls, namei
|
|
translations, signal processing, and
|
|
.Tn 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
|
|
.Nm ktruss
|
|
is functionally the same as
|
|
.Nm ktrace
|
|
except that trace output is printed
|
|
on standard output or to the file specified with the
|
|
.Fl o
|
|
option.
|
|
.Nm ktruss
|
|
is useful to see the kernel operations interleaved with
|
|
the program output.
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width indent
|
|
.It Fl a
|
|
Append to the trace file instead of truncating it.
|
|
.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 specified file or processes.
|
|
.It Fl d
|
|
Descendants; perform the operation for all current children of the
|
|
designated processes.
|
|
.It Fl e Ar emulation
|
|
If an emulation of a process is unknown,
|
|
interpret system call maps assuming the named emulation instead of
|
|
default "netbsd".
|
|
.It Fl f Ar trfile
|
|
Log trace records to
|
|
.Ar trfile
|
|
instead of
|
|
.Pa ktrace.out .
|
|
.It Fl f Ar infile
|
|
Read the trace records from
|
|
.Ar infile
|
|
and print them in a human readable format to standard 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 l
|
|
Poll the trace file for new data and print it to standard out.
|
|
Only for use together with the
|
|
.Fl f
|
|
option.
|
|
.It Fl m Ar maxdata
|
|
Print at most
|
|
.Ar maxdata
|
|
bytes of data.
|
|
This is used for pointer type arguments, e.g., strings.
|
|
The data will be escaped in C-style unless
|
|
.Fl x
|
|
is specified when it will be output in hex and ascii.
|
|
.It Fl n
|
|
Stop tracing if attempts to write to the trace file would block.
|
|
This option always affects
|
|
.Nm ktruss
|
|
and only affects
|
|
.Nm ktrace
|
|
when writing to
|
|
.Dv stdout .
|
|
If this flag is not set, then the traced program will block until it can
|
|
write more data to the trace file descriptor.
|
|
.It Fl o Ar outfile
|
|
Log trace records to
|
|
.Ar outfile .
|
|
Without this option
|
|
.Nm ktruss
|
|
will print its output in a human
|
|
readable format to standard out.
|
|
.It Fl p Ar pid
|
|
Enable (disable) tracing on the indicated process id (only one
|
|
.Fl p
|
|
flag is permitted).
|
|
.It Fl R
|
|
Display relative time stamps to output.
|
|
.It Fl s
|
|
Write to the trace file with synchronized I/O.
|
|
.It Fl T
|
|
Same as the
|
|
.Fl R
|
|
option, but use absolute timestamps instead.
|
|
.It Fl t Ar trstr
|
|
The string argument represents the kernel trace points, one per letter.
|
|
The following table equates the letters with the tracepoints:
|
|
.Pp
|
|
.Bl -tag -width flag -compact
|
|
.It Cm A
|
|
trace all tracepoints
|
|
.It Cm a
|
|
trace exec arguments
|
|
.It Cm c
|
|
trace system calls
|
|
.It Cm e
|
|
trace emulation changes
|
|
.It Cm f
|
|
trace open file descriptors after exec
|
|
.It Cm i
|
|
trace
|
|
.Tn I/O
|
|
.It Cm n
|
|
trace namei translations
|
|
.It Cm S
|
|
trace MIB access (sysctl)
|
|
.It Cm s
|
|
trace signal processing
|
|
.\" .It Cm U
|
|
.\" trace scheduler activations upcall data
|
|
.It Cm u
|
|
trace user data
|
|
.It Cm v
|
|
trace exec environment
|
|
.It Cm w
|
|
trace context switches
|
|
.It Cm +
|
|
trace the default set of trace points (c, e, i, n, s, u)
|
|
.It Cm -
|
|
do not trace following trace points
|
|
.El
|
|
.It Fl v Ar version
|
|
Determines the
|
|
.Ar version
|
|
of the file generated.
|
|
Version 0 is the compatible ktrace format, and
|
|
version 1 is the new format with lwp IDs and nanosecond (instead of
|
|
microsecond) timestamps.
|
|
.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.
|
|
The
|
|
.Fl R
|
|
and
|
|
.Fl T
|
|
options are also mutually exclusive.
|
|
.Sh EXAMPLES
|
|
# trace all kernel operations of process id 34
|
|
.Dl $ ktrace -p 34
|
|
.Pp
|
|
.Bd -literal
|
|
# trace all kernel operations of processes in process group 15 and
|
|
# pass the trace flags to all current and future children
|
|
.Ed
|
|
.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
|
|
.Tn I/O
|
|
on process 67
|
|
.Dl $ ktrace -ti -p 67
|
|
.Pp
|
|
# run the command "w", 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
|
|
.Pp
|
|
# run the command "w", displaying to standard output
|
|
.Dl $ ktruss w
|
|
.Pp
|
|
# trace process 42 and log the records to "ktruss.out"
|
|
.Dl $ ktruss -p 42 -o ktruss.out
|
|
.Pp
|
|
# poll ktruss.out for available records and print them
|
|
.Dl $ ktruss -lf ktruss.out
|
|
.Sh SEE ALSO
|
|
.Xr kdump 1 ,
|
|
.Xr ktrace 2
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
command appeared in
|
|
.Bx 4.4 .
|
|
The
|
|
.Nm ktrace
|
|
command appeared in
|
|
.Nx 1.5 .
|