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

.\" Copyright (c) 1990 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.roff%
.\"
.\"	@(#)ktrace.1	5.5 (Berkeley) 07/26/91
.\"
.Dd
.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 pgrp
.Op Fl p Ar pid
.Op Fl t Ar trstr
.Nm ktrace
.Op Fl adi
.Op Fl f Ar trfile
.Op Fl t Ar trstr
command
.Sh DESCRIPTION
.Nm Ktrace
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 \&$ trace -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 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 f Ar file
Log trace records to
.Ar file
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 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 c
trace system calls
.It Cm n
trace namei translations
.It Cm i
trace
.Tn I/O
.It Cm s
trace signal processing
.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 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
.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
.Sh SEE ALSO
.Xr kdump 1
.Sh HISTORY
The
.Nm ktrace
command is
.Ud .