libstatgrab/docs/diskio.txt

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

$Id$

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