August 27, 2007 KTRACE 1

### NAME

ktrace,ktruss - enable kernel process tracing

### SYNOPSIS

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

### DESCRIPTION

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 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:

```$``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 program 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 processes.

-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 designated 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 ascii.

-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 program will block until it can write more data to the trace file descriptor.

-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 tracepoints:

  A
    trace all tracepoints
  a
    trace exec arguments
  c
    trace system calls
  e
    trace emulation changes
  i
    trace I/O
  l
    trace Mach out of line data when running Mach binaries with COMPAT_MACH (currently limited to i386 and powerpc ports).
  m
    trace Mach messages when running Mach binaries with COMPAT_MACH (currently limited to i386 and powerpc ports).
  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, u)
  -
    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".

command
  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.

### EXAMPLES

# 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`

### SEE ALSO

kdump(1), ktrace(2)

### HISTORY

The ktrace command appears in 4.4BSD.