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="sg_get_cpu_stats">

  <refentryinfo>
    <date>$Date: 2004/05/02 17:39:19 $</date>
    <releaseinfo>$Id: sg_get_cpu_stats.xml,v 1.6 2004/05/02 17:39:19 tdb Exp $</releaseinfo>
  </refentryinfo>

  <refmeta>
    <refentrytitle>sg_get_cpu_stats</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo>i-scream</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>sg_get_cpu_stats</refname>
    <refname>sg_get_cpu_stats_diff</refname>
    <refname>sg_get_cpu_percents</refname>
    <refpurpose>get cpu usage</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;statgrab.h&gt;</funcsynopsisinfo>
      <funcprototype>
        <funcdef>sg_cpu_percents *<function>sg_get_cpu_percents</function></funcdef>
        <void/>
      </funcprototype>
      <funcprototype>
        <funcdef>sg_cpu_stats *<function>sg_get_cpu_stats</function></funcdef>
        <void/>
      </funcprototype>
      <funcprototype>
        <funcdef>sg_cpu_stats *<function>sg_get_cpu_stats_diff</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      <function>sg_get_cpu_stats()</function> and
      <function>sg_get_cpu_stats_diff()</function> both return static pointers
      of type <structname>sg_cpu_stats</structname>.
      <function>sg_get_cpu_stats()</function> returns the total amount of
      "ticks" the operating system has spent in each of the different
      states. <function>sg_get_cpu_stats_diff()</function> returns the
      difference in "ticks" for each of the states since last time
      <function>sg_get_cpu_stats_diff()</function> or
      <function>sg_get_cpu_stats()</function> was called. If it has never
      been called, it will return the result of
      <function>sg_get_cpu_stats()</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>sg_get_cpu_percents()</function> returns a pointer to a
      static <structname>sg_cpu_percents</structname>.  The function
      calls <function>sg_get_cpu_stats_diff()</function> and changes the values
      into percentages. If it has never been called before (and nor has
      <function>sg_get_cpu_stats()</function> or
      <function>sg_get_cpu_stats_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;
}sg_cpu_stats;
    </programlisting>

    <programlisting>
typedef struct{
        float user;
        float kernel;
        float idle;
        float iowait;
        float swap;
        float nice;
        time_t time_taken;
}sg_cpu_percents;
    </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.7
Committed:	Mon Apr 25 11:25:47 2005 UTC (19 years ago) by tdb
Content type:	text/xml
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.6:	+2 -2 lines
State:	*FILE REMOVED*
Log Message:	Move by repocopy the libstatgrab docs in to a subdirectory. This is so I can create separate directories for statgrab/saidar docs.
#	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	tdb	1.5	<refentry id="sg_get_cpu_stats">
7	tdb	1.1
8			<refentryinfo>
9	tdb	1.7	<date>$Date: 2004/05/02 17:39:19 $</date>
10			<releaseinfo>$Id: sg_get_cpu_stats.xml,v 1.6 2004/05/02 17:39:19 tdb Exp $</releaseinfo>
11	tdb	1.1	</refentryinfo>
12	tdb	1.5
13	tdb	1.1	<refmeta>
14	tdb	1.5	<refentrytitle>sg_get_cpu_stats</refentrytitle>
15	tdb	1.1	<manvolnum>3</manvolnum>
16			<refmiscinfo>i-scream</refmiscinfo>
17			</refmeta>
18	tdb	1.5
19	tdb	1.1	<refnamediv>
20	tdb	1.5	<refname>sg_get_cpu_stats</refname>
21			<refname>sg_get_cpu_stats_diff</refname>
22	tdb	1.6	<refname>sg_get_cpu_percents</refname>
23	tdb	1.1	<refpurpose>get cpu usage</refpurpose>
24			</refnamediv>
25	tdb	1.5
26	tdb	1.1	<refsynopsisdiv>
27			<funcsynopsis>
28			<funcsynopsisinfo>#include <statgrab.h></funcsynopsisinfo>
29			<funcprototype>
30	tdb	1.5	<funcdef>sg_cpu_percents *<function>sg_get_cpu_percents</function></funcdef>
31	tdb	1.1	<void/>
32			</funcprototype>
33			<funcprototype>
34	tdb	1.5	<funcdef>sg_cpu_stats *<function>sg_get_cpu_stats</function></funcdef>
35	tdb	1.1	<void/>
36			</funcprototype>
37			<funcprototype>
38	tdb	1.5	<funcdef>sg_cpu_stats *<function>sg_get_cpu_stats_diff</function></funcdef>
39	tdb	1.1	<void/>
40			</funcprototype>
41			</funcsynopsis>
42			</refsynopsisdiv>
43	tdb	1.5
44	tdb	1.1	<refsect1>
45			<title>Description</title>
46			<para>
47	tdb	1.5	<function>sg_get_cpu_stats()</function> and
48			<function>sg_get_cpu_stats_diff()</function> both return static pointers
49			of type <structname>sg_cpu_stats</structname>.
50			<function>sg_get_cpu_stats()</function> returns the total amount of
51	tdb	1.1	"ticks" the operating system has spent in each of the different
52	tdb	1.5	states. <function>sg_get_cpu_stats_diff()</function> returns the
53	tdb	1.1	difference in "ticks" for each of the states since last time
54	tdb	1.5	<function>sg_get_cpu_stats_diff()</function> or
55			<function>sg_get_cpu_stats()</function> was called. If it has never
56	tdb	1.1	been called, it will return the result of
57	tdb	1.5	<function>sg_get_cpu_stats()</function>.
58	tdb	1.1	</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	tdb	1.5	<function>sg_get_cpu_percents()</function> returns a pointer to a
72			static <structname>sg_cpu_percents</structname>. The function
73			calls <function>sg_get_cpu_stats_diff()</function> and changes the values
74	tdb	1.1	into percentages. If it has never been called before (and nor has
75	tdb	1.5	<function>sg_get_cpu_stats()</function> or
76			<function>sg_get_cpu_stats_diff()</function>), the returned percentages
77	tdb	1.1	will be the systems total ever since its uptime. (Unless the
78			counters have cycled)
79			</para>
80			</refsect1>
81	tdb	1.5
82	tdb	1.1	<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	tdb	1.5	}sg_cpu_stats;
101	tdb	1.1	</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	tdb	1.5	}sg_cpu_percents;
113	tdb	1.1	</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	tdb	1.5
159	tdb	1.1	<refsect1>
160			<title>Website</title>
161	tdb	1.5
162	tdb	1.1	<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>