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

Comparing projects/libstatgrab/docs/statgrab.xml (file contents):
Revision 1.2 by pajs, Tue Oct 21 15:48:55 2003 UTC vs.
Revision 1.5 by pajs, Tue Jan 6 17:15:04 2004 UTC

# Line 29 | Line 29
29          <funcdef>int <function>statgrab_init</function></funcdef>
30          <void/>
31        </funcprototype>
32 +      <funcprototype>
33 +        <funcdef>int <function>statgrab_drop_privileges</function></funcdef>
34 +        <void/>
35 +      </funcprototype>
36  
37        <funcprototype>
38          <funcdef>cpu_percent_t *<function>cpu_percent_usage</function></funcdef>
# Line 105 | Line 109
109    <refsect1>
110      <title>Description</title>
111      <para>
112 <      The statgrab library provides a cross platform interface to getting
112 >      The statgrab library provides a cross-platform interface to getting
113        system statistics. Each of the function calls returns a structure
114        containing statistics. See the manual page for each individual
115        function for more details on usage.
116      </para>
117      <para>
118 <      <function>statgrab_init(void)</function> should be the first
119 <      function you call before you start to use libstatgrab. This
120 <      function on *bsd systems opens up the kernel structures and
121 <      leaves them open for future use. Because of this, any special
122 <      privileges the program has (e.g. setgid kmem) can be dropped
123 <      after this call, and all the libstatgrab calls should continue to
124 <      work.
118 >      <function>statgrab_init</function> must be the first
119 >      function you call before you start to use libstatgrab; it performs all
120 >      the one-time initialisation operations that need setuid/setgid
121 >      privileges. For instance, on *BSD it opens a descriptor to be able to
122 >      read kernel structures later on, and on Solaris it reads the device
123 >      mappings that in some cases are only accessible by root (machines with
124 >      a /dev/osa). Once this has run, the other libstatgrab functions no longer
125 >      need elevated privileges. It is therefore a good idea to call
126 >      <function>statgrab_drop_privileges</function>, which discards
127 >      setuid and setgid privileges, immediately after you call
128 >      <function>statgrab_init</function>, unless your application has
129 >      another reason for needing setuid or setgid privileges.
130      </para>
131      <para>
132 <      <function>statgrab_init</function> returns 0 on success, and
132 >      <function>statgrab_init</function> and
133 >      <function>statgrab_drop_privileges</function> return 0 on success, and
134        non-zero on failure.
135      </para>
136      <para>
137        The library was originally written to support the i-scream central
138        monitoring system, but has since become a standalone package. It
139 <      has been ported to work on Linux, FreeBSD, and Solaris.
139 >      has been ported to work on Linux, NetBSD, FreeBSD, Solaris and Cygwin.
140      </para>
141    </refsect1>
142    

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines