libstatgrab/docs/cpu_percent_usage.xml

<?xml version="1.0"?>

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="cpu_percent_usage">

  <refentryinfo>
    <date>$Date: 2004/03/11 17:35:24 $</date>
    <releaseinfo>$Id: cpu_percent_usage.xml,v 1.3 2004/03/11 17:35:24 tdb Exp $</releaseinfo>
  </refentryinfo>
  
  <refmeta>
    <refentrytitle>cpu_percent_usage</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo>i-scream</refmiscinfo>
  </refmeta>
  
  <refnamediv>
    <refname>cpu_percent_usage</refname>
    <refname>get_cpu_totals</refname>
    <refname>get_cpu_diff</refname>
    <refpurpose>get cpu usage</refpurpose>
  </refnamediv>
    
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;statgrab.h&gt;</funcsynopsisinfo>
      <funcprototype>
        <funcdef>cpu_percent_t *<function>cpu_percent_usage</function></funcdef>
        <void/>
      </funcprototype>
      <funcprototype>
        <funcdef>cpu_states_t *<function>get_cpu_totals</function></funcdef>
        <void/>
      </funcprototype>
      <funcprototype>
        <funcdef>cpu_states_t *<function>get_cpu_diff</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
    
  <refsect1>
    <title>Description</title>
    <para>
      <function>get_cpu_totals()</function> and
      <function>get_cpu_diff()</function> both return static pointers
      of type <structname>cpu_states_t</structname>.
      <function>get_cpu_totals()</function> returns the total amount of
      "ticks" the operating system has spent in each of the different
      states. <function>get_cpu_diff()</function> returns the
      difference in "ticks" for each of the states since last time
      <function>get_cpu_diff()</function> or
      <function>get_cpu_totals()</function> was called. If it has never
      been called, it will return the result of
      <function>get_cpu_totals()</function>.
    </para>
    <para>
      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.
    </para>
    <para>
      Because of this,  you will ideally always want to work on a scale
      against the total, or in percentages.
    </para>
    <para>
      <function>cpu_percent_usage()</function> returns a pointer to a
      static <structname>cpu_percent_t</structname>.  The function
      calls <function>get_cpu_diff()</function> and changes the values
      into percentages. If it has never been called before (and nor has
      <function>get_cpu_totals()</function> or
      <function>get_cpu_diff()</function>), the returned percentages
      will be the systems total ever since its uptime. (Unless the
      counters have cycled)
    </para>
  </refsect1>
  
  <refsect1>
    <title>Return Values</title>

    <para>
      There are two structures returned by the CPU statistics
      functions.
    </para>

    <programlisting>
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;
    </programlisting>

    <programlisting>
typedef struct{
        float user;
        float kernel;
        float idle;
        float iowait;
        float swap;
        float nice;
        time_t time_taken;
}cpu_percent_t;
    </programlisting>

    <variablelist>
      <varlistentry>
        <term>
          <structfield>user</structfield>
          <structfield>kernel</structfield>
          <structfield>idle</structfield>
          <structfield>iowait</structfield>
          <structfield>swap</structfield>
          <structfield>nice</structfield>
        </term>
        <listitem>
          <para>
            The different CPU states.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <structfield>systime</structfield>
          <structfield>time_taken</structfield>
        </term>
        <listitem>
          <para>
            The time taken in seconds since the last call of the
            function, or the system time.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>See Also</title>

    <simplelist type="inline">
      <member>
        <citerefentry>
          <refentrytitle>statgrab</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
      </member>
    </simplelist>
  </refsect1>
  
  <refsect1>
    <title>Website</title>
    
    <simplelist type="vert">
      <member>
        <ulink url="http://www.i-scream.org/libstatgrab/">
          http://www.i-scream.org/libstatgrab/
        </ulink>
      </member>
    </simplelist>
  </refsect1>

