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/⟩