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.1 by tdb, Thu Oct 2 17:38:03 2003 UTC vs.
Revision 1.10 by tdb, Wed May 5 10:40:50 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>cpu_percent_t *<function>cpu_percent_usage</function></funcdef>
29 >        <funcdef>int <function>sg_init</function></funcdef>
30          <void/>
31        </funcprototype>
32        <funcprototype>
33 <        <funcdef>cpu_states_t *<function>get_cpu_totals</function></funcdef>
33 >        <funcdef>int <function>sg_drop_privileges</function></funcdef>
34          <void/>
35        </funcprototype>
36 +
37        <funcprototype>
38 <        <funcdef>cpu_states_t *<function>get_cpu_diff</function></funcdef>
38 >        <funcdef>sg_error <function>sg_get_error</function></funcdef>
39          <void/>
40        </funcprototype>
41 +      <funcprototype>
42 +        <funcdef>const char *<function>sg_get_error_arg</function></funcdef>
43 +        <void/>
44 +      </funcprototype>
45 +      <funcprototype>
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>diskio_stat_t *<function>get_diskio_stats</function></funcdef>
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>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 <      The library was originally written to support the i-scream central
142 <      monitoring system, but has since become a standalone package. It
143 <      has been ported to work on Linux, FreeBSD, and Solaris.
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>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 +      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_host_info</refentrytitle>
195            <manvolnum>3</manvolnum>
196          </citerefentry>
197          <citerefentry>
198 <          <refentrytitle>get_load_stats</refentrytitle>
198 >          <refentrytitle>sg_get_load_stats</refentrytitle>
199            <manvolnum>3</manvolnum>
200          </citerefentry>
201          <citerefentry>
202 <          <refentrytitle>get_memory_stats</refentrytitle>
202 >          <refentrytitle>sg_get_mem_stats</refentrytitle>
203            <manvolnum>3</manvolnum>
204          </citerefentry>
205          <citerefentry>
206 <          <refentrytitle>get_network_stats</refentrytitle>
206 >          <refentrytitle>sg_get_network_io_stats</refentrytitle>
207            <manvolnum>3</manvolnum>
208          </citerefentry>
209          <citerefentry>
210 <          <refentrytitle>get_page_stats</refentrytitle>
210 >          <refentrytitle>sg_get_network_iface_stats</refentrytitle>
211            <manvolnum>3</manvolnum>
212          </citerefentry>
213          <citerefentry>
214 <          <refentrytitle>get_process_stats</refentrytitle>
214 >          <refentrytitle>sg_get_page_stats</refentrytitle>
215            <manvolnum>3</manvolnum>
216          </citerefentry>
217          <citerefentry>
218 <          <refentrytitle>get_user_stats</refentrytitle>
218 >          <refentrytitle>sg_get_process_stats</refentrytitle>
219            <manvolnum>3</manvolnum>
220          </citerefentry>
221 +        <citerefentry>
222 +          <refentrytitle>sg_get_user_stats</refentrytitle>
223 +          <manvolnum>3</manvolnum>
224 +        </citerefentry>
225        </member>
226      </simplelist>
227    </refsect1>
228 <  
228 >
229    <refsect1>
230      <title>Website</title>
231 <    
231 >
232      <simplelist type="vert">
233        <member>
234 <        <ulink url="http://www.i-scream.org">http://www.i-scream.org</ulink>
234 >        <ulink url="http://www.i-scream.org/libstatgrab/">
235 >          http://www.i-scream.org/libstatgrab/
236 >        </ulink>
237        </member>
238      </simplelist>
239    </refsect1>

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines