docs/libstatgrab/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/04 19:28:06 $</date>
    <releaseinfo>$Id: sg_get_process_stats.xml,v 1.7 2004/05/04 19:28:06 tdb 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>
    <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>
    </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>
  </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.8
Committed:	Sat May 8 16:27:13 2004 UTC (20 years ago) by tdb
Content type:	text/xml
Branch:	MAIN
Changes since 1.7:	+7 -6 lines
Log Message:	Reword some bits about the entries parameter.
#	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.8	<date>$Date: 2004/05/04 19:28:06 $</date>
10			<releaseinfo>$Id: sg_get_process_stats.xml,v 1.7 2004/05/04 19:28:06 tdb 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	tdb	1.1	<refpurpose>get process statistics</refpurpose>
23			</refnamediv>
24	tdb	1.5
25	tdb	1.1	<refsynopsisdiv>
26			<funcsynopsis>
27			<funcsynopsisinfo>#include <statgrab.h></funcsynopsisinfo>
28			<funcprototype>
29	tdb	1.7	<funcdef>sg_process_stats *<function>sg_get_process_stats</function></funcdef>
30			<paramdef>int *<parameter>entries</parameter></paramdef>
31			</funcprototype>
32			<funcprototype>
33	tdb	1.5	<funcdef>sg_process_count *<function>sg_get_process_count</function></funcdef>
34	tdb	1.1	<void/>
35			</funcprototype>
36			</funcsynopsis>
37			</refsynopsisdiv>
38	tdb	1.5
39	tdb	1.1	<refsect1>
40			<title>Description</title>
41			<para>
42	tdb	1.7	The <function>sg_get_process_stats</function> takes a pointer to
43			an int, <parameter>entries</parameter>, which is filled with the
44	tdb	1.8	number of processes the snapshot contains. The return value is a
45			pointer to the first member of an array of
46			<structname>sg_process_stats</structname> structures; the number
47			of entries in the array is returned in
48			<parameter>entries</parameter>.
49	tdb	1.7	</para>
50			<para>
51	tdb	1.5	<function>sg_get_process_count</function> returns a pointer to a
52			static buffer of type <structname>sg_process_count</structname>.
53	tdb	1.1	</para>
54			<para>
55	tdb	1.7	These two functions provide information on the process running
56			on the system. In the first case lots of detail is provided, and
57			in the second case a summary of the states of the current processes.
58	tdb	1.1	</para>
59			</refsect1>
60	tdb	1.5
61	tdb	1.1	<refsect1>
62			<title>Return Values</title>
63
64			<para>
65	tdb	1.7	The structure returned by sg_get_process_stats is of type
66			<structname>sg_process_stats</structname>.
67			</para>
68
69			<programlisting>
70			typedef struct {
71			char *process_name;
72			char *proctitle;
73
74			pid_t pid;
75			pid_t parent; /* Parent pid */
76			pid_t pgid; /* process id of process group leader */
77
78			uid_t uid;
79			uid_t euid;
80			gid_t gid;
81			gid_t egid;
82
83			unsigned long long proc_size; /* in bytes */
84			unsigned long long proc_resident; /* in bytes */
85			time_t time_spent; /* time running in seconds */
86			double cpu_percent;
87			int nice;
88			sg_process_state state;
89			} sg_process_stats;
90			</programlisting>
91
92			<programlisting>
93			typedef enum {
94			SG_PROCESS_STATE_RUNNING,
95			SG_PROCESS_STATE_SLEEPING,
96			SG_PROCESS_STATE_STOPPED,
97			SG_PROCESS_STATE_ZOMBIE,
98			SG_PROCESS_STATE_UNKNOWN
99			} sg_process_state;
100			</programlisting>
101
102			<variablelist>
103			<varlistentry>
104			<term><structfield>process_name</structfield></term>
105			<listitem>
106			<para>
107			The name of the command that was run.
108			</para>
109			</listitem>
110			</varlistentry>
111			<varlistentry>
112			<term><structfield>proctitle</structfield></term>
113			<listitem>
114			<para>
115			The command line (the "title") of the process. Take
116			note - this can be modified by the process, so isn't
117			guaranteed to be the original command line.
118			</para>
119			</listitem>
120			</varlistentry>
121			<varlistentry>
122			<term><structfield>pid</structfield></term>
123			<listitem>
124			<para>
125			The process ID.
126			</para>
127			</listitem>
128			</varlistentry>
129			<varlistentry>
130			<term><structfield>parent</structfield></term>
131			<listitem>
132			<para>
133			The parent process ID.
134			</para>
135			</listitem>
136			</varlistentry>
137			<varlistentry>
138			<term><structfield>pgid</structfield></term>
139			<listitem>
140			<para>
141			The process ID of the process group leader.
142			</para>
143			</listitem>
144			</varlistentry>
145			<varlistentry>
146			<term><structfield>uid</structfield></term>
147			<listitem>
148			<para>
149			The UID the process is running as.
150			</para>
151			</listitem>
152			</varlistentry>
153			<varlistentry>
154			<term><structfield>euid</structfield></term>
155			<listitem>
156			<para>
157			The effective UID the process is running as.
158			</para>
159			</listitem>
160			</varlistentry>
161			<varlistentry>
162			<term><structfield>gid</structfield></term>
163			<listitem>
164			<para>
165			The GID the process is running as.
166			</para>
167			</listitem>
168			</varlistentry>
169			<varlistentry>
170			<term><structfield>egid</structfield></term>
171			<listitem>
172			<para>
173			The effective GID the process is running as.
174			</para>
175			</listitem>
176			</varlistentry>
177			<varlistentry>
178			<term><structfield>proc_size</structfield></term>
179			<listitem>
180			<para>
181			The size of the process in bytes.
182			</para>
183			</listitem>
184			</varlistentry>
185			<varlistentry>
186			<term><structfield>proc_resident</structfield></term>
187			<listitem>
188			<para>
189			The size of the process that's resident in memory.
190			</para>
191			</listitem>
192			</varlistentry>
193			<varlistentry>
194			<term><structfield>time_spent</structfield></term>
195			<listitem>
196			<para>
197			The number of seconds the process has been running.
198			</para>
199			</listitem>
200			</varlistentry>
201			<varlistentry>
202			<term><structfield>cpu_percent</structfield></term>
203			<listitem>
204			<para>
205			The current percentage of CPU the process is using.
206			</para>
207			</listitem>
208			</varlistentry>
209			<varlistentry>
210			<term><structfield>nice</structfield></term>
211			<listitem>
212			<para>
213			The nice value of the process.
214			</para>
215			</listitem>
216			</varlistentry>
217			<varlistentry>
218			<term><structfield>state</structfield></term>
219			<listitem>
220			<para>
221			The current state of the process. See sg_process_state
222			for permitted values.
223			</para>
224			</listitem>
225			</varlistentry>
226			</variablelist>
227
228			<para>
229			The structure returned by sg_get_process_count is of type
230	tdb	1.5	<structname>sg_process_count</structname>.
231	tdb	1.1	</para>
232
233			<programlisting>
234			typedef struct{
235			int total;
236			int running;
237			int sleeping;
238			int stopped;
239			int zombie;
240	tdb	1.5	}sg_process_count;
241	tdb	1.1	</programlisting>
242
243			<variablelist>
244			<varlistentry>
245			<term><structfield>total</structfield></term>
246			<listitem>
247			<para>
248			The total number of processes.
249			</para>
250			</listitem>
251			</varlistentry>
252			<varlistentry>
253			<term><structfield>running</structfield></term>
254			<listitem>
255			<para>
256			The number of running processes.
257			</para>
258			</listitem>
259			</varlistentry>
260			<varlistentry>
261			<term><structfield>sleeping</structfield></term>
262			<listitem>
263			<para>
264			The number of sleeping processes.
265			</para>
266			</listitem>
267			</varlistentry>
268			<varlistentry>
269			<term><structfield>stopped</structfield></term>
270			<listitem>
271			<para>
272			The number of stopped processes.
273			</para>
274			</listitem>
275			</varlistentry>
276			<varlistentry>
277			<term><structfield>zombie</structfield></term>
278			<listitem>
279			<para>
280			The number of zombie processes.
281			</para>
282			</listitem>
283			</varlistentry>
284			</variablelist>
285			</refsect1>
286
287			<refsect1>
288			<title>See Also</title>
289	tdb	1.2
290			<simplelist type="inline">
291			<member>
292			<citerefentry>
293			<refentrytitle>statgrab</refentrytitle>
294			<manvolnum>3</manvolnum>
295			</citerefentry>
296			</member>
297			</simplelist>
298	tdb	1.1	</refsect1>
299	tdb	1.5
300	tdb	1.1	<refsect1>
301			<title>Website</title>
302	tdb	1.5
303	tdb	1.1	<simplelist type="vert">
304			<member>
305	tdb	1.3	<ulink url="http://www.i-scream.org/libstatgrab/">
306			http://www.i-scream.org/libstatgrab/
307			</ulink>
308	tdb	1.1	</member>
309			</simplelist>
310			</refsect1>
311
312			</refentry>