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