ioping: add documentation

- add some stuff into man page
- add README
- add changelog
Signed-off-by: Konstantin Khlebnikov <koct9i@gmail.com>

Makefile

@@ -8,12 +8,13 @@ SRCS=ioping.c
 OBJS=$(SRCS:.c=.o)
 BINS=ioping
 MANS=ioping.1
+DOCS=README changelog
 SPEC=ioping.spec
 
 PACKAGE=ioping
 VERSION=$(shell cat version)
 DISTDIR=$(PACKAGE)-$(VERSION)
-DISTFILES=$(SRCS) $(MANS) $(SPEC) Makefile
+DISTFILES=$(SRCS) $(MANS) $(DOCS) $(SPEC) Makefile
 
 STRIP=strip
 TARGET=$(shell ${CC} -dumpmachine | cut -d- -f 2)

README

+ioping
+======
+
+An tool to monitor I/O latency in real time.
+It shows disk latency in the same way as ping shows network latency.
+
+Authors:
+Konstantin Khlebnikov <koct9i@gmail.com>
+Kir Kolyshkin <kir@openvz.org>
+
+Licensed under GPLv3 (or later) <http://www.gnu.org/licenses/gpl-3.0.txt>

changelog

+since v0.4
+ - rate-test, new key -R
+ - FreeBSD port
+ - OSX port
+
+since v0.5
+ - fixes in man page and internal help
+ - fixes in OSX and FreeBSD ports
+ - Debian/kFreeBSD port
+ - Debian/HURD port
+
+since v0.6
+ - Linux AIO support, new key -A
+ - extended raw statistics, keys -p -P
+ - batched mode, new key -B
+ - write requests, key -W
+ - automatic git-based versioning
+ - Windows/MinGW port
+ - DragonFlyBSD port

ioping.1

-.TH IOPING "1" "July 2011" "" "User Commands"
+.TH IOPING "1" "Aug 2012" "" "User Commands"
 .SH NAME
 ioping \- simple disk I/O latency monitoring tool
 .SH SYNOPSYS
@@ -12,7 +12,7 @@ ioping \- simple disk I/O latency monitoring tool
 .OP \-s size
 .OP \-S wsize
 .OP \-o offset
-.IR device | file | directory
+.IR directory | file | device
 .br
 .SY ioping
 .B -h
@@ -42,27 +42,27 @@ Set time between requests to \fIinterval\fR (\fB1s\fR).
 Request size (\fB4k\fR).
 .TP
 .BI \-S \ size
-Working set size (\fB1m\fR).
+Working set size (\fB1m\fR for directory, full size for file or device).
 .TP
 .BI \-o \ offset
-Offset in input file.
+Offset of working set in the file/device (0).
 .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.
+Use asynchronous I/O (syscalls \fBio_submit\fR(2), \fBio_submit\fR(2), etc).
 .TP
 .B \-C
-Use cached I/O.
+Use cached I/O (suppress cache invalidation via \fBposix_fadvise\fR(2)).
 .TP
 .B \-D
-Use direct I/O.
+Use direct I/O (see \fBO_DIRECT\fR in \fBopen\fR(2)).
 .TP
 .B \-W
 Use writes rather than reads.
-\fB*DANGEROUS*\fR It will shred your data in non-directory targets,
+\fB*DANGEROUS*\fR It will shred your data if target is file or device,
 repeat key tree times (\fB-WWW\fR) to do this.
 .TP
 .B \-R
@@ -72,7 +72,7 @@ Disk seek rate test (same as \fB-q -i 0 -w 3 -S 64m\fR).
 Batch mode. Be quiet and print final statistics in raw format.
 .TP
 .B \-q
-Suppress human-readable output.
+Suppress periodical human-readable output.
 .TP
 .B \-h
 Display help message and exit.

ioping.c

@@ -195,7 +195,7 @@ void usage(void)
 {
 	fprintf(stderr,
 			" Usage: ioping [-LABCDWRq] [-c count] [-w deadline] [-pP period] [-i interval]\n"
-			"               [-s size] [-S wsize] [-o offset] device|file|directory\n"
+			"               [-s size] [-S wsize] [-o offset] directory|file|device\n"
 			"        ioping -h | -v\n"
 			"\n"
 			"      -c <count>      stop after <count> requests\n"
@@ -205,12 +205,12 @@ void usage(void)
 			"      -i <interval>   interval between requests (1s)\n"
 			"      -s <size>       request size (4k)\n"
 			"      -S <wsize>      working set size (1m)\n"
-			"      -o <offset>     in file offset\n"
+			"      -o <offset>     working set offset (0)\n"
 			"      -L              use sequential operations (includes -s 256k)\n"
 			"      -A              use asynchronous I/O\n"
 			"      -C              use cached I/O\n"
 			"      -D              use direct I/O\n"
-			"      -W              use write I/O *DANGEROUS* require -WWW for non-directory\n"
+			"      -W              use write I/O *DANGEROUS*\n"
 			"      -R              seek rate test (same as -q -i 0 -w 3 -S 64m)\n"
 			"      -B              print final statistics in raw format\n"
 			"      -q              suppress human-readable output\n"