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