--- projects/libstatgrab/docs/sg_get_process_stats.xml	2004/05/02 17:21:35	1.5
+++ projects/libstatgrab/docs/sg_get_process_stats.xml	2004/05/08 16:27:13	1.8
@@ -6,8 +6,8 @@
 <refentry id="sg_get_process_stats">
 
   <refentryinfo>
-    <date>$Date: 2004/05/02 17:21:35 $</date>
-    <releaseinfo>$Id: sg_get_process_stats.xml,v 1.5 2004/05/02 17:21:35 tdb Exp $</releaseinfo>
+    <date>$Date: 2004/05/08 16:27:13 $</date>
+    <releaseinfo>$Id: sg_get_process_stats.xml,v 1.8 2004/05/08 16:27:13 tdb Exp $</releaseinfo>
   </refentryinfo>
 
   <refmeta>
@@ -17,6 +17,7 @@
   </refmeta>
 
   <refnamediv>
+    <refname>sg_get_process_stats</refname>
     <refname>sg_get_process_count</refname>
     <refpurpose>get process statistics</refpurpose>
   </refnamediv>
@@ -25,6 +26,10 @@
     <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>
@@ -34,12 +39,22 @@
   <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>
-      It provides information on the number of processes and the
-      system and the different states they're in.
+      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>
 
@@ -47,7 +62,171 @@
     <title>Return Values</title>
 
     <para>
-      The structure returned is of type
+      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>