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