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.9 by tdb, Tue May 4 19:28:06 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>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_host_info *<function>sg_get_host_info</function></funcdef>
74          <void/>
75        </funcprototype>
76  
77        <funcprototype>
78 <        <funcdef>load_stat_t *<function>get_load_stats</function></funcdef>
78 >        <funcdef>sg_load_stats *<function>sg_get_load_stats</function></funcdef>
79          <void/>
80        </funcprototype>
81  
82        <funcprototype>
83 <        <funcdef>mem_stat_t *<function>get_memory_stats</function></funcdef>
83 >        <funcdef>sg_mem_stats *<function>sg_get_mem_stats</function></funcdef>
84          <void/>
85        </funcprototype>
86        <funcprototype>
87 <        <funcdef>swap_stat_t *<function>get_swap_stats</function></funcdef>
87 >        <funcdef>sg_swap_stats *<function>sg_get_swap_stats</function></funcdef>
88          <void/>
89        </funcprototype>
90  
91        <funcprototype>
92 <        <funcdef>network_stat_t *<function>get_network_stats</function></funcdef>
92 >        <funcdef>sg_network_io_stats *<function>sg_get_network_io_stats</function></funcdef>
93          <paramdef>int *<parameter>entries</parameter></paramdef>
94        </funcprototype>
95        <funcprototype>
96 <        <funcdef>network_stat_t *<function>get_network_stats_diff</function></funcdef>
96 >        <funcdef>sg_network_io_stats *<function>sg_get_network_io_stats_diff</function></funcdef>
97          <paramdef>int *<parameter>entries</parameter></paramdef>
98        </funcprototype>
99  
100        <funcprototype>
101 <        <funcdef>network_iface_stat_t *<function>get_network_iface_stats</function></funcdef>
101 >        <funcdef>sg_network_iface_stats *<function>sg_get_network_iface_stats</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_page_stats *<function>sg_get_page_stats</function></funcdef>
107          <void/>
108        </funcprototype>
109        <funcprototype>
110 <        <funcdef>page_stat_t *<function>get_page_stats_diff</function></funcdef>
110 >        <funcdef>sg_page_stats *<function>sg_get_page_stats_diff</function></funcdef>
111          <void/>
112        </funcprototype>
113  
114        <funcprototype>
115 <        <funcdef>process_stat_t *<function>get_process_stats</function></funcdef>
115 >        <funcdef>sg_process_count *<function>sg_get_process_stats</function></funcdef>
116          <void/>
117        </funcprototype>
118  
119        <funcprototype>
120 <        <funcdef>user_stat_t *<function>get_user_stats</function></funcdef>
120 >        <funcdef>sg_user_stats *<function>sg_get_user_stats</function></funcdef>
121          <void/>
122        </funcprototype>
123  
124      </funcsynopsis>
125    </refsynopsisdiv>
126 <    
126 >
127    <refsect1>
128      <title>Description</title>
129      <para>
# Line 120 | Line 133
133        function for more details on usage.
134      </para>
135      <para>
136 <      <function>statgrab_init</function> must be the first
136 >      <function>sg_init</function> must be the first
137        function you call before you start to use libstatgrab; it performs all
138        the one-time initialisation operations that need setuid/setgid
139        privileges. For instance, on *BSD it opens a descriptor to be able to
# Line 128 | Line 141
141        mappings that in some cases are only accessible by root (machines with
142        a /dev/osa). Once this has run, the other libstatgrab functions no longer
143        need elevated privileges. It is therefore a good idea to call
144 <      <function>statgrab_drop_privileges</function>, which discards
144 >      <function>sg_drop_privileges</function>, which discards
145        setuid and setgid privileges, immediately after you call
146 <      <function>statgrab_init</function>, unless your application has
146 >      <function>sg_init</function>, unless your application has
147        another reason for needing setuid or setgid privileges.
148      </para>
149      <para>
150 <      <function>statgrab_init</function> and
151 <      <function>statgrab_drop_privileges</function> return 0 on success, and
150 >      <function>sg_init</function> and
151 >      <function>sg_drop_privileges</function> return 0 on success, and
152        non-zero on failure.
153      </para>
154      <para>
155 +      There are three functions relating to error reporting in libstatgrab.
156 +      The first, <function>sg_get_error</function> returns an sg_error code
157 +      which relates to the last error generated by libstatgrab. This can be
158 +      converted to a string by calling <function>sg_str_error</function>
159 +      giving the sg_error code as an argument. Finally, an optional
160 +      argument may be set when the error was generated. This can be
161 +      accessed by calling <function>sg_get_error_arg</function>.
162 +    </para>
163 +    <para>
164 +      It is the intended practice that whenever a libstatgrab function is
165 +      called and subsequently fails that an appropriate error will be set.
166 +    </para>
167 +    <para>
168        The library was originally written to support the i-scream
169        central monitoring system, but has since become a standalone
170        package. It has been ported to work on Linux, NetBSD, FreeBSD,
171        OpenBSD, DragonFly BSD, Solaris and Cygwin.
172      </para>
173    </refsect1>
174 <  
174 >
175    <refsect1>
176      <title>See Also</title>
177  
178      <simplelist type="inline">
179        <member>
180          <citerefentry>
181 <          <refentrytitle>cpu_percent_usage</refentrytitle>
181 >          <refentrytitle>sg_get_cpu_percents</refentrytitle>
182            <manvolnum>3</manvolnum>
183          </citerefentry>
184          <citerefentry>
185 <          <refentrytitle>get_diskio_stats</refentrytitle>
185 >          <refentrytitle>sg_get_disk_io_stats</refentrytitle>
186            <manvolnum>3</manvolnum>
187          </citerefentry>
188          <citerefentry>
189 <          <refentrytitle>get_general_stats</refentrytitle>
189 >          <refentrytitle>sg_get_host_info</refentrytitle>
190            <manvolnum>3</manvolnum>
191          </citerefentry>
192          <citerefentry>
193 <          <refentrytitle>get_load_stats</refentrytitle>
193 >          <refentrytitle>sg_get_load_stats</refentrytitle>
194            <manvolnum>3</manvolnum>
195          </citerefentry>
196          <citerefentry>
197 <          <refentrytitle>get_memory_stats</refentrytitle>
197 >          <refentrytitle>sg_get_mem_stats</refentrytitle>
198            <manvolnum>3</manvolnum>
199          </citerefentry>
200          <citerefentry>
201 <          <refentrytitle>get_network_stats</refentrytitle>
201 >          <refentrytitle>sg_get_network_io_stats</refentrytitle>
202            <manvolnum>3</manvolnum>
203          </citerefentry>
204          <citerefentry>
205 <          <refentrytitle>get_network_iface_stats</refentrytitle>
205 >          <refentrytitle>sg_get_network_iface_stats</refentrytitle>
206            <manvolnum>3</manvolnum>
207          </citerefentry>
208          <citerefentry>
209 <          <refentrytitle>get_page_stats</refentrytitle>
209 >          <refentrytitle>sg_get_page_stats</refentrytitle>
210            <manvolnum>3</manvolnum>
211          </citerefentry>
212          <citerefentry>
213 <          <refentrytitle>get_process_stats</refentrytitle>
213 >          <refentrytitle>sg_get_process_stats</refentrytitle>
214            <manvolnum>3</manvolnum>
215          </citerefentry>
216          <citerefentry>
217 <          <refentrytitle>get_user_stats</refentrytitle>
217 >          <refentrytitle>sg_get_user_stats</refentrytitle>
218            <manvolnum>3</manvolnum>
219          </citerefentry>
220        </member>
221      </simplelist>
222    </refsect1>
223 <  
223 >
224    <refsect1>
225      <title>Website</title>
226 <    
226 >
227      <simplelist type="vert">
228        <member>
229          <ulink url="http://www.i-scream.org/libstatgrab/">

Diff Legend

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