'\" t -*- coding: UTF-8 -*-
.if \n(.g .ds T< \\FC
.if \n(.g .ds T> \\F[\n[.fam]]
.de URL
\\$2 \(la\\$1\(ra\\$3
..
.if \n(.g .mso www.tmac
.TH sg_get_disk_io_stats 3 2019-03-08 libstatgrab ""
.SH 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
.SH SYNOPSIS
'nh
.nf
\*(T<#include <statgrab.h>\*(T>
.fi
.sp 1
.PP
.fi
.ad l
\*(T<sg_disk_io_stats *\fBsg_get_disk_io_stats\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(size_t *\fIentries\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<sg_disk_io_stats *\fBsg_get_disk_io_stats_r\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(size_t *\fIentries\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<sg_disk_io_stats *\fBsg_get_disk_io_stats_diff\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(size_t *\fIentries\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<sg_disk_io_stats *\fBsg_get_disk_io_stats_diff_between\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(const sg_disk_io_stats *\fIcur\fR, const sg_disk_io_stats *\fIlast\fR, size_t *\fIentries\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<sg_error \fBsg_free_disk_io_stats\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(sg_disk_io_stats *\fIdata\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<int \fBsg_disk_io_compare_name\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(const void *\fIva\fR, const void *\fIvb\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<int \fBsg_disk_io_compare_traffic\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(const void *\fIva\fR, const void *\fIvb\fR);\*(T>
'in \n(.iu-\nxu
.ad b
'hy
.SH DESCRIPTION
The \*(T<\fBsg_get_disk_io_stats\fR\*(T> functions provide disk
I/O statistics on a per disk basis. All get- and diff-functions take
an optional \*(T<entries\*(T> parameter, which points
(when given) to a size_t to take the number of returned vector
entries.
.PP
The \*(T<\fBsg_get_disk_io_stats\fR\*(T>() and
\*(T<\fBsg_get_disk_io_stats_r\fR\*(T>() functions deliver the
I/O-statistics since the disk has been attached to the system.
The \*(T<\fBsg_get_disk_io_stats_diff\fR\*(T>() and
\*(T<\fBsg_get_disk_io_stats_diff_between\fR\*(T>() deliver the
difference between two calls of
\*(T<\fBsg_get_disk_io_stats\fR\*(T>() or
\*(T<\fBsg_get_disk_io_stats_r\fR\*(T>(), respectively.
.PP
\fBAPI Shortcut\fR
.TS
allbox ;
l | l | l.
T{
function
T}	T{
returns
T}	T{
data owner
T}
.T&
l | l | l.
T{
sg_get_disk_io_stats
T}	T{
sg_disk_io_stats *
T}	T{
libstatgrab (thread local)
T}
T{
sg_get_disk_io_stats_r
T}	T{
sg_disk_io_stats *
T}	T{
caller
T}
T{
sg_get_disk_io_stats_diff
T}	T{
sg_disk_io_stats *
T}	T{
libstatgrab (thread local)
T}
T{
sg_get_disk_io_stats_diff_between
T}	T{
sg_disk_io_stats *
T}	T{
caller
T}
.TE
.PP
\*(T<sg_disk_io_stats\*(T> vectors got from
\*(T<\fBsg_get_disk_io_stats_r\fR\*(T>() or
\*(T<\fBsg_get_disk_io_stats_diff_between\fR\*(T>() must be
freed using \*(T<\fBsg_free_disk_io_stats\fR\*(T>() when
not needed any more. The caller is responsible for doing it.
.PP
Additionally two support functions for \*(T<\fBqsort\fR\*(T>(3)
are available: \*(T<\fBsg_disk_io_compare_name\fR\*(T>() and
\*(T<\fBsg_disk_io_compare_traffic\fR\*(T>().

\fBExample\fR
.PP
.nf
\*(T<
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 );
}
        \*(T>
.fi
.PP
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 \*(T<\fBsg_get_disk_io_stats_diff\fR\*(T>() function and
the \*(T<\fBsg_get_disk_io_stats_diff_between\fR\*(T>()
function care about these overflows and try to detect overflows
when the diff is calculated.
.PP
On Solaris libstatgrab will attempt to get the cXtXdXsX
representation for the \*(T<disk_name\*(T> 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
\*(T<\fBsg_init\fR\*(T>() is called for the first time.
.SH "RETURN VALUES"
All diskio statistics return a pointer to a structure of type
\*(T<sg_disk_io_stats\*(T>.
.PP
.nf
\*(T<
typedef struct {
        char *disk_name;
        unsigned long long read_bytes;
        unsigned long long write_bytes;
        time_t systime;
} sg_disk_io_stats;
    \*(T>
.fi
.TP 
\*(T<disk_name\*(T> 
The name known to the operating system.
(eg. on linux it might be hda)
.TP 
\*(T<read_bytes\*(T> 
The number of bytes the disk has read.
.TP 
\*(T<write_bytes\*(T> 
The number of bytes the disk has written.
.TP 
\*(T<systime\*(T> 
The time period over which \*(T<read_bytes\*(T>
and \*(T<write_bytes\*(T> were transferred.
.SH BUGS
\*(T<\fBsg_get_disk_io_stats_diff\fR\*(T> and
\*(T<\fBsg_get_disk_io_stats_diff_between\fR\*(T> 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
\*(T<\fBsg_get_disk_io_stats_diff\fR\*(T> will return the same
as \*(T<\fBsg_get_disk_io_stats\fR\*(T>.
.PP
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
\*(T<\fBsg_get_disk_io_stats_diff\fR\*(T>() function will return
5GB.
.PP
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.
.SH "SEE ALSO"
\fBstatgrab\fR(3)
.SH WEBSITE
\(lahttps://libstatgrab.org/\(ra