Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
KTRACE(1)		  BSD General Commands Manual		     KTRACE(1)

     ktrace, ktruss -- enable kernel process tracing

     ktrace [-aCcdins] [-f trfile] [-g pgrp] [-p pid] [-t trstr]
     ktrace [-adis] [-f	trfile]	[-t trstr] command
     ktruss [-aCcdilnRT] [-e emulation]	[-f infile] [-g	pgrp] [-m maxdata]
	    [-o	outfile] [-p pid] [-t trstr]
     ktruss [-adinRT] [-e emulation] [-m maxdata] [-o outfile] [-t trstr]
	    [-v	vers] command

     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.

     Once tracing is enabled on	a process, trace data will be logged until ei-
     ther the process exits or the trace point is cleared.  A traced process
     can generate enormous amounts of log data quickly;	It is strongly sug-
     gested 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:

	   $ ktrace -C

     The trace file is not human readable; use kdump(1)	to decode it.

     ktruss is functionally the	same as	ktrace except that trace output	is
     printed on	standard output	or to the file specified with the -o option.
     ktruss is useful to see the kernel	operations interleaved with the	pro-
     gram output.

     The options are as	follows:

     -a	     Append to the trace file instead of truncating it.

     -C	     Disable tracing on	all user owned processes, and, if executed by
	     root, all processes in the	system.

     -c	     Clear the trace points associated with the	specified file or pro-

     -d	     Descendants; perform the operation	for all	current	children of
	     the designated processes.

     -f	trfile
	     Log trace records to trfile instead of ktrace.out.

     -f	infile
	     Read the trace records from infile	and print them in a human
	     readable format to	standard out.

     -g	pgid
	     Enable (disable) tracing on all processes in the process group
	     (only one -g flag is permitted).

     -i	     Inherit; pass the trace flags to all future children of the des-
	     ignated processes.

     -l	     Poll the trace file for new data and print	it to standard out.
	     Only for use together with	the -f option.

     -m	maxdata
	     Print at most maxdata bytes of data.  This	is used	for pointer
	     type arguments, e.g., strings.  The data will be escaped in C-
	     style unless -x is	specified when it will be output in hex	and

     -n	     Stop tracing if attempts to write to the trace file would block.
	     This option always	affects	ktruss and only	affects	ktrace when
	     writing to	stdout.	 If this flag is not set, then the traced pro-
	     gram will block until it can write	more data to the trace file

     -o	outfile
	     Log trace records to outfile.  Without this option	ktruss will
	     print its output in a human readable format to standard out.

     -p	pid  Enable (disable) tracing on the indicated process id (only	one -p
	     flag is permitted).

     -s	     Write to the trace	file with synchronized I/O.

     -R	     Display relative time stamps to output.

     -T	     Same as the -R option, but	use absolute timestamps	instead.

     -t	trstr
	     The string	argument represents the	kernel trace points, one per
	     letter.  The following table equates the letters with the trace-

	     A	   trace all tracepoints
	     a	   trace exec arguments
	     c	   trace system	calls
	     e	   trace emulation changes
	     f	   trace open file descriptors after exec
	     i	   trace I/O
	     n	   trace namei translations
	     S	   trace MIB access (sysctl)
	     s	   trace signal	processing
	     u	   trace user data
	     v	   trace exec environment
	     w	   trace context switches
	     +	   trace the default set of trace points (c, e,	i, l, m, n, s,
	     -	   do not trace	following trace	points

     -e	emulation
	     If	an emulation of	a process is unknown, interpret	system call
	     maps assuming the named emulation instead of default "netbsd".

	     Execute command with the specified	trace flags.

     -v	version
	     Determines	the 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.

     The -p, -g, and command options are mutually exclusive.  The -R and -T
     options are also mutually exclusive.

     # trace all kernel	operations of process id 34
	   $ ktrace -p 34

     # trace all kernel	operations of processes	in process group 15 and
     # pass the	trace flags to all current and future children
	   $ ktrace -idg 15

     # disable all tracing of process 65
	   $ ktrace -cp	65

     # disable tracing signals on process 70 and all current children
	   $ ktrace -t s -cdp 70

     # enable tracing of I/O on	process	67
	   $ ktrace -ti	-p 67

     # run the command "w", tracing only system	calls
	   $ ktrace -tc	w

     # disable all tracing to the file "tracedata"
	   $ ktrace -c -f tracedata

     # disable tracing of all processes	owned by the user
	   $ ktrace -C

     # run the command "w", displaying to standard output
	   $ ktruss w

     # trace process 42	and log	the records to "ktruss.out"
	   $ ktruss -p 42 -o ktruss.out

     # poll ktruss.out for available records and print them
	   $ ktruss -lf	ktruss.out

     kdump(1), ktrace(2)

     The ktrace	command	appears	in 4.4BSD.

BSD				 June 1, 2011				   BSD


Want to link to this manual page? Use this URL:

home | help