1 |
tdb |
1.1 |
<?xml version="1.0"?> |
2 |
|
|
|
3 |
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
4 |
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
5 |
|
|
|
6 |
|
|
<refentry id="statgrab"> |
7 |
|
|
|
8 |
|
|
<refentryinfo> |
9 |
tdb |
1.14 |
<date>$Date: 2004/11/01 18:43:03 $</date> |
10 |
|
|
<releaseinfo>$Id: statgrab.xml,v 1.13 2004/11/01 18:43:03 tdb Exp $</releaseinfo> |
11 |
tdb |
1.1 |
</refentryinfo> |
12 |
tdb |
1.8 |
|
13 |
tdb |
1.1 |
<refmeta> |
14 |
|
|
<refentrytitle>statgrab</refentrytitle> |
15 |
|
|
<manvolnum>3</manvolnum> |
16 |
|
|
<refmiscinfo>i-scream</refmiscinfo> |
17 |
|
|
</refmeta> |
18 |
tdb |
1.8 |
|
19 |
tdb |
1.1 |
<refnamediv> |
20 |
|
|
<refname>statgrab</refname> |
21 |
|
|
<refpurpose>get system statistics</refpurpose> |
22 |
|
|
</refnamediv> |
23 |
tdb |
1.8 |
|
24 |
tdb |
1.1 |
<refsynopsisdiv> |
25 |
|
|
<funcsynopsis> |
26 |
|
|
<funcsynopsisinfo>#include <statgrab.h></funcsynopsisinfo> |
27 |
|
|
|
28 |
|
|
<funcprototype> |
29 |
tdb |
1.8 |
<funcdef>int <function>sg_init</function></funcdef> |
30 |
pajs |
1.2 |
<void/> |
31 |
|
|
</funcprototype> |
32 |
ats |
1.3 |
<funcprototype> |
33 |
tdb |
1.8 |
<funcdef>int <function>sg_drop_privileges</function></funcdef> |
34 |
ats |
1.3 |
<void/> |
35 |
|
|
</funcprototype> |
36 |
pajs |
1.2 |
|
37 |
|
|
<funcprototype> |
38 |
tdb |
1.9 |
<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 |
ats |
1.12 |
<funcdef>int<function>sg_get_error_errno</function></funcdef> |
47 |
|
|
<void/> |
48 |
|
|
</funcprototype> |
49 |
|
|
<funcprototype> |
50 |
tdb |
1.9 |
<funcdef>const char *<function>sg_str_error</function></funcdef> |
51 |
|
|
<paramdef>sg_error <parameter>code</parameter></paramdef> |
52 |
|
|
</funcprototype> |
53 |
|
|
|
54 |
|
|
<funcprototype> |
55 |
tdb |
1.8 |
<funcdef>sg_cpu_stats *<function>sg_get_cpu_stats</function></funcdef> |
56 |
tdb |
1.1 |
<void/> |
57 |
|
|
</funcprototype> |
58 |
|
|
<funcprototype> |
59 |
tdb |
1.8 |
<funcdef>sg_cpu_stats *<function>sg_get_cpu_stats_diff</function></funcdef> |
60 |
tdb |
1.1 |
<void/> |
61 |
|
|
</funcprototype> |
62 |
|
|
<funcprototype> |
63 |
tdb |
1.8 |
<funcdef>sg_cpu_percents *<function>sg_get_cpu_percents</function></funcdef> |
64 |
tdb |
1.1 |
<void/> |
65 |
|
|
</funcprototype> |
66 |
|
|
|
67 |
|
|
<funcprototype> |
68 |
tdb |
1.8 |
<funcdef>sg_disk_io_stats *<function>sg_get_disk_io_stats</function></funcdef> |
69 |
tdb |
1.1 |
<paramdef>int *<parameter>entries</parameter></paramdef> |
70 |
|
|
</funcprototype> |
71 |
|
|
<funcprototype> |
72 |
tdb |
1.8 |
<funcdef>sg_disk_io_stats *<function>sg_get_disk_io_stats_diff</function></funcdef> |
73 |
tdb |
1.1 |
<paramdef>int *<parameter>entries</parameter></paramdef> |
74 |
tdb |
1.10 |
</funcprototype> |
75 |
|
|
|
76 |
|
|
<funcprototype> |
77 |
|
|
<funcdef>sg_fs_stats *<function>sg_get_fs_stats</function></funcdef> |
78 |
|
|
<void/> |
79 |
tdb |
1.1 |
</funcprototype> |
80 |
|
|
|
81 |
|
|
<funcprototype> |
82 |
tdb |
1.8 |
<funcdef>sg_host_info *<function>sg_get_host_info</function></funcdef> |
83 |
tdb |
1.1 |
<void/> |
84 |
|
|
</funcprototype> |
85 |
|
|
|
86 |
|
|
<funcprototype> |
87 |
tdb |
1.8 |
<funcdef>sg_load_stats *<function>sg_get_load_stats</function></funcdef> |
88 |
tdb |
1.1 |
<void/> |
89 |
|
|
</funcprototype> |
90 |
|
|
|
91 |
|
|
<funcprototype> |
92 |
tdb |
1.8 |
<funcdef>sg_mem_stats *<function>sg_get_mem_stats</function></funcdef> |
93 |
tdb |
1.1 |
<void/> |
94 |
|
|
</funcprototype> |
95 |
|
|
<funcprototype> |
96 |
tdb |
1.8 |
<funcdef>sg_swap_stats *<function>sg_get_swap_stats</function></funcdef> |
97 |
tdb |
1.1 |
<void/> |
98 |
|
|
</funcprototype> |
99 |
|
|
|
100 |
|
|
<funcprototype> |
101 |
tdb |
1.8 |
<funcdef>sg_network_io_stats *<function>sg_get_network_io_stats</function></funcdef> |
102 |
tdb |
1.1 |
<paramdef>int *<parameter>entries</parameter></paramdef> |
103 |
|
|
</funcprototype> |
104 |
|
|
<funcprototype> |
105 |
tdb |
1.8 |
<funcdef>sg_network_io_stats *<function>sg_get_network_io_stats_diff</function></funcdef> |
106 |
tdb |
1.1 |
<paramdef>int *<parameter>entries</parameter></paramdef> |
107 |
|
|
</funcprototype> |
108 |
|
|
|
109 |
|
|
<funcprototype> |
110 |
tdb |
1.8 |
<funcdef>sg_network_iface_stats *<function>sg_get_network_iface_stats</function></funcdef> |
111 |
tdb |
1.6 |
<paramdef>int *<parameter>entries</parameter></paramdef> |
112 |
|
|
</funcprototype> |
113 |
|
|
|
114 |
|
|
<funcprototype> |
115 |
tdb |
1.8 |
<funcdef>sg_page_stats *<function>sg_get_page_stats</function></funcdef> |
116 |
tdb |
1.1 |
<void/> |
117 |
|
|
</funcprototype> |
118 |
|
|
<funcprototype> |
119 |
tdb |
1.8 |
<funcdef>sg_page_stats *<function>sg_get_page_stats_diff</function></funcdef> |
120 |
tdb |
1.1 |
<void/> |
121 |
|
|
</funcprototype> |
122 |
|
|
|
123 |
|
|
<funcprototype> |
124 |
tdb |
1.8 |
<funcdef>sg_process_count *<function>sg_get_process_stats</function></funcdef> |
125 |
tdb |
1.1 |
<void/> |
126 |
|
|
</funcprototype> |
127 |
|
|
|
128 |
|
|
<funcprototype> |
129 |
tdb |
1.8 |
<funcdef>sg_user_stats *<function>sg_get_user_stats</function></funcdef> |
130 |
tdb |
1.1 |
<void/> |
131 |
|
|
</funcprototype> |
132 |
|
|
|
133 |
|
|
</funcsynopsis> |
134 |
|
|
</refsynopsisdiv> |
135 |
tdb |
1.8 |
|
136 |
tdb |
1.1 |
<refsect1> |
137 |
|
|
<title>Description</title> |
138 |
|
|
<para> |
139 |
ats |
1.4 |
The statgrab library provides a cross-platform interface to getting |
140 |
tdb |
1.1 |
system statistics. Each of the function calls returns a structure |
141 |
|
|
containing statistics. See the manual page for each individual |
142 |
|
|
function for more details on usage. |
143 |
pajs |
1.2 |
</para> |
144 |
|
|
<para> |
145 |
tdb |
1.8 |
<function>sg_init</function> must be the first |
146 |
ats |
1.4 |
function you call before you start to use libstatgrab; it performs all |
147 |
|
|
the one-time initialisation operations that need setuid/setgid |
148 |
pajs |
1.5 |
privileges. For instance, on *BSD it opens a descriptor to be able to |
149 |
ats |
1.4 |
read kernel structures later on, and on Solaris it reads the device |
150 |
pajs |
1.5 |
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 |
tdb |
1.8 |
<function>sg_drop_privileges</function>, which discards |
154 |
ats |
1.3 |
setuid and setgid privileges, immediately after you call |
155 |
tdb |
1.8 |
<function>sg_init</function>, unless your application has |
156 |
ats |
1.3 |
another reason for needing setuid or setgid privileges. |
157 |
pajs |
1.2 |
</para> |
158 |
|
|
<para> |
159 |
tdb |
1.8 |
<function>sg_init</function> and |
160 |
|
|
<function>sg_drop_privileges</function> return 0 on success, and |
161 |
pajs |
1.2 |
non-zero on failure. |
162 |
tdb |
1.9 |
</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 |
ats |
1.12 |
giving the sg_error code as an argument. An optional |
169 |
tdb |
1.9 |
argument may be set when the error was generated. This can be |
170 |
ats |
1.12 |
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 |
tdb |
1.9 |
</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 |
tdb |
1.1 |
</para> |
181 |
|
|
<para> |
182 |
tdb |
1.6 |
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 |
tdb |
1.13 |
OpenBSD, DragonFly BSD, Solaris, HP-UX and Cygwin. |
186 |
tdb |
1.1 |
</para> |
187 |
|
|
</refsect1> |
188 |
tdb |
1.8 |
|
189 |
tdb |
1.1 |
<refsect1> |
190 |
|
|
<title>See Also</title> |
191 |
|
|
|
192 |
|
|
<simplelist type="inline"> |
193 |
|
|
<member> |
194 |
|
|
<citerefentry> |
195 |
tdb |
1.8 |
<refentrytitle>sg_get_cpu_percents</refentrytitle> |
196 |
tdb |
1.1 |
<manvolnum>3</manvolnum> |
197 |
|
|
</citerefentry> |
198 |
|
|
<citerefentry> |
199 |
tdb |
1.8 |
<refentrytitle>sg_get_disk_io_stats</refentrytitle> |
200 |
tdb |
1.11 |
<manvolnum>3</manvolnum> |
201 |
|
|
</citerefentry> |
202 |
|
|
<citerefentry> |
203 |
|
|
<refentrytitle>sg_get_fs_stats</refentrytitle> |
204 |
tdb |
1.1 |
<manvolnum>3</manvolnum> |
205 |
|
|
</citerefentry> |
206 |
|
|
<citerefentry> |
207 |
tdb |
1.8 |
<refentrytitle>sg_get_host_info</refentrytitle> |
208 |
tdb |
1.1 |
<manvolnum>3</manvolnum> |
209 |
|
|
</citerefentry> |
210 |
|
|
<citerefentry> |
211 |
tdb |
1.8 |
<refentrytitle>sg_get_load_stats</refentrytitle> |
212 |
tdb |
1.1 |
<manvolnum>3</manvolnum> |
213 |
|
|
</citerefentry> |
214 |
|
|
<citerefentry> |
215 |
tdb |
1.8 |
<refentrytitle>sg_get_mem_stats</refentrytitle> |
216 |
tdb |
1.1 |
<manvolnum>3</manvolnum> |
217 |
|
|
</citerefentry> |
218 |
|
|
<citerefentry> |
219 |
tdb |
1.8 |
<refentrytitle>sg_get_network_io_stats</refentrytitle> |
220 |
tdb |
1.6 |
<manvolnum>3</manvolnum> |
221 |
|
|
</citerefentry> |
222 |
|
|
<citerefentry> |
223 |
tdb |
1.8 |
<refentrytitle>sg_get_network_iface_stats</refentrytitle> |
224 |
tdb |
1.1 |
<manvolnum>3</manvolnum> |
225 |
|
|
</citerefentry> |
226 |
|
|
<citerefentry> |
227 |
tdb |
1.8 |
<refentrytitle>sg_get_page_stats</refentrytitle> |
228 |
tdb |
1.1 |
<manvolnum>3</manvolnum> |
229 |
|
|
</citerefentry> |
230 |
|
|
<citerefentry> |
231 |
tdb |
1.8 |
<refentrytitle>sg_get_process_stats</refentrytitle> |
232 |
tdb |
1.1 |
<manvolnum>3</manvolnum> |
233 |
|
|
</citerefentry> |
234 |
|
|
<citerefentry> |
235 |
tdb |
1.8 |
<refentrytitle>sg_get_user_stats</refentrytitle> |
236 |
tdb |
1.1 |
<manvolnum>3</manvolnum> |
237 |
|
|
</citerefentry> |
238 |
|
|
</member> |
239 |
|
|
</simplelist> |
240 |
|
|
</refsect1> |
241 |
tdb |
1.8 |
|
242 |
tdb |
1.1 |
<refsect1> |
243 |
|
|
<title>Website</title> |
244 |
tdb |
1.8 |
|
245 |
tdb |
1.1 |
<simplelist type="vert"> |
246 |
|
|
<member> |
247 |
tdb |
1.7 |
<ulink url="http://www.i-scream.org/libstatgrab/"> |
248 |
|
|
http://www.i-scream.org/libstatgrab/ |
249 |
|
|
</ulink> |
250 |
tdb |
1.1 |
</member> |
251 |
|
|
</simplelist> |
252 |
|
|
</refsect1> |
253 |
|
|
|
254 |
|
|
</refentry> |