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$</date>
    <releaseinfo>$Id$</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 tx and rx 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>
    <para>Nothing yet</para>
  </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.1
Committed:	Thu Oct 2 14:53:22 2003 UTC (20 years, 7 months ago) by tdb
Content type:	text/xml
Branch:	MAIN
Log Message:	Add network stats manpage.
#	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			<date>$Date$</date>
10			<releaseinfo>$Id$</releaseinfo>
11			</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			The time period over which tx and rx were transferred.
125			</para>
126			</listitem>
127			</varlistentry>
128			</variablelist>
129			</refsect1>
130
131			<refsect1>
132			<title>Bugs</title>
133			<para>
134			On the very first call
135			<function>get_network_stats_diff</function> will return the same
136			as <function>get_network_stats</function>. After the first call
137			it will always return the difference.
138			</para>
139			<para>
140			On operating system that hold only 32bits of data there is a
141			problem if the values wrap twice. For example, on Solaris 7 if
142			9GB is transferred and the operating system wraps at 4GB, the
143			<function>get_network_stats_diff</function> function will return
144			5GB.
145			</para>
146			</refsect1>
147
148			<refsect1>
149			<title>See Also</title>
150			<para>Nothing yet</para>
151			</refsect1>
152
153			<refsect1>
154			<title>Website</title>
155
156			<simplelist type="vert">
157			<member>
158			<ulink url="http://www.i-scream.org">http://www.i-scream.org</ulink>
159			</member>
160			</simplelist>
161			</refsect1>
162
163			</refentry>