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 16:01:52 $</date>
    <releaseinfo>$Id: get_network_stats.xml,v 1.2 2003/10/02 16:01:52 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_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;
        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>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.3
Committed:	Thu Oct 2 17:38:03 2003 UTC (21 years, 1 month ago) by tdb
Content type:	text/xml
Branch:	MAIN
CVS Tags:	LIBSTATGRAB_0_8_2, LIBSTATGRAB_0_8_1, LIBSTATGRAB_0_8, LIBSTATGRAB_0_7, LIBSTATGRAB_0_6_1, LIBSTATGRAB_0_6
Changes since 1.2:	+11 -3 lines
Log Message:	Add a central page statgrab(3) which links all the functions together. Add a link in the See Also section of each manual page back to the central one.
#	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.3	<date>$Date: 2003/10/02 16:01:52 $</date>
10			<releaseinfo>$Id: get_network_stats.xml,v 1.2 2003/10/02 16:01:52 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			<function>get_network_stats_diff</function> is the same as
59			<function>get_network_stats</function> except it will return the
60			difference since the last call. So, for instance a call to
61			<function>get_network_stats_diff</function> is made, and called
62			again 5 seconds later. Over that time, 20 bytes of traffic was
63			transmitted and 10 bytes received. Tx will store 20, rx will
64			store 10 and systime will store 5. This function copes with wrap
65			arounds by the O/S so should be seemless to use.
66			</para>
67			</refsect1>
68
69			<refsect1>
70			<title>Return Values</title>
71
72			<para>
73			All network statistics return a pointer to a structure of type
74			<structname>network_stat_t</structname>.
75			</para>
76
77			<programlisting>
78			typedef struct{
79			char *interface_name;
80			long long tx;
81			long long rx;
82			time_t systime;
83			}network_stat_t;
84			</programlisting>
85
86			<variablelist>
87			<varlistentry>
88			<term>
89			<structfield>interface_name</structfield>
90			</term>
91			<listitem>
92			<para>
93			The name known to the operating system.
94			(eg. on linux it might be eth0)
95			</para>
96			</listitem>
97			</varlistentry>
98			<varlistentry>
99			<term>
100			<structfield>tx</structfield>
101			</term>
102			<listitem>
103			<para>
104			The number of bytes transmitted.
105			</para>
106			</listitem>
107			</varlistentry>
108			<varlistentry>
109			<term>
110			<structfield>rx</structfield>
111			</term>
112			<listitem>
113			<para>
114			The number of bytes received.
115			</para>
116			</listitem>
117			</varlistentry>
118			<varlistentry>
119			<term>
120			<structfield>systime</structfield>
121			</term>
122			<listitem>
123			<para>
124	tdb	1.2	The time period over which <parameter>tx</parameter>
125			and <parameter>rx</parameter> were transferred.
126	tdb	1.1	</para>
127			</listitem>
128			</varlistentry>
129			</variablelist>
130			</refsect1>
131
132			<refsect1>
133			<title>Bugs</title>
134			<para>
135			On the very first call
136			<function>get_network_stats_diff</function> will return the same
137			as <function>get_network_stats</function>. After the first call
138			it will always return the difference.
139			</para>
140			<para>
141			On operating system that hold only 32bits of data there is a
142			problem if the values wrap twice. For example, on Solaris 7 if
143			9GB is transferred and the operating system wraps at 4GB, the
144			<function>get_network_stats_diff</function> function will return
145			5GB.
146			</para>
147			</refsect1>
148
149			<refsect1>
150			<title>See Also</title>
151	tdb	1.3
152			<simplelist type="inline">
153			<member>
154			<citerefentry>
155			<refentrytitle>statgrab</refentrytitle>
156			<manvolnum>3</manvolnum>
157			</citerefentry>
158			</member>
159			</simplelist>
160	tdb	1.1	</refsect1>
161
162			<refsect1>
163			<title>Website</title>
164
165			<simplelist type="vert">
166			<member>
167			<ulink url="http://www.i-scream.org">http://www.i-scream.org</ulink>
168			</member>
169			</simplelist>
170			</refsect1>
171
172			</refentry>