NAME

       sg_get_network_io_stats,             sg_get_network_io_stats_r,             sg_get_network_io_stats_diff,
       sg_get_network_io_stats_diff_between, sg_free_network_io_stats, sg_network_io_compare_name - get  network
       statistics

SYNOPSIS

       #include <statgrab.h>

       sg_network_io_stats *sg_get_network_io_stats (size_t *entries);

       sg_network_io_stats *sg_get_network_io_stats_r (size_t *entries);

       sg_network_io_stats *sg_get_network_io_stats_diff (size_t *entries);

       sg_network_io_stats *sg_get_network_io_stats_diff_between (const sg_network_io_stats *cur, const
                             sg_network_io_stats *last, size_t *entries);

       sg_error sg_free_network_io_stats (sg_network_iface_stats *data);

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

DESCRIPTION

       The sg_get_network_io_stats functions provide network interface I/O statistics on a per interface  basis.
       All  get- and diff-functions take an optional entries parameter, which points (when given) to a size_t to
       take the number of returned vector entries.

       The sg_get_network_io_stats() and sg_get_network_io_stats_r() functions deliver the I/O-statistics  since
       the   interface   has   been   attached   to   the   system.    The   sg_get_network_io_stats_diff()  and
       sg_get_network_io_stats_diff_between()    deliver    the    difference    between    two     calls     of
       sg_get_network_io_stats() or sg_get_network_io_stats_r(), respectively.

       API Shortcut

       ┌─────────────────────────────────────┬───────────────────────┬────────────────────────────┐
       │function                             │ returns               │ data owner                 │
       ├─────────────────────────────────────┼───────────────────────┼────────────────────────────┤
       │sg_get_network_io_stats              │ sg_network_io_stats * │ libstatgrab (thread local) │
       ├─────────────────────────────────────┼───────────────────────┼────────────────────────────┤
       │sg_get_network_io_stats_r            │ sg_network_io_stats * │ caller                     │
       ├─────────────────────────────────────┼───────────────────────┼────────────────────────────┤
       │sg_get_network_io_stats_diff         │ sg_network_io_stats * │ libstatgrab (thread local) │
       ├─────────────────────────────────────┼───────────────────────┼────────────────────────────┤
       │sg_get_network_io_stats_diff_between │ sg_network_io_stats * │ caller                     │
       └─────────────────────────────────────┴───────────────────────┴────────────────────────────┘
       sg_network_io_stats       vectors       received        from        sg_get_network_io_stats_r()        or
       sg_get_network_io_stats_diff_between() must be freed using sg_free_network_io_stats() when not needed any
       more. The caller is responsible for doing it.

       Additionally a support function for qsort(3) are available: sg_network_io_compare_name().

       Example

       size_t entries;
       sg_network_io_stats *network_stats = NULL;
       while( NULL != ( network_stats = sg_get_network_io_stats_diff(&entries) ) ) {
           /* sort interface by name */
           qsort( network_stats, entries, sizeof(network_stats[0]), &sg_network_io_compare_name );
           show_network_io_stats( network_stats );
       }

       sg_get_network_io_stats returns the network traffic stored in the kernel which holds the amount  of  data
       transferred  since  device  was attached. On some platforms, such as Solaris 7, this value is stored in a
       32bit int, so wraps around when it reaches 4GB. Other platforms, such as Solaris 8, hold the value  in  a
       64bit  int, which wraps somewhere near 17 million terabytes.  The sg_get_network_io_stats_diff() function
       and the sg_get_network_io_stats_diff_between() function care about these  overflows  and  try  to  detect
       overflows when the diff is calculated.

RETURN VALUES

       All network statistics return a pointer to a structure of type sg_network_io_stats.

       typedef struct {
               char *interface_name;
               unsigned long long tx;
               unsigned long long rx;
               unsigned long long ipackets;
               unsigned long long opackets;
               unsigned long long ierrors;
               unsigned long long oerrors;
               unsigned long long collisions;
               time_t systime;
       } sg_network_io_stats;

       interface_name
              The name known to the operating system.  (eg. on linux it might be eth0, on AIX en0 and on FreeBSD
              fxp0)

       tx     The number of bytes transmitted.

       rx     The number of bytes received.

       ipackets
              The number of packets received.

       opackets
              The number of packets transmitted.

       ierrors
              The number of receive errors.

       oerrors
              The number of transmit errors.

       collisions
              The number of collisions.

       systime
              The timestamp when the above stats where collected in seconds since epoch or the time period  over
              which tx and rx were transferred.

BUGS

       sg_get_network_io_stats_diff  and  sg_get_network_io_stats_diff_between  compare  two  lists  of  network
       interface related I/O statistics. Each entry occurring only in the second list is passed through  to  the
       resulting  list  as  if  it would have been compared to an entry with all statistic values set to 0. This
       implies,  on   the   very   first   call   sg_get_network_io_stats_diff   will   return   the   same   as
       sg_get_network_io_stats.

       On  operating  systems  that  hold  only  32bits of data there is a problem if the values wrap twice. For
       example,  on  Solaris  7  if  9GB  is  transferred  and  the  operating  system   wraps   at   4GB,   the
       sg_get_network_io_stats_diff function will return 5GB.

SEE ALSO

       statgrab(3)

WEBSITE

       ⟨https://libstatgrab.org/⟩