DragonFly On-Line Manual Pages
sg_get_network_io_stats(3) sg_get_network_io_stats(3)
NAME
sg_get_network_io_stats, sg_get_network_io_stats_r,
sg_get_network_io_stats_diff, sg_get_network_io_stats_diff_between,
sg_free_network_io_stats, sg_network_io_compare_name - get network
statistics
SYNOPSIS
#include <statgrab.h>
sg_network_io_stats *sg_get_network_io_stats
(size_t *entries);
sg_network_io_stats *sg_get_network_io_stats_r
(size_t *entries);
sg_network_io_stats *sg_get_network_io_stats_diff
(size_t *entries);
sg_network_io_stats *sg_get_network_io_stats_diff_between
(const sg_network_io_stats *cur, const sg_network_io_stats *last, size_t
*entries);
sg_error sg_free_network_io_stats
(sg_network_iface_stats *data);
int sg_network_io_compare_name
(const void *va, const void *vb);
DESCRIPTION
The sg_get_network_io_stats functions provide network interface I/O
statistics on a per interface basis. All get- and diff-functions take
an optional entries parameter, which points (when given) to a size_t to
take the number of returned vector entries.
The sg_get_network_io_stats() and sg_get_network_io_stats_r() functions
deliver the I/O-statistics since the interface has been attached to the
system. The sg_get_network_io_stats_diff() and
sg_get_network_io_stats_diff_between() deliver the difference between
two calls of sg_get_network_io_stats() or sg_get_network_io_stats_r(),
respectively.
API Shortcut
+-------------------------------------+---------------------+---------------------+
|function | returns | data owner |
+-------------------------------------+---------------------+---------------------+
|sg_get_network_io_stats | sg_network_io_stats | libstatgrab (thread |
| | * | local) |
+-------------------------------------+---------------------+---------------------+
|sg_get_network_io_stats_r | sg_network_io_stats | caller |
| | * | |
+-------------------------------------+---------------------+---------------------+
|sg_get_network_io_stats_diff | sg_network_io_stats | libstatgrab (thread |
| | * | local) |
+-------------------------------------+---------------------+---------------------+
|sg_get_network_io_stats_diff_between | sg_network_io_stats | caller |
| | * | |
+-------------------------------------+---------------------+---------------------+
sg_network_io_stats vectors received from sg_get_network_io_stats_r()
or sg_get_network_io_stats_diff_between() must be freed using
sg_free_network_io_stats() when not needed any more. The caller is
responsible for doing it.
Additionally a support function for qsort(3) are available:
sg_network_io_compare_name().
Example
size_t entries;
sg_network_io_stats *network_stats = NULL;
while( NULL != ( network_stats = sg_get_network_io_stats_diff(&entries) ) ) {
/* sort interface by name */
qsort( network_stats, entries, sizeof(network_stats[0]), &sg_network_io_compare_name );
show_network_io_stats( network_stats );
}
sg_get_network_io_stats returns the network traffic stored in the
kernel which holds the amount of data transferred since device was
attached. 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. The sg_get_network_io_stats_diff() function and
the sg_get_network_io_stats_diff_between() function care about these
overflows and try to detect overflows when the diff is calculated.
RETURN VALUES
All network statistics return a pointer to a structure of type
sg_network_io_stats.
typedef struct {
char *interface_name;
unsigned long long tx;
unsigned long long rx;
unsigned long long ipackets;
unsigned long long opackets;
unsigned long long ierrors;
unsigned long long oerrors;
unsigned long long collisions;
time_t systime;
} sg_network_io_stats;
interface_name
The name known to the operating system. (eg. on linux it might
be eth0, on AIX en0 and on FreeBSD fxp0)
tx The number of bytes transmitted.
rx The number of bytes received.
ipackets
The number of packets received.
opackets
The number of packets transmitted.
ierrors
The number of receive errors.
oerrors
The number of transmit errors.
collisions
The number of collisions.
systime
The timestamp when the above stats where collected in seconds
since epoch or the time period over which tx and rx were
transferred.
BUGS
sg_get_network_io_stats_diff and sg_get_network_io_stats_diff_between
compare two lists of network interface related I/O statistics. Each
entry occurring only in the second list is passed through to the
resulting list as if it would have been compared to an entry with all
statistic values set to 0. This implies, on the very first call
sg_get_network_io_stats_diff will return the same as
sg_get_network_io_stats.
On operating systems 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
sg_get_network_io_stats_diff function will return 5GB.
SEE ALSO
statgrab(3)
WEBSITE
<http://www.i-scream.org/libstatgrab/>
i-scream 2013-06-07 sg_get_network_io_stats(3)