sys/man/4/iostats

   1 .TH IOSTATS 4
   2 .SH NAME
   3 iostats \- file system to measure I/O
   4 .SH SYNOPSIS
   5 .B iostats
   6 [
   7 .B -d
   8 ]
   9 [
  10 .B -f
  11 .I dbfile
  12 ]
  13 .I cmd
  14 [
  15 .I args...
  16 ]
  17 .SH DESCRIPTION
  18 .I Iostats
  19 is a user-level file server that interposes itself between a program
  20 and the regular file server, which
  21 allows it to gather statistics of file system
  22 use at the level of the Plan 9 file system protocol, 9P.
  23 After a program
  24 exits a report is printed on standard error.
  25 .PP
  26 The report consists of three sections.
  27 The first section reports the amount
  28 of user data in
  29 .B read
  30 and
  31 .B write
  32 messages sent by the program and the average rate at
  33 which the data was transferred.
  34 The
  35 .B protocol
  36 line reports the amount
  37 of data sent as message headers, that is,
  38 protocol overhead.
  39 The
  40 .B rpc
  41 line reports the
  42 total number of file system transactions.
  43 .PP
  44 The second section gives
  45 the number of messages, the fastest, slowest, and average turn around
  46 time and the amount of data involved with each 9P
  47 message type.
  48 The final section gives an I/O summary for each file used
  49 by the program in terms of opens, reads and writes.
  50 .PP
  51 If the
  52 .B -d
  53 flag is present, a debugging log including all traffic
  54 is written to
  55 .I dbfile
  56 (default
  57 .BR iostats.out ).
  58 .SH EXAMPLE
  59 Display summary of file I/O incurred by
  60 .IR ls (1):
  61 .IP
  62 .EX
  63 iostats ls
  64 .EE
  65 .PP
  66 Start a new shell, displaying all 9P traffic caused by the shell or its children:
  67 .IP
  68 .EX
  69 iostats -df /fd/1 rc
  70 .EE
  71 .SH SOURCE
  72 .B /sys/src/cmd/iostats
  73 .SH SEE ALSO
  74 .IR dup (3)
  75 .SH BUGS
  76 Poor clock resolution means that large amounts of I/O must be done to
  77 get accurate rate figures.
  78 .PP
  79 Can be fooled by programs that do fresh mounts outside its purview,
  80 or by the use of names of files with content that can vary by process (e.g.,
  81 .LR #d ,
  82 .LR /dev/cons ).