.TH IOPING "1" "Oct 2014" "" "User Commands"
.SH NAME
ioping \- simple disk I/O latency monitoring tool
.SH SYNOPSYS
.SY ioping
.OP \-LABCDWRkq
.OP \-c count
.OP \-w deadline
.OP \-p period
.OP \-P period
.OP \-i interval
.OP \-s size
.OP \-S wsize
.OP \-o offset
.IR directory | file | device
.br
.SY ioping
.B -h
|
.B -v
.br
.SH DESCRIPTION
This tool lets you monitor I/O latency in real time.
.SH OPTIONS
.TP
.BI \-c \ count
Stop after \fIcount\fR requests.
.TP
.BI \-w \ deadline
Stop after \fIdeadline\fR time passed.
.TP
.BI \-p \ period
Print raw statistics for every \fIperiod\fR requests.
.TP
.BI \-P \ period
Print raw statistics for every \fIperiod\fR in time.
.TP
.BI \-i \ interval
Set time between requests to \fIinterval\fR (\fB1s\fR).
.TP
.BI \-s \ size
Request size (\fB4k\fR).
.TP
.BI \-S \ size
Working set size (\fB1m\fR for directory, whole size for file or device).
.TP
.BI \-o \ offset
Starting offset in the file/device (0).
.TP
.BI \-k
Keep (do not delete) working file "ioping.tmp". Works for directory target.
.TP
.B \-L
Use sequential operations rather than random. This also sets request size
to \fB256k\fR (as in \fB-s 256k\fR).
.TP
.B \-A
Use asynchronous I/O (syscalls \fBio_submit\fR(2), \fBio_submit\fR(2), etc).
.TP
.B \-C
Use cached I/O (suppress cache invalidation via \fBposix_fadvise\fR(2)).
.TP
.B \-D
Use direct I/O (see \fBO_DIRECT\fR in \fBopen\fR(2)).
.TP
.B \-W
Use writes rather than reads. Safe for directory target.
\fB*DANGEROUS*\fR for file/device, it will shred your data.
In this case should be repeated tree times (\fB-WWW\fR).
.TP
.B \-R
Disk seek rate test (same as \fB\-q \-i 0 \-w 3 \-S 64m\fR).
If disk has huge cache working set (-S) should be increased accordingly.
.TP
.B \-B
Batch mode. Be quiet and print final statistics in raw format.
.TP
.B \-q
Suppress periodical human-readable output.
.TP
.B \-h
Display help message and exit.
.TP
.B \-v
Display version and exit.
.SS Argument suffixes
For options that expect time argument (\fB\-i\fR, \fB\-P\fR and \fB\-w\fR),
default is seconds, unless you specify one of the following suffixes
(case-insensitive):
.TP
.BR us ,\  usec
microseconds (a millionth of a second, 1 / 1 000 000)
.TP
.BR ms ,\  msec
milliseconds (a thousandth of a second, 1 / 1 000)
.TP
.BR s ,\  sec
seconds
.TP
.BR m ,\  min
minutes
.TP
.BR h ,\  hour
hours
.PP
For options that expect "size" argument (\fB\-s\fR, \fB\-S\fR and \fB\-o\fR),
default is bytes, unless you specify one of the following suffixes
(case-insensitive):
.TP
.B sector
disk sectors (a sector is always 512).
.TP
.BR KiB ,\  k ,\  kb
kilobytes (1 024 bytes)
.TP
.B page
memory pages (a page is always 4KiB).
.TP
.BR MiB ,\  m ,\  mb
megabytes (1 048 576 bytes)
.TP
.BR GiB ,\  g ,\  gb
gigabytes (1 073 741 824 bytes)
.TP
.BR TiB ,\  t ,\  tb
terabytes (1 099 511 627 776 bytes)
.PP
For options that expect "number" argument (\fB-p\fR and \fB-c\fR) you
can optionally specify one of the following suffixes (case-insensitive):
.TP
.B k
kilo (thousands, 1 000)
.TP
.B m
mega (millions, 1 000 000)
.TP
.B g
giga (billions, 1 000 000 000)
.TP
.B t
tera (trillions, 1 000 000 000 000)
.SH EXIT STATUS
Returns \fB0\fR upon success. The following error codes are defined:
.TP
.B 1
Invalid usage (error in arguments).
.TP
.B 2
Error during preparation stage.
.TP
.B 3
Error during runtime.
.SH RAW STATISTICS
.B ioping -p 100 -c 200 -i 0 -q .
.ad l
.br
\f(CW100 26694 3746 15344272 188 267 1923 228
.br
100 24165 4138 16950134 190 242 2348 214
.br
(1) (2)   (3)  (4)      (5) (6) (7)  (8)
.br

.br
(1) number of requests
.br
(2) serving time         (usec)
.br
(3) requests per second  (iops)
.br
(4) transfer speed       (bytes/sec)
.br
(5) minimal request time (usec)
.br
(6) average request time (usec)
.br
(7) maximum request time (usec)
.br
(8) request time standard deviation (usec)
.SH EXAMPLES
.TP
.B ioping .
Show disk I/O latency using the default values and the current directory,
until interrupted.
.TP
.B ioping -c 10 -s 1M /tmp
Measure latency on \fB/tmp\fR using 10 requests of 1 megabyte each.
.TP
.B ioping -R /dev/sda
Measure disk seek rate.
.TP
.B ioping -RL /dev/sda
Measure disk sequential speed.
.TP
.B ioping -RLB . | awk '{print $4}'
Get disk sequential speed in bytes per second.
.SH SEE ALSO
.BR iostat (1),
.BR dd (1),
.BR fio (1),
.BR dbench (1),
.BR fsstress,
.BR xfstests,
.BR hdparm (8),
.BR badblocks (8),
.BR
.SH HOMEPAGE
.UR http://code.google.com/p/ioping/
.UE .
.SH AUTHORS
This program was written by Konstantin Khlebnikov
.MT koct9i@gmail.com
.ME .
.br
Man-page was written by Kir Kolyshkin
.MT kir@openvz.org
.ME .