libstatgrab/docs/sg_get_cpu_stats.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: 2003/10/01 14:59:11 $</date>
    <releaseinfo>$Id: cpu_percent_usage.xml,v 1.1 2003/10/01 14:59:11 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">http://www.i-scream.org</ulink>
      </member>
    </simplelist>
  </refsect1>

</refentry>
Revision:	1.2
Committed:	Thu Oct 2 17:38:03 2003 UTC (20 years, 7 months ago) by tdb
Content type:	text/xml
Branch:	MAIN
CVS Tags:	LIBSTATGRAB_0_9, LIBSTATGRAB_0_8_2, LIBSTATGRAB_0_8_1, LIBSTATGRAB_0_8, LIBSTATGRAB_0_7, LIBSTATGRAB_0_6_1, LIBSTATGRAB_0_6
Changes since 1.1:	+11 -3 lines
Log Message:	Add a central page statgrab(3) which links all the functions together. Add a link in the See Also section of each manual page back to the central one.
#	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.2	<date>$Date: 2003/10/01 14:59:11 $</date>
10			<releaseinfo>$Id: cpu_percent_usage.xml,v 1.1 2003/10/01 14:59:11 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			<ulink url="http://www.i-scream.org">http://www.i-scream.org</ulink>
165			</member>
166			</simplelist>
167			</refsect1>
168
169			</refentry>