libstatgrab/docs/get_network_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="get_network_stats">

  <refentryinfo>
    <date>$Date: 2003/10/02 17:38:03 $</date>
    <releaseinfo>$Id: get_network_stats.xml,v 1.3 2003/10/02 17:38:03 tdb Exp $</releaseinfo>
  </refentryinfo>
  
  <refmeta>
    <refentrytitle>get_network_stats</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo>i-scream</refmiscinfo>
  </refmeta>
  
  <refnamediv>
    <refname>get_network_stats</refname>
    <refname>get_network_stats_diff</refname>
    <refpurpose>get network statistics</refpurpose>
  </refnamediv>
    
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;statgrab.h&gt;</funcsynopsisinfo>
      <funcprototype>
        <funcdef>network_stat_t *<function>get_network_stats</function></funcdef>
        <paramdef>int *<parameter>entries</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>network_stat_t *<function>get_network_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>network_stat_t</structname> structures have been
      returned. A pointer is returned to the first
      <structname>network_stat_t</structname>.
    </para>
    <para>
      <function>get_network_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>get_network_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>get_network_stats_diff</function> is the same as
      <function>get_network_stats</function> except it will return the
      difference since the last call. So, for instance a call to
      <function>get_network_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>network_stat_t</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;
}network_stat_t;
    </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>get_network_stats_diff</function> will return the same
      as <function>get_network_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>get_network_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">http://www.i-scream.org</ulink>
      </member>
    </simplelist>
  </refsect1>

</refentry>
Revision:	1.4
Committed:	Sat Mar 6 23:35:20 2004 UTC (20 years, 2 months ago) by tdb
Content type:	text/xml
Branch:	MAIN
CVS Tags:	LIBSTATGRAB_0_9
Changes since 1.3:	+62 -2 lines
Log Message:	Update documentation to know about the new functions and return data.
#	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			<refentry id="get_network_stats">
7
8			<refentryinfo>
9	tdb	1.4	<date>$Date: 2003/10/02 17:38:03 $</date>
10			<releaseinfo>$Id: get_network_stats.xml,v 1.3 2003/10/02 17:38:03 tdb Exp $</releaseinfo>
11	tdb	1.1	</refentryinfo>
12
13			<refmeta>
14			<refentrytitle>get_network_stats</refentrytitle>
15			<manvolnum>3</manvolnum>
16			<refmiscinfo>i-scream</refmiscinfo>
17			</refmeta>
18
19			<refnamediv>
20			<refname>get_network_stats</refname>
21			<refname>get_network_stats_diff</refname>
22			<refpurpose>get network statistics</refpurpose>
23			</refnamediv>
24
25			<refsynopsisdiv>
26			<funcsynopsis>
27			<funcsynopsisinfo>#include <statgrab.h></funcsynopsisinfo>
28			<funcprototype>
29			<funcdef>network_stat_t *<function>get_network_stats</function></funcdef>
30			<paramdef>int *<parameter>entries</parameter></paramdef>
31			</funcprototype>
32			<funcprototype>
33			<funcdef>network_stat_t *<function>get_network_stats_diff</function></funcdef>
34			<paramdef>int *<parameter>entries</parameter></paramdef>
35			</funcprototype>
36			</funcsynopsis>
37			</refsynopsisdiv>
38
39			<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			many <structname>network_stat_t</structname> structures have been
46			returned. A pointer is returned to the first
47			<structname>network_stat_t</structname>.
48			</para>
49			<para>
50			<function>get_network_stats</function> returns the network
51			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.4	<function>get_network_stats</function> also returns the number
59			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.1	<function>get_network_stats_diff</function> is the same as
64			<function>get_network_stats</function> except it will return the
65			difference since the last call. So, for instance a call to
66			<function>get_network_stats_diff</function> is made, and called
67			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
74			<refsect1>
75			<title>Return Values</title>
76
77			<para>
78			All network statistics return a pointer to a structure of type
79			<structname>network_stat_t</structname>.
80			</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			}network_stat_t;
94			</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			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			<function>get_network_stats_diff</function> will return the same
197			as <function>get_network_stats</function>. After the first call
198			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			<function>get_network_stats_diff</function> function will return
205			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
222			<refsect1>
223			<title>Website</title>
224
225			<simplelist type="vert">
226			<member>
227			<ulink url="http://www.i-scream.org">http://www.i-scream.org</ulink>
228			</member>
229			</simplelist>
230			</refsect1>
231
232			</refentry>