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:40:50 $</date>
    <releaseinfo>$Id: statgrab.xml,v 1.10 2004/05/05 10:40:50 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>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. Finally, an optional
      argument may be set when the error was generated. This can be
      accessed by calling <function>sg_get_error_arg</function>.
    </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.11
Committed:	Wed May 5 10:41:42 2004 UTC (20 years, 6 months ago) by tdb
Content type:	text/xml
Branch:	MAIN
CVS Tags:	LIBSTATGRAB_0_10
Changes since 1.10:	+6 -2 lines
Log Message:	And add sg_get_fs_stats properly :-)
#	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.11	<date>$Date: 2004/05/05 10:40:50 $</date>
10			<releaseinfo>$Id: statgrab.xml,v 1.10 2004/05/05 10:40:50 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			<funcdef>const char *<function>sg_str_error</function></funcdef>
47			<paramdef>sg_error <parameter>code</parameter></paramdef>
48			</funcprototype>
49
50			<funcprototype>
51	tdb	1.8	<funcdef>sg_cpu_stats *<function>sg_get_cpu_stats</function></funcdef>
52	tdb	1.1	<void/>
53			</funcprototype>
54			<funcprototype>
55	tdb	1.8	<funcdef>sg_cpu_stats *<function>sg_get_cpu_stats_diff</function></funcdef>
56	tdb	1.1	<void/>
57			</funcprototype>
58			<funcprototype>
59	tdb	1.8	<funcdef>sg_cpu_percents *<function>sg_get_cpu_percents</function></funcdef>
60	tdb	1.1	<void/>
61			</funcprototype>
62
63			<funcprototype>
64	tdb	1.8	<funcdef>sg_disk_io_stats *<function>sg_get_disk_io_stats</function></funcdef>
65	tdb	1.1	<paramdef>int *<parameter>entries</parameter></paramdef>
66			</funcprototype>
67			<funcprototype>
68	tdb	1.8	<funcdef>sg_disk_io_stats *<function>sg_get_disk_io_stats_diff</function></funcdef>
69	tdb	1.1	<paramdef>int *<parameter>entries</parameter></paramdef>
70	tdb	1.10	</funcprototype>
71
72			<funcprototype>
73			<funcdef>sg_fs_stats *<function>sg_get_fs_stats</function></funcdef>
74			<void/>
75	tdb	1.1	</funcprototype>
76
77			<funcprototype>
78	tdb	1.8	<funcdef>sg_host_info *<function>sg_get_host_info</function></funcdef>
79	tdb	1.1	<void/>
80			</funcprototype>
81
82			<funcprototype>
83	tdb	1.8	<funcdef>sg_load_stats *<function>sg_get_load_stats</function></funcdef>
84	tdb	1.1	<void/>
85			</funcprototype>
86
87			<funcprototype>
88	tdb	1.8	<funcdef>sg_mem_stats *<function>sg_get_mem_stats</function></funcdef>
89	tdb	1.1	<void/>
90			</funcprototype>
91			<funcprototype>
92	tdb	1.8	<funcdef>sg_swap_stats *<function>sg_get_swap_stats</function></funcdef>
93	tdb	1.1	<void/>
94			</funcprototype>
95
96			<funcprototype>
97	tdb	1.8	<funcdef>sg_network_io_stats *<function>sg_get_network_io_stats</function></funcdef>
98	tdb	1.1	<paramdef>int *<parameter>entries</parameter></paramdef>
99			</funcprototype>
100			<funcprototype>
101	tdb	1.8	<funcdef>sg_network_io_stats *<function>sg_get_network_io_stats_diff</function></funcdef>
102	tdb	1.1	<paramdef>int *<parameter>entries</parameter></paramdef>
103			</funcprototype>
104
105			<funcprototype>
106	tdb	1.8	<funcdef>sg_network_iface_stats *<function>sg_get_network_iface_stats</function></funcdef>
107	tdb	1.6	<paramdef>int *<parameter>entries</parameter></paramdef>
108			</funcprototype>
109
110			<funcprototype>
111	tdb	1.8	<funcdef>sg_page_stats *<function>sg_get_page_stats</function></funcdef>
112	tdb	1.1	<void/>
113			</funcprototype>
114			<funcprototype>
115	tdb	1.8	<funcdef>sg_page_stats *<function>sg_get_page_stats_diff</function></funcdef>
116	tdb	1.1	<void/>
117			</funcprototype>
118
119			<funcprototype>
120	tdb	1.8	<funcdef>sg_process_count *<function>sg_get_process_stats</function></funcdef>
121	tdb	1.1	<void/>
122			</funcprototype>
123
124			<funcprototype>
125	tdb	1.8	<funcdef>sg_user_stats *<function>sg_get_user_stats</function></funcdef>
126	tdb	1.1	<void/>
127			</funcprototype>
128
129			</funcsynopsis>
130			</refsynopsisdiv>
131	tdb	1.8
132	tdb	1.1	<refsect1>
133			<title>Description</title>
134			<para>
135	ats	1.4	The statgrab library provides a cross-platform interface to getting
136	tdb	1.1	system statistics. Each of the function calls returns a structure
137			containing statistics. See the manual page for each individual
138			function for more details on usage.
139	pajs	1.2	</para>
140			<para>
141	tdb	1.8	<function>sg_init</function> must be the first
142	ats	1.4	function you call before you start to use libstatgrab; it performs all
143			the one-time initialisation operations that need setuid/setgid
144	pajs	1.5	privileges. For instance, on *BSD it opens a descriptor to be able to
145	ats	1.4	read kernel structures later on, and on Solaris it reads the device
146	pajs	1.5	mappings that in some cases are only accessible by root (machines with
147			a /dev/osa). Once this has run, the other libstatgrab functions no longer
148			need elevated privileges. It is therefore a good idea to call
149	tdb	1.8	<function>sg_drop_privileges</function>, which discards
150	ats	1.3	setuid and setgid privileges, immediately after you call
151	tdb	1.8	<function>sg_init</function>, unless your application has
152	ats	1.3	another reason for needing setuid or setgid privileges.
153	pajs	1.2	</para>
154			<para>
155	tdb	1.8	<function>sg_init</function> and
156			<function>sg_drop_privileges</function> return 0 on success, and
157	pajs	1.2	non-zero on failure.
158	tdb	1.9	</para>
159			<para>
160			There are three functions relating to error reporting in libstatgrab.
161			The first, <function>sg_get_error</function> returns an sg_error code
162			which relates to the last error generated by libstatgrab. This can be
163			converted to a string by calling <function>sg_str_error</function>
164			giving the sg_error code as an argument. Finally, an optional
165			argument may be set when the error was generated. This can be
166			accessed by calling <function>sg_get_error_arg</function>.
167			</para>
168			<para>
169			It is the intended practice that whenever a libstatgrab function is
170			called and subsequently fails that an appropriate error will be set.
171	tdb	1.1	</para>
172			<para>
173	tdb	1.6	The library was originally written to support the i-scream
174			central monitoring system, but has since become a standalone
175			package. It has been ported to work on Linux, NetBSD, FreeBSD,
176			OpenBSD, DragonFly BSD, Solaris and Cygwin.
177	tdb	1.1	</para>
178			</refsect1>
179	tdb	1.8
180	tdb	1.1	<refsect1>
181			<title>See Also</title>
182
183			<simplelist type="inline">
184			<member>
185			<citerefentry>
186	tdb	1.8	<refentrytitle>sg_get_cpu_percents</refentrytitle>
187	tdb	1.1	<manvolnum>3</manvolnum>
188			</citerefentry>
189			<citerefentry>
190	tdb	1.8	<refentrytitle>sg_get_disk_io_stats</refentrytitle>
191	tdb	1.11	<manvolnum>3</manvolnum>
192			</citerefentry>
193			<citerefentry>
194			<refentrytitle>sg_get_fs_stats</refentrytitle>
195	tdb	1.1	<manvolnum>3</manvolnum>
196			</citerefentry>
197			<citerefentry>
198	tdb	1.8	<refentrytitle>sg_get_host_info</refentrytitle>
199	tdb	1.1	<manvolnum>3</manvolnum>
200			</citerefentry>
201			<citerefentry>
202	tdb	1.8	<refentrytitle>sg_get_load_stats</refentrytitle>
203	tdb	1.1	<manvolnum>3</manvolnum>
204			</citerefentry>
205			<citerefentry>
206	tdb	1.8	<refentrytitle>sg_get_mem_stats</refentrytitle>
207	tdb	1.1	<manvolnum>3</manvolnum>
208			</citerefentry>
209			<citerefentry>
210	tdb	1.8	<refentrytitle>sg_get_network_io_stats</refentrytitle>
211	tdb	1.6	<manvolnum>3</manvolnum>
212			</citerefentry>
213			<citerefentry>
214	tdb	1.8	<refentrytitle>sg_get_network_iface_stats</refentrytitle>
215	tdb	1.1	<manvolnum>3</manvolnum>
216			</citerefentry>
217			<citerefentry>
218	tdb	1.8	<refentrytitle>sg_get_page_stats</refentrytitle>
219	tdb	1.1	<manvolnum>3</manvolnum>
220			</citerefentry>
221			<citerefentry>
222	tdb	1.8	<refentrytitle>sg_get_process_stats</refentrytitle>
223	tdb	1.1	<manvolnum>3</manvolnum>
224			</citerefentry>
225			<citerefentry>
226	tdb	1.8	<refentrytitle>sg_get_user_stats</refentrytitle>
227	tdb	1.1	<manvolnum>3</manvolnum>
228			</citerefentry>
229			</member>
230			</simplelist>
231			</refsect1>
232	tdb	1.8
233	tdb	1.1	<refsect1>
234			<title>Website</title>
235	tdb	1.8
236	tdb	1.1	<simplelist type="vert">
237			<member>
238	tdb	1.7	<ulink url="http://www.i-scream.org/libstatgrab/">
239			http://www.i-scream.org/libstatgrab/
240			</ulink>
241	tdb	1.1	</member>
242			</simplelist>
243			</refsect1>
244
245			</refentry>