ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/i-scream/projects/libstatgrab/docs/sg_get_process_stats.xml
(Generate patch)

Comparing projects/libstatgrab/docs/sg_get_process_stats.xml (file contents):
Revision 1.2 by tdb, Thu Oct 2 17:38:03 2003 UTC vs.
Revision 1.9 by pajs, Tue May 18 14:33:11 2004 UTC

# Line 3 | Line 3
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="get_process_stats">
6 > <refentry id="sg_get_process_stats">
7  
8    <refentryinfo>
9      <date>$Date$</date>
10      <releaseinfo>$Id$</releaseinfo>
11    </refentryinfo>
12 <  
12 >
13    <refmeta>
14 <    <refentrytitle>get_process_stats</refentrytitle>
14 >    <refentrytitle>sg_get_process_stats</refentrytitle>
15      <manvolnum>3</manvolnum>
16      <refmiscinfo>i-scream</refmiscinfo>
17    </refmeta>
18 <  
18 >
19    <refnamediv>
20 <    <refname>get_process_stats</refname>
20 >    <refname>sg_get_process_stats</refname>
21 >    <refname>sg_get_process_count</refname>
22 >    <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      <refpurpose>get process statistics</refpurpose>
31    </refnamediv>
32 <    
32 >
33    <refsynopsisdiv>
34      <funcsynopsis>
35        <funcsynopsisinfo>#include &lt;statgrab.h&gt;</funcsynopsisinfo>
36        <funcprototype>
37 <        <funcdef>process_stat_t *<function>get_process_stats</function></funcdef>
37 >        <funcdef>sg_process_stats *<function>sg_get_process_stats</function></funcdef>
38 >        <paramdef>int *<parameter>entries</parameter></paramdef>
39 >      </funcprototype>
40 >      <funcprototype>
41 >        <funcdef>sg_process_count *<function>sg_get_process_count</function></funcdef>
42          <void/>
43        </funcprototype>
44 +
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      </funcsynopsis>
87    </refsynopsisdiv>
88 <    
88 >
89    <refsect1>
90      <title>Description</title>
91      <para>
92 <      <function>get_process_stats</function> returns a pointer to a
93 <      static buffer of type <structname>process_stat_t</structname>.
92 >      The <function>sg_get_process_stats</function> takes a pointer to
93 >      an int, <parameter>entries</parameter>, which is filled with the
94 >      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      </para>
100      <para>
101 <      It provides information on the number of processes and the
102 <      system and the different states they're in.
101 >      <function>sg_get_process_count</function> returns a pointer to a
102 >      static buffer of type <structname>sg_process_count</structname>.
103      </para>
104 +    <para>
105 +      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 +    </para>
109 +    <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    </refsect1>
134 <  
134 >
135    <refsect1>
136      <title>Return Values</title>
137  
138      <para>
139 <      The structure returned is of type
140 <      <structname>process_stat_t</structname>.
139 >      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 +      <structname>sg_process_count</structname>.
305 +    </para>
306 +
307 +    <programlisting>
308   typedef struct{
309          int total;
310          int running;
311          int sleeping;
312          int stopped;
313          int zombie;
314 < }process_stat_t;
314 > }sg_process_count;
315      </programlisting>
316  
317      <variablelist>
# Line 117 | Line 370 | typedef struct{
370        </member>
371      </simplelist>
372    </refsect1>
373 <  
373 >
374    <refsect1>
375      <title>Website</title>
376 <    
376 >
377      <simplelist type="vert">
378        <member>
379 <        <ulink url="http://www.i-scream.org">http://www.i-scream.org</ulink>
379 >        <ulink url="http://www.i-scream.org/libstatgrab/">
380 >          http://www.i-scream.org/libstatgrab/
381 >        </ulink>
382        </member>
383      </simplelist>
384    </refsect1>

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines