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/01/05 17:20:29 $</date>
    <releaseinfo>$Id: statgrab.xml,v 1.3 2004/01/05 17:20:29 ats 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>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 are only accessible by root). 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, 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_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">http://www.i-scream.org</ulink>
      </member>
    </simplelist>
  </refsect1>

</refentry>
Revision:	1.4
Committed:	Mon Jan 5 17:27:29 2004 UTC (20 years, 4 months ago) by ats
Content type:	text/xml
Branch:	MAIN
Changes since 1.3:	+12 -11 lines
Log Message:	Fix a typo. Tidy up the description of statgrab_init a bit. Update the list of supported platforms.
#	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	ats	1.4	<date>$Date: 2004/01/05 17:20:29 $</date>
10			<releaseinfo>$Id: statgrab.xml,v 1.3 2004/01/05 17:20:29 ats 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			<funcdef>page_stat_t *<function>get_page_stats</function></funcdef>
89			<void/>
90			</funcprototype>
91			<funcprototype>
92			<funcdef>page_stat_t *<function>get_page_stats_diff</function></funcdef>
93			<void/>
94			</funcprototype>
95
96			<funcprototype>
97			<funcdef>process_stat_t *<function>get_process_stats</function></funcdef>
98			<void/>
99			</funcprototype>
100
101			<funcprototype>
102			<funcdef>user_stat_t *<function>get_user_stats</function></funcdef>
103			<void/>
104			</funcprototype>
105
106			</funcsynopsis>
107			</refsynopsisdiv>
108
109			<refsect1>
110			<title>Description</title>
111			<para>
112	ats	1.4	The statgrab library provides a cross-platform interface to getting
113	tdb	1.1	system statistics. Each of the function calls returns a structure
114			containing statistics. See the manual page for each individual
115			function for more details on usage.
116	pajs	1.2	</para>
117			<para>
118	ats	1.4	<function>statgrab_init</function> must be the first
119			function you call before you start to use libstatgrab; it performs all
120			the one-time initialisation operations that need setuid/setgid
121			privileges (for instance, on *BSD it opens a descriptor to be able to
122			read kernel structures later on, and on Solaris it reads the device
123			mappings that are only accessible by root). Once this has run,
124			the other libstatgrab functions no longer need elevated privileges.
125			It is therefore a good idea to call
126	ats	1.3	<function>statgrab_drop_privileges</function>, which discards
127			setuid and setgid privileges, immediately after you call
128			<function>statgrab_init</function>, unless your application has
129			another reason for needing setuid or setgid privileges.
130	pajs	1.2	</para>
131			<para>
132	ats	1.3	<function>statgrab_init</function> and
133			<function>statgrab_drop_privileges</function> return 0 on success, and
134	pajs	1.2	non-zero on failure.
135	tdb	1.1	</para>
136			<para>
137			The library was originally written to support the i-scream central
138			monitoring system, but has since become a standalone package. It
139	ats	1.4	has been ported to work on Linux, NetBSD, FreeBSD, Solaris and Cygwin.
140	tdb	1.1	</para>
141			</refsect1>
142
143			<refsect1>
144			<title>See Also</title>
145
146			<simplelist type="inline">
147			<member>
148			<citerefentry>
149			<refentrytitle>cpu_percent_usage</refentrytitle>
150			<manvolnum>3</manvolnum>
151			</citerefentry>
152			<citerefentry>
153			<refentrytitle>get_diskio_stats</refentrytitle>
154			<manvolnum>3</manvolnum>
155			</citerefentry>
156			<citerefentry>
157			<refentrytitle>get_general_stats</refentrytitle>
158			<manvolnum>3</manvolnum>
159			</citerefentry>
160			<citerefentry>
161			<refentrytitle>get_load_stats</refentrytitle>
162			<manvolnum>3</manvolnum>
163			</citerefentry>
164			<citerefentry>
165			<refentrytitle>get_memory_stats</refentrytitle>
166			<manvolnum>3</manvolnum>
167			</citerefentry>
168			<citerefentry>
169			<refentrytitle>get_network_stats</refentrytitle>
170			<manvolnum>3</manvolnum>
171			</citerefentry>
172			<citerefentry>
173			<refentrytitle>get_page_stats</refentrytitle>
174			<manvolnum>3</manvolnum>
175			</citerefentry>
176			<citerefentry>
177			<refentrytitle>get_process_stats</refentrytitle>
178			<manvolnum>3</manvolnum>
179			</citerefentry>
180			<citerefentry>
181			<refentrytitle>get_user_stats</refentrytitle>
182			<manvolnum>3</manvolnum>
183			</citerefentry>
184			</member>
185			</simplelist>
186			</refsect1>
187
188			<refsect1>
189			<title>Website</title>
190
191			<simplelist type="vert">
192			<member>
193			<ulink url="http://www.i-scream.org">http://www.i-scream.org</ulink>
194			</member>
195			</simplelist>
196			</refsect1>
197
198			</refentry>