NAME

       sg_get_disk_io_stats,          sg_get_disk_io_stats_r,          sg_get_disk_io_stats_diff,
       sg_get_disk_io_stats_diff_between,     sg_free_disk_io_stats,     sg_disk_io_compare_name,
       sg_disk_io_compare_traffic - get disk io statistics

SYNOPSIS

       #include <statgrab.h>

       sg_disk_io_stats *sg_get_disk_io_stats (size_t *entries);

       sg_disk_io_stats *sg_get_disk_io_stats_r (size_t *entries);

       sg_disk_io_stats *sg_get_disk_io_stats_diff (size_t *entries);

       sg_disk_io_stats *sg_get_disk_io_stats_diff_between (const sg_disk_io_stats *cur, const
                          sg_disk_io_stats *last, size_t *entries);

       sg_error sg_free_disk_io_stats (sg_disk_io_stats *data);

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

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

DESCRIPTION

       The sg_get_disk_io_stats functions provide disk I/O statistics on a per  disk  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_disk_io_stats()  and  sg_get_disk_io_stats_r()  functions  deliver  the   I/O-
       statistics    since    the    disk    has    been    attached    to   the   system.    The
       sg_get_disk_io_stats_diff() and sg_get_disk_io_stats_diff_between() deliver the difference
       between two calls of sg_get_disk_io_stats() or sg_get_disk_io_stats_r(), respectively.

       API Shortcut

       ┌──────────────────────────────────┬────────────────────┬──────────────────────────┐
       │function                          │ returns            │ data owner               │
       ├──────────────────────────────────┼────────────────────┼──────────────────────────┤
       │sg_get_disk_io_stats              │ sg_disk_io_stats * │ libstatgrab      (thread │
       │                                  │                    │ local)                   │
       ├──────────────────────────────────┼────────────────────┼──────────────────────────┤
       │sg_get_disk_io_stats_r            │ sg_disk_io_stats * │ caller                   │
       ├──────────────────────────────────┼────────────────────┼──────────────────────────┤
       │sg_get_disk_io_stats_diff         │ sg_disk_io_stats * │ libstatgrab      (thread │
       │                                  │                    │ local)                   │
       ├──────────────────────────────────┼────────────────────┼──────────────────────────┤
       │sg_get_disk_io_stats_diff_between │ sg_disk_io_stats * │ caller                   │
       └──────────────────────────────────┴────────────────────┴──────────────────────────┘
       sg_disk_io_stats       vectors       got       from       sg_get_disk_io_stats_r()      or
       sg_get_disk_io_stats_diff_between() must be freed using sg_free_disk_io_stats()  when  not
       needed any more. The caller is responsible for doing it.

       Additionally  two  support functions for qsort(3) are available: sg_disk_io_compare_name()
       and sg_disk_io_compare_traffic().

       Example

       size_t entries;
       sg_disk_io_stats *io_stats = NULL;
       while( NULL != ( io_stats = sg_get_disk_io_stats_diff(&entries) ) ) {
           /* show disks with most traffic first */
           qsort( io_stats, entries, sizeof(io_stats[0]), &sg_disk_io_compare_traffic );
           show_disk_io_stats( io_stats );
       }

       On some platforms, such as Solaris 7, the kernel value is stored in a 32bit int, so  wraps
       around  when  it  reaches  4GB.  Other platforms, such as Solaris 8 (and most other modern
       systems), hold the value in a 64bit int, which wraps somewhere near 17 million  terabytes.
       The   sg_get_disk_io_stats_diff()  function  and  the  sg_get_disk_io_stats_diff_between()
       function care about these  overflows  and  try  to  detect  overflows  when  the  diff  is
       calculated.

       On  Solaris  libstatgrab will attempt to get the cXtXdXsX representation for the disk_name
       string. If it fails it will use  a  name  like  sd0.  On  some  systems  programs  calling
       libstatgrab  will  need  elevated privileges to lookup some of the names. The mappings are
       built up when sg_init() is called for the first time.

RETURN VALUES

       All diskio statistics return a pointer to a structure of type sg_disk_io_stats.

       typedef struct {
               char *disk_name;
               unsigned long long read_bytes;
               unsigned long long write_bytes;
               time_t systime;
       } sg_disk_io_stats;

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

       read_bytes
              The number of bytes the disk has read.

       write_bytes
              The number of bytes the disk has written.

       systime
              The time period over which read_bytes and write_bytes were transferred.

BUGS

       sg_get_disk_io_stats_diff and sg_get_disk_io_stats_diff_between compare two lists of  disk
       (block  device)  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_disk_io_stats_diff will return the same as sg_get_disk_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_disk_io_stats_diff() function will return 5GB.

       The compare functions exists 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/⟩