libstatgrab/docs/statgrab.xml

<?xml version="1.0"?>

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="statgrab">

  <refentryinfo>
    <date>$Date: 2004/05/05 10:41:42 $</date>
    <releaseinfo>$Id: statgrab.xml,v 1.11 2004/05/05 10:41:42 tdb Exp $</releaseinfo>
  </refentryinfo>

  <refmeta>
    <refentrytitle>statgrab</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo>i-scream</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>statgrab</refname>
    <refpurpose>get system statistics</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;statgrab.h&gt;</funcsynopsisinfo>

      <funcprototype>
        <funcdef>int <function>sg_init</function></funcdef>
        <void/>
      </funcprototype>
      <funcprototype>
        <funcdef>int <function>sg_drop_privileges</function></funcdef>
        <void/>
      </funcprototype>

      <funcprototype>
        <funcdef>sg_error <function>sg_get_error</function></funcdef>
        <void/>
      </funcprototype>
      <funcprototype>
        <funcdef>const char *<function>sg_get_error_arg</function></funcdef>
        <void/>
      </funcprototype>
      <funcprototype>
        <funcdef>int<function>sg_get_error_errno</function></funcdef>
        <void/>
      </funcprototype>
      <funcprototype>
        <funcdef>const char *<function>sg_str_error</function></funcdef>
        <paramdef>sg_error <parameter>code</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>sg_cpu_stats *<function>sg_get_cpu_stats</function></funcdef>
        <void/>
      </funcprototype>
      <funcprototype>
        <funcdef>sg_cpu_stats *<function>sg_get_cpu_stats_diff</function></funcdef>
        <void/>
      </funcprototype>
      <funcprototype>
        <funcdef>sg_cpu_percents *<function>sg_get_cpu_percents</function></funcdef>
        <void/>
      </funcprototype>

      <funcprototype>
        <funcdef>sg_disk_io_stats *<function>sg_get_disk_io_stats</function></funcdef>
        <paramdef>int *<parameter>entries</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>sg_disk_io_stats *<function>sg_get_disk_io_stats_diff</function></funcdef>
        <paramdef>int *<parameter>entries</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>sg_fs_stats *<function>sg_get_fs_stats</function></funcdef>
        <void/>
      </funcprototype>

      <funcprototype>
        <funcdef>sg_host_info *<function>sg_get_host_info</function></funcdef>
        <void/>
      </funcprototype>

      <funcprototype>
        <funcdef>sg_load_stats *<function>sg_get_load_stats</function></funcdef>
        <void/>
      </funcprototype>

      <funcprototype>
        <funcdef>sg_mem_stats *<function>sg_get_mem_stats</function></funcdef>
        <void/>
      </funcprototype>
      <funcprototype>
        <funcdef>sg_swap_stats *<function>sg_get_swap_stats</function></funcdef>
        <void/>
      </funcprototype>

      <funcprototype>
        <funcdef>sg_network_io_stats *<function>sg_get_network_io_stats</function></funcdef>
        <paramdef>int *<parameter>entries</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>sg_network_io_stats *<function>sg_get_network_io_stats_diff</function></funcdef>
        <paramdef>int *<parameter>entries</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>sg_network_iface_stats *<function>sg_get_network_iface_stats</function></funcdef>
        <paramdef>int *<parameter>entries</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>sg_page_stats *<function>sg_get_page_stats</function></funcdef>
        <void/>
      </funcprototype>
      <funcprototype>
        <funcdef>sg_page_stats *<function>sg_get_page_stats_diff</function></funcdef>
        <void/>
      </funcprototype>

      <funcprototype>
        <funcdef>sg_process_count *<function>sg_get_process_stats</function></funcdef>
        <void/>
      </funcprototype>

      <funcprototype>
        <funcdef>sg_user_stats *<function>sg_get_user_stats</function></funcdef>
        <void/>
      </funcprototype>

    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      The statgrab library provides a cross-platform interface to getting
      system statistics. Each of the function calls returns a structure
      containing statistics. See the manual page for each individual
      function for more details on usage.
    </para>
    <para>
      <function>sg_init</function> must be the first
      function you call before you start to use libstatgrab; it performs all
      the one-time initialisation operations that need setuid/setgid
      privileges. For instance, on *BSD it opens a descriptor to be able to
      read kernel structures later on, and on Solaris it reads the device
      mappings that in some cases are only accessible by root (machines with
      a /dev/osa). Once this has run, the other libstatgrab functions no longer 
      need elevated privileges. It is therefore a good idea to call
      <function>sg_drop_privileges</function>, which discards
      setuid and setgid privileges, immediately after you call
      <function>sg_init</function>, unless your application has
      another reason for needing setuid or setgid privileges.
    </para>
    <para>
      <function>sg_init</function> and
      <function>sg_drop_privileges</function> return 0 on success, and
      non-zero on failure.
    </para>
    <para>
      There are three functions relating to error reporting in libstatgrab.
      The first, <function>sg_get_error</function> returns an sg_error code
      which relates to the last error generated by libstatgrab. This can be
      converted to a string by calling <function>sg_str_error</function>
      giving the sg_error code as an argument. An optional
      argument may be set when the error was generated. This can be
      accessed by calling <function>sg_get_error_arg</function>;
      <constant>NULL</constant> will be returned if no argument has
      been set. Some errors will also record the value of the system
      errno variable when the error occurred; this can be retrieved by
      calling <function>sg_get_error_errno</function>, which will
      return <constant>0</constant> if no valid errno has been recorded.
    </para>
    <para>
      It is the intended practice that whenever a libstatgrab function is
      called and subsequently fails that an appropriate error will be set.
    </para>
    <para>
      The library was originally written to support the i-scream
      central monitoring system, but has since become a standalone
      package. It has been ported to work on Linux, NetBSD, FreeBSD,
      OpenBSD, DragonFly BSD, Solaris and Cygwin.
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>

    <simplelist type="inline">
      <member>
        <citerefentry>
          <refentrytitle>sg_get_cpu_percents</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>sg_get_disk_io_stats</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>sg_get_fs_stats</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>sg_get_host_info</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>sg_get_load_stats</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>sg_get_mem_stats</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>sg_get_network_io_stats</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>sg_get_network_iface_stats</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>sg_get_page_stats</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>sg_get_process_stats</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>sg_get_user_stats</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
      </member>
    </simplelist>
  </refsect1>

  <refsect1>
    <title>Website</title>

    <simplelist type="vert">
      <member>
        <ulink url="http://www.i-scream.org/libstatgrab/">
          http://www.i-scream.org/libstatgrab/
        </ulink>
      </member>
    </simplelist>
  </refsect1>

</refentry>
Revision:	1.12
Committed:	Sun Jul 18 20:48:57 2004 UTC (20 years, 4 months ago) by ats
Content type:	text/xml
Branch:	MAIN
CVS Tags:	LIBSTATGRAB_0_10_3, LIBSTATGRAB_0_10_2, LIBSTATGRAB_0_10_1
Changes since 1.11:	+13 -4 lines
Log Message:	Document sg_get_error_errno. Note that sg_get_error_arg can return NULL.
#	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	ats	1.12	<date>$Date: 2004/05/05 10:41:42 $</date>
10			<releaseinfo>$Id: statgrab.xml,v 1.11 2004/05/05 10:41:42 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			OpenBSD, DragonFly BSD, Solaris 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>