ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/i-scream/projects/libstatgrab/docs/statgrab.xml
Revision: 1.14
Committed: Mon Apr 25 11:25:47 2005 UTC (19 years, 6 months ago) by tdb
Content type: text/xml
Branch: MAIN
CVS Tags: HEAD
Changes since 1.13: +2 -2 lines
State: FILE REMOVED
Log Message:
Move by repocopy the libstatgrab docs in to a subdirectory. This is so
I can create separate directories for statgrab/saidar docs.

File Contents

# User Rev Content
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 &lt;statgrab.h&gt;</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>