--- projects/libstatgrab/docs/sg_get_process_stats.xml	2004/05/02 17:39:19	1.6
+++ projects/libstatgrab/docs/sg_get_process_stats.xml	2004/05/04 19:28:06	1.7
@@ -3,20 +3,21 @@
 <!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_count">
+<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>
+    <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_count</refentrytitle>
+    <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>
@@ -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,21 @@
   <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>
-      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 +61,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>