xref: /csrg-svn/usr.bin/ktrace/ktrace.1 (revision 44955)

.\" Copyright (c) 1990 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)ktrace.1	1.3 (Berkeley) 07/24/90
.\"
.Dd
.Dt KTRACE 1
.Sh NAME
.Nm ktrace
.Nd enable kernel process tracing
.Sh SYNOPSIS
.Nm ktrace
.Op Fl Cica
.Op Fl p Ar pid
.Op Fl g Ar pgrp
.Op Fl f Ar trfile
.Op Fl t Ar trstr
.Nm ktrace
.Op Fl ida
.Op Fl f Ar trfile
.Op command
.Sh DESCRIPTION
.Nm Ktrace
enables kernel trace logging for the specified processes.
Kernel trace data is logged to the file
.Sq Pa ktrace.out
in the
current directory, or to the file named with the
.Fl f
flag.
The current set of kernel operations that can be traced include:
system calls, namei translations, signal processing, and i/o.
By default, all operations are
traced.  To restrict logging to specific operations, use the
.Fl t
flag as described below.  Once tracing is enabled on a process,
trace data will be logged until either the process exits or the
trace point is cleared with the
.Fl c
flag.  A traced process can generate enormous amounts of log
data quickly; compounded with the action of the inherit flag,
.Fl i  ,
tracing can become unwieldly.
It is strongly suggested that the user memorize
how to globally disable all tracing before attempting
to trace a process.  The following command is sufficient to
disable tracing on all user owned processes
(if root, all processes in the system):
.Pp
.Dl \&$ trace -C
.Pp
The
trace file is binary format: use
.Xr kdump 1
to decode it.
Following
is a description of the options:
.Tw Ds
.Tp Fl C
Disable tracing on all user owned processes (if root, all processes in the
system).
.Tc Fl f
.Ws
.Ar trfile
.Cx
Log trace records to
.Ar trfile
instead
of
.Dq Pa trace.out .
.Tc Fl t
.Ws
.Ar trstr
.Cx
The string argument represents the kernel trace points, one
per letter.  The following table equates the letters with the tracepoints:
.Dw Ds
.Dp Cm c
trace system calls
.Dp Cm n
trace namei translations
.Dp Cm i
trace I/O
.Dp Cm s
trace processing of signals
.Dp
.Tc Fl p
.Ws
.Ar pid
.Cx
Enable (disable) tracing on the indicated process id (only one
.Fl p
flag
allowed);
.Tc Fl g
.Ws
.Ar pgid
.Cx
Enable (disable) tracing on all processes in the indicated
process group.
.Tp Fl a
Append to the tracefile instead of truncating it.
.Tp Fl c
Clear
the indicated trace points.
.Tp Fl i
Pass the trace flag to all future children of the
designated processes.
.Tp Fl I
Pass the trace flag to all current and future children of the
designated processes.
.Tp Ar command
Run
.Ar command
with the specified trace flags.
.Tp
.Pp
The
.Fl p ,
.Fl g ,
and command options are mutually exclusive.
.Sh EXAMPLES
.Ds I
# trace all kernel operations of process id 34
.Dl $ ktrace -p34
# trace all kernel operations of processes in process group 15 and
# pass the trace flags to all current and future children
.Dl $ ktrace -Ig15
# disable all tracing of process 65
.Dl $ ktrace -cp65
# disable tracing signals on process 70 and all current children
.Dl $ ktrace -ts -cip70
# enable tracing of i/o on process 67
.Dl $ ktrace -ti -p67
# run the command "w", tracing only system calls
.Dl $ ktrace -tc w
# disable all tracing to the file "tracedata"
.Dl $ ktrace -c -f tracedata
# disable tracing of all processes owned by the user
.Dl $ ktrace -C
.De
.Sh SEE ALSO
.Xr kdump 1
\- display kernel trace data.
.Sh HISTORY
4.4 BSD.