libstatgrab/docs/network.txt

Network Statistics
==================

$Id$

Data Structure
--------------

All network statistics return a structure of type network_stat_t that
looks like this:

typedef struct{
        char *interface_name;
        long long tx;
        long long rx;
        time_t systime;
}network_stat_t;

interface_name  is the name know to the operating system.
                (eg. on linux is might be eth0)
tx              is the number of bytes transmitted.
rx              is the number of bytes received.
sysname         is the time period over which tx and rx were
                transferred.

Functions
---------

network_stat_t *get_network_stats(int *entries);

network_stat_t *get_network_stats_diff(int *entries);

Both calls take a pointer to an int, "entries", which is filled with
the number of network interfaces the machine has. This is needed to
know how many network_stat_t structures have been returned. A pointer
is returned to the first network_stat_t.

get_network_stats 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.

get_network_stats_diff is the same as get_network_stats except it will 
return the difference since the last call. So, for instance a call to 
get_network_stats_diff 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.

Bugs
----

On the very first call get_network_stats_diff will return the same as
get_network_stats. After the first call it will always return the
difference.

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 get_network_stats_diff
function will return 5GB.

Example
-------

A very basic example can be found in examples/network_traffic.c
Revision:	1.4
Committed:	Sun Aug 24 20:24:08 2003 UTC (22 years, 3 months ago) by tdb
Content type:	text/plain
Branch:	MAIN
CVS Tags:	LIBSTATGRAB_0_5_1, LIBSTATGRAB_0_5
Changes since 1.3:	+2 -1 lines
Log Message:	Tidy up of lots of little things. :)
#	User	Rev	Content
1	pajs	1.1	Network Statistics
2	tdb	1.3	==================
3	pajs	1.1
4	tdb	1.4	$Id$
5
6	tdb	1.3	Data Structure
7			--------------
8
9			All network statistics return a structure of type network_stat_t that
10			looks like this:
11	pajs	1.1
12			typedef struct{
13			char *interface_name;
14			long long tx;
15			long long rx;
16			time_t systime;
17			}network_stat_t;
18
19	tdb	1.3	interface_name is the name know to the operating system.
20			(eg. on linux is might be eth0)
21			tx is the number of bytes transmitted.
22			rx is the number of bytes received.
23			sysname is the time period over which tx and rx were
24			transferred.
25	pajs	1.1
26	tdb	1.3	Functions
27			---------
28	pajs	1.1
29			network_stat_t get_network_stats(int entries);
30
31			network_stat_t get_network_stats_diff(int entries);
32
33	tdb	1.3	Both calls take a pointer to an int, "entries", which is filled with
34			the number of network interfaces the machine has. This is needed to
35			know how many network_stat_t structures have been returned. A pointer
36			is returned to the first network_stat_t.
37
38			get_network_stats returns the network traffic stored in the kernel
39			which holds the amount of data transferred since bootup. On some
40			platforms, such as Solaris 7, this value is stored in a 32bit int, so
41			wraps around when it reaches 4GB. Other platforms, such as Solaris 8,
42			hold the value in a 64bit int, which wraps somewhere near 17 million
43			terabytes.
44	pajs	1.1
45			get_network_stats_diff is the same as get_network_stats except it will
46			return the difference since the last call. So, for instance a call to
47			get_network_stats_diff is made, and called again 5 seconds later. Over that
48			time, 20 bytes of traffic was transmitted and 10 bytes received. Tx will
49			store 20, rx will store 10 and systime will store 5. This function copes
50			with wrap arounds by the O/S so should be seemless to use.
51
52	tdb	1.3	Bugs
53			----
54
55			On the very first call get_network_stats_diff will return the same as
56			get_network_stats. After the first call it will always return the
57			difference.
58
59			On operating system that hold only 32bits of data there is a problem if
60			the values wrap twice. For example, on Solaris 7 if 9GB is transferred
61			and the operating system wraps at 4GB, the get_network_stats_diff
62			function will return 5GB.
63
64			Example
65			-------
66	pajs	1.1
67	tdb	1.3	A very basic example can be found in examples/network_traffic.c