NAME

       sg_get_network_iface_stats,           sg_get_network_iface_stats_r,          sg_free_network_iface_stats,
       sg_network_iface_compare_name - get network interface statistics

SYNOPSIS

       #include <statgrab.h>

       sg_network_iface_stats *sg_get_network_iface_stats (size_t *entries);

       sg_network_iface_stats *sg_get_network_iface_stats_r (size_t *entries);

       sg_error sg_free_network_iface_stats (sg_network_iface_stats *data);

       int sg_network_iface_compare_name (const void *va, const void *vb);

DESCRIPTION

       The functions sg_get_network_iface_stats() and sg_get_network_iface_stats_r() return statistics about the
       network  interfaces  in  the  machine.  Specifically,  they return the speed of the interface, the duplex
       state, and whether it is currently up. Both functions take an optional entries  parameter,  which  points
       (when given) to a size_t to take the number of returned vector entries.

       API Shortcut

       ┌─────────────────────────────┬──────────────────────────┬────────────────────────────┐
       │function                     │ returns                  │ data owner                 │
       ├─────────────────────────────┼──────────────────────────┼────────────────────────────┤
       │sg_get_network_iface_stats   │ sg_network_iface_stats * │ libstatgrab (thread local) │
       ├─────────────────────────────┼──────────────────────────┼────────────────────────────┤
       │sg_get_network_iface_stats_r │ sg_network_iface_stats * │ caller                     │
       └─────────────────────────────┴──────────────────────────┴────────────────────────────┘
       The  sg_network_iface_stats  vectors  received  from  sg_get_network_iface_stats_r()  must be freed using
       sg_free_network_iface_stats() when not needed any more. The caller is responsible for doing it.

       Additionally a support function for qsort(3) in available: sg_network_iface_compare_name().

       Sort Example

       size_t entries;
       sg_network_iface_stats *network_iface_stats = NULL;
       while( NULL != ( network_iface_stats = sg_get_network_iface_stats(&entries) ) ) {
           /* order entries alphabetically using the mountpoint */
           qsort( network_iface_stats, entries, sizeof(network_iface_stats[0]), &sg_network_iface_compare_name );
           show_network_iface_stats( network_iface_stats );
       }

RETURN VALUES

       The sg_get_network_iface_stats returns a pointer to a structure of type sg_network_iface_stats.

       typedef enum{
               SG_IFACE_DUPLEX_FULL,
               SG_IFACE_DUPLEX_HALF,
               SG_IFACE_DUPLEX_UNKNOWN
       }sg_iface_duplex;

       Note: The SG_IFACE_DUPLEX_UNKNOWN value could mean that duplex hasn't been negotiated yet.

       typedef struct {
               char *interface_name;
               int speed;
               sg_iface_duplex duplex;
               int up;
               time_t systime;
       } sg_network_iface_stats;

       interface_name
              The name known to the operating system.  (eg. on linux it might be eth0)

       speed  The speed of the interface, in megabits/sec.

       duplex The duplex state the interface is in. See sg_iface_duplex for permitted values.

       up     Whether the interface is up.

       systime
              The timestamp when the above stats where collected in seconds since epoch

BUGS

       Getting specific details may require elevated privileges, eg. on Linux the interface speed isn't  visible
       to non-privileged processes.

       The  compare  functions  exist  rather  for  backward  compatibility than for functionality enhancements.
       Limited flexibility (e.g. reverse order) and lack of optimising opportunities for the compiler  leads  to
       the recommendation to implement the required compare routines locally.

SEE ALSO

       statgrab(3)

WEBSITE

       ⟨https://libstatgrab.org/⟩