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.
#	Content
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	<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	</refentryinfo>
12
13	<refmeta>
14	<refentrytitle>statgrab</refentrytitle>
15	<manvolnum>3</manvolnum>
16	<refmiscinfo>i-scream</refmiscinfo>
17	</refmeta>
18
19	<refnamediv>
20	<refname>statgrab</refname>
21	<refpurpose>get system statistics</refpurpose>
22	</refnamediv>
23
24	<refsynopsisdiv>
25	<funcsynopsis>
26	<funcsynopsisinfo>#include <statgrab.h></funcsynopsisinfo>
27
28	<funcprototype>
29	<funcdef>int <function>sg_init</function></funcdef>
30	<void/>
31	</funcprototype>
32	<funcprototype>
33	<funcdef>int <function>sg_drop_privileges</function></funcdef>
34	<void/>
35	</funcprototype>
36
37	<funcprototype>
38	<funcdef>sg_cpu_stats *<function>sg_get_cpu_stats</function></funcdef>
39	<void/>
40	</funcprototype>
41	<funcprototype>
42	<funcdef>sg_cpu_stats *<function>sg_get_cpu_stats_diff</function></funcdef>
43	<void/>
44	</funcprototype>
45	<funcprototype>
46	<funcdef>sg_cpu_percents *<function>sg_get_cpu_percents</function></funcdef>
47	<void/>
48	</funcprototype>
49
50	<funcprototype>
51	<funcdef>sg_disk_io_stats *<function>sg_get_disk_io_stats</function></funcdef>
52	<paramdef>int *<parameter>entries</parameter></paramdef>
53	</funcprototype>
54	<funcprototype>
55	<funcdef>sg_disk_io_stats *<function>sg_get_disk_io_stats_diff</function></funcdef>
56	<paramdef>int *<parameter>entries</parameter></paramdef>
57	</funcprototype>
58
59	<funcprototype>
60	<funcdef>sg_host_info *<function>sg_get_host_info</function></funcdef>
61	<void/>
62	</funcprototype>
63
64	<funcprototype>
65	<funcdef>sg_load_stats *<function>sg_get_load_stats</function></funcdef>
66	<void/>
67	</funcprototype>
68
69	<funcprototype>
70	<funcdef>sg_mem_stats *<function>sg_get_mem_stats</function></funcdef>
71	<void/>
72	</funcprototype>
73	<funcprototype>
74	<funcdef>sg_swap_stats *<function>sg_get_swap_stats</function></funcdef>
75	<void/>
76	</funcprototype>
77
78	<funcprototype>
79	<funcdef>sg_network_io_stats *<function>sg_get_network_io_stats</function></funcdef>
80	<paramdef>int *<parameter>entries</parameter></paramdef>
81	</funcprototype>
82	<funcprototype>
83	<funcdef>sg_network_io_stats *<function>sg_get_network_io_stats_diff</function></funcdef>
84	<paramdef>int *<parameter>entries</parameter></paramdef>
85	</funcprototype>
86
87	<funcprototype>
88	<funcdef>sg_network_iface_stats *<function>sg_get_network_iface_stats</function></funcdef>
89	<paramdef>int *<parameter>entries</parameter></paramdef>
90	</funcprototype>
91
92	<funcprototype>
93	<funcdef>sg_page_stats *<function>sg_get_page_stats</function></funcdef>
94	<void/>
95	</funcprototype>
96	<funcprototype>
97	<funcdef>sg_page_stats *<function>sg_get_page_stats_diff</function></funcdef>
98	<void/>
99	</funcprototype>
100
101	<funcprototype>
102	<funcdef>sg_process_count *<function>sg_get_process_stats</function></funcdef>
103	<void/>
104	</funcprototype>
105
106	<funcprototype>
107	<funcdef>sg_user_stats *<function>sg_get_user_stats</function></funcdef>
108	<void/>
109	</funcprototype>
110
111	</funcsynopsis>
112	</refsynopsisdiv>
113
114	<refsect1>
115	<title>Description</title>
116	<para>
117	The statgrab library provides a cross-platform interface to getting
118	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	</para>
122	<para>
123	<function>sg_init</function> must be the first
124	function you call before you start to use libstatgrab; it performs all
125	the one-time initialisation operations that need setuid/setgid
126	privileges. For instance, on *BSD it opens a descriptor to be able to
127	read kernel structures later on, and on Solaris it reads the device
128	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	<function>sg_drop_privileges</function>, which discards
132	setuid and setgid privileges, immediately after you call
133	<function>sg_init</function>, unless your application has
134	another reason for needing setuid or setgid privileges.
135	</para>
136	<para>
137	<function>sg_init</function> and
138	<function>sg_drop_privileges</function> return 0 on success, and
139	non-zero on failure.
140	</para>
141	<para>
142	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	</para>
147	</refsect1>
148
149	<refsect1>
150	<title>See Also</title>
151
152	<simplelist type="inline">
153	<member>
154	<citerefentry>
155	<refentrytitle>sg_get_cpu_percents</refentrytitle>
156	<manvolnum>3</manvolnum>
157	</citerefentry>
158	<citerefentry>
159	<refentrytitle>sg_get_disk_io_stats</refentrytitle>
160	<manvolnum>3</manvolnum>
161	</citerefentry>
162	<citerefentry>
163	<refentrytitle>sg_get_host_info</refentrytitle>
164	<manvolnum>3</manvolnum>
165	</citerefentry>
166	<citerefentry>
167	<refentrytitle>sg_get_load_stats</refentrytitle>
168	<manvolnum>3</manvolnum>
169	</citerefentry>
170	<citerefentry>
171	<refentrytitle>sg_get_mem_stats</refentrytitle>
172	<manvolnum>3</manvolnum>
173	</citerefentry>
174	<citerefentry>
175	<refentrytitle>sg_get_network_io_stats</refentrytitle>
176	<manvolnum>3</manvolnum>
177	</citerefentry>
178	<citerefentry>
179	<refentrytitle>sg_get_network_iface_stats</refentrytitle>
180	<manvolnum>3</manvolnum>
181	</citerefentry>
182	<citerefentry>
183	<refentrytitle>sg_get_page_stats</refentrytitle>
184	<manvolnum>3</manvolnum>
185	</citerefentry>
186	<citerefentry>
187	<refentrytitle>sg_get_process_stats</refentrytitle>
188	<manvolnum>3</manvolnum>
189	</citerefentry>
190	<citerefentry>
191	<refentrytitle>sg_get_user_stats</refentrytitle>
192	<manvolnum>3</manvolnum>
193	</citerefentry>
194	</member>
195	</simplelist>
196	</refsect1>
197
198	<refsect1>
199	<title>Website</title>
200
201	<simplelist type="vert">
202	<member>
203	<ulink url="http://www.i-scream.org/libstatgrab/">
204	http://www.i-scream.org/libstatgrab/
205	</ulink>
206	</member>
207	</simplelist>
208	</refsect1>
209
210	</refentry>