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/04 19:28:06 $</date>
    <releaseinfo>$Id: statgrab.xml,v 1.9 2004/05/04 19:28:06 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_fs_stats *<function>sg_get_fs_stats</function></funcdef>
        <void/>
      </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.10
Committed:	Wed May 5 10:40:50 2004 UTC (20 years ago) by tdb
Content type:	text/xml
Branch:	MAIN
Changes since 1.9:	+7 -2 lines
Log Message:	Add sg_get_fs_stats to statgrab.xml.
#	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/05/04 19:28:06 $</date>
10	<releaseinfo>$Id: statgrab.xml,v 1.9 2004/05/04 19:28:06 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_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	<funcdef>sg_cpu_stats *<function>sg_get_cpu_stats</function></funcdef>
52	<void/>
53	</funcprototype>
54	<funcprototype>
55	<funcdef>sg_cpu_stats *<function>sg_get_cpu_stats_diff</function></funcdef>
56	<void/>
57	</funcprototype>
58	<funcprototype>
59	<funcdef>sg_cpu_percents *<function>sg_get_cpu_percents</function></funcdef>
60	<void/>
61	</funcprototype>
62
63	<funcprototype>
64	<funcdef>sg_disk_io_stats *<function>sg_get_disk_io_stats</function></funcdef>
65	<paramdef>int *<parameter>entries</parameter></paramdef>
66	</funcprototype>
67	<funcprototype>
68	<funcdef>sg_disk_io_stats *<function>sg_get_disk_io_stats_diff</function></funcdef>
69	<paramdef>int *<parameter>entries</parameter></paramdef>
70	</funcprototype>
71
72	<funcprototype>
73	<funcdef>sg_fs_stats *<function>sg_get_fs_stats</function></funcdef>
74	<void/>
75	</funcprototype>
76
77	<funcprototype>
78	<funcdef>sg_host_info *<function>sg_get_host_info</function></funcdef>
79	<void/>
80	</funcprototype>
81
82	<funcprototype>
83	<funcdef>sg_load_stats *<function>sg_get_load_stats</function></funcdef>
84	<void/>
85	</funcprototype>
86
87	<funcprototype>
88	<funcdef>sg_mem_stats *<function>sg_get_mem_stats</function></funcdef>
89	<void/>
90	</funcprototype>
91	<funcprototype>
92	<funcdef>sg_swap_stats *<function>sg_get_swap_stats</function></funcdef>
93	<void/>
94	</funcprototype>
95
96	<funcprototype>
97	<funcdef>sg_network_io_stats *<function>sg_get_network_io_stats</function></funcdef>
98	<paramdef>int *<parameter>entries</parameter></paramdef>
99	</funcprototype>
100	<funcprototype>
101	<funcdef>sg_network_io_stats *<function>sg_get_network_io_stats_diff</function></funcdef>
102	<paramdef>int *<parameter>entries</parameter></paramdef>
103	</funcprototype>
104
105	<funcprototype>
106	<funcdef>sg_network_iface_stats *<function>sg_get_network_iface_stats</function></funcdef>
107	<paramdef>int *<parameter>entries</parameter></paramdef>
108	</funcprototype>
109
110	<funcprototype>
111	<funcdef>sg_page_stats *<function>sg_get_page_stats</function></funcdef>
112	<void/>
113	</funcprototype>
114	<funcprototype>
115	<funcdef>sg_page_stats *<function>sg_get_page_stats_diff</function></funcdef>
116	<void/>
117	</funcprototype>
118
119	<funcprototype>
120	<funcdef>sg_process_count *<function>sg_get_process_stats</function></funcdef>
121	<void/>
122	</funcprototype>
123
124	<funcprototype>
125	<funcdef>sg_user_stats *<function>sg_get_user_stats</function></funcdef>
126	<void/>
127	</funcprototype>
128
129	</funcsynopsis>
130	</refsynopsisdiv>
131
132	<refsect1>
133	<title>Description</title>
134	<para>
135	The statgrab library provides a cross-platform interface to getting
136	system statistics. Each of the function calls returns a structure
137	containing statistics. See the manual page for each individual
138	function for more details on usage.
139	</para>
140	<para>
141	<function>sg_init</function> must be the first
142	function you call before you start to use libstatgrab; it performs all
143	the one-time initialisation operations that need setuid/setgid
144	privileges. For instance, on *BSD it opens a descriptor to be able to
145	read kernel structures later on, and on Solaris it reads the device
146	mappings that in some cases are only accessible by root (machines with
147	a /dev/osa). Once this has run, the other libstatgrab functions no longer
148	need elevated privileges. It is therefore a good idea to call
149	<function>sg_drop_privileges</function>, which discards
150	setuid and setgid privileges, immediately after you call
151	<function>sg_init</function>, unless your application has
152	another reason for needing setuid or setgid privileges.
153	</para>
154	<para>
155	<function>sg_init</function> and
156	<function>sg_drop_privileges</function> return 0 on success, and
157	non-zero on failure.
158	</para>
159	<para>
160	There are three functions relating to error reporting in libstatgrab.
161	The first, <function>sg_get_error</function> returns an sg_error code
162	which relates to the last error generated by libstatgrab. This can be
163	converted to a string by calling <function>sg_str_error</function>
164	giving the sg_error code as an argument. Finally, an optional
165	argument may be set when the error was generated. This can be
166	accessed by calling <function>sg_get_error_arg</function>.
167	</para>
168	<para>
169	It is the intended practice that whenever a libstatgrab function is
170	called and subsequently fails that an appropriate error will be set.
171	</para>
172	<para>
173	The library was originally written to support the i-scream
174	central monitoring system, but has since become a standalone
175	package. It has been ported to work on Linux, NetBSD, FreeBSD,
176	OpenBSD, DragonFly BSD, Solaris and Cygwin.
177	</para>
178	</refsect1>
179
180	<refsect1>
181	<title>See Also</title>
182
183	<simplelist type="inline">
184	<member>
185	<citerefentry>
186	<refentrytitle>sg_get_cpu_percents</refentrytitle>
187	<manvolnum>3</manvolnum>
188	</citerefentry>
189	<citerefentry>
190	<refentrytitle>sg_get_disk_io_stats</refentrytitle>
191	<manvolnum>3</manvolnum>
192	</citerefentry>
193	<citerefentry>
194	<refentrytitle>sg_get_host_info</refentrytitle>
195	<manvolnum>3</manvolnum>
196	</citerefentry>
197	<citerefentry>
198	<refentrytitle>sg_get_load_stats</refentrytitle>
199	<manvolnum>3</manvolnum>
200	</citerefentry>
201	<citerefentry>
202	<refentrytitle>sg_get_mem_stats</refentrytitle>
203	<manvolnum>3</manvolnum>
204	</citerefentry>
205	<citerefentry>
206	<refentrytitle>sg_get_network_io_stats</refentrytitle>
207	<manvolnum>3</manvolnum>
208	</citerefentry>
209	<citerefentry>
210	<refentrytitle>sg_get_network_iface_stats</refentrytitle>
211	<manvolnum>3</manvolnum>
212	</citerefentry>
213	<citerefentry>
214	<refentrytitle>sg_get_page_stats</refentrytitle>
215	<manvolnum>3</manvolnum>
216	</citerefentry>
217	<citerefentry>
218	<refentrytitle>sg_get_process_stats</refentrytitle>
219	<manvolnum>3</manvolnum>
220	</citerefentry>
221	<citerefentry>
222	<refentrytitle>sg_get_user_stats</refentrytitle>
223	<manvolnum>3</manvolnum>
224	</citerefentry>
225	</member>
226	</simplelist>
227	</refsect1>
228
229	<refsect1>
230	<title>Website</title>
231
232	<simplelist type="vert">
233	<member>
234	<ulink url="http://www.i-scream.org/libstatgrab/">
235	http://www.i-scream.org/libstatgrab/
236	</ulink>
237	</member>
238	</simplelist>
239	</refsect1>
240
241	</refentry>