DragonFly On-Line Manual Pages

sg_get_disk_io_stats(3)                                sg_get_disk_io_stats(3)

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

i-scream                          2013-06-07           sg_get_disk_io_stats(3)