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: 2004/03/11 17:35:24 $</date>
    <releaseinfo>$Id: get_network_stats.xml,v 1.5 2004/03/11 17:35:24 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/libstatgrab/">
          http://www.i-scream.org/libstatgrab/
        </ulink>
      </member>
    </simplelist>
  </refsect1>

</refentry>
Revision:	1.6
Committed:	Sun May 2 09:35:15 2004 UTC (21 years, 6 months ago) by tdb
Content type:	text/xml
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.5:	+2 -2 lines
State:	*FILE REMOVED*
Error occurred while calculating annotation data.
Log Message:	Do a repo copy of the documentation to their new names, then delete the old ones. They still need their content updating though. We also need docs for the new process stats stuff, the error reporting code, and I think the FS stats which seem to be missing.
#	Content
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: 2004/03/11 17:35:24 $</date>
10	<releaseinfo>$Id: get_network_stats.xml,v 1.5 2004/03/11 17:35:24 tdb Exp $</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</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	<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	long long ipackets;
88	long long opackets;
89	long long ierrors;
90	long long oerrors;
91	long long collisions;
92	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	</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	</para>
176	</listitem>
177	</varlistentry>
178	<varlistentry>
179	<term>
180	<structfield>systime</structfield>
181	</term>
182	<listitem>
183	<para>
184	The time period over which <parameter>tx</parameter>
185	and <parameter>rx</parameter> were transferred.
186	</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
212	<simplelist type="inline">
213	<member>
214	<citerefentry>
215	<refentrytitle>statgrab</refentrytitle>
216	<manvolnum>3</manvolnum>
217	</citerefentry>
218	</member>
219	</simplelist>
220	</refsect1>
221
222	<refsect1>
223	<title>Website</title>
224
225	<simplelist type="vert">
226	<member>
227	<ulink url="http://www.i-scream.org/libstatgrab/">
228	http://www.i-scream.org/libstatgrab/
229	</ulink>
230	</member>
231	</simplelist>
232	</refsect1>
233
234	</refentry>