libstatgrab/docs/diskio.txt

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

$Id: diskio.txt,v 1.3 2003/08/24 20:24:08 tdb Exp $

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.4
Committed:	Thu Oct 2 16:30:54 2003 UTC (20 years, 7 months ago) by tdb
Content type:	text/plain
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.3:	+1 -1 lines
State:	*FILE REMOVED*
Log Message:	Dropped the old text documentation in favour of manpages.
#	Content
1	DiskIO Statistics
2	=================
3
4	$Id: diskio.txt,v 1.3 2003/08/24 20:24:08 tdb Exp $
5
6	Data Structure
7	--------------
8
9	All diskio statistics return a structure of type diskio_stat_t that
10	looks like this:
11
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	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
29	diskio_stat_t get_diskio_stats(int entries);
30
31	diskio_stat_t get_diskio_stats_diff(int entries);
32
33	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
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	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
67	A very basic example can be found in examples/disk_traffic.c