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.
#	User	Rev	Content
1	tdb	1.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	tdb	1.4	<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	tdb	1.1	</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	tdb	1.2
149			<simplelist type="inline">
150			<member>
151			<citerefentry>
152			<refentrytitle>statgrab</refentrytitle>
153			<manvolnum>3</manvolnum>
154			</citerefentry>
155			</member>
156			</simplelist>
157	tdb	1.1	</refsect1>
158
159			<refsect1>
160			<title>Website</title>
161
162			<simplelist type="vert">
163			<member>
164	tdb	1.3	<ulink url="http://www.i-scream.org/libstatgrab/">
165			http://www.i-scream.org/libstatgrab/
166			</ulink>
167	tdb	1.1	</member>
168			</simplelist>
169			</refsect1>
170
171			</refentry>