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/06 23:35:20 $</date>
    <releaseinfo>$Id: statgrab.xml,v 1.6 2004/03/06 23:35:20 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>statgrab_init</function></funcdef>
        <void/>
      </funcprototype>
      <funcprototype>
        <funcdef>int <function>statgrab_drop_privileges</function></funcdef>
        <void/>
      </funcprototype>

      <funcprototype>
        <funcdef>cpu_percent_t *<function>cpu_percent_usage</function></funcdef>
        <void/>
      </funcprototype>
      <funcprototype>
        <funcdef>cpu_states_t *<function>get_cpu_totals</function></funcdef>
        <void/>
      </funcprototype>
      <funcprototype>
        <funcdef>cpu_states_t *<function>get_cpu_diff</function></funcdef>
        <void/>
      </funcprototype>

      <funcprototype>
        <funcdef>diskio_stat_t *<function>get_diskio_stats</function></funcdef>
        <paramdef>int *<parameter>entries</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>diskio_stat_t *<function>get_diskio_stats_diff</function></funcdef>
        <paramdef>int *<parameter>entries</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>general_stat_t *<function>get_general_stats</function></funcdef>
        <void/>
      </funcprototype>

      <funcprototype>
        <funcdef>load_stat_t *<function>get_load_stats</function></funcdef>
        <void/>
      </funcprototype>

      <funcprototype>
        <funcdef>mem_stat_t *<function>get_memory_stats</function></funcdef>
        <void/>
      </funcprototype>
      <funcprototype>
        <funcdef>swap_stat_t *<function>get_swap_stats</function></funcdef>
        <void/>
      </funcprototype>

      <funcprototype>
        <funcdef>network_stat_t *<function>get_network_stats</function></funcdef>
        <paramdef>int *<parameter>entries</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>network_stat_t *<function>get_network_stats_diff</function></funcdef>
        <paramdef>int *<parameter>entries</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>network_iface_stat_t *<function>get_network_iface_stats</function></funcdef>
        <paramdef>int *<parameter>entries</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>page_stat_t *<function>get_page_stats</function></funcdef>
        <void/>
      </funcprototype>
      <funcprototype>
        <funcdef>page_stat_t *<function>get_page_stats_diff</function></funcdef>
        <void/>
      </funcprototype>

      <funcprototype>
        <funcdef>process_stat_t *<function>get_process_stats</function></funcdef>
        <void/>
      </funcprototype>

      <funcprototype>
        <funcdef>user_stat_t *<function>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>statgrab_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>statgrab_drop_privileges</function>, which discards
      setuid and setgid privileges, immediately after you call
      <function>statgrab_init</function>, unless your application has
      another reason for needing setuid or setgid privileges.
    </para>
    <para>
      <function>statgrab_init</function> and
      <function>statgrab_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>cpu_percent_usage</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>get_diskio_stats</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>get_general_stats</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>get_load_stats</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>get_memory_stats</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>get_network_stats</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>get_network_iface_stats</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>get_page_stats</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>get_process_stats</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry>
        <citerefentry>
          <refentrytitle>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.7
