--- projects/libstatgrab/docs/statgrab.xml	2003/10/02 17:38:03	1.1
+++ projects/libstatgrab/docs/statgrab.xml	2004/03/06 23:35:20	1.6
@@ -6,8 +6,8 @@
 <refentry id="statgrab">
 
   <refentryinfo>
-    <date>$Date: 2003/10/02 17:38:03 $</date>
-    <releaseinfo>$Id: statgrab.xml,v 1.1 2003/10/02 17:38:03 tdb Exp $</releaseinfo>
+    <date>$Date: 2004/03/06 23:35:20 $</date>
+    <releaseinfo>$Id: statgrab.xml,v 1.6 2004/03/06 23:35:20 tdb Exp $</releaseinfo>
   </refentryinfo>
   
   <refmeta>
@@ -26,6 +26,15 @@
       <funcsynopsisinfo>#include &lt;statgrab.h&gt;</funcsynopsisinfo>
 
       <funcprototype>
+        <funcdef>int <function>statgrab_init</function></funcdef>
+        <void/>
+      </funcprototype>
+      <funcprototype>
+        <funcdef>int <function>statgrab_drop_privileges</function></funcdef>
+        <void/>
+      </funcprototype>
+
+      <funcprototype>
         <funcdef>cpu_percent_t *<function>cpu_percent_usage</function></funcdef>
         <void/>
       </funcprototype>
@@ -76,6 +85,11 @@
       </funcprototype>
 
       <funcprototype>
+        <funcdef>network_iface_stat_t *<function>get_network_iface_stats</function></funcdef>
+        <paramdef>int *<parameter>entries</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
         <funcdef>page_stat_t *<function>get_page_stats</function></funcdef>
         <void/>
       </funcprototype>
@@ -100,16 +114,36 @@
   <refsect1>
     <title>Description</title>
     <para>
-      The statgrab library provides a cross platform interface to getting
+      The statgrab library provides a cross-platform interface to getting
       system statistics. Each of the function calls returns a structure
       containing statistics. See the manual page for each individual
       function for more details on usage.
     </para>
     <para>
-      The library was originally written to support the i-scream central
-      monitoring system, but has since become a standalone package. It
-      has been ported to work on Linux, FreeBSD, and Solaris.
+      <function>statgrab_init</function> must be the first
+      function you call before you start to use libstatgrab; it performs all
+      the one-time initialisation operations that need setuid/setgid
+      privileges. For instance, on *BSD it opens a descriptor to be able to
+      read kernel structures later on, and on Solaris it reads the device
+      mappings that in some cases are only accessible by root (machines with
+      a /dev/osa). Once this has run, the other libstatgrab functions no longer 
+      need elevated privileges. It is therefore a good idea to call
+      <function>statgrab_drop_privileges</function>, which discards
+      setuid and setgid privileges, immediately after you call
+      <function>statgrab_init</function>, unless your application has
+      another reason for needing setuid or setgid privileges.
     </para>
+    <para>
+      <function>statgrab_init</function> and
+      <function>statgrab_drop_privileges</function> return 0 on success, and
+      non-zero on failure.
+    </para>
+    <para>
+      The library was originally written to support the i-scream
+      central monitoring system, but has since become a standalone
+      package. It has been ported to work on Linux, NetBSD, FreeBSD,
+      OpenBSD, DragonFly BSD, Solaris and Cygwin.
+    </para>
   </refsect1>
   
   <refsect1>
@@ -139,6 +173,10 @@
         </citerefentry>
         <citerefentry>
           <refentrytitle>get_network_stats</refentrytitle>
+          <manvolnum>3</manvolnum>
+        </citerefentry>
+        <citerefentry>
+          <refentrytitle>get_network_iface_stats</refentrytitle>
           <manvolnum>3</manvolnum>
         </citerefentry>
         <citerefentry>