libstatgrab/docs/cpu.txt

CPU Statistics
==============

$Id$

Data Structures
---------------

There are two structures returned by the CPU statistics functions.
They look like this:

typedef struct{
        long long user;
        long long kernel;
        long long idle;
        long long iowait;
        long long swap;
        long long nice;
        long long total;
        time_t systime;
}cpu_states_t;

typedef struct{
        float user;
        float kernel;
        float idle;
        float iowait;
        float swap;
        float nice;
        time_t time_taken;
}cpu_percent_t;

user, kernel, idle, iowait, swap, and nice are different CPU states.
systime and time_taken are the time in seconds since the last call
of the function.

Functions
---------

cpu_states_t *get_cpu_totals();
cpu_states_t *get_cpu_diff();
cpu_percent_t *cpu_percent_usage();

get_cpu_totals() and get_cpu_diff() both return static pointers of
type cpu_states_t. get_cpu_totals() returns the total amount of
"ticks" the operating system has spent in each of the different
states. get_cpu_diff() returns the difference in "ticks" for each
of the states since last time get_cpu_diff() or get_cpu_totals()
was called. If it has never been called, it will return the result
of get_cpu_totals()

The value stored (the "ticks") will vary between operating systems.
For example Solaris has a total of 100 per second, while Linux has
substantially more.  Also, different operating systems store different
information - you won't find nice cpu on Solaris for example.

Because of this,  you will ideally always want to work on a scale
against the total, or in percentages.

cpu_percent_usage() returns a pointer to a static cpu_percent_t.
The function calls get_cpu_diff() and changes the values into
percentages. If it has never been called before (and nor has
get_cpu_totals() or get_cpu_diff() ), the returned percentages will
be the systems total ever since its uptime. (Unless the counters
have cycled)

Example
-------

A basic example can be found in examples/cpu_usage.c
Revision:	1.2
Committed:	Sun Aug 24 21:20:36 2003 UTC (20 years, 9 months ago) by tdb
Content type:	text/plain
Branch:	MAIN
CVS Tags:	LIBSTATGRAB_0_5_1, LIBSTATGRAB_0_5
Changes since 1.1:	+45 -20 lines
Log Message:	Tidy cpu.txt and add to Makefile.
#	User	Rev	Content
1	pajs	1.1	CPU Statistics
2	tdb	1.2	==============
3	pajs	1.1
4	tdb	1.2	$Id$
5
6			Data Structures
7			---------------
8
9			There are two structures returned by the CPU statistics functions.
10			They look like this:
11	pajs	1.1
12			typedef struct{
13			long long user;
14			long long kernel;
15			long long idle;
16			long long iowait;
17			long long swap;
18			long long nice;
19			long long total;
20			time_t systime;
21			}cpu_states_t;
22
23			typedef struct{
24			float user;
25			float kernel;
26			float idle;
27			float iowait;
28			float swap;
29			float nice;
30			time_t time_taken;
31			}cpu_percent_t;
32
33	tdb	1.2	user, kernel, idle, iowait, swap, and nice are different CPU states.
34			systime and time_taken are the time in seconds since the last call
35			of the function.
36
37			Functions
38			---------
39
40			cpu_states_t *get_cpu_totals();
41			cpu_states_t *get_cpu_diff();
42			cpu_percent_t *cpu_percent_usage();
43
44	pajs	1.1	get_cpu_totals() and get_cpu_diff() both return static pointers of
45	tdb	1.2	type cpu_states_t. get_cpu_totals() returns the total amount of
46			"ticks" the operating system has spent in each of the different
47			states. get_cpu_diff() returns the difference in "ticks" for each
48			of the states since last time get_cpu_diff() or get_cpu_totals()
49			was called. If it has never been called, it will return the result
50			of get_cpu_totals()
51
52			The value stored (the "ticks") will vary between operating systems.
53			For example Solaris has a total of 100 per second, while Linux has
54			substantially more. Also, different operating systems store different
55			information - you won't find nice cpu on Solaris for example.
56
57			Because of this, you will ideally always want to work on a scale
58			against the total, or in percentages.
59
60			cpu_percent_usage() returns a pointer to a static cpu_percent_t.
61			The function calls get_cpu_diff() and changes the values into
62			percentages. If it has never been called before (and nor has
63			get_cpu_totals() or get_cpu_diff() ), the returned percentages will
64			be the systems total ever since its uptime. (Unless the counters
65			have cycled)
66
67			Example
68			-------
69
70			A basic example can be found in examples/cpu_usage.c