1sg_get_network_io_stats(3) sg_get_network_io_stats(3)
2
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
11 #include <statgrab.h>
12 sg_network_io_stats *sg_get_network_io_stats (size_t *entries);
15 sg_network_io_stats *sg_get_network_io_stats_r (size_t *entries);
17 sg_network_io_stats *sg_get_network_io_stats_diff (size_t *entries);
19 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 sg_error sg_free_network_io_stats (sg_network_iface_stats *data);
25 int sg_network_io_compare_name (const void *va, const void *vb);
27
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 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 API Shortcut
42 ┌───────────────────────┬─────────────────────┬─────────────────────┐
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 Additionally a support function for qsort(3) are available: sg_net‐
65 work_io_compare_name().
66 Example
68 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 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
88 All network statistics return a pointer to a structure of type sg_net‐
89 work_io_stats.
90 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 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 tx The number of bytes transmitted.
109 rx The number of bytes received.
111 ipackets
113 The number of packets received.
114 opackets
116 The number of packets transmitted.
117 ierrors
119 The number of receive errors.
120 oerrors
122 The number of transmit errors.
123 collisions
125 The number of collisions.
126 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
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 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
146 statgrab(3)
147
149 ⟨http://www.i-scream.org/libstatgrab/⟩
150i-scream 2013-06-07 sg_get_network_io_stats(3)