libstatgrab/docs/diskio.txt

DiskIO Statistics
=================

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;
        long long write_bytes;
        time_t systime;
}diskio_stat_t;

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", 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 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 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
----

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
Revision:	1.2
Committed:	Thu Jun 5 16:02:43 2003 UTC (21 years, 5 months ago) by tdb
Content type:	text/plain
Branch:	MAIN
Changes since 1.1:	+47 -28 lines
Log Message:	Proof read and slightly alter diskio.txt and network.txt. Also add diskio.txt to the Makefile.
#	User	Rev	Content
1	tdb	1.2	DiskIO Statistics
2			=================
3	pajs	1.1
4	tdb	1.2	Data Structure
5			--------------
6
7			All diskio statistics return a structure of type diskio_stat_t that
8			looks like this:
9	pajs	1.1
10			typedef struct{
11			char *disk_name;
12			long long read_bytes;
13			long long write_bytes;
14			time_t systime;
15			}diskio_stat_t;
16
17	tdb	1.2	disk_name is the name known to the operating system.
18			(eg. on linux it might be hda)
19			read_bytes is the number of bytes that disk has read.
20			write_bytes is the number of bytes that disk has written.
21			sysname is the time period over which read_bytes and
22			write_bytes were transferred.
23
24			Functions
25			---------
26	pajs	1.1
27			diskio_stat_t get_diskio_stats(int entries);
28
29			diskio_stat_t get_diskio_stats_diff(int entries);
30
31	tdb	1.2	Both calls take a pointer to an int, "entries", which is filled with
32			the number of disks the machine has. This is needed to know how many
33			diskio_stat_t structures have been returned. A pointer is returned to
34			the first diskio_stat_t.
35
36			get_diskio_stats returns the disk IO stored in the kernel which holds
37			the amount of data transferred since bootup. On some platforms, such as
38			Solaris 7, this value is stored in a 32bit int, so wraps around when it
39			reaches 4GB. Other platforms, such as Solaris 8, hold the value in a
40			64bit int, which wraps somewhere near 17 million terabytes.
41	pajs	1.1
42			get_diskio_stats_diff is the same as get_diskio_stats except it will
43			return the difference since the last call. So, for instance a call to
44	tdb	1.2	get_diskio_stats_diff is made, and called again 5 seconds later. Over
45			that time, 2000 bytes of traffic were written and 10000 bytes read.
46			write_bytes will store 2000 bytes, read_bytes will store 10000, and
47			systime will store 5. This function copes with wrap arounds by the O/S
48			so should be seemless to use.
49
50			Bugs
51			----
52
53			On the very first call get_diskio_stats_diff will return the same as
54			get_diskio_stats. After the first call it will always return the
55			difference.
56
57			On operating systems that hold only 32bits of data there is a problem
58			if the values wrap twice. For example, on Solaris 7 if 9GB is
59			transferred and the operating system wraps at 4GB, the
60			get_diskio_stats_diff function will return 5GB.
61
62			Example
63			-------
64	pajs	1.1
65	tdb	1.2	A very basic example can be found in examples/disk_traffic.c