sg_get_disk_io_stats_diff_between(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

FC#include <statgrab.h>F[0]

FCsg_disk_io_stats *sg_get_disk_io_statsF[0] FC(size_t *entries);F[0]

FCsg_disk_io_stats *sg_get_disk_io_stats_rF[0] FC(size_t *entries);F[0]

FCsg_disk_io_stats *sg_get_disk_io_stats_diffF[0] FC(size_t *entries);F[0]

FCsg_disk_io_stats *sg_get_disk_io_stats_diff_betweenF[0] FC(const sg_disk_io_stats *cur, const sg_disk_io_stats *last, size_t *entries);F[0]

FCsg_error sg_free_disk_io_statsF[0] FC(sg_disk_io_stats *data);F[0]

FCint sg_disk_io_compare_nameF[0] FC(const void *va, const void *vb);F[0]

FCint sg_disk_io_compare_trafficF[0] FC(const void *va, const void *vb);F[0]

DESCRIPTION

The FCsg_get_disk_io_statsF[0] functions provide disk I/O statistics on a per disk basis. All get- and diff-functions take an optional FCentriesF[0] parameter, which points (when given) to a size_t to take the number of returned vector entries.

The FCsg_get_disk_io_statsF[0]() and FCsg_get_disk_io_stats_rF[0]() functions deliver the I/O-statistics since the disk has been attached to the system. The FCsg_get_disk_io_stats_diffF[0]() and FCsg_get_disk_io_stats_diff_betweenF[0]() deliver the difference between two calls of FCsg_get_disk_io_statsF[0]() or FCsg_get_disk_io_stats_rF[0](), 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

FCsg_disk_io_statsF[0] vectors got from FCsg_get_disk_io_stats_rF[0]() or FCsg_get_disk_io_stats_diff_betweenF[0]() must be freed using FCsg_free_disk_io_statsF[0]() when not needed any more. The caller is responsible for doing it.

Additionally two support functions for FCqsortF[0](3) are available: FCsg_disk_io_compare_nameF[0]() and FCsg_disk_io_compare_trafficF[0]().

Example

FC
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 );
}
        F[0]

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 FCsg_get_disk_io_stats_diffF[0]() function and the FCsg_get_disk_io_stats_diff_betweenF[0]() 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 FCdisk_nameF[0] 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 FCsg_initF[0]() is called for the first time.

RETURN VALUES

All diskio statistics return a pointer to a structure of type FCsg_disk_io_statsF[0].

FC
typedef struct {
        char *disk_name;
        unsigned long long read_bytes;
        unsigned long long write_bytes;
        time_t systime;
} sg_disk_io_stats;
    F[0]

FCdisk_nameF[0]: The name known to the operating system. (eg. on linux it might be hda)

FCread_bytesF[0]: The number of bytes the disk has read.

FCwrite_bytesF[0]: The number of bytes the disk has written.

FCsystimeF[0]: The time period over which FCread_bytesF[0] and FCwrite_bytesF[0] were transferred.

BUGS

FCsg_get_disk_io_stats_diffF[0] and FCsg_get_disk_io_stats_diff_betweenF[0] 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 FCsg_get_disk_io_stats_diffF[0] will return the same as FCsg_get_disk_io_statsF[0].

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 FCsg_get_disk_io_stats_diffF[0]() 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.

WEBSITE

⟨https://libstatgrab.org/⟩