2 .\" Copyright (c) 1998, 1999 Kenneth D. Merry.
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\" 3. The name of the author may not be used to endorse or promote products
14 .\" derived from this software without specific prior written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" $FreeBSD: src/lib/libdevstat/devstat.3,v 1.7.2.8 2001/12/17 10:08:29 ru Exp $
29 .\" $DragonFly: src/lib/libdevstat/devstat.3,v 1.2 2003/06/17 04:26:49 dillon Exp $
45 .Nd device statistics utility library
54 .Fn getgeneration "void"
58 .Fn checkversion "void"
60 .Fn getdevs "struct statinfo *stats"
63 .Fa "struct device_selection **dev_select"
64 .Fa "int *num_selected"
65 .Fa "int *num_selections"
66 .Fa "long *select_generation"
67 .Fa "long current_generation"
68 .Fa "struct devstat *devices"
70 .Fa "struct devstat_match *matches"
72 .Fa "char **dev_selections"
73 .Fa "int num_dev_selections"
74 .Fa "devstat_select_mode select_mode"
81 .Fa "struct devstat_match **matches"
82 .Fa "int *num_matches"
86 .Fa "struct devstat *current"
87 .Fa "struct devstat *previous"
88 .Fa "long double etime"
89 .Fa "u_int64_t *total_bytes"
90 .Fa "u_int64_t *total_transfers"
91 .Fa "u_int64_t *total_blocks"
92 .Fa "long double *kb_per_transfer"
93 .Fa "long double *transfers_per_second"
94 .Fa "long double *mb_per_second"
95 .Fa "long double *blocks_per_second"
96 .Fa "long double *ms_per_transaction"
100 .Fa "struct timeval cur_time"
101 .Fa "struct timeval prev_time"
106 library is a library of helper functions for dealing with the kernel
108 interface, which is accessible to users via
112 returns the number of devices registered with the
114 subsystem in the kernel.
117 returns the current generation of the
119 list of devices in the kernel.
122 returns the current kernel
127 checks the userland devstat version against the kernel devstat version.
128 If the two are identical, it returns zero.
129 Otherwise, it prints an appropriate error in
134 fetches the current list of devices and statistics into the supplied
139 structure can be found in
141 .Bd -literal -offset indent
143 long cp_time[CPUSTATES];
146 struct devinfo *dinfo;
147 struct timeval busy_time;
154 structure to be allocated, and it also expects the
156 subelement to be allocated and zeroed prior to the first invocation of
160 subelement is used to store state between calls, and should not be modified
161 after the first call to
165 subelement contains the following elements:
166 .Bd -literal -offset indent
168 struct devstat *devices;
178 variable contains an array of
180 structures, but at the head of the array is the current
183 The reason the generation is at the head of the buffer is so that userland
184 software accessing the devstat statistics information can atomically get
185 both the statistics information and the corresponding generation number.
186 If client software were forced to get the generation number via a separate
188 variable (which is available for convenience), the list of devices could
189 change between the time the client gets the generation and the time the
190 client gets the device list.
196 structure is a pointer to memory that is allocated, and resized if
199 The devices subelement of the
201 structure is basically a pointer to the beginning of the array of devstat
206 The generation subelement of the
208 structure contains the generation number from the
216 structure contains the current
217 number of devices registered with the kernel
222 selects devices to display based upon a number of criteria:
224 .It specified devices
225 Specified devices are the first selection priority.
226 These are generally devices specified by name by the user e.g. da0, da1, cd0.
228 These are pattern matching expressions generated by
232 If performance mode is enabled, devices will be sorted based on the
236 structure passed in to
240 value currently must be maintained by the user.
241 In the future, this may be done for him in a
244 If no devices have been selected by name or by pattern, the performance
245 tracking code will select every device in the system, and sort them by
247 If devices have been selected by name or pattern, the performance tracking
248 code will honor those selections and will only sort among the selected
250 .It order in the devstat list
251 If the selection mode is set to DS_SELECT_ADD, and if there are still less
256 will automatically select up to
262 performs selections in four different modes:
263 .Bl -tag -width DS_SELECT_ADDONLY
267 will select any unselected devices specified by name or matching pattern.
268 It will also select more devices, in devstat list order, until the number
269 of selected devices is equal to
271 or until all devices are
276 will clear all current selections, and will only select devices specified
277 by name or by matching pattern.
281 will remove devices specified by name or by matching pattern.
282 It will not select any additional devices.
283 .It DS_SELECT_ADDONLY
286 will select any unselected devices specified by name or matching pattern.
287 In this respect it is identical to add mode.
288 It will not, however, select any devices other than those specified.
291 In all selection modes,
293 will not select any more than
296 One exception to this is when you are in
298 mode and no devices have been selected.
301 will select every device in the system.
302 Client programs must pay attention to selection order when deciding whether
303 to pay attention to a particular device.
304 This may be the wrong behavior, and probably requires additional thought.
307 handles allocation and resizing of the
315 .Va current_generation
319 generation and number of devices.
326 .Va select_generation
328 .Va current_generation ,
330 will resize the selection list as necessary, and re-initialize the
334 takes a comma separated match string and compiles it into a
335 \fBdevstat_match\fR structure that is understood by
337 Match strings have the following format:
339 .Bd -literal -offset indent
344 takes care of allocating and reallocating the match list as necessary.
345 Currently known match types include:
347 .Bl -tag -width indent -compact
349 .Bl -tag -width 9n -compact
351 Direct Access devices
353 Sequential Access devices
359 Write Once Read Multiple devices
365 Optical Memory devices
367 Medium Changer devices
369 Communication devices
371 Storage Array devices
373 Enclosure Services devices
379 .Bl -tag -width 9n -compact
381 Integrated Drive Electronics devices
383 Small Computer System Interface devices
385 Any other device interface
389 .Bl -tag -width 9n -compact
396 provides an easy way to obtain various device statistics.
397 Only two arguments are mandatory:
401 Every other argument is optional.
402 For most applications, the user will want to supply both
406 devstat structures so that statistics may be calculated over a given period
408 In some instances, for instance when calculating statistics since system boot,
409 the user may pass in a NULL pointer for the
414 will use the total stats in the
416 structure to calculate statistics over
418 The various statistics that may be calculated by
420 should be mostly explained by the function declaration itself, but for
421 completeness here is a list of variable names and the statistics that will
423 .Bl -tag -width transfers_per_second
425 This is the total number of bytes transferred on the given device, both
426 reads and writes, between the acquisition of
428 and the acquisition of
432 is NULL, the result will be the total reads and writes given in
435 This is the total number of transfers completed between the
438 and the acquisition of
442 is NULL, the result will be the total number of transactions listed in
447 divided by the device blocksize.
448 If the device blocksize is listed as
450 the device blocksize will default to 512 bytes.
452 This is the average number of kilobytes per transfer during the measurement
454 .It transfers_per_second
455 This is the average number of transfers per second.
457 This is average megabytes per second.
458 .It blocks_per_second
459 This is average blocks per second.
460 If the device blocksize is
462 a default blocksize of 512 bytes will be used instead.
463 .It ms_per_transaction
464 The average number of milliseconds per transaction.
468 provides an easy way to find the difference in seconds between two
471 This is most commonly used in conjunction with the time recorded by the
475 each time it fetches the current
483 return the indicated \fBsysctl\fR variable, or -1 if there is an error
484 fetching the variable.
487 returns 0 if the kernel and userland
490 If they do not match, it returns -1.
495 return -1 in case of an error, 0 if there is no error and 1 if the device
496 list or selected devices have changed.
497 A return value of 1 from
499 is usually a hint to re-run
501 because the device list has changed.
504 returns -1 for error, and 0 if there is no error.
507 returns -1 for error, and 0 for success.
510 returns the computed elapsed time.
512 If an error is returned from one of the
514 library functions, the reason for the error is generally printed in
518 .Dv DEVSTAT_ERRBUF_SIZE
529 statistics system first appeared in
532 .An Kenneth Merry Aq ken@FreeBSD.org
534 There should probably be an interface to de-allocate memory allocated by
541 should probably not select more than
545 mode when no devices have been selected previously.
547 There should probably be functions to perform the statistics buffer
548 swapping that goes on in most of the clients of this library.
554 structures should probably be cleaned up and thought out a little more.