1sg_get_network_io_stats(3)                          sg_get_network_io_stats(3)
2
3
4

NAME

6       sg_get_network_io_stats,     sg_get_network_io_stats_r,     sg_get_net‐
7       work_io_stats_diff, sg_get_network_io_stats_diff_between,  sg_free_net‐
8       work_io_stats, sg_network_io_compare_name - get network statistics
9

SYNOPSIS

11       #include <statgrab.h>
12
13
14       sg_network_io_stats *sg_get_network_io_stats (size_t *entries);
15
16       sg_network_io_stats *sg_get_network_io_stats_r (size_t *entries);
17
18       sg_network_io_stats *sg_get_network_io_stats_diff (size_t *entries);
19
20       sg_network_io_stats *sg_get_network_io_stats_diff_between (const
21                       sg_network_io_stats *cur, const sg_network_io_stats
22                       *last, size_t *entries);
23
24       sg_error sg_free_network_io_stats (sg_network_iface_stats *data);
25
26       int sg_network_io_compare_name (const void *va, const void *vb);
27

DESCRIPTION

29       The  sg_get_network_io_stats  functions  provide  network interface I/O
30       statistics on a per interface basis. All get- and  diff-functions  take
31       an optional entries parameter, which points (when given) to a size_t to
32       take the number of returned vector entries.
33
34       The sg_get_network_io_stats() and sg_get_network_io_stats_r() functions
35       deliver the I/O-statistics since the interface has been attached to the
36       system.     The    sg_get_network_io_stats_diff()    and    sg_get_net‐
37       work_io_stats_diff_between()  deliver  the difference between two calls
38       of sg_get_network_io_stats()  or  sg_get_network_io_stats_r(),  respec‐
39       tively.
40
41       API Shortcut
42
43       ┌───────────────────────┬─────────────────────┬─────────────────────┐
44       │function               │ returns             │ data owner          │
45       ├───────────────────────┼─────────────────────┼─────────────────────┤
46       │sg_get_net‐            │ sg_network_io_stats │ libstatgrab (thread │
47       │work_io_stats          │ *                   │ local)              │
48       ├───────────────────────┼─────────────────────┼─────────────────────┤
49       │sg_get_net‐            │ sg_network_io_stats │ caller              │
50       │work_io_stats_r        │ *                   │                     │
51       ├───────────────────────┼─────────────────────┼─────────────────────┤
52       │sg_get_net‐            │ sg_network_io_stats │ libstatgrab (thread │
53       │work_io_stats_diff     │ *                   │ local)              │
54       ├───────────────────────┼─────────────────────┼─────────────────────┤
55       │sg_get_net‐            │ sg_network_io_stats │ caller              │
56       │work_io_stats_diff_be‐ │ *                   │                     │
57       │tween                  │                     │                     │
58       └───────────────────────┴─────────────────────┴─────────────────────┘
59       sg_network_io_stats vectors received  from  sg_get_network_io_stats_r()
60       or   sg_get_network_io_stats_diff_between()   must   be   freed   using
61       sg_free_network_io_stats() when not needed any more. The caller is  re‐
62       sponsible for doing it.
63
64       Additionally  a  support  function  for qsort(3) are available: sg_net‐
65       work_io_compare_name().
66
67       Example
68
69       size_t entries;
70       sg_network_io_stats *network_stats = NULL;
71       while( NULL != ( network_stats = sg_get_network_io_stats_diff(&entries) ) ) {
72           /* sort interface by name */
73           qsort( network_stats, entries, sizeof(network_stats[0]), &sg_network_io_compare_name );
74           show_network_io_stats( network_stats );
75       }
76
77
78       sg_get_network_io_stats returns the network traffic stored in the  ker‐
79       nel  which  holds  the  amount of data transferred since device was at‐
80       tached. On some platforms, such as Solaris 7, this value is stored in a
81       32bit  int,  so wraps around when it reaches 4GB. Other platforms, such
82       as Solaris 8, hold the value in a 64bit int, which wraps somewhere near
83       17  million terabytes.  The sg_get_network_io_stats_diff() function and
84       the sg_get_network_io_stats_diff_between() function  care  about  these
85       overflows and try to detect overflows when the diff is calculated.
86

RETURN VALUES

88       All  network statistics return a pointer to a structure of type sg_net‐
89       work_io_stats.
90
91       typedef struct {
92               char *interface_name;
93               unsigned long long tx;
94               unsigned long long rx;
95               unsigned long long ipackets;
96               unsigned long long opackets;
97               unsigned long long ierrors;
98               unsigned long long oerrors;
99               unsigned long long collisions;
100               time_t systime;
101       } sg_network_io_stats;
102
103
104       interface_name
105              The name known to the operating system.  (eg. on linux it  might
106              be eth0, on AIX en0 and on FreeBSD fxp0)
107
108       tx     The number of bytes transmitted.
109
110       rx     The number of bytes received.
111
112       ipackets
113              The number of packets received.
114
115       opackets
116              The number of packets transmitted.
117
118       ierrors
119              The number of receive errors.
120
121       oerrors
122              The number of transmit errors.
123
124       collisions
125              The number of collisions.
126
127       systime
128              The  timestamp  when  the above stats where collected in seconds
129              since epoch or the time period over which tx and rx were  trans‐
130              ferred.
131

BUGS

133       sg_get_network_io_stats_diff  and  sg_get_network_io_stats_diff_between
134       compare two lists of network interface related I/O statistics. Each en‐
135       try  occurring only in the second list is passed through to the result‐
136       ing list as if it would have been compared to an entry with all statis‐
137       tic  values  set to 0. This implies, on the very first call sg_get_net‐
138       work_io_stats_diff will return the same as sg_get_network_io_stats.
139
140       On operating systems that hold only 32bits of data there is  a  problem
141       if  the  values  wrap twice. For example, on Solaris 7 if 9GB is trans‐
142       ferred  and  the  operating  system  wraps  at  4GB,  the   sg_get_net‐
143       work_io_stats_diff function will return 5GB.
144

SEE ALSO

146       statgrab(3)
147

WEBSITE

149http://www.i-scream.org/libstatgrab/
150
151
152
153i-scream                          2013-06-07        sg_get_network_io_stats(3)
Impressum