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.7 by tdb, Thu Mar 11 17:35:24 2004 UTC vs.
Revision 1.12 by ats, Sun Jul 18 20:48:57 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>statgrab_drop_privileges</function></funcdef>
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>int<function>sg_get_error_errno</function></funcdef>
47          <void/>
48        </funcprototype>
49 +      <funcprototype>
50 +        <funcdef>const char *<function>sg_str_error</function></funcdef>
51 +        <paramdef>sg_error <parameter>code</parameter></paramdef>
52 +      </funcprototype>
53  
54        <funcprototype>
55 <        <funcdef>diskio_stat_t *<function>get_diskio_stats</function></funcdef>
55 >        <funcdef>sg_cpu_stats *<function>sg_get_cpu_stats</function></funcdef>
56 >        <void/>
57 >      </funcprototype>
58 >      <funcprototype>
59 >        <funcdef>sg_cpu_stats *<function>sg_get_cpu_stats_diff</function></funcdef>
60 >        <void/>
61 >      </funcprototype>
62 >      <funcprototype>
63 >        <funcdef>sg_cpu_percents *<function>sg_get_cpu_percents</function></funcdef>
64 >        <void/>
65 >      </funcprototype>
66 >
67 >      <funcprototype>
68 >        <funcdef>sg_disk_io_stats *<function>sg_get_disk_io_stats</function></funcdef>
69          <paramdef>int *<parameter>entries</parameter></paramdef>
70        </funcprototype>
71        <funcprototype>
72 <        <funcdef>diskio_stat_t *<function>get_diskio_stats_diff</function></funcdef>
72 >        <funcdef>sg_disk_io_stats *<function>sg_get_disk_io_stats_diff</function></funcdef>
73          <paramdef>int *<parameter>entries</parameter></paramdef>
74        </funcprototype>
75  
76        <funcprototype>
77 <        <funcdef>general_stat_t *<function>get_general_stats</function></funcdef>
77 >        <funcdef>sg_fs_stats *<function>sg_get_fs_stats</function></funcdef>
78          <void/>
79        </funcprototype>
80  
81        <funcprototype>
82 <        <funcdef>load_stat_t *<function>get_load_stats</function></funcdef>
82 >        <funcdef>sg_host_info *<function>sg_get_host_info</function></funcdef>
83          <void/>
84        </funcprototype>
85  
86        <funcprototype>
87 <        <funcdef>mem_stat_t *<function>get_memory_stats</function></funcdef>
87 >        <funcdef>sg_load_stats *<function>sg_get_load_stats</function></funcdef>
88          <void/>
89        </funcprototype>
90 +
91        <funcprototype>
92 <        <funcdef>swap_stat_t *<function>get_swap_stats</function></funcdef>
92 >        <funcdef>sg_mem_stats *<function>sg_get_mem_stats</function></funcdef>
93          <void/>
94        </funcprototype>
95 +      <funcprototype>
96 +        <funcdef>sg_swap_stats *<function>sg_get_swap_stats</function></funcdef>
97 +        <void/>
98 +      </funcprototype>
99  
100        <funcprototype>
101 <        <funcdef>network_stat_t *<function>get_network_stats</function></funcdef>
101 >        <funcdef>sg_network_io_stats *<function>sg_get_network_io_stats</function></funcdef>
102          <paramdef>int *<parameter>entries</parameter></paramdef>
103        </funcprototype>
104        <funcprototype>
105 <        <funcdef>network_stat_t *<function>get_network_stats_diff</function></funcdef>
105 >        <funcdef>sg_network_io_stats *<function>sg_get_network_io_stats_diff</function></funcdef>
106          <paramdef>int *<parameter>entries</parameter></paramdef>
107        </funcprototype>
108  
109        <funcprototype>
110 <        <funcdef>network_iface_stat_t *<function>get_network_iface_stats</function></funcdef>
110 >        <funcdef>sg_network_iface_stats *<function>sg_get_network_iface_stats</function></funcdef>
111          <paramdef>int *<parameter>entries</parameter></paramdef>
112        </funcprototype>
113  
114        <funcprototype>
115 <        <funcdef>page_stat_t *<function>get_page_stats</function></funcdef>
115 >        <funcdef>sg_page_stats *<function>sg_get_page_stats</function></funcdef>
116          <void/>
117        </funcprototype>
118        <funcprototype>
119 <        <funcdef>page_stat_t *<function>get_page_stats_diff</function></funcdef>
119 >        <funcdef>sg_page_stats *<function>sg_get_page_stats_diff</function></funcdef>
120          <void/>
121        </funcprototype>
122  
123        <funcprototype>
124 <        <funcdef>process_stat_t *<function>get_process_stats</function></funcdef>
124 >        <funcdef>sg_process_count *<function>sg_get_process_stats</function></funcdef>
125          <void/>
126        </funcprototype>
127  
128        <funcprototype>
129 <        <funcdef>user_stat_t *<function>get_user_stats</function></funcdef>
129 >        <funcdef>sg_user_stats *<function>sg_get_user_stats</function></funcdef>
130          <void/>
131        </funcprototype>
132  
133      </funcsynopsis>
134    </refsynopsisdiv>
135 <    
135 >
136    <refsect1>
137      <title>Description</title>
138      <para>
# Line 120 | Line 142
142        function for more details on usage.
143      </para>
144      <para>
145 <      <function>statgrab_init</function> must be the first
145 >      <function>sg_init</function> must be the first
146        function you call before you start to use libstatgrab; it performs all
147        the one-time initialisation operations that need setuid/setgid
148        privileges. For instance, on *BSD it opens a descriptor to be able to
# Line 128 | Line 150
150        mappings that in some cases are only accessible by root (machines with
151        a /dev/osa). Once this has run, the other libstatgrab functions no longer
152        need elevated privileges. It is therefore a good idea to call
153 <      <function>statgrab_drop_privileges</function>, which discards
153 >      <function>sg_drop_privileges</function>, which discards
154        setuid and setgid privileges, immediately after you call
155 <      <function>statgrab_init</function>, unless your application has
155 >      <function>sg_init</function>, unless your application has
156        another reason for needing setuid or setgid privileges.
157      </para>
158      <para>
159 <      <function>statgrab_init</function> and
160 <      <function>statgrab_drop_privileges</function> return 0 on success, and
159 >      <function>sg_init</function> and
160 >      <function>sg_drop_privileges</function> return 0 on success, and
161        non-zero on failure.
162      </para>
163      <para>
164 +      There are three functions relating to error reporting in libstatgrab.
165 +      The first, <function>sg_get_error</function> returns an sg_error code
166 +      which relates to the last error generated by libstatgrab. This can be
167 +      converted to a string by calling <function>sg_str_error</function>
168 +      giving the sg_error code as an argument. An optional
169 +      argument may be set when the error was generated. This can be
170 +      accessed by calling <function>sg_get_error_arg</function>;
171 +      <constant>NULL</constant> will be returned if no argument has
172 +      been set. Some errors will also record the value of the system
173 +      errno variable when the error occurred; this can be retrieved by
174 +      calling <function>sg_get_error_errno</function>, which will
175 +      return <constant>0</constant> if no valid errno has been recorded.
176 +    </para>
177 +    <para>
178 +      It is the intended practice that whenever a libstatgrab function is
179 +      called and subsequently fails that an appropriate error will be set.
180 +    </para>
181 +    <para>
182        The library was originally written to support the i-scream
183        central monitoring system, but has since become a standalone
184        package. It has been ported to work on Linux, NetBSD, FreeBSD,
185        OpenBSD, DragonFly BSD, Solaris and Cygwin.
186      </para>
187    </refsect1>
188 <  
188 >
189    <refsect1>
190      <title>See Also</title>
191  
192      <simplelist type="inline">
193        <member>
194          <citerefentry>
195 <          <refentrytitle>cpu_percent_usage</refentrytitle>
195 >          <refentrytitle>sg_get_cpu_percents</refentrytitle>
196            <manvolnum>3</manvolnum>
197          </citerefentry>
198          <citerefentry>
199 <          <refentrytitle>get_diskio_stats</refentrytitle>
199 >          <refentrytitle>sg_get_disk_io_stats</refentrytitle>
200            <manvolnum>3</manvolnum>
201          </citerefentry>
202          <citerefentry>
203 <          <refentrytitle>get_general_stats</refentrytitle>
203 >          <refentrytitle>sg_get_fs_stats</refentrytitle>
204            <manvolnum>3</manvolnum>
205          </citerefentry>
206          <citerefentry>
207 <          <refentrytitle>get_load_stats</refentrytitle>
207 >          <refentrytitle>sg_get_host_info</refentrytitle>
208            <manvolnum>3</manvolnum>
209          </citerefentry>
210          <citerefentry>
211 <          <refentrytitle>get_memory_stats</refentrytitle>
211 >          <refentrytitle>sg_get_load_stats</refentrytitle>
212            <manvolnum>3</manvolnum>
213          </citerefentry>
214          <citerefentry>
215 <          <refentrytitle>get_network_stats</refentrytitle>
215 >          <refentrytitle>sg_get_mem_stats</refentrytitle>
216            <manvolnum>3</manvolnum>
217          </citerefentry>
218          <citerefentry>
219 <          <refentrytitle>get_network_iface_stats</refentrytitle>
219 >          <refentrytitle>sg_get_network_io_stats</refentrytitle>
220            <manvolnum>3</manvolnum>
221          </citerefentry>
222          <citerefentry>
223 <          <refentrytitle>get_page_stats</refentrytitle>
223 >          <refentrytitle>sg_get_network_iface_stats</refentrytitle>
224            <manvolnum>3</manvolnum>
225          </citerefentry>
226          <citerefentry>
227 <          <refentrytitle>get_process_stats</refentrytitle>
227 >          <refentrytitle>sg_get_page_stats</refentrytitle>
228            <manvolnum>3</manvolnum>
229          </citerefentry>
230          <citerefentry>
231 <          <refentrytitle>get_user_stats</refentrytitle>
231 >          <refentrytitle>sg_get_process_stats</refentrytitle>
232            <manvolnum>3</manvolnum>
233          </citerefentry>
234 +        <citerefentry>
235 +          <refentrytitle>sg_get_user_stats</refentrytitle>
236 +          <manvolnum>3</manvolnum>
237 +        </citerefentry>
238        </member>
239      </simplelist>
240    </refsect1>
241 <  
241 >
242    <refsect1>
243      <title>Website</title>
244 <    
244 >
245      <simplelist type="vert">
246        <member>
247          <ulink url="http://www.i-scream.org/libstatgrab/">

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines