libstatgrab/docs/sg_get_process_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_process_stats">

  <refentryinfo>
    <date>$Date: 2004/05/18 14:33:11 $</date>
    <releaseinfo>$Id: sg_get_process_stats.xml,v 1.9 2004/05/18 14:33:11 pajs Exp $</releaseinfo>
  </refentryinfo>

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

  <refnamediv>
    <refname>sg_get_process_stats</refname>
    <refname>sg_get_process_count</refname>
    <refname>sg_process_compare_name</refname>
    <refname>sg_process_compare_pid</refname>
    <refname>sg_process_compare_uid</refname>
    <refname>sg_process_compare_gid</refname>
    <refname>sg_process_compare_size</refname>
    <refname>sg_process_compare_res</refname>
    <refname>sg_process_compare_cpu</refname>
    <refname>sg_process_compare_time</refname>
    <refpurpose>get process statistics</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;statgrab.h&gt;</funcsynopsisinfo>
      <funcprototype>
        <funcdef>sg_process_stats *<function>sg_get_process_stats</function></funcdef>
        <paramdef>int *<parameter>entries</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>sg_process_count *<function>sg_get_process_count</function></funcdef>
        <void/>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sg_process_compare_name</function></funcdef>
        <paramdef>const void *<parameter>va</parameter></paramdef>
        <paramdef>const void *<parameter>vb</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>int <function>sg_process_compare_pid</function></funcdef>
        <paramdef>const void *<parameter>va</parameter></paramdef>
        <paramdef>const void *<parameter>vb</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>int <function>sg_process_compare_uid</function></funcdef>
        <paramdef>const void *<parameter>va</parameter></paramdef>
        <paramdef>const void *<parameter>vb</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>int <function>sg_process_compare_gid</function></funcdef>
        <paramdef>const void *<parameter>va</parameter></paramdef>
        <paramdef>const void *<parameter>vb</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>int <function>sg_process_compare_size</function></funcdef>
        <paramdef>const void *<parameter>va</parameter></paramdef>
        <paramdef>const void *<parameter>vb</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>int <function>sg_process_compare_res</function></funcdef>
        <paramdef>const void *<parameter>va</parameter></paramdef>
        <paramdef>const void *<parameter>vb</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>int <function>sg_process_compare_cpu</function></funcdef>
        <paramdef>const void *<parameter>va</parameter></paramdef>
        <paramdef>const void *<parameter>vb</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>int <function>sg_process_compare_time</function></funcdef>
        <paramdef>const void *<parameter>va</parameter></paramdef>
        <paramdef>const void *<parameter>vb</parameter></paramdef>
      </funcprototype>

    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      The <function>sg_get_process_stats</function> takes a pointer to
      an int, <parameter>entries</parameter>, which is filled with the
      number of processes the snapshot contains. The return value is a
      pointer to the first member of an array of
      <structname>sg_process_stats</structname> structures; the number
      of entries in the array is returned in
      <parameter>entries</parameter>.
    </para>
    <para>
      <function>sg_get_process_count</function> returns a pointer to a
      static buffer of type <structname>sg_process_count</structname>.
    </para>
    <para>
      These two functions provide information on the process running
      on the system. In the first case lots of detail is provided, and
      in the second case a summary of the states of the current processes.
    </para>
    <para>
      <simplelist type="vert">
        <member><function>sg_process_compare_name</function></member>
        <member><function>sg_process_compare_pid</function></member>
        <member><function>sg_process_compare_uid</function></member>
        <member><function>sg_process_compare_gid</function></member>
        <member><function>sg_process_compare_size</function></member>
        <member><function>sg_process_compare_res</function></member>
        <member><function>sg_process_compare_cpu</function></member>
        <member><function>sg_process_compare_time</function></member>
      </simplelist>
    </para>
    <para>
      These functions compare two sg_process_stats entries, and return an 
      int to represent which one is greater. The main use of these functions
      is to be passed to qsort to sort the sg_process_stats by the given type.
    </para>
    <para> 
      For example: 
    </para>
    <para>
        <function>qsort</function>(<structname>sg_process_stats</structname> ps, int ps_size, sizeof *ps, sg_process_compare_pid);
    </para>

  </refsect1>

  <refsect1>
    <title>Return Values</title>

    <para>
      The structure returned by sg_get_process_stats is of type
      <structname>sg_process_stats</structname>.
    </para>

    <programlisting>
typedef struct {
        char *process_name;
        char *proctitle;

        pid_t pid;
        pid_t parent; /* Parent pid */
        pid_t pgid;   /* process id of process group leader */

        uid_t uid;
        uid_t euid;
        gid_t gid;
        gid_t egid;

        unsigned long long proc_size; /* in bytes */
        unsigned long long proc_resident; /* in bytes */
        time_t time_spent; /* time running in seconds */
        double cpu_percent;
        int nice;
        sg_process_state state;
} sg_process_stats;
    </programlisting>

    <programlisting>
typedef enum {
        SG_PROCESS_STATE_RUNNING,
        SG_PROCESS_STATE_SLEEPING,
        SG_PROCESS_STATE_STOPPED,
        SG_PROCESS_STATE_ZOMBIE,
        SG_PROCESS_STATE_UNKNOWN
} sg_process_state;
    </programlisting>

    <variablelist>
      <varlistentry>
        <term><structfield>process_name</structfield></term>
        <listitem>
          <para>
            The name of the command that was run.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><structfield>proctitle</structfield></term>
        <listitem>
          <para>
            The command line (the "title") of the process. Take
            note - this can be modified by the process, so isn't
            guaranteed to be the original command line.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><structfield>pid</structfield></term>
        <listitem>
          <para>
            The process ID.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><structfield>parent</structfield></term>
        <listitem>
          <para>
            The parent process ID.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><structfield>pgid</structfield></term>
        <listitem>
          <para>
            The process ID of the process group leader.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><structfield>uid</structfield></term>
        <listitem>
          <para>
            The UID the process is running as.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><structfield>euid</structfield></term>
        <listitem>
          <para>
            The effective UID the process is running as.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><structfield>gid</structfield></term>
        <listitem>
          <para>
            The GID the process is running as.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><structfield>egid</structfield></term>
        <listitem>
          <para>
            The effective GID the process is running as.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><structfield>proc_size</structfield></term>
        <listitem>
          <para>
            The size of the process in bytes.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><structfield>proc_resident</structfield></term>
        <listitem>
          <para>
            The size of the process that's resident in memory.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><structfield>time_spent</structfield></term>
        <listitem>
          <para>
            The number of seconds the process has been running.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><structfield>cpu_percent</structfield></term>
        <listitem>
          <para>
            The current percentage of CPU the process is using.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><structfield>nice</structfield></term>
        <listitem>
          <para>
            The nice value of the process.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><structfield>state</structfield></term>
        <listitem>
          <para>
            The current state of the process. See sg_process_state
            for permitted values.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>
      The structure returned by sg_get_process_count is of type
      <structname>sg_process_count</structname>.
    </para>

    <programlisting>
typedef struct{
        int total;
        int running;
        int sleeping;
        int stopped;
        int zombie;
}sg_process_count;
    </programlisting>

    <variablelist>
      <varlistentry>
        <term><structfield>total</structfield></term>
        <listitem>
          <para>
            The total number of processes.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><structfield>running</structfield></term>
        <listitem>
          <para>
            The number of running processes.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><structfield>sleeping</structfield></term>
        <listitem>
          <para>
            The number of sleeping processes.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><structfield>stopped</structfield></term>
        <listitem>
          <para>
            The number of stopped processes.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><structfield>zombie</structfield></term>
        <listitem>
          <para>
            The number of zombie processes.
          </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.10
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.9:	+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.7	<refentry id="sg_get_process_stats">
7	tdb	1.1
8			<refentryinfo>
9	tdb	1.10	<date>$Date: 2004/05/18 14:33:11 $</date>
10			<releaseinfo>$Id: sg_get_process_stats.xml,v 1.9 2004/05/18 14:33:11 pajs Exp $</releaseinfo>
11	tdb	1.1	</refentryinfo>
12	tdb	1.5
13	tdb	1.1	<refmeta>
14	tdb	1.7	<refentrytitle>sg_get_process_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.7	<refname>sg_get_process_stats</refname>
21	tdb	1.5	<refname>sg_get_process_count</refname>
22	pajs	1.9	<refname>sg_process_compare_name</refname>
23			<refname>sg_process_compare_pid</refname>
24			<refname>sg_process_compare_uid</refname>
25			<refname>sg_process_compare_gid</refname>
26			<refname>sg_process_compare_size</refname>
27			<refname>sg_process_compare_res</refname>
28			<refname>sg_process_compare_cpu</refname>
29			<refname>sg_process_compare_time</refname>
30	tdb	1.1	<refpurpose>get process statistics</refpurpose>
31			</refnamediv>
32	tdb	1.5
33	tdb	1.1	<refsynopsisdiv>
34			<funcsynopsis>
35			<funcsynopsisinfo>#include <statgrab.h></funcsynopsisinfo>
36			<funcprototype>
37	tdb	1.7	<funcdef>sg_process_stats *<function>sg_get_process_stats</function></funcdef>
38			<paramdef>int *<parameter>entries</parameter></paramdef>
39			</funcprototype>
40			<funcprototype>
41	tdb	1.5	<funcdef>sg_process_count *<function>sg_get_process_count</function></funcdef>
42	tdb	1.1	<void/>
43			</funcprototype>
44	pajs	1.9
45			<funcprototype>
46			<funcdef>int <function>sg_process_compare_name</function></funcdef>
47			<paramdef>const void *<parameter>va</parameter></paramdef>
48			<paramdef>const void *<parameter>vb</parameter></paramdef>
49			</funcprototype>
50			<funcprototype>
51			<funcdef>int <function>sg_process_compare_pid</function></funcdef>
52			<paramdef>const void *<parameter>va</parameter></paramdef>
53			<paramdef>const void *<parameter>vb</parameter></paramdef>
54			</funcprototype>
55			<funcprototype>
56			<funcdef>int <function>sg_process_compare_uid</function></funcdef>
57			<paramdef>const void *<parameter>va</parameter></paramdef>
58			<paramdef>const void *<parameter>vb</parameter></paramdef>
59			</funcprototype>
60			<funcprototype>
61			<funcdef>int <function>sg_process_compare_gid</function></funcdef>
62			<paramdef>const void *<parameter>va</parameter></paramdef>
63			<paramdef>const void *<parameter>vb</parameter></paramdef>
64			</funcprototype>
65			<funcprototype>
66			<funcdef>int <function>sg_process_compare_size</function></funcdef>
67			<paramdef>const void *<parameter>va</parameter></paramdef>
68			<paramdef>const void *<parameter>vb</parameter></paramdef>
69			</funcprototype>
70			<funcprototype>
71			<funcdef>int <function>sg_process_compare_res</function></funcdef>
72			<paramdef>const void *<parameter>va</parameter></paramdef>
73			<paramdef>const void *<parameter>vb</parameter></paramdef>
74			</funcprototype>
75			<funcprototype>
76			<funcdef>int <function>sg_process_compare_cpu</function></funcdef>
77			<paramdef>const void *<parameter>va</parameter></paramdef>
78			<paramdef>const void *<parameter>vb</parameter></paramdef>
79			</funcprototype>
80			<funcprototype>
81			<funcdef>int <function>sg_process_compare_time</function></funcdef>
82			<paramdef>const void *<parameter>va</parameter></paramdef>
83			<paramdef>const void *<parameter>vb</parameter></paramdef>
84			</funcprototype>
85
86	tdb	1.1	</funcsynopsis>
87			</refsynopsisdiv>
88	tdb	1.5
89	tdb	1.1	<refsect1>
90			<title>Description</title>
91			<para>
92	tdb	1.7	The <function>sg_get_process_stats</function> takes a pointer to
93			an int, <parameter>entries</parameter>, which is filled with the
94	tdb	1.8	number of processes the snapshot contains. The return value is a
95			pointer to the first member of an array of
96			<structname>sg_process_stats</structname> structures; the number
97			of entries in the array is returned in
98			<parameter>entries</parameter>.
99	tdb	1.7	</para>
100			<para>
101	tdb	1.5	<function>sg_get_process_count</function> returns a pointer to a
102			static buffer of type <structname>sg_process_count</structname>.
103	tdb	1.1	</para>
104			<para>
105	tdb	1.7	These two functions provide information on the process running
106			on the system. In the first case lots of detail is provided, and
107			in the second case a summary of the states of the current processes.
108	tdb	1.1	</para>
109	pajs	1.9	<para>
110			<simplelist type="vert">
111			<member><function>sg_process_compare_name</function></member>
112			<member><function>sg_process_compare_pid</function></member>
113			<member><function>sg_process_compare_uid</function></member>
114			<member><function>sg_process_compare_gid</function></member>
115			<member><function>sg_process_compare_size</function></member>
116			<member><function>sg_process_compare_res</function></member>
117			<member><function>sg_process_compare_cpu</function></member>
118			<member><function>sg_process_compare_time</function></member>
119			</simplelist>
120			</para>
121			<para>
122			These functions compare two sg_process_stats entries, and return an
123			int to represent which one is greater. The main use of these functions
124			is to be passed to qsort to sort the sg_process_stats by the given type.
125			</para>
126			<para>
127			For example:
128			</para>
129			<para>
130			<function>qsort</function>(<structname>sg_process_stats</structname> ps, int ps_size, sizeof *ps, sg_process_compare_pid);
131			</para>
132
133	tdb	1.1	</refsect1>
134	tdb	1.5
135	tdb	1.1	<refsect1>
136			<title>Return Values</title>
137
138			<para>
139	tdb	1.7	The structure returned by sg_get_process_stats is of type
140			<structname>sg_process_stats</structname>.
141			</para>
142
143			<programlisting>
144			typedef struct {
145			char *process_name;
146			char *proctitle;
147
148			pid_t pid;
149			pid_t parent; /* Parent pid */
150			pid_t pgid; /* process id of process group leader */
151
152			uid_t uid;
153			uid_t euid;
154			gid_t gid;
155			gid_t egid;
156
157			unsigned long long proc_size; /* in bytes */
158			unsigned long long proc_resident; /* in bytes */
159			time_t time_spent; /* time running in seconds */
160			double cpu_percent;
161			int nice;
162			sg_process_state state;
163			} sg_process_stats;
164			</programlisting>
165
166			<programlisting>
167			typedef enum {
168			SG_PROCESS_STATE_RUNNING,
169			SG_PROCESS_STATE_SLEEPING,
170			SG_PROCESS_STATE_STOPPED,
171			SG_PROCESS_STATE_ZOMBIE,
172			SG_PROCESS_STATE_UNKNOWN
173			} sg_process_state;
174			</programlisting>
175
176			<variablelist>
177			<varlistentry>
178			<term><structfield>process_name</structfield></term>
179			<listitem>
180			<para>
181			The name of the command that was run.
182			</para>
183			</listitem>
184			</varlistentry>
185			<varlistentry>
186			<term><structfield>proctitle</structfield></term>
187			<listitem>
188			<para>
189			The command line (the "title") of the process. Take
190			note - this can be modified by the process, so isn't
191			guaranteed to be the original command line.
192			</para>
193			</listitem>
194			</varlistentry>
195			<varlistentry>
196			<term><structfield>pid</structfield></term>
197			<listitem>
198			<para>
199			The process ID.
200			</para>
201			</listitem>
202			</varlistentry>
203			<varlistentry>
204			<term><structfield>parent</structfield></term>
205			<listitem>
206			<para>
207			The parent process ID.
208			</para>
209			</listitem>
210			</varlistentry>
211			<varlistentry>
212			<term><structfield>pgid</structfield></term>
213			<listitem>
214			<para>
215			The process ID of the process group leader.
216			</para>
217			</listitem>
218			</varlistentry>
219			<varlistentry>
220			<term><structfield>uid</structfield></term>
221			<listitem>
222			<para>
223			The UID the process is running as.
224			</para>
225			</listitem>
226			</varlistentry>
227			<varlistentry>
228			<term><structfield>euid</structfield></term>
229			<listitem>
230			<para>
231			The effective UID the process is running as.
232			</para>
233			</listitem>
234			</varlistentry>
235			<varlistentry>
236			<term><structfield>gid</structfield></term>
237			<listitem>
238			<para>
239			The GID the process is running as.
240			</para>
241			</listitem>
242			</varlistentry>
243			<varlistentry>
244			<term><structfield>egid</structfield></term>
245			<listitem>
246			<para>
247			The effective GID the process is running as.
248			</para>
249			</listitem>
250			</varlistentry>
251			<varlistentry>
252			<term><structfield>proc_size</structfield></term>
253			<listitem>
254			<para>
255			The size of the process in bytes.
256			</para>
257			</listitem>
258			</varlistentry>
259			<varlistentry>
260			<term><structfield>proc_resident</structfield></term>
261			<listitem>
262			<para>
263			The size of the process that's resident in memory.
264			</para>
265			</listitem>
266			</varlistentry>
267			<varlistentry>
268			<term><structfield>time_spent</structfield></term>
269			<listitem>
270			<para>
271			The number of seconds the process has been running.
272			</para>
273			</listitem>
274			</varlistentry>
275			<varlistentry>
276			<term><structfield>cpu_percent</structfield></term>
277			<listitem>
278			<para>
279			The current percentage of CPU the process is using.
280			</para>
281			</listitem>
282			</varlistentry>
283			<varlistentry>
284			<term><structfield>nice</structfield></term>
285			<listitem>
286			<para>
287			The nice value of the process.
288			</para>
289			</listitem>
290			</varlistentry>
291			<varlistentry>
292			<term><structfield>state</structfield></term>
293			<listitem>
294			<para>
295			The current state of the process. See sg_process_state
296			for permitted values.
297			</para>
298			</listitem>
299			</varlistentry>
300			</variablelist>
301
302			<para>
303			The structure returned by sg_get_process_count is of type
304	tdb	1.5	<structname>sg_process_count</structname>.
305	tdb	1.1	</para>
306
307			<programlisting>
308			typedef struct{
309			int total;
310			int running;
311			int sleeping;
312			int stopped;
313			int zombie;
314	tdb	1.5	}sg_process_count;
315	tdb	1.1	</programlisting>
316
317			<variablelist>
318			<varlistentry>
319			<term><structfield>total</structfield></term>
320			<listitem>
321			<para>
322			The total number of processes.
323			</para>
324			</listitem>
325			</varlistentry>
326			<varlistentry>
327			<term><structfield>running</structfield></term>
328			<listitem>
329			<para>
330			The number of running processes.
331			</para>
332			</listitem>
333			</varlistentry>
334			<varlistentry>
335			<term><structfield>sleeping</structfield></term>
336			<listitem>
337			<para>
338			The number of sleeping processes.
339			</para>
340			</listitem>
341			</varlistentry>
342			<varlistentry>
343			<term><structfield>stopped</structfield></term>
344			<listitem>
345			<para>
346			The number of stopped processes.
347			</para>
348			</listitem>
349			</varlistentry>
350			<varlistentry>
351			<term><structfield>zombie</structfield></term>
352			<listitem>
353			<para>
354			The number of zombie processes.
355			</para>
356			</listitem>
357			</varlistentry>
358			</variablelist>
359			</refsect1>
360
361			<refsect1>
362			<title>See Also</title>
363	tdb	1.2
364			<simplelist type="inline">
365			<member>
366			<citerefentry>
367			<refentrytitle>statgrab</refentrytitle>
368			<manvolnum>3</manvolnum>
369			</citerefentry>
370			</member>
371			</simplelist>
372	tdb	1.1	</refsect1>
373	tdb	1.5
374	tdb	1.1	<refsect1>
375			<title>Website</title>
376	tdb	1.5
377	tdb	1.1	<simplelist type="vert">
378			<member>
379	tdb	1.3	<ulink url="http://www.i-scream.org/libstatgrab/">
380			http://www.i-scream.org/libstatgrab/
381			</ulink>
382	tdb	1.1	</member>
383			</simplelist>
384			</refsect1>
385
386			</refentry>