1sg_get_disk_io_stats(3) sg_get_disk_io_stats(3)
2
6 sg_get_disk_io_stats, sg_get_disk_io_stats_r,
7 sg_get_disk_io_stats_diff, sg_get_disk_io_stats_diff_between,
8 sg_free_disk_io_stats, sg_disk_io_compare_name, sg_disk_io_com‐
9 pare_traffic - get disk io statistics
10
12 #include <statgrab.h>
13 sg_disk_io_stats *sg_get_disk_io_stats (size_t *entries);
16 sg_disk_io_stats *sg_get_disk_io_stats_r (size_t *entries);
18 sg_disk_io_stats *sg_get_disk_io_stats_diff (size_t *entries);
20 sg_disk_io_stats *sg_get_disk_io_stats_diff_between (const
22 sg_disk_io_stats *cur, const sg_disk_io_stats *last,
23 size_t *entries);
24 sg_error sg_free_disk_io_stats (sg_disk_io_stats *data);
26 int sg_disk_io_compare_name (const void *va, const void *vb);
28 int sg_disk_io_compare_traffic (const void *va, const void *vb);
30
32 The sg_get_disk_io_stats functions provide disk I/O statistics on a per
33 disk basis. All get- and diff-functions take an optional entries param‐
34 eter, which points (when given) to a size_t to take the number of re‐
35 turned vector entries.
36 The sg_get_disk_io_stats() and sg_get_disk_io_stats_r() functions de‐
38 liver the I/O-statistics since the disk has been attached to the sys‐
39 tem. The sg_get_disk_io_stats_diff() and sg_get_disk_io_stats_diff_be‐
40 tween() deliver the difference between two calls of
41 sg_get_disk_io_stats() or sg_get_disk_io_stats_r(), respectively.
42 API Shortcut
44 ┌──────────────────────────────┬────────────────────┬─────────────────────┐
46 │function │ returns │ data owner │
47 ├──────────────────────────────┼────────────────────┼─────────────────────┤
48 │sg_get_disk_io_stats │ sg_disk_io_stats * │ libstatgrab (thread │
49 │ │ │ local) │
50 ├──────────────────────────────┼────────────────────┼─────────────────────┤
51 │sg_get_disk_io_stats_r │ sg_disk_io_stats * │ caller │
52 ├──────────────────────────────┼────────────────────┼─────────────────────┤
53 │sg_get_disk_io_stats_diff │ sg_disk_io_stats * │ libstatgrab (thread │
54 │ │ │ local) │
55 ├──────────────────────────────┼────────────────────┼─────────────────────┤
56 │sg_get_disk_io_stats_diff_be‐ │ sg_disk_io_stats * │ caller │
57 │tween │ │ │
58 └──────────────────────────────┴────────────────────┴─────────────────────┘
59 sg_disk_io_stats vectors got from sg_get_disk_io_stats_r() or
60 sg_get_disk_io_stats_diff_between() must be freed using
61 sg_free_disk_io_stats() when not needed any more. The caller is respon‐
62 sible for doing it.
63 Additionally two support functions for qsort(3) are available:
65 sg_disk_io_compare_name() and sg_disk_io_compare_traffic().
66 Example
68 size_t entries;
70 sg_disk_io_stats *io_stats = NULL;
71 while( NULL != ( io_stats = sg_get_disk_io_stats_diff(&entries) ) ) {
72 /* show disks with most traffic first */
73 qsort( io_stats, entries, sizeof(io_stats[0]), &sg_disk_io_compare_traffic );
74 show_disk_io_stats( io_stats );
75 }
76 On some platforms, such as Solaris 7, the kernel value is stored in a
79 32bit int, so wraps around when it reaches 4GB. Other platforms, such
80 as Solaris 8 (and most other modern systems), hold the value in a 64bit
81 int, which wraps somewhere near 17 million terabytes. The
82 sg_get_disk_io_stats_diff() function and the
83 sg_get_disk_io_stats_diff_between() function care about these overflows
84 and try to detect overflows when the diff is calculated.
85 On Solaris libstatgrab will attempt to get the cXtXdXsX representation
87 for the disk_name string. If it fails it will use a name like sd0. On
88 some systems programs calling libstatgrab will need elevated privileges
89 to lookup some of the names. The mappings are built up when sg_init()
90 is called for the first time.
91
93 All diskio statistics return a pointer to a structure of type
94 sg_disk_io_stats.
95 typedef struct {
97 char *disk_name;
98 unsigned long long read_bytes;
99 unsigned long long write_bytes;
100 time_t systime;
101 } sg_disk_io_stats;
102 disk_name
105 The name known to the operating system. (eg. on linux it might
106 be hda)
107 read_bytes
109 The number of bytes the disk has read.
110 write_bytes
112 The number of bytes the disk has written.
113 systime
115 The time period over which read_bytes and write_bytes were
116 transferred.
117
119 sg_get_disk_io_stats_diff and sg_get_disk_io_stats_diff_between compare
120 two lists of disk (block device) related I/O statistics. Each entry oc‐
121 curring only in the second list is passed through to the resulting list
122 as if it would have been compared to an entry with all statistic values
123 set to 0. This implies, on the very first call
124 sg_get_disk_io_stats_diff will return the same as sg_get_disk_io_stats.
125 On operating systems that hold only 32bits of data there is a problem
127 if the values wrap twice. For example, on Solaris 7 if 9GB is trans‐
128 ferred and the operating system wraps at 4GB, the
129 sg_get_disk_io_stats_diff() function will return 5GB.
130 The compare functions exists rather for backward compatibility than for
132 functionality enhancements. Limited flexibility (e.g. reverse order)
133 and lack of optimising opportunities for the compiler leads to the rec‐
134 ommendation to implement the required compare routines locally.
135
137 statgrab(3)
138
140 ⟨https://libstatgrab.org/⟩
141libstatgrab 2019-03-08 sg_get_disk_io_stats(3)