libstatgrab/docs/cpu.txt

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

$Id: cpu.txt,v 1.2 2003/08/24 21:20:36 tdb Exp $

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.3
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.2:	+1 -1 lines
State:	*FILE REMOVED*
Log Message:	Dropped the old text documentation in favour of manpages.
#	Content
1	CPU Statistics
2	==============
3
4	$Id: cpu.txt,v 1.2 2003/08/24 21:20:36 tdb Exp $
5
6	Data Structures
7	---------------
8
9	There are two structures returned by the CPU statistics functions.
10	They look like this:
11
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	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	get_cpu_totals() and get_cpu_diff() both return static pointers of
45	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