.\" Copyright (c) 1990 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)ktrace.1	5.4 (Berkeley) 03/14/91
.\"
.Vx
.Vx
.Dd 
.Dt KTRACE 1
.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 ``ktrace.out''.
The kernel operations that are traced include 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 \&$ trace -C
.Pp
The trace file is not human readable; use
.Xr kdump 1
to decode it.
.Pp
The options are as follows:
.Tw Ds
.Tp Fl a
Append to the trace file instead of truncating it.
.Tp Fl C
Disable tracing on all user owned processes, and, if executed by root, all
processes in the system.
.Tp Fl c
Clear the trace points associated with the specified file or processes.
.Tp Fl d
Descendants; perform the operation for all current children of the
designated processes.
.Tc Fl f
.Ws
.Ar file
.Cx
Log trace records to
.Ar file
instead of ``ktrace.out''.
.Tc Fl g
.Ws
.Ar pgid
.Cx
Enable (disable) tracing on all processes in the process group (only one
.Fl g
flag is permitted).
.Tp Fl i
Inherit; pass the trace flags to all future children of the designated
processes.
.Tc Fl p
.Ws
.Ar pid
.Cx
Enable (disable) tracing on the indicated process id (only one
.Fl p
flag is permitted).
.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 Dp
.Dp Cm c
trace system calls
.Dp Cm n
trace namei translations
.Dp Cm i
trace I/O
.Dp Cm s
trace signal processing
.Dp
.Tp Ar command
Execute
.Ar command
with the specified trace flags.
.Tp
.Pp
The
.Fl p ,
.Fl g ,
and command options are mutually exclusive.
.Sh EXAMPLES
# trace all kernel operations of process id 34
.Dl $ ktrace -p 34
.sp
.nf
# trace all kernel operations of processes in process group 15 and
# pass the trace flags to all current and future children
.fi
.Dl $ ktrace -idg 15
.sp
# disable all tracing of process 65
.Dl $ ktrace -cp 65
.sp
# disable tracing signals on process 70 and all current children
.Dl $ ktrace -t s -cdp 70
.sp
# enable tracing of i/o on process 67
.Dl $ ktrace -ti -p 67
.sp
# run the command "w", tracing only system calls
.Dl $ ktrace -tc w
.sp
# disable all tracing to the file "tracedata"
.Dl $ ktrace -c -f tracedata
.sp
# disable tracing of all processes owned by the user
.Dl $ ktrace -C
.Sh SEE ALSO
.Xr kdump 1
.Sh HISTORY
4.4 BSD.