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

       ⟨http://www.i-scream.org/libstatgrab/⟩