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/02 17:39:19 $</date>
    <releaseinfo>$Id: statgrab.xml,v 1.8 2004/05/02 17:39:19 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_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_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.9
Committed:	Tue May 4 19:28:06 2004 UTC (20 years, 6 months ago) by tdb
Content type:	text/xml
Branch:	MAIN
Changes since 1.8:	+28 -2 lines
Log Message:	Document the new process stats code a bit, and the error reporting code. No mention of the sorting stuff, because I'm not sure how that works. That's it for new stuff - assuming I haven't missed anything.
#	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.9	<date>$Date: 2004/05/02 17:39:19 $</date>
10			<releaseinfo>$Id: statgrab.xml,v 1.8 2004/05/02 17:39:19 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			</funcprototype>
71
72			<funcprototype>
73	tdb	1.8	<funcdef>sg_host_info *<function>sg_get_host_info</function></funcdef>
74	tdb	1.1	<void/>
75			</funcprototype>
76
77			<funcprototype>
78	tdb	1.8	<funcdef>sg_load_stats *<function>sg_get_load_stats</function></funcdef>
79	tdb	1.1	<void/>
80			</funcprototype>
81
82			<funcprototype>
83	tdb	1.8	<funcdef>sg_mem_stats *<function>sg_get_mem_stats</function></funcdef>
84	tdb	1.1	<void/>
85			</funcprototype>
86			<funcprototype>
87	tdb	1.8	<funcdef>sg_swap_stats *<function>sg_get_swap_stats</function></funcdef>
88	tdb	1.1	<void/>
89			</funcprototype>
90
91			<funcprototype>
92	tdb	1.8	<funcdef>sg_network_io_stats *<function>sg_get_network_io_stats</function></funcdef>
93	tdb	1.1	<paramdef>int *<parameter>entries</parameter></paramdef>
94			</funcprototype>
95			<funcprototype>
96	tdb	1.8	<funcdef>sg_network_io_stats *<function>sg_get_network_io_stats_diff</function></funcdef>
97	tdb	1.1	<paramdef>int *<parameter>entries</parameter></paramdef>
98			</funcprototype>
99
100			<funcprototype>
101	tdb	1.8	<funcdef>sg_network_iface_stats *<function>sg_get_network_iface_stats</function></funcdef>
102	tdb	1.6	<paramdef>int *<parameter>entries</parameter></paramdef>
103			</funcprototype>
104
105			<funcprototype>
106	tdb	1.8	<funcdef>sg_page_stats *<function>sg_get_page_stats</function></funcdef>
107	tdb	1.1	<void/>
108			</funcprototype>
109			<funcprototype>
110	tdb	1.8	<funcdef>sg_page_stats *<function>sg_get_page_stats_diff</function></funcdef>
111	tdb	1.1	<void/>
112			</funcprototype>
113
114			<funcprototype>
115	tdb	1.8	<funcdef>sg_process_count *<function>sg_get_process_stats</function></funcdef>
116	tdb	1.1	<void/>
117			</funcprototype>
118
119			<funcprototype>
120	tdb	1.8	<funcdef>sg_user_stats *<function>sg_get_user_stats</function></funcdef>
121	tdb	1.1	<void/>
122			</funcprototype>
123
124			</funcsynopsis>
125			</refsynopsisdiv>
126	tdb	1.8
127	tdb	1.1	<refsect1>
128			<title>Description</title>
129			<para>
130	ats	1.4	The statgrab library provides a cross-platform interface to getting
131	tdb	1.1	system statistics. Each of the function calls returns a structure
132			containing statistics. See the manual page for each individual
133			function for more details on usage.
134	pajs	1.2	</para>
135			<para>
136	tdb	1.8	<function>sg_init</function> must be the first
137	ats	1.4	function you call before you start to use libstatgrab; it performs all
138			the one-time initialisation operations that need setuid/setgid
139	pajs	1.5	privileges. For instance, on *BSD it opens a descriptor to be able to
140	ats	1.4	read kernel structures later on, and on Solaris it reads the device
141	pajs	1.5	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	tdb	1.8	<function>sg_drop_privileges</function>, which discards
145	ats	1.3	setuid and setgid privileges, immediately after you call
146	tdb	1.8	<function>sg_init</function>, unless your application has
147	ats	1.3	another reason for needing setuid or setgid privileges.
148	pajs	1.2	</para>
149			<para>
150	tdb	1.8	<function>sg_init</function> and
151			<function>sg_drop_privileges</function> return 0 on success, and
152	pajs	1.2	non-zero on failure.
153	tdb	1.9	</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	tdb	1.1	</para>
167			<para>
168	tdb	1.6	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	tdb	1.1	</para>
173			</refsect1>
174	tdb	1.8
175	tdb	1.1	<refsect1>
176			<title>See Also</title>
177
178			<simplelist type="inline">
179			<member>
180			<citerefentry>
181	tdb	1.8	<refentrytitle>sg_get_cpu_percents</refentrytitle>
182	tdb	1.1	<manvolnum>3</manvolnum>
183			</citerefentry>
184			<citerefentry>
185	tdb	1.8	<refentrytitle>sg_get_disk_io_stats</refentrytitle>
186	tdb	1.1	<manvolnum>3</manvolnum>
187			</citerefentry>
188			<citerefentry>
189	tdb	1.8	<refentrytitle>sg_get_host_info</refentrytitle>
190	tdb	1.1	<manvolnum>3</manvolnum>
191			</citerefentry>
192			<citerefentry>
193	tdb	1.8	<refentrytitle>sg_get_load_stats</refentrytitle>
194	tdb	1.1	<manvolnum>3</manvolnum>
195			</citerefentry>
196			<citerefentry>
197	tdb	1.8	<refentrytitle>sg_get_mem_stats</refentrytitle>
198	tdb	1.1	<manvolnum>3</manvolnum>
199			</citerefentry>
200			<citerefentry>
201	tdb	1.8	<refentrytitle>sg_get_network_io_stats</refentrytitle>
202	tdb	1.6	<manvolnum>3</manvolnum>
203			</citerefentry>
204			<citerefentry>
205	tdb	1.8	<refentrytitle>sg_get_network_iface_stats</refentrytitle>
206	tdb	1.1	<manvolnum>3</manvolnum>
207			</citerefentry>
208			<citerefentry>
209	tdb	1.8	<refentrytitle>sg_get_page_stats</refentrytitle>
210	tdb	1.1	<manvolnum>3</manvolnum>
211			</citerefentry>
212			<citerefentry>
213	tdb	1.8	<refentrytitle>sg_get_process_stats</refentrytitle>
214	tdb	1.1	<manvolnum>3</manvolnum>
215			</citerefentry>
216			<citerefentry>
217	tdb	1.8	<refentrytitle>sg_get_user_stats</refentrytitle>
218	tdb	1.1	<manvolnum>3</manvolnum>
219			</citerefentry>
220			</member>
221			</simplelist>
222			</refsect1>
223	tdb	1.8
224	tdb	1.1	<refsect1>
225			<title>Website</title>
226	tdb	1.8
227	tdb	1.1	<simplelist type="vert">
228			<member>
229	tdb	1.7	<ulink url="http://www.i-scream.org/libstatgrab/">
230			http://www.i-scream.org/libstatgrab/
231			</ulink>
232	tdb	1.1	</member>
233			</simplelist>
234			</refsect1>
235
236			</refentry>