libstatgrab/docs/sg_get_network_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_network_io_stats">

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

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

  <refnamediv>
    <refname>sg_get_network_io_stats</refname>
    <refname>sg_get_network_io_stats_diff</refname>
    <refpurpose>get network statistics</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;statgrab.h&gt;</funcsynopsisinfo>
      <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>
    </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 network interfaces the machine has. This is needed to know how
      many <structname>sg_network_io_stats</structname> structures have been
      returned. A pointer is returned to the first
      <structname>sg_network_io_stats</structname>.
    </para>
    <para>
      <function>sg_get_network_io_stats</function> returns the network
      traffic 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_network_io_stats</function> also returns the number
      of packets sent and received, and the number of errors that
      have occured. It also makes the number of collisions available.
    </para>
    <para>
      <function>sg_get_network_io_stats_diff</function> is the same as
      <function>sg_get_network_io_stats</function> except it will return the
      difference since the last call. So, for instance a call to
      <function>sg_get_network_io_stats_diff</function> is made, and called
      again 5 seconds later. Over that time, 20 bytes of traffic was
      transmitted and 10 bytes received. Tx will store 20, rx will
      store 10 and systime will store 5. This function copes with wrap
      arounds by the O/S so should be seemless to use.
    </para>
  </refsect1>

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

    <para>
      All network statistics return a pointer to a structure of type
      <structname>sg_network_io_stats</structname>.
    </para>

    <programlisting>
typedef struct{
        char *interface_name;
        long long tx;
        long long rx;
        long long ipackets;
        long long opackets;
        long long ierrors;
        long long oerrors;
        long long collisions;
        time_t systime;
}sg_network_io_stats;
    </programlisting>

    <variablelist>
      <varlistentry>
        <term>
          <structfield>interface_name</structfield>
        </term>
        <listitem>
          <para>
            The name known to the operating system.
            (eg. on linux it might be eth0)
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <structfield>tx</structfield>
        </term>
        <listitem>
          <para>
            The number of bytes transmitted.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <structfield>rx</structfield>
        </term>
        <listitem>
          <para>
            The number of bytes received.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <structfield>ipackets</structfield>
        </term>
        <listitem>
          <para>
            The number of packets received.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <structfield>opackets</structfield>
        </term>
        <listitem>
          <para>
            The number of packets transmitted.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <structfield>ierrors</structfield>
        </term>
        <listitem>
          <para>
            The number of receive errors.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <structfield>oerrors</structfield>
        </term>
        <listitem>
          <para>
            The number of transmit errors.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <structfield>collisions</structfield>
        </term>
        <listitem>
          <para>
            The number of collisions.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <structfield>systime</structfield>
        </term>
        <listitem>
          <para>
            The time period over which <parameter>tx</parameter>
            and <parameter>rx</parameter> were transferred.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Bugs</title>
    <para>
      On the very first call
      <function>sg_get_network_io_stats_diff</function> will return the same
      as <function>sg_get_network_io_stats</function>. After the first call
      it will always return the difference.
    </para>
    <para>
      On operating system 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_network_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:	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.7:	+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.
