docs/libstatgrab/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 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.
#	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/02 17:39:19 $</date>
10	<releaseinfo>$Id: statgrab.xml,v 1.8 2004/05/02 17:39:19 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_host_info *<function>sg_get_host_info</function></funcdef>
74	<void/>
75	</funcprototype>
76
77	<funcprototype>
78	<funcdef>sg_load_stats *<function>sg_get_load_stats</function></funcdef>
79	<void/>
80	</funcprototype>
81
82	<funcprototype>
83	<funcdef>sg_mem_stats *<function>sg_get_mem_stats</function></funcdef>
84	<void/>
85	</funcprototype>
86	<funcprototype>
87	<funcdef>sg_swap_stats *<function>sg_get_swap_stats</function></funcdef>
88	<void/>
89	</funcprototype>
90
91	<funcprototype>
92	<funcdef>sg_network_io_stats *<function>sg_get_network_io_stats</function></funcdef>
93	<paramdef>int *<parameter>entries</parameter></paramdef>
94	</funcprototype>
95	<funcprototype>
96	<funcdef>sg_network_io_stats *<function>sg_get_network_io_stats_diff</function></funcdef>
97	<paramdef>int *<parameter>entries</parameter></paramdef>
98	</funcprototype>
99
100	<funcprototype>
101	<funcdef>sg_network_iface_stats *<function>sg_get_network_iface_stats</function></funcdef>
102	<paramdef>int *<parameter>entries</parameter></paramdef>
103	</funcprototype>
104
105	<funcprototype>
106	<funcdef>sg_page_stats *<function>sg_get_page_stats</function></funcdef>
107	<void/>
108	</funcprototype>
109	<funcprototype>
110	<funcdef>sg_page_stats *<function>sg_get_page_stats_diff</function></funcdef>
111	<void/>
112	</funcprototype>
113
114	<funcprototype>
115	<funcdef>sg_process_count *<function>sg_get_process_stats</function></funcdef>
116	<void/>
117	</funcprototype>
118
119	<funcprototype>
120	<funcdef>sg_user_stats *<function>sg_get_user_stats</function></funcdef>
121	<void/>
122	</funcprototype>
123
124	</funcsynopsis>
125	</refsynopsisdiv>
126
127	<refsect1>
128	<title>Description</title>
129	<para>
130	The statgrab library provides a cross-platform interface to getting
131	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	</para>
135	<para>
136	<function>sg_init</function> must be the first
137	function you call before you start to use libstatgrab; it performs all
138	the one-time initialisation operations that need setuid/setgid
139	privileges. For instance, on *BSD it opens a descriptor to be able to
140	read kernel structures later on, and on Solaris it reads the device
141	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	<function>sg_drop_privileges</function>, which discards
145	setuid and setgid privileges, immediately after you call
146	<function>sg_init</function>, unless your application has
147	another reason for needing setuid or setgid privileges.
148	</para>
149	<para>
150	<function>sg_init</function> and
151	<function>sg_drop_privileges</function> return 0 on success, and
152	non-zero on failure.
153	</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	</para>
167	<para>
168	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	</para>
173	</refsect1>
174
175	<refsect1>
176	<title>See Also</title>
177
178	<simplelist type="inline">
179	<member>
180	<citerefentry>
181	<refentrytitle>sg_get_cpu_percents</refentrytitle>
182	<manvolnum>3</manvolnum>
183	</citerefentry>
184	<citerefentry>
185	<refentrytitle>sg_get_disk_io_stats</refentrytitle>
186	<manvolnum>3</manvolnum>
187	</citerefentry>
188	<citerefentry>
189	<refentrytitle>sg_get_host_info</refentrytitle>
190	<manvolnum>3</manvolnum>
191	</citerefentry>
192	<citerefentry>
193	<refentrytitle>sg_get_load_stats</refentrytitle>
194	<manvolnum>3</manvolnum>
195	</citerefentry>
196	<citerefentry>
197	<refentrytitle>sg_get_mem_stats</refentrytitle>
198	<manvolnum>3</manvolnum>
199	</citerefentry>
200	<citerefentry>
201	<refentrytitle>sg_get_network_io_stats</refentrytitle>
202	<manvolnum>3</manvolnum>
203	</citerefentry>
204	<citerefentry>
205	<refentrytitle>sg_get_network_iface_stats</refentrytitle>
206	<manvolnum>3</manvolnum>
207	</citerefentry>
208	<citerefentry>
209	<refentrytitle>sg_get_page_stats</refentrytitle>
210	<manvolnum>3</manvolnum>
211	</citerefentry>
212	<citerefentry>
213	<refentrytitle>sg_get_process_stats</refentrytitle>
214	<manvolnum>3</manvolnum>
215	</citerefentry>
216	<citerefentry>
217	<refentrytitle>sg_get_user_stats</refentrytitle>
218	<manvolnum>3</manvolnum>
219	</citerefentry>
220	</member>
221	</simplelist>
222	</refsect1>
223
224	<refsect1>
225	<title>Website</title>
226
227	<simplelist type="vert">
228	<member>
229	<ulink url="http://www.i-scream.org/libstatgrab/">
230	http://www.i-scream.org/libstatgrab/
231	</ulink>
232	</member>
233	</simplelist>
234	</refsect1>
235
236	</refentry>