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.11 by tdb, Wed May 5 10:41:42 2004 UTC

# Line 9 | Line 9
9      <date>$Date$</date>
10      <releaseinfo>$Id$</releaseinfo>
11    </refentryinfo>
12 <  
12 >
13    <refmeta>
14      <refentrytitle>statgrab</refentrytitle>
15      <manvolnum>3</manvolnum>
16      <refmiscinfo>i-scream</refmiscinfo>
17    </refmeta>
18 <  
18 >
19    <refnamediv>
20      <refname>statgrab</refname>
21      <refpurpose>get system statistics</refpurpose>
22    </refnamediv>
23 <    
23 >
24    <refsynopsisdiv>
25      <funcsynopsis>
26        <funcsynopsisinfo>#include &lt;statgrab.h&gt;</funcsynopsisinfo>
27  
28        <funcprototype>
29 <        <funcdef>int <function>statgrab_init</function></funcdef>
29 >        <funcdef>int <function>sg_init</function></funcdef>
30          <void/>
31        </funcprototype>
32 +      <funcprototype>
33 +        <funcdef>int <function>sg_drop_privileges</function></funcdef>
34 +        <void/>
35 +      </funcprototype>
36  
37        <funcprototype>
38 <        <funcdef>cpu_percent_t *<function>cpu_percent_usage</function></funcdef>
38 >        <funcdef>sg_error <function>sg_get_error</function></funcdef>
39          <void/>
40        </funcprototype>
41        <funcprototype>
42 <        <funcdef>cpu_states_t *<function>get_cpu_totals</function></funcdef>
42 >        <funcdef>const char *<function>sg_get_error_arg</function></funcdef>
43          <void/>
44        </funcprototype>
45        <funcprototype>
46 <        <funcdef>cpu_states_t *<function>get_cpu_diff</function></funcdef>
46 >        <funcdef>const char *<function>sg_str_error</function></funcdef>
47 >        <paramdef>sg_error <parameter>code</parameter></paramdef>
48 >      </funcprototype>
49 >
50 >      <funcprototype>
51 >        <funcdef>sg_cpu_stats *<function>sg_get_cpu_stats</function></funcdef>
52          <void/>
53        </funcprototype>
54 +      <funcprototype>
55 +        <funcdef>sg_cpu_stats *<function>sg_get_cpu_stats_diff</function></funcdef>
56 +        <void/>
57 +      </funcprototype>
58 +      <funcprototype>
59 +        <funcdef>sg_cpu_percents *<function>sg_get_cpu_percents</function></funcdef>
60 +        <void/>
61 +      </funcprototype>
62  
63        <funcprototype>
64 <        <funcdef>diskio_stat_t *<function>get_diskio_stats</function></funcdef>
64 >        <funcdef>sg_disk_io_stats *<function>sg_get_disk_io_stats</function></funcdef>
65          <paramdef>int *<parameter>entries</parameter></paramdef>
66        </funcprototype>
67        <funcprototype>
68 <        <funcdef>diskio_stat_t *<function>get_diskio_stats_diff</function></funcdef>
68 >        <funcdef>sg_disk_io_stats *<function>sg_get_disk_io_stats_diff</function></funcdef>
69          <paramdef>int *<parameter>entries</parameter></paramdef>
70        </funcprototype>
71  
72        <funcprototype>
73 <        <funcdef>general_stat_t *<function>get_general_stats</function></funcdef>
73 >        <funcdef>sg_fs_stats *<function>sg_get_fs_stats</function></funcdef>
74          <void/>
75        </funcprototype>
76  
77        <funcprototype>
78 <        <funcdef>load_stat_t *<function>get_load_stats</function></funcdef>
78 >        <funcdef>sg_host_info *<function>sg_get_host_info</function></funcdef>
79          <void/>
80        </funcprototype>
81  
82        <funcprototype>
83 <        <funcdef>mem_stat_t *<function>get_memory_stats</function></funcdef>
83 >        <funcdef>sg_load_stats *<function>sg_get_load_stats</function></funcdef>
84          <void/>
85        </funcprototype>
86 +
87        <funcprototype>
88 <        <funcdef>swap_stat_t *<function>get_swap_stats</function></funcdef>
88 >        <funcdef>sg_mem_stats *<function>sg_get_mem_stats</function></funcdef>
89          <void/>
90        </funcprototype>
91 +      <funcprototype>
92 +        <funcdef>sg_swap_stats *<function>sg_get_swap_stats</function></funcdef>
93 +        <void/>
94 +      </funcprototype>
95  
96        <funcprototype>
97 <        <funcdef>network_stat_t *<function>get_network_stats</function></funcdef>
97 >        <funcdef>sg_network_io_stats *<function>sg_get_network_io_stats</function></funcdef>
98          <paramdef>int *<parameter>entries</parameter></paramdef>
99        </funcprototype>
100        <funcprototype>
101 <        <funcdef>network_stat_t *<function>get_network_stats_diff</function></funcdef>
101 >        <funcdef>sg_network_io_stats *<function>sg_get_network_io_stats_diff</function></funcdef>
102          <paramdef>int *<parameter>entries</parameter></paramdef>
103        </funcprototype>
104  
105        <funcprototype>
106 <        <funcdef>page_stat_t *<function>get_page_stats</function></funcdef>
106 >        <funcdef>sg_network_iface_stats *<function>sg_get_network_iface_stats</function></funcdef>
107 >        <paramdef>int *<parameter>entries</parameter></paramdef>
108 >      </funcprototype>
109 >
110 >      <funcprototype>
111 >        <funcdef>sg_page_stats *<function>sg_get_page_stats</function></funcdef>
112          <void/>
113        </funcprototype>
114        <funcprototype>
115 <        <funcdef>page_stat_t *<function>get_page_stats_diff</function></funcdef>
115 >        <funcdef>sg_page_stats *<function>sg_get_page_stats_diff</function></funcdef>
116          <void/>
117        </funcprototype>
118  
119        <funcprototype>
120 <        <funcdef>process_stat_t *<function>get_process_stats</function></funcdef>
120 >        <funcdef>sg_process_count *<function>sg_get_process_stats</function></funcdef>
121          <void/>
122        </funcprototype>
123  
124        <funcprototype>
125 <        <funcdef>user_stat_t *<function>get_user_stats</function></funcdef>
125 >        <funcdef>sg_user_stats *<function>sg_get_user_stats</function></funcdef>
126          <void/>
127        </funcprototype>
128  
129      </funcsynopsis>
130    </refsynopsisdiv>
131 <    
131 >
132    <refsect1>
133      <title>Description</title>
134      <para>
135 <      The statgrab library provides a cross platform interface to getting
135 >      The statgrab library provides a cross-platform interface to getting
136        system statistics. Each of the function calls returns a structure
137        containing statistics. See the manual page for each individual
138        function for more details on usage.
139      </para>
140      <para>
141 <      <function>statgrab_init(void)</function> should be the first
142 <      function you call before you start to use libstatgrab. This
143 <      function on *bsd systems opens up the kernel structures and
144 <      leaves them open for future use. Because of this, any special
145 <      privileges the program has (e.g. setgid kmem) can be dropped
146 <      after this call, and all the libstatgrab calls should continue to
147 <      work.
141 >      <function>sg_init</function> must be the first
142 >      function you call before you start to use libstatgrab; it performs all
143 >      the one-time initialisation operations that need setuid/setgid
144 >      privileges. For instance, on *BSD it opens a descriptor to be able to
145 >      read kernel structures later on, and on Solaris it reads the device
146 >      mappings that in some cases are only accessible by root (machines with
147 >      a /dev/osa). Once this has run, the other libstatgrab functions no longer
148 >      need elevated privileges. It is therefore a good idea to call
149 >      <function>sg_drop_privileges</function>, which discards
150 >      setuid and setgid privileges, immediately after you call
151 >      <function>sg_init</function>, unless your application has
152 >      another reason for needing setuid or setgid privileges.
153      </para>
154      <para>
155 <      <function>statgrab_init</function> returns 0 on success, and
155 >      <function>sg_init</function> and
156 >      <function>sg_drop_privileges</function> return 0 on success, and
157        non-zero on failure.
158      </para>
159      <para>
160 <      The library was originally written to support the i-scream central
161 <      monitoring system, but has since become a standalone package. It
162 <      has been ported to work on Linux, FreeBSD, and Solaris.
160 >      There are three functions relating to error reporting in libstatgrab.
161 >      The first, <function>sg_get_error</function> returns an sg_error code
162 >      which relates to the last error generated by libstatgrab. This can be
163 >      converted to a string by calling <function>sg_str_error</function>
164 >      giving the sg_error code as an argument. Finally, an optional
165 >      argument may be set when the error was generated. This can be
166 >      accessed by calling <function>sg_get_error_arg</function>.
167      </para>
168 +    <para>
169 +      It is the intended practice that whenever a libstatgrab function is
170 +      called and subsequently fails that an appropriate error will be set.
171 +    </para>
172 +    <para>
173 +      The library was originally written to support the i-scream
174 +      central monitoring system, but has since become a standalone
175 +      package. It has been ported to work on Linux, NetBSD, FreeBSD,
176 +      OpenBSD, DragonFly BSD, Solaris and Cygwin.
177 +    </para>
178    </refsect1>
179 <  
179 >
180    <refsect1>
181      <title>See Also</title>
182  
183      <simplelist type="inline">
184        <member>
185          <citerefentry>
186 <          <refentrytitle>cpu_percent_usage</refentrytitle>
186 >          <refentrytitle>sg_get_cpu_percents</refentrytitle>
187            <manvolnum>3</manvolnum>
188          </citerefentry>
189          <citerefentry>
190 <          <refentrytitle>get_diskio_stats</refentrytitle>
190 >          <refentrytitle>sg_get_disk_io_stats</refentrytitle>
191            <manvolnum>3</manvolnum>
192          </citerefentry>
193          <citerefentry>
194 <          <refentrytitle>get_general_stats</refentrytitle>
194 >          <refentrytitle>sg_get_fs_stats</refentrytitle>
195            <manvolnum>3</manvolnum>
196          </citerefentry>
197          <citerefentry>
198 <          <refentrytitle>get_load_stats</refentrytitle>
198 >          <refentrytitle>sg_get_host_info</refentrytitle>
199            <manvolnum>3</manvolnum>
200          </citerefentry>
201          <citerefentry>
202 <          <refentrytitle>get_memory_stats</refentrytitle>
202 >          <refentrytitle>sg_get_load_stats</refentrytitle>
203            <manvolnum>3</manvolnum>
204          </citerefentry>
205          <citerefentry>
206 <          <refentrytitle>get_network_stats</refentrytitle>
206 >          <refentrytitle>sg_get_mem_stats</refentrytitle>
207            <manvolnum>3</manvolnum>
208          </citerefentry>
209          <citerefentry>
210 <          <refentrytitle>get_page_stats</refentrytitle>
210 >          <refentrytitle>sg_get_network_io_stats</refentrytitle>
211            <manvolnum>3</manvolnum>
212          </citerefentry>
213          <citerefentry>
214 <          <refentrytitle>get_process_stats</refentrytitle>
214 >          <refentrytitle>sg_get_network_iface_stats</refentrytitle>
215            <manvolnum>3</manvolnum>
216          </citerefentry>
217          <citerefentry>
218 <          <refentrytitle>get_user_stats</refentrytitle>
218 >          <refentrytitle>sg_get_page_stats</refentrytitle>
219            <manvolnum>3</manvolnum>
220          </citerefentry>
221 +        <citerefentry>
222 +          <refentrytitle>sg_get_process_stats</refentrytitle>
223 +          <manvolnum>3</manvolnum>
224 +        </citerefentry>
225 +        <citerefentry>
226 +          <refentrytitle>sg_get_user_stats</refentrytitle>
227 +          <manvolnum>3</manvolnum>
228 +        </citerefentry>
229        </member>
230      </simplelist>
231    </refsect1>
232 <  
232 >
233    <refsect1>
234      <title>Website</title>
235 <    
235 >
236      <simplelist type="vert">
237        <member>
238 <        <ulink url="http://www.i-scream.org">http://www.i-scream.org</ulink>
238 >        <ulink url="http://www.i-scream.org/libstatgrab/">
239 >          http://www.i-scream.org/libstatgrab/
240 >        </ulink>
241        </member>
242      </simplelist>
243    </refsect1>

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines