<?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: 2006/04/15 18:16:33 $</date>
<releaseinfo>$Id: statgrab.xml,v 1.1 2006/04/15 18:16:33 stevecheng 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 <statgrab.h></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 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>