1sg_get_network_iface_stats(3)                    sg_get_network_iface_stats(3)
2
3
4

NAME

6       sg_get_network_iface_stats,  sg_get_network_iface_stats_r, sg_free_net‐
7       work_iface_stats, sg_network_iface_compare_name - get network interface
8       statistics
9

SYNOPSIS

11       #include <statgrab.h>
12
13
14       sg_network_iface_stats *sg_get_network_iface_stats (size_t *entries);
15
16       sg_network_iface_stats *sg_get_network_iface_stats_r (size_t *entries);
17
18       sg_error sg_free_network_iface_stats (sg_network_iface_stats *data);
19
20       int sg_network_iface_compare_name (const void *va, const void *vb);
21

DESCRIPTION

23       The     functions    sg_get_network_iface_stats()    and    sg_get_net‐
24       work_iface_stats_r() return statistics about the network interfaces  in
25       the  machine. Specifically, they return the speed of the interface, the
26       duplex state, and whether it is currently up. Both  functions  take  an
27       optional  entries  parameter,  which points (when given) to a size_t to
28       take the number of returned vector entries.
29
30       API Shortcut
31
32       ┌───────────────────┬────────────────────┬─────────────────────┐
33       │function           │ returns            │ data owner          │
34       ├───────────────────┼────────────────────┼─────────────────────┤
35       │sg_get_net‐        │ sg_net‐            │ libstatgrab (thread │
36       │work_iface_stats   │ work_iface_stats * │ local)              │
37       ├───────────────────┼────────────────────┼─────────────────────┤
38       │sg_get_net‐        │ sg_net‐            │ caller              │
39       │work_iface_stats_r │ work_iface_stats * │                     │
40       └───────────────────┴────────────────────┴─────────────────────┘
41       The    sg_network_iface_stats   vectors   received   from   sg_get_net‐
42       work_iface_stats_r() must be freed using  sg_free_network_iface_stats()
43       when not needed any more. The caller is responsible for doing it.
44
45       Additionally  a  support  function  for  qsort(3) in available: sg_net‐
46       work_iface_compare_name().
47
48       Sort Example
49
50       size_t entries;
51       sg_network_iface_stats *network_iface_stats = NULL;
52       while( NULL != ( network_iface_stats = sg_get_network_iface_stats(&entries) ) ) {
53           /* order entries alphabetically using the mountpoint */
54           qsort( network_iface_stats, entries, sizeof(network_iface_stats[0]), &sg_network_iface_compare_name );
55           show_network_iface_stats( network_iface_stats );
56       }
57
58

RETURN VALUES

60       The sg_get_network_iface_stats returns a pointer to a structure of type
61       sg_network_iface_stats.
62
63       typedef enum{
64               SG_IFACE_DUPLEX_FULL,
65               SG_IFACE_DUPLEX_HALF,
66               SG_IFACE_DUPLEX_UNKNOWN
67       }sg_iface_duplex;
68
69
70       Note:  The  SG_IFACE_DUPLEX_UNKNOWN value could mean that duplex hasn't
71       been negotiated yet.
72
73       typedef struct {
74               char *interface_name;
75               int speed;
76               sg_iface_duplex duplex;
77               int up;
78               time_t systime;
79       } sg_network_iface_stats;
80
81
82       interface_name
83              The name known to the operating system.  (eg. on linux it  might
84              be eth0)
85
86       speed  The speed of the interface, in megabits/sec.
87
88       duplex The  duplex  state  the interface is in. See sg_iface_duplex for
89              permitted values.
90
91       up     Whether the interface is up.
92
93       systime
94              The timestamp when the above stats where  collected  in  seconds
95              since epoch
96

BUGS

98       Getting  specific details may require elevated privileges, eg. on Linux
99       the interface speed isn't visible to non-privileged processes.
100
101       The compare functions exist rather for backward compatibility than  for
102       functionality  enhancements.  Limited  flexibility (e.g. reverse order)
103       and lack of optimising opportunities for the compiler leads to the rec‐
104       ommendation to implement the required compare routines locally.
105

SEE ALSO

107       statgrab(3)
108

WEBSITE

110       ⟨https://libstatgrab.org/⟩
111
112
113
114libstatgrab                       2019-03-08     sg_get_network_iface_stats(3)