#	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_network_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_network_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_network_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_network_io_stats</refname>
21			<refname>sg_get_network_io_stats_diff</refname>
22	tdb	1.1	<refpurpose>get network 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_network_io_stats *<function>sg_get_network_io_stats</function></funcdef>
30	tdb	1.1	<paramdef>int *<parameter>entries</parameter></paramdef>
31			</funcprototype>
32			<funcprototype>
33	tdb	1.7	<funcdef>sg_network_io_stats *<function>sg_get_network_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 network interfaces the machine has. This is needed to know how
45	tdb	1.7	many <structname>sg_network_io_stats</structname> structures have been
46	tdb	1.1	returned. A pointer is returned to the first
47	tdb	1.7	<structname>sg_network_io_stats</structname>.
48	tdb	1.1	</para>
49			<para>
50	tdb	1.7	<function>sg_get_network_io_stats</function> returns the network
51	tdb	1.1	traffic stored in the kernel which holds the amount of data
52			transferred since bootup. On some platforms, such as Solaris 7,
53			this value is stored in a 32bit int, so wraps around when it
54			reaches 4GB. Other platforms, such as Solaris 8, hold the value
55			in a 64bit int, which wraps somewhere near 17 million terabytes.
56			</para>
57			<para>
58	tdb	1.7	<function>sg_get_network_io_stats</function> also returns the number
59	tdb	1.4	of packets sent and received, and the number of errors that
60			have occured. It also makes the number of collisions available.
61			</para>
62			<para>
63	tdb	1.7	<function>sg_get_network_io_stats_diff</function> is the same as
64			<function>sg_get_network_io_stats</function> except it will return the
65	tdb	1.1	difference since the last call. So, for instance a call to
66	tdb	1.7	<function>sg_get_network_io_stats_diff</function> is made, and called
67	tdb	1.1	again 5 seconds later. Over that time, 20 bytes of traffic was
68			transmitted and 10 bytes received. Tx will store 20, rx will
69			store 10 and systime will store 5. This function copes with wrap
70			arounds by the O/S so should be seemless to use.
71			</para>
72			</refsect1>
73	tdb	1.7
74	tdb	1.1	<refsect1>
75			<title>Return Values</title>
76
77			<para>
78			All network statistics return a pointer to a structure of type
79	tdb	1.7	<structname>sg_network_io_stats</structname>.
80	tdb	1.1	</para>
81
82			<programlisting>
83			typedef struct{
84			char *interface_name;
85			long long tx;
86			long long rx;
87	tdb	1.4	long long ipackets;
88			long long opackets;
89			long long ierrors;
90			long long oerrors;
91			long long collisions;
92	tdb	1.1	time_t systime;
93	tdb	1.7	}sg_network_io_stats;
94	tdb	1.1	</programlisting>
95
96			<variablelist>
97			<varlistentry>
98			<term>
99			<structfield>interface_name</structfield>
100			</term>
101			<listitem>
102			<para>
103			The name known to the operating system.
104			(eg. on linux it might be eth0)
105			</para>
106			</listitem>
107			</varlistentry>
108			<varlistentry>
109			<term>
110			<structfield>tx</structfield>
111			</term>
112			<listitem>
113			<para>
114			The number of bytes transmitted.
115			</para>
116			</listitem>
117			</varlistentry>
118			<varlistentry>
119			<term>
120			<structfield>rx</structfield>
121			</term>
122			<listitem>
123			<para>
124			The number of bytes received.
125	tdb	1.4	</para>
126			</listitem>
127			</varlistentry>
128			<varlistentry>
129			<term>
130			<structfield>ipackets</structfield>
131			</term>
132			<listitem>
133			<para>
134			The number of packets received.
135			</para>
136			</listitem>
137			</varlistentry>
138			<varlistentry>
139			<term>
140			<structfield>opackets</structfield>
141			</term>
142			<listitem>
143			<para>
144			The number of packets transmitted.
145			</para>
146			</listitem>
147			</varlistentry>
148			<varlistentry>
149			<term>
150			<structfield>ierrors</structfield>
151			</term>
152			<listitem>
153			<para>
154			The number of receive errors.
155			</para>
156			</listitem>
157			</varlistentry>
158			<varlistentry>
159			<term>
160			<structfield>oerrors</structfield>
161			</term>
162			<listitem>
163			<para>
164			The number of transmit errors.
165			</para>
166			</listitem>
167			</varlistentry>
168			<varlistentry>
169			<term>
170			<structfield>collisions</structfield>
171			</term>
172			<listitem>
173			<para>
174			The number of collisions.
175	tdb	1.1	</para>
176			</listitem>
177			</varlistentry>
178			<varlistentry>
179			<term>
180			<structfield>systime</structfield>
181			</term>
182			<listitem>
183			<para>
184	tdb	1.2	The time period over which <parameter>tx</parameter>
185	tdb	1.7	and <parameter>rx</parameter> were transferred.
186	tdb	1.1	</para>
187			</listitem>
188			</varlistentry>
189			</variablelist>
190			</refsect1>
191
192			<refsect1>
193			<title>Bugs</title>
194			<para>
195			On the very first call
196	tdb	1.7	<function>sg_get_network_io_stats_diff</function> will return the same
197			as <function>sg_get_network_io_stats</function>. After the first call
198	tdb	1.1	it will always return the difference.
199			</para>
200			<para>
201			On operating system that hold only 32bits of data there is a
202			problem if the values wrap twice. For example, on Solaris 7 if
203			9GB is transferred and the operating system wraps at 4GB, the
204	tdb	1.7	<function>sg_get_network_io_stats_diff</function> function will return
205	tdb	1.1	5GB.
206			</para>
207			</refsect1>
208
209			<refsect1>
210			<title>See Also</title>
211	tdb	1.3
212			<simplelist type="inline">
213			<member>
214			<citerefentry>
215			<refentrytitle>statgrab</refentrytitle>
216			<manvolnum>3</manvolnum>
217			</citerefentry>
218			</member>
219			</simplelist>
220	tdb	1.1	</refsect1>
221	tdb	1.7
222	tdb	1.1	<refsect1>
223			<title>Website</title>
224	tdb	1.7
225	tdb	1.1	<simplelist type="vert">
226			<member>
227	tdb	1.5	<ulink url="http://www.i-scream.org/libstatgrab/">
228			http://www.i-scream.org/libstatgrab/
229			</ulink>
230	tdb	1.1	</member>
231			</simplelist>
232			</refsect1>
233
234			</refentry>