</refentry>
Revision:	1.4
Committed:	Sun May 2 09:35:15 2004 UTC (20 years ago) by tdb
Content type:	text/xml
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.3:	+2 -2 lines
State:	*FILE REMOVED*
Log Message:	Do a repo copy of the documentation to their new names, then delete the old ones. They still need their content updating though. We also need docs for the new process stats stuff, the error reporting code, and I think the FS stats which seem to be missing.
#	Content
1	<?xml version="1.0"?>
2
3	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
4	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
6	<refentry id="cpu_percent_usage">
7
8	<refentryinfo>
9	<date>$Date: 2004/03/11 17:35:24 $</date>
10	<releaseinfo>$Id: cpu_percent_usage.xml,v 1.3 2004/03/11 17:35:24 tdb Exp $</releaseinfo>
11	</refentryinfo>
12
13	<refmeta>
14	<refentrytitle>cpu_percent_usage</refentrytitle>
15	<manvolnum>3</manvolnum>
16	<refmiscinfo>i-scream</refmiscinfo>
17	</refmeta>
18
19	<refnamediv>
20	<refname>cpu_percent_usage</refname>
21	<refname>get_cpu_totals</refname>
22	<refname>get_cpu_diff</refname>
23	<refpurpose>get cpu usage</refpurpose>
24	</refnamediv>
25
26	<refsynopsisdiv>
27	<funcsynopsis>
28	<funcsynopsisinfo>#include <statgrab.h></funcsynopsisinfo>
29	<funcprototype>
30	<funcdef>cpu_percent_t *<function>cpu_percent_usage</function></funcdef>
31	<void/>
32	</funcprototype>
33	<funcprototype>
34	<funcdef>cpu_states_t *<function>get_cpu_totals</function></funcdef>
35	<void/>
36	</funcprototype>
37	<funcprototype>
38	<funcdef>cpu_states_t *<function>get_cpu_diff</function></funcdef>
39	<void/>
40	</funcprototype>
41	</funcsynopsis>
42	</refsynopsisdiv>
43
44	<refsect1>
45	<title>Description</title>
46	<para>
47	<function>get_cpu_totals()</function> and
48	<function>get_cpu_diff()</function> both return static pointers
49	of type <structname>cpu_states_t</structname>.
50	<function>get_cpu_totals()</function> returns the total amount of
51	"ticks" the operating system has spent in each of the different
52	states. <function>get_cpu_diff()</function> returns the
53	difference in "ticks" for each of the states since last time
54	<function>get_cpu_diff()</function> or
55	<function>get_cpu_totals()</function> was called. If it has never
56	been called, it will return the result of
57	<function>get_cpu_totals()</function>.
58	</para>
59	<para>
60	The value stored (the "ticks") will vary between operating
61	systems. For example Solaris has a total of 100 per second,
62	while Linux has substantially more. Also, different operating
63	systems store different information - you won't find nice cpu on
64	Solaris for example.
65	</para>
66	<para>
67	Because of this, you will ideally always want to work on a scale
68	against the total, or in percentages.
69	</para>
70	<para>
71	<function>cpu_percent_usage()</function> returns a pointer to a
72	static <structname>cpu_percent_t</structname>. The function
73	calls <function>get_cpu_diff()</function> and changes the values
74	into percentages. If it has never been called before (and nor has
75	<function>get_cpu_totals()</function> or
76	<function>get_cpu_diff()</function>), the returned percentages
77	will be the systems total ever since its uptime. (Unless the
78	counters have cycled)
79	</para>
80	</refsect1>
81
82	<refsect1>
83	<title>Return Values</title>
84
85	<para>
86	There are two structures returned by the CPU statistics
87	functions.
88	</para>
89
90	<programlisting>
91	typedef struct{
92	long long user;
93	long long kernel;
94	long long idle;
95	long long iowait;
96	long long swap;
97	long long nice;
98	long long total;
99	time_t systime;
100	}cpu_states_t;
101	</programlisting>
102
103	<programlisting>
104	typedef struct{
105	float user;
106	float kernel;
107	float idle;
108	float iowait;
109	float swap;
110	float nice;
111	time_t time_taken;
112	}cpu_percent_t;
113	</programlisting>
114
115	<variablelist>
116	<varlistentry>
117	<term>
118	<structfield>user</structfield>
119	<structfield>kernel</structfield>
120	<structfield>idle</structfield>
121	<structfield>iowait</structfield>
122	<structfield>swap</structfield>
123	<structfield>nice</structfield>
124	</term>
125	<listitem>
126	<para>
127	The different CPU states.
128	</para>
129	</listitem>
130	</varlistentry>
131	<varlistentry>
132	<term>
133	<structfield>systime</structfield>
134	<structfield>time_taken</structfield>
135	</term>
136	<listitem>
137	<para>
138	The time taken in seconds since the last call of the
139	function, or the system time.
140	</para>
141	</listitem>
142	</varlistentry>
143	</variablelist>
144	</refsect1>
145
146	<refsect1>
147	<title>See Also</title>
148
149	<simplelist type="inline">
150	<member>
151	<citerefentry>
152	<refentrytitle>statgrab</refentrytitle>
153	<manvolnum>3</manvolnum>
154	</citerefentry>
155	</member>
156	</simplelist>
157	</refsect1>
158
159	<refsect1>
160	<title>Website</title>
161
162	<simplelist type="vert">
163	<member>
164	<ulink url="http://www.i-scream.org/libstatgrab/">
165	http://www.i-scream.org/libstatgrab/
166	</ulink>
167	</member>
168	</simplelist>
169	</refsect1>
170
171	</refentry>