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/03/11 17:35:24 $</date>
    <releaseinfo>$Id: statgrab.xml,v 1.7 2004/03/11 17:35:24 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_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_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>
      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_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.8
Committed:	Sun May 2 17:39:19 2004 UTC (20 years, 6 months ago) by tdb
Content type:	text/xml
Branch:	MAIN
Changes since 1.7:	+42 -42 lines
Log Message:	Another pass, finish off the main page and fix a few problems. Still to document: process stats (new stuff), error stuff, and some fs related stuff.
#	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.8	<date>$Date: 2004/03/11 17:35:24 $</date>
10			<releaseinfo>$Id: statgrab.xml,v 1.7 2004/03/11 17:35:24 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.8	<funcdef>sg_cpu_stats *<function>sg_get_cpu_stats</function></funcdef>
39	tdb	1.1	<void/>
40			</funcprototype>
41			<funcprototype>
42	tdb	1.8	<funcdef>sg_cpu_stats *<function>sg_get_cpu_stats_diff</function></funcdef>
43	tdb	1.1	<void/>
44			</funcprototype>
45			<funcprototype>
46	tdb	1.8	<funcdef>sg_cpu_percents *<function>sg_get_cpu_percents</function></funcdef>
47	tdb	1.1	<void/>
48			</funcprototype>
49
50			<funcprototype>
51	tdb	1.8	<funcdef>sg_disk_io_stats *<function>sg_get_disk_io_stats</function></funcdef>
52	tdb	1.1	<paramdef>int *<parameter>entries</parameter></paramdef>
53			</funcprototype>
54			<funcprototype>
55	tdb	1.8	<funcdef>sg_disk_io_stats *<function>sg_get_disk_io_stats_diff</function></funcdef>
56	tdb	1.1	<paramdef>int *<parameter>entries</parameter></paramdef>
57			</funcprototype>
58
59			<funcprototype>
60	tdb	1.8	<funcdef>sg_host_info *<function>sg_get_host_info</function></funcdef>
61	tdb	1.1	<void/>
62			</funcprototype>
63
64			<funcprototype>
65	tdb	1.8	<funcdef>sg_load_stats *<function>sg_get_load_stats</function></funcdef>
66	tdb	1.1	<void/>
67			</funcprototype>
68
69			<funcprototype>
70	tdb	1.8	<funcdef>sg_mem_stats *<function>sg_get_mem_stats</function></funcdef>
71	tdb	1.1	<void/>
72			</funcprototype>
73			<funcprototype>
74	tdb	1.8	<funcdef>sg_swap_stats *<function>sg_get_swap_stats</function></funcdef>
75	tdb	1.1	<void/>
76			</funcprototype>
77
78			<funcprototype>
79	tdb	1.8	<funcdef>sg_network_io_stats *<function>sg_get_network_io_stats</function></funcdef>
80	tdb	1.1	<paramdef>int *<parameter>entries</parameter></paramdef>
81			</funcprototype>
82			<funcprototype>
83	tdb	1.8	<funcdef>sg_network_io_stats *<function>sg_get_network_io_stats_diff</function></funcdef>
84	tdb	1.1	<paramdef>int *<parameter>entries</parameter></paramdef>
85			</funcprototype>
86
87			<funcprototype>
88	tdb	1.8	<funcdef>sg_network_iface_stats *<function>sg_get_network_iface_stats</function></funcdef>
89	tdb	1.6	<paramdef>int *<parameter>entries</parameter></paramdef>
90			</funcprototype>
91
92			<funcprototype>
93	tdb	1.8	<funcdef>sg_page_stats *<function>sg_get_page_stats</function></funcdef>
94	tdb	1.1	<void/>
95			</funcprototype>
96			<funcprototype>
97	tdb	1.8	<funcdef>sg_page_stats *<function>sg_get_page_stats_diff</function></funcdef>
98	tdb	1.1	<void/>
99			</funcprototype>
100
101			<funcprototype>
102	tdb	1.8	<funcdef>sg_process_count *<function>sg_get_process_stats</function></funcdef>
103	tdb	1.1	<void/>
104			</funcprototype>
105
106			<funcprototype>
107	tdb	1.8	<funcdef>sg_user_stats *<function>sg_get_user_stats</function></funcdef>
108	tdb	1.1	<void/>
109			</funcprototype>
110
111			</funcsynopsis>
112			</refsynopsisdiv>
113	tdb	1.8
114	tdb	1.1	<refsect1>
115			<title>Description</title>
116			<para>
117	ats	1.4	The statgrab library provides a cross-platform interface to getting
118	tdb	1.1	system statistics. Each of the function calls returns a structure
119			containing statistics. See the manual page for each individual
120			function for more details on usage.
121	pajs	1.2	</para>
122			<para>
123	tdb	1.8	<function>sg_init</function> must be the first
124	ats	1.4	function you call before you start to use libstatgrab; it performs all
125			the one-time initialisation operations that need setuid/setgid
126	pajs	1.5	privileges. For instance, on *BSD it opens a descriptor to be able to
127	ats	1.4	read kernel structures later on, and on Solaris it reads the device
128	pajs	1.5	mappings that in some cases are only accessible by root (machines with
129			a /dev/osa). Once this has run, the other libstatgrab functions no longer
130			need elevated privileges. It is therefore a good idea to call
131	tdb	1.8	<function>sg_drop_privileges</function>, which discards
132	ats	1.3	setuid and setgid privileges, immediately after you call
133	tdb	1.8	<function>sg_init</function>, unless your application has
134	ats	1.3	another reason for needing setuid or setgid privileges.
135	pajs	1.2	</para>
136			<para>
137	tdb	1.8	<function>sg_init</function> and
138			<function>sg_drop_privileges</function> return 0 on success, and
139	pajs	1.2	non-zero on failure.
140	tdb	1.1	</para>
141			<para>
142	tdb	1.6	The library was originally written to support the i-scream
143			central monitoring system, but has since become a standalone
144			package. It has been ported to work on Linux, NetBSD, FreeBSD,
145			OpenBSD, DragonFly BSD, Solaris and Cygwin.
146	tdb	1.1	</para>
147			</refsect1>
148	tdb	1.8
149	tdb	1.1	<refsect1>
150			<title>See Also</title>
151
152			<simplelist type="inline">
153			<member>
154			<citerefentry>
155	tdb	1.8	<refentrytitle>sg_get_cpu_percents</refentrytitle>
156	tdb	1.1	<manvolnum>3</manvolnum>
157			</citerefentry>
158			<citerefentry>
159	tdb	1.8	<refentrytitle>sg_get_disk_io_stats</refentrytitle>
160	tdb	1.1	<manvolnum>3</manvolnum>
161			</citerefentry>
162			<citerefentry>
163	tdb	1.8	<refentrytitle>sg_get_host_info</refentrytitle>
164	tdb	1.1	<manvolnum>3</manvolnum>
165			</citerefentry>
166			<citerefentry>
167	tdb	1.8	<refentrytitle>sg_get_load_stats</refentrytitle>
168	tdb	1.1	<manvolnum>3</manvolnum>
169			</citerefentry>
170			<citerefentry>
171	tdb	1.8	<refentrytitle>sg_get_mem_stats</refentrytitle>
172	tdb	1.1	<manvolnum>3</manvolnum>
173			</citerefentry>
174			<citerefentry>
175	tdb	1.8	<refentrytitle>sg_get_network_io_stats</refentrytitle>
176	tdb	1.6	<manvolnum>3</manvolnum>
177			</citerefentry>
178			<citerefentry>
179	tdb	1.8	<refentrytitle>sg_get_network_iface_stats</refentrytitle>
180	tdb	1.1	<manvolnum>3</manvolnum>
181			</citerefentry>
182			<citerefentry>
183	tdb	1.8	<refentrytitle>sg_get_page_stats</refentrytitle>
184	tdb	1.1	<manvolnum>3</manvolnum>
185			</citerefentry>
186			<citerefentry>
187	tdb	1.8	<refentrytitle>sg_get_process_stats</refentrytitle>
188	tdb	1.1	<manvolnum>3</manvolnum>
189			</citerefentry>
190			<citerefentry>
191	tdb	1.8	<refentrytitle>sg_get_user_stats</refentrytitle>
192	tdb	1.1	<manvolnum>3</manvolnum>
193			</citerefentry>
194			</member>
195			</simplelist>
196			</refsect1>
197	tdb	1.8
198	tdb	1.1	<refsect1>
199			<title>Website</title>
200	tdb	1.8
201	tdb	1.1	<simplelist type="vert">
202			<member>
203	tdb	1.7	<ulink url="http://www.i-scream.org/libstatgrab/">
204			http://www.i-scream.org/libstatgrab/
205			</ulink>
206	tdb	1.1	</member>
207			</simplelist>
208			</refsect1>
209
210			</refentry>