libstatgrab/docs/sg_get_disk_io_stats.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="sg_get_disk_io_stats">

  <refentryinfo>
    <date>$Date: 2004/05/02 17:21:35 $</date>
    <releaseinfo>$Id: sg_get_disk_io_stats.xml,v 1.7 2004/05/02 17:21:35 tdb Exp $</releaseinfo>
  </refentryinfo>

  <refmeta>
    <refentrytitle>sg_get_disk_io_stats</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo>i-scream</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>sg_get_disk_io_stats</refname>
    <refname>sg_get_disk_io_stats_diff</refname>
    <refpurpose>get disk io statistics</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;statgrab.h&gt;</funcsynopsisinfo>
      <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>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      Both calls take a pointer to an int,
      <parameter>entries</parameter>, which is filled with the number
      of disks the machine has. This is needed to know how many
      <structname>sg_disk_io_stats</structname> structures have been
      returned. A pointer is returned to the first
      <structname>sg_disk_io_stats</structname>.
    </para>
    <para>
      <function>sg_get_disk_io_stats</function> returns the disk IO stored
      in the kernel which holds the amount of data transferred since
      bootup. On some platforms, such as Solaris 7, this value is
      stored in a 32bit int, so wraps around when it reaches 4GB. Other
      platforms, such as Solaris 8, hold the value in a 64bit int,
      which wraps somewhere near 17 million terabytes.
    </para>
    <para>
      <function>sg_get_disk_io_stats_diff</function> is the same as
      <function>sg_get_disk_io_stats</function> except it will return the
      difference since the last call. So, for instance a call to
      <function>sg_get_disk_io_stats_diff</function> is made, and called
      again 5 seconds later. Over that time, 2000 bytes of traffic were
      written and 10000 bytes read.  <parameter>write_bytes</parameter>
      will store 2000 bytes, <parameter>read_bytes</parameter> will
      store 10000, and <parameter>systime</parameter> will store 5.
      This function copes with wrap arounds by the O/S so should be
      seemless to use.
    </para>
    <para>
      On Solaris libstatgrab will attempt to get the cXtXdXsX
      representation for the <varname>disk_name</varname> string. If
      it fails it will use a name like sd0. On some systems programs
      calling libstatgrab will need elevated privileges to lookup
      some of the names. The mappings are built up when
      <function>sg_init</function> is called.
    </para>
  </refsect1>

  <refsect1>
    <title>Return Values</title>

    <para>
      All diskio statistics return a pointer to a structure of type
      <structname>sg_disk_io_stats</structname>.
    </para>

    <programlisting>
typedef struct{
        char *disk_name;
        long long read_bytes;
        long long write_bytes;
        time_t systime;
}sg_disk_io_stats;
    </programlisting>

    <variablelist>
      <varlistentry>
        <term>
          <structfield>disk_name</structfield>
        </term>
        <listitem>
          <para>
            The name known to the operating system.
            (eg. on linux it might be hda)
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <structfield>read_bytes</structfield>
        </term>
        <listitem>
          <para>
            The number of bytes the disk has read.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <structfield>write_bytes</structfield>
        </term>
        <listitem>
          <para>
            The number of bytes the disk has written.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <structfield>systime</structfield>
        </term>
        <listitem>
          <para>
            The time period over which <parameter>read_bytes</parameter>
            and <parameter>write_bytes</parameter> were transferred.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Bugs</title>
    <para>
      On the very first call <function>sg_get_disk_io_stats_diff</function>
      will return the same as <function>sg_get_disk_io_stats</function>.
      After the first call it will always return the difference.
    </para>
    <para>
      On operating systems that hold only 32bits of data there is a
      problem if the values wrap twice. For example, on Solaris 7 if
      9GB is transferred and the operating system wraps at 4GB, the
      <function>sg_get_disk_io_stats_diff</function> function will return
      5GB.
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>

    <simplelist type="inline">
      <member>
        <citerefentry>
          <refentrytitle>statgrab</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.8
