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_net‐
       work_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_net‐                  │ sg_network_io_stats * │ caller                     │
       │ work_io_stats_diff_between   │                       │                            │
       └──────────────────────────────┴───────────────────────┴────────────────────────────┘

       sg_network_io_stats vectors received from sg_get_network_io_stats_r() or sg_get_network_io_stats_diff_be‐
       tween() must be freed using sg_free_network_io_stats() when not needed any more. The caller is  responsi‐
       ble 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 inter‐
       face  related  I/O  statistics. Each entry occurring only in the second list is passed through to the re‐
       sulting list as if it would have been compared to an entry with all statistic values set to 0.  This  im‐
       plies,  on  the  very  first  call  sg_get_network_io_stats_diff  will  return  the  same  as sg_get_net‐
       work_io_stats.

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

SEE ALSO

       statgrab(3)

WEBSITE

       ⟨https://libstatgrab.org/⟩

libstatgrab                                        2019-03-08                         sg_get_network_io_stats(3)