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