Committed:	Thu Mar 11 17:35:24 2004 UTC (20 years, 7 months ago) by tdb
Content type:	text/xml
Branch:	MAIN
Changes since 1.6:	+5 -3 lines
Log Message:	Put libstatgrab URL, rather than i-scream URL, in the docs.
#	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.7	<date>$Date: 2004/03/06 23:35:20 $</date>
10			<releaseinfo>$Id: statgrab.xml,v 1.6 2004/03/06 23:35:20 tdb Exp $</releaseinfo>
11	tdb	1.1	</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	pajs	1.2	<funcdef>int <function>statgrab_init</function></funcdef>
30			<void/>
31			</funcprototype>
32	ats	1.3	<funcprototype>
33			<funcdef>int <function>statgrab_drop_privileges</function></funcdef>
34			<void/>
35			</funcprototype>
36	pajs	1.2
37			<funcprototype>
38	tdb	1.1	<funcdef>cpu_percent_t *<function>cpu_percent_usage</function></funcdef>
39			<void/>
40			</funcprototype>
41			<funcprototype>
42			<funcdef>cpu_states_t *<function>get_cpu_totals</function></funcdef>
43			<void/>
44			</funcprototype>
45			<funcprototype>
46			<funcdef>cpu_states_t *<function>get_cpu_diff</function></funcdef>
47			<void/>
48			</funcprototype>
49
50			<funcprototype>
51			<funcdef>diskio_stat_t *<function>get_diskio_stats</function></funcdef>
52			<paramdef>int *<parameter>entries</parameter></paramdef>
53			</funcprototype>
54			<funcprototype>
55			<funcdef>diskio_stat_t *<function>get_diskio_stats_diff</function></funcdef>
56			<paramdef>int *<parameter>entries</parameter></paramdef>
57			</funcprototype>
58
59			<funcprototype>
60			<funcdef>general_stat_t *<function>get_general_stats</function></funcdef>
61			<void/>
62			</funcprototype>
63
64			<funcprototype>
65			<funcdef>load_stat_t *<function>get_load_stats</function></funcdef>
66			<void/>
67			</funcprototype>
68
69			<funcprototype>
70			<funcdef>mem_stat_t *<function>get_memory_stats</function></funcdef>
71			<void/>
72			</funcprototype>
73			<funcprototype>
74			<funcdef>swap_stat_t *<function>get_swap_stats</function></funcdef>
75			<void/>
76			</funcprototype>
77
78			<funcprototype>
79			<funcdef>network_stat_t *<function>get_network_stats</function></funcdef>
80			<paramdef>int *<parameter>entries</parameter></paramdef>
81			</funcprototype>
82			<funcprototype>
83			<funcdef>network_stat_t *<function>get_network_stats_diff</function></funcdef>
84			<paramdef>int *<parameter>entries</parameter></paramdef>
85			</funcprototype>
86
87			<funcprototype>
88	tdb	1.6	<funcdef>network_iface_stat_t *<function>get_network_iface_stats</function></funcdef>
89			<paramdef>int *<parameter>entries</parameter></paramdef>
90			</funcprototype>
91
92			<funcprototype>
93	tdb	1.1	<funcdef>page_stat_t *<function>get_page_stats</function></funcdef>
94			<void/>
95			</funcprototype>
96			<funcprototype>
97			<funcdef>page_stat_t *<function>get_page_stats_diff</function></funcdef>
98			<void/>
99			</funcprototype>
100
101			<funcprototype>
102			<funcdef>process_stat_t *<function>get_process_stats</function></funcdef>
103			<void/>
104			</funcprototype>
105
106			<funcprototype>
107			<funcdef>user_stat_t *<function>get_user_stats</function></funcdef>
108			<void/>
109			</funcprototype>
110
111			</funcsynopsis>
112			</refsynopsisdiv>
113
114			<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	ats	1.4	<function>statgrab_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	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	ats	1.3	<function>statgrab_drop_privileges</function>, which discards
132			setuid and setgid privileges, immediately after you call
133			<function>statgrab_init</function>, unless your application has
134			another reason for needing setuid or setgid privileges.
135	pajs	1.2	</para>
136			<para>
137	ats	1.3	<function>statgrab_init</function> and
138			<function>statgrab_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
149			<refsect1>
150			<title>See Also</title>
151
152			<simplelist type="inline">
153			<member>
154			<citerefentry>
155			<refentrytitle>cpu_percent_usage</refentrytitle>
156			<manvolnum>3</manvolnum>
157			</citerefentry>
158			<citerefentry>
159			<refentrytitle>get_diskio_stats</refentrytitle>
160			<manvolnum>3</manvolnum>
161			</citerefentry>
162			<citerefentry>
163			<refentrytitle>get_general_stats</refentrytitle>
164			<manvolnum>3</manvolnum>
165			</citerefentry>
166			<citerefentry>
167			<refentrytitle>get_load_stats</refentrytitle>
168			<manvolnum>3</manvolnum>
169			</citerefentry>
170			<citerefentry>
171			<refentrytitle>get_memory_stats</refentrytitle>
172			<manvolnum>3</manvolnum>
173			</citerefentry>
174			<citerefentry>
175			<refentrytitle>get_network_stats</refentrytitle>
176	tdb	1.6	<manvolnum>3</manvolnum>
177			</citerefentry>
178			<citerefentry>
179			<refentrytitle>get_network_iface_stats</refentrytitle>
180	tdb	1.1	<manvolnum>3</manvolnum>
181			</citerefentry>
182			<citerefentry>
183			<refentrytitle>get_page_stats</refentrytitle>
184			<manvolnum>3</manvolnum>
185			</citerefentry>
186			<citerefentry>
187			<refentrytitle>get_process_stats</refentrytitle>
188			<manvolnum>3</manvolnum>
189			</citerefentry>
190			<citerefentry>
191			<refentrytitle>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	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>