--- projects/libstatgrab/docs/diskio.txt	2003/06/04 16:24:52	1.1
+++ projects/libstatgrab/docs/diskio.txt	2003/06/05 16:02:43	1.2
@@ -1,7 +1,12 @@
-Diskio Statistics
+DiskIO Statistics
+=================
 
-All diskio statistics return a diskio_stat_t structure.
+Data Structure
+--------------
 
+All diskio statistics return a structure of type diskio_stat_t that
+looks like this:
+
 typedef struct{
         char *disk_name;
         long long read_bytes;
@@ -9,38 +14,52 @@ typedef struct{
         time_t systime;
 }diskio_stat_t;
 
-disk_name is the name know to the OS. E.g. hda on linux.
-read_bytes is the number of bytes that disk has read.
-write_bytes is the number of bytes that disk has written.
-sysname is time_t covering the time the amount of data in rx/tx was
-generated.
+disk_name	is the name known to the operating system.
+		(eg. on linux it might be hda)
+read_bytes	is the number of bytes that disk has read.
+write_bytes	is the number of bytes that disk has written.
+sysname         is the time period over which read_bytes and
+		write_bytes were transferred.
 
+Functions
+---------
+
 diskio_stat_t *get_diskio_stats(int *entries);
 
 diskio_stat_t *get_diskio_stats_diff(int *entries);
 
-Both calls take a pointer to an int, "entries". This is filled with the number
-of disks the machine has. You need to know this to know how many diskio_stat_t 
-have been returned.
+Both calls take a pointer to an int, "entries", which is filled with
+the number of disks the machine has. This is needed to know how many
+diskio_stat_t structures have been returned. A pointer is returned to
+the first diskio_stat_t.
 
-get_diskio_stats returns the disk io stored in the kernel. E.g.
-since bootup as long as the way it is stored in the kernel can store a large
-enough number. Solaris 7 can not, it only stores it in a 32bit int, so it
-can only store upto 4gb before it will wrap around. Solaris 8 upwards stores
-it in a 64bit int and so is a very large number :)
+get_diskio_stats returns the disk IO stored in the kernel which holds
+the amount of data transferred since bootup. On some platforms, such as
+Solaris 7, this value is stored in a 32bit int, so wraps around when it
+reaches 4GB. Other platforms, such as Solaris 8, hold the value in a
+64bit int, which wraps somewhere near 17 million terabytes.
 
 get_diskio_stats_diff is the same as get_diskio_stats except it will
 return the difference since the last call. So, for instance a call to
-get_diskio_stats_diff is made, and called again 5 seconds later. Over that
-time, 2000 bytes of traffic was written and 10000 bytes read. write_bytes will
-store 2000 bytes, read_bytes will store 10000 and systime will store 5. This 
-function copes with wrap arounds by the O/S so should be seemless to use.
+get_diskio_stats_diff is made, and called again 5 seconds later. Over
+that time, 2000 bytes of traffic were written and 10000 bytes read.
+write_bytes will store 2000 bytes, read_bytes will store 10000, and
+systime will store 5. This function copes with wrap arounds by the O/S
+so should be seemless to use.
 
-Bugs:
-get_diskio_stats_diff on very first call will return the same as
-get_diskio_stats. After first call it will always return the difference.
-On machines that hold only 32bits of information, if the call is made 2x
-wrap around (eg sol7 9gb has been transferred, and it wraps at 4gb) it will
-return incorrect results (case above, it would say 5gb transferred).
+Bugs
+----
 
-Very basic example in examples/disk_traffic.c
+On the very first call get_diskio_stats_diff will return the same as
+get_diskio_stats. After the first call it will always return the
+difference.
+
+On operating systems that hold only 32bits of data there is a problem
+if the values wrap twice. For example, on Solaris 7 if 9GB is
+transferred and the operating system wraps at 4GB, the
+get_diskio_stats_diff function will return 5GB.
+
+Example
+-------
+
+A very basic example can be found in examples/disk_traffic.c