Committed:	Sun Jul 18 20:21:20 2004 UTC (21 years, 3 months ago) by tdb
Content type:	text/xml
Branch:	MAIN
CVS Tags:	LIBSTATGRAB_0_11_1, LIBSTATGRAB_0_11, LIBSTATGRAB_0_10_3, LIBSTATGRAB_0_10_2, LIBSTATGRAB_0_10_1
Changes since 1.7:	+3 -3 lines
Log Message:	Catch a few bits of documentation/comments containing the deprecated function names.
#	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	tdb	1.7	<refentry id="sg_get_disk_io_stats">
7	tdb	1.1
8			<refentryinfo>
9	tdb	1.8	<date>$Date: 2004/05/02 17:21:35 $</date>
10			<releaseinfo>$Id: sg_get_disk_io_stats.xml,v 1.7 2004/05/02 17:21:35 tdb Exp $</releaseinfo>
11	tdb	1.1	</refentryinfo>
12	tdb	1.7
13	tdb	1.1	<refmeta>
14	tdb	1.7	<refentrytitle>sg_get_disk_io_stats</refentrytitle>
15	tdb	1.1	<manvolnum>3</manvolnum>
16			<refmiscinfo>i-scream</refmiscinfo>
17			</refmeta>
18	tdb	1.7
19	tdb	1.1	<refnamediv>
20	tdb	1.7	<refname>sg_get_disk_io_stats</refname>
21			<refname>sg_get_disk_io_stats_diff</refname>
22	tdb	1.1	<refpurpose>get disk io statistics</refpurpose>
23			</refnamediv>
24	tdb	1.7
25	tdb	1.1	<refsynopsisdiv>
26			<funcsynopsis>
27			<funcsynopsisinfo>#include <statgrab.h></funcsynopsisinfo>
28			<funcprototype>
29	tdb	1.7	<funcdef>sg_disk_io_stats *<function>sg_get_disk_io_stats</function></funcdef>
30	tdb	1.1	<paramdef>int *<parameter>entries</parameter></paramdef>
31			</funcprototype>
32			<funcprototype>
33	tdb	1.7	<funcdef>sg_disk_io_stats *<function>sg_get_disk_io_stats_diff</function></funcdef>
34	tdb	1.1	<paramdef>int *<parameter>entries</parameter></paramdef>
35			</funcprototype>
36			</funcsynopsis>
37			</refsynopsisdiv>
38	tdb	1.7
39	tdb	1.1	<refsect1>
40			<title>Description</title>
41			<para>
42			Both calls take a pointer to an int,
43			<parameter>entries</parameter>, which is filled with the number
44			of disks the machine has. This is needed to know how many
45	tdb	1.7	<structname>sg_disk_io_stats</structname> structures have been
46	tdb	1.1	returned. A pointer is returned to the first
47	tdb	1.7	<structname>sg_disk_io_stats</structname>.
48	tdb	1.1	</para>
49			<para>
50	tdb	1.7	<function>sg_get_disk_io_stats</function> returns the disk IO stored
51	tdb	1.1	in the kernel which holds the amount of data transferred since
52			bootup. On some platforms, such as Solaris 7, this value is
53			stored in a 32bit int, so wraps around when it reaches 4GB. Other
54			platforms, such as Solaris 8, hold the value in a 64bit int,
55			which wraps somewhere near 17 million terabytes.
56			</para>
57			<para>
58	tdb	1.7	<function>sg_get_disk_io_stats_diff</function> is the same as
59			<function>sg_get_disk_io_stats</function> except it will return the
60	tdb	1.1	difference since the last call. So, for instance a call to
61	tdb	1.7	<function>sg_get_disk_io_stats_diff</function> is made, and called
62	tdb	1.1	again 5 seconds later. Over that time, 2000 bytes of traffic were
63			written and 10000 bytes read. <parameter>write_bytes</parameter>
64			will store 2000 bytes, <parameter>read_bytes</parameter> will
65			store 10000, and <parameter>systime</parameter> will store 5.
66			This function copes with wrap arounds by the O/S so should be
67			seemless to use.
68	tdb	1.4	</para>
69			<para>
70			On Solaris libstatgrab will attempt to get the cXtXdXsX
71			representation for the <varname>disk_name</varname> string. If
72			it fails it will use a name like sd0. On some systems programs
73			calling libstatgrab will need elevated privileges to lookup
74			some of the names. The mappings are built up when
75	tdb	1.8	<function>sg_init</function> is called.
76	tdb	1.1	</para>
77			</refsect1>
78	tdb	1.7
79	tdb	1.1	<refsect1>
80			<title>Return Values</title>
81
82			<para>
83			All diskio statistics return a pointer to a structure of type
84	tdb	1.7	<structname>sg_disk_io_stats</structname>.
85	tdb	1.1	</para>
86
87			<programlisting>
88			typedef struct{
89			char *disk_name;
90			long long read_bytes;
91			long long write_bytes;
92			time_t systime;
93	tdb	1.7	}sg_disk_io_stats;
94	tdb	1.1	</programlisting>
95
96			<variablelist>
97			<varlistentry>
98			<term>
99			<structfield>disk_name</structfield>
100			</term>
101			<listitem>
102			<para>
103			The name known to the operating system.
104			(eg. on linux it might be hda)
105			</para>
106			</listitem>
107			</varlistentry>
108			<varlistentry>
109			<term>
110			<structfield>read_bytes</structfield>
111			</term>
112			<listitem>
113			<para>
114			The number of bytes the disk has read.
115			</para>
116			</listitem>
117			</varlistentry>
118			<varlistentry>
119			<term>
120			<structfield>write_bytes</structfield>
121			</term>
122			<listitem>
123			<para>
124			The number of bytes the disk has written.
125			</para>
126			</listitem>
127			</varlistentry>
128			<varlistentry>
129			<term>
130			<structfield>systime</structfield>
131			</term>
132			<listitem>
133			<para>
134	tdb	1.2	The time period over which <parameter>read_bytes</parameter>
135	tdb	1.7	and <parameter>write_bytes</parameter> were transferred.
136	tdb	1.1	</para>
137			</listitem>
138			</varlistentry>
139			</variablelist>
140			</refsect1>
141
142			<refsect1>
143			<title>Bugs</title>
144			<para>
145	tdb	1.7	On the very first call <function>sg_get_disk_io_stats_diff</function>
146			will return the same as <function>sg_get_disk_io_stats</function>.
147	tdb	1.1	After the first call it will always return the difference.
148			</para>
149			<para>
150			On operating systems that hold only 32bits of data there is a
151			problem if the values wrap twice. For example, on Solaris 7 if
152			9GB is transferred and the operating system wraps at 4GB, the
153	tdb	1.7	<function>sg_get_disk_io_stats_diff</function> function will return
154	tdb	1.1	5GB.
155			</para>
156			</refsect1>
157
158			<refsect1>
159			<title>See Also</title>
160	tdb	1.3
161			<simplelist type="inline">
162			<member>
163			<citerefentry>
164			<refentrytitle>statgrab</refentrytitle>
165			<manvolnum>3</manvolnum>
166			</citerefentry>
167			</member>
168			</simplelist>
169	tdb	1.1	</refsect1>
170	tdb	1.7
171	tdb	1.1	<refsect1>
172			<title>Website</title>
173	tdb	1.7
174	tdb	1.1	<simplelist type="vert">
175			<member>
176	tdb	1.5	<ulink url="http://www.i-scream.org/libstatgrab/">
177			http://www.i-scream.org/libstatgrab/
178			</ulink>
179	tdb	1.1	</member>
180			</simplelist>
181			</refsect1>
182
183			</refentry>