man/man8/btrace.8

   1 .TH BTRACE 8
   2 .SH NAME
   3 btrace \- block-level tracing interface
   4 .SH SYNOPSIS
   5 \fBbtrace\fR \fBstart\fR \fIdevice\fR \fIentries\fR
   6 .PP
   7 \fBbtrace\fR \fBstop\fR \fIdevice\fR \fIfile\fR
   8 .PP
   9 \fBbtrace\fR \fBreset\fR \fIdevice\fR
  10 .PP
  11 \fBbtrace\fR \fBdump\fR \fIfile\fR
  12 .SH DESCRIPTION
  13 The \fBbtrace\fR tool is the user interface to MINIX3's block-level tracing
  14 facility. It allows one to start, stop, and reset tracing, and dump a trace
  15 output file in a somewhat human-readable format.
  16 .SH COMMANDS
  17 .TP 10
  18 \fBstart\fR
  19 This command starts tracing all block requests on the given \fIdevice\fR. Each
  20 block request takes up one entry in the log. The \fIentries\fR parameter
  21 specifies the allocation side of the log in the driver process, in number of
  22 (32-byte) entries. Once the log is full, no more entries will be added.
  23 .TP 10
  24 \fBstop\fR
  25 This command stops tracing on the given \fIdevice\fR, and dumps the resulting
  26 log to the given output \fIfile\fR.
  27 .TP 10
  28 \fBreset\fR
  29 This command stops tracing on the given \fIdevice\fR and resets the state of
  30 the block tracer. This should be useful only in emergency situations.
  31 .TP 10
  32 \fBdump\fR
  33 Dump the contents of a log file generated earlier with \fBbtrace stop\fR, in
  34 human-readable format. Heavy users of the block tracing facility will probably
  35 want to write their own tools for parsing and visualizing dump files.
  36 .SH LIMITATIONS
  37 Only one block device can be traced per driver at once. It is therefore also
  38 not possible to trace a device and all its partitions at the same time. The
  39 tracing facility has been designed for tracing activity of a single file
  40 system, in which case these limitations are not important.
  41 .PP
  42 The log will always start with a \fIclose\fR operation on the device, since
  43 \fBbtrace\fR closes the file descriptor used to instruct the driver to start
  44 tracing. Similarly, for logs that have not already filled up during tracing,
  45 the last entry will be a \fBbtrace\fR-triggered \fIopen\fR operation.
  46 .SH EXAMPLES
  47 .TP 35
  48 .B btrace start /dev/c2d0 10240
  49 # Start a block trace on c2d0.
  50 .TP 35
  51 .B btrace stop /dev/c2d0 outfile
  52 # Stop the block trace on c2d0.
  53 .TP 35
  54 .B btrace dump outfile
  55 # View the output of the trace.
  56 .SH "SEE ALSO"
  57 .BR ioctl (2).
  58 .SH AUTHOR
  59 David van Moolenbroek <david@minix3.org>