lib/libdevstat/devstat.3

   1 .\"
   2 .\" Copyright (c) 1998, 1999 Kenneth D. Merry.
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   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.
  15 .\"
  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
  26 .\" SUCH DAMAGE.
  27 .\"
  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.4 2005/01/08 19:19:26 joerg Exp $
  30 .\"
  31 .Dd May 21, 1998
  32 .Dt DEVSTAT 3
  33 .Os
  34 .Sh NAME
  35 .Nm devstat ,
  36 .Nm getnumdevs ,
  37 .Nm getgeneration ,
  38 .Nm getversion ,
  39 .Nm checkversion ,
  40 .Nm getdevs ,
  41 .Nm selectdevs ,
  42 .Nm buildmatch ,
  43 .Nm compute_stats ,
  44 .Nm compute_etime
  45 .Nd device statistics utility library
  46 .Sh LIBRARY
  47 .Lb libdevstat
  48 .Sh SYNOPSIS
  49 .In devstat.h
  50 .Ft int
  51 .Fn getnumdevs "void"
  52 .Ft long
  53 .Fn getgeneration "void"
  54 .Ft int
  55 .Fn getversion "void"
  56 .Ft int
  57 .Fn checkversion "void"
  58 .Ft int
  59 .Fn getdevs "struct statinfo *stats"
  60 .Ft int
  61 .Fo selectdevs
  62 .Fa "struct device_selection **dev_select"
  63 .Fa "int *num_selected"
  64 .Fa "int *num_selections"
  65 .Fa "long *select_generation"
  66 .Fa "long current_generation"
  67 .Fa "struct devstat *devices"
  68 .Fa "int numdevs"
  69 .Fa "struct devstat_match *matches"
  70 .Fa "int num_matches"
  71 .Fa "char **dev_selections"
  72 .Fa "int num_dev_selections"
  73 .Fa "devstat_select_mode select_mode"
  74 .Fa "int maxshowdevs"
  75 .Fa "int perf_select"
  76 .Fc
  77 .Ft int
  78 .Fo buildmatch
  79 .Fa "const char *match_str"
  80 .Fa "struct devstat_match **matches"
  81 .Fa "int *num_matches"
  82 .Fc
  83 .Ft int
  84 .Fo compute_stats
  85 .Fa "struct devstat *current"
  86 .Fa "struct devstat *previous"
  87 .Fa "long double etime"
  88 .Fa "u_int64_t *total_bytes"
  89 .Fa "u_int64_t *total_transfers"
  90 .Fa "u_int64_t *total_blocks"
  91 .Fa "long double *kb_per_transfer"
  92 .Fa "long double *transfers_per_second"
  93 .Fa "long double *mb_per_second"
  94 .Fa "long double *blocks_per_second"
  95 .Fa "long double *ms_per_transaction"
  96 .Fc
  97 .Ft long double
  98 .Fo compute_etime
  99 .Fa "struct timeval cur_time"
 100 .Fa "struct timeval prev_time"
 101 .Fc
 102 .Sh DESCRIPTION
 103 The
 104 .Nm
 105 library is a library of helper functions for dealing with the kernel
 106 .Xr devstat 9
 107 interface, which is accessible to users via
 108 .Xr sysctl 3 .
 109 .Pp
 110 .Fn getnumdevs
 111 returns the number of devices registered with the
 112 .Nm
 113 subsystem in the kernel.
 114 .Pp
 115 .Fn getgeneration
 116 returns the current generation of the
 117 .Nm
 118 list of devices in the kernel.
 119 .Pp
 120 .Fn getversion
 121 returns the current kernel
 122 .Nm
 123 version.
 124 .Pp
 125 .Fn checkversion
 126 checks the userland devstat version against the kernel devstat version.
 127 If the two are identical, it returns zero.
 128 Otherwise, it prints an appropriate error in
 129 .Va devstat_errbuf
 130 and returns -1.
 131 .Pp
 132 .Fn getdevs
 133 fetches the current list of devices and statistics into the supplied
 134 .Va statinfo
 135 structure.
 136 The
 137 .Va statinfo
 138 structure can be found in
 139 .Aq Pa devstat.h :
 140 .Bd -literal -offset indent
 141 struct statinfo {
 142         struct kinfo_cputime    cp_time;
 143         struct devinfo  *dinfo;
 144         struct timeval  busy_time;
 145 };
 146 .Ed
 147 .Pp
 148 .Fn getdevs
 149 expects the
 150 .Va statinfo
 151 structure to be allocated, and it also expects the
 152 .Va dinfo
 153 subelement to be allocated and zeroed prior to the first invocation of
 154 .Fn getdevs .
 155 The
 156 .Va dinfo
 157 subelement is used to store state between calls, and should not be modified
 158 after the first call to
 159 .Fn getdevs .
 160 The
 161 .Va dinfo
 162 subelement contains the following elements:
 163 .Bd -literal -offset indent
 164 struct devinfo {
 165         struct devstat  *devices;
 166         u_int8_t        *mem_ptr;
 167         long            generation;
 168         int             numdevs;
 169 };
 170 .Ed
 171 .Pp
 172 The
 173 .Va kern.devstat.all
 174 .Nm sysctl
 175 variable contains an array of
 176 .Nm
 177 structures, but at the head of the array is the current
 178 .Nm
 179 generation.
 180 The reason the generation is at the head of the buffer is so that userland
 181 software accessing the devstat statistics information can atomically get
 182 both the statistics information and the corresponding generation number.
 183 If client software were forced to get the generation number via a separate
 184 .Nm sysctl
 185 variable (which is available for convenience), the list of devices could
 186 change between the time the client gets the generation and the time the
 187 client gets the device list.
 188 .Pp
 189 The
 190 .Va mem_ptr
 191 subelement of the
 192 .Va devinfo
 193 structure is a pointer to memory that is allocated, and resized if
 194 necessary, by
 195 .Fn getdevs .
 196 The devices subelement of the
 197 .Va devinfo
 198 structure is basically a pointer to the beginning of the array of devstat
 199 structures from the
 200 .Va kern.devstat.all
 201 .Nm sysctl
 202 variable.
 203 The generation subelement of the
 204 .Va devinfo
 205 structure contains the generation number from the
 206 .Va kern.devstat.all
 207 .Nm sysctl
 208 variable.
 209 The
 210 .Va numdevs
 211 subelement of the
 212 .Va devinfo
 213 structure contains the current
 214 number of devices registered with the kernel
 215 .Nm
 216 subsystem.
 217 .Pp
 218 .Fn selectdevs
 219 selects devices to display based upon a number of criteria:
 220 .Bl -tag -width flag
 221 .It specified devices
 222 Specified devices are the first selection priority.
 223 These are generally devices specified by name by the user e.g. da0, da1, cd0.
 224 .It match patterns
 225 These are pattern matching expressions generated by
 226 .Fn buildmatch
 227 from user input.
 228 .It performance
 229 If performance mode is enabled, devices will be sorted based on the
 230 .Va bytes
 231 field in the
 232 .Va device_selection
 233 structure passed in to
 234 .Fn selectdevs .
 235 The
 236 .Va bytes
 237 value currently must be maintained by the user.
 238 In the future, this may be done for him in a
 239 .Nm
 240 library routine.
 241 If no devices have been selected by name or by pattern, the performance
 242 tracking code will select every device in the system, and sort them by
 243 performance.
 244 If devices have been selected by name or pattern, the performance tracking
 245 code will honor those selections and will only sort among the selected
 246 devices.
 247 .It order in the devstat list
 248 If the selection mode is set to DS_SELECT_ADD, and if there are still less
 249 than
 250 .Va maxshowdevs
 251 devices selected,
 252 .Fn selectdevs
 253 will automatically select up to
 254 .Va maxshowdevs
 255 devices.
 256 .El
 257 .Pp
 258 .Fn selectdevs
 259 performs selections in four different modes:
 260 .Bl -tag -width DS_SELECT_ADDONLY
 261 .It DS_SELECT_ADD
 262 In add mode,
 263 .Fn selectdevs
 264 will select any unselected devices specified by name or matching pattern.
 265 It will also select more devices, in devstat list order, until the number
 266 of selected devices is equal to
 267 .Va maxshowdevs
 268 or until all devices are
 269 selected.
 270 .It DS_SELECT_ONLY
 271 In only mode,
 272 .Fn selectdevs
 273 will clear all current selections, and will only select devices specified
 274 by name or by matching pattern.
 275 .It DS_SELECT_REMOVE
 276 In remove mode,
 277 .Fn selectdevs
 278 will remove devices specified by name or by matching pattern.
 279 It will not select any additional devices.
 280 .It DS_SELECT_ADDONLY
 281 In add only mode,
 282 .Fn selectdevs
 283 will select any unselected devices specified by name or matching pattern.
 284 In this respect it is identical to add mode.
 285 It will not, however, select any devices other than those specified.
 286 .El
 287 .Pp
 288 In all selection modes,
 289 .Fn selectdevs
 290 will not select any more than
 291 .Va maxshowdevs
 292 devices.
 293 One exception to this is when you are in
 294 .Dq top
 295 mode and no devices have been selected.
 296 In this case,
 297 .Fn selectdevs
 298 will select every device in the system.
 299 Client programs must pay attention to selection order when deciding whether
 300 to pay attention to a particular device.
 301 This may be the wrong behavior, and probably requires additional thought.
 302 .Pp
 303 .Fn selectdevs
 304 handles allocation and resizing of the
 305 .Va dev_select
 306 structure passed in
 307 by the client.
 308 .Fn selectdevs
 309 uses the
 310 .Va numdevs
 311 and
 312 .Va current_generation
 313 fields to track the
 314 current
 315 .Nm
 316 generation and number of devices.
 317 If
 318 .Va num_selections
 319 is not the same
 320 as
 321 .Va numdevs
 322 or if
 323 .Va select_generation
 324 is not the same as
 325 .Va current_generation ,
 326 .Fn selectdevs
 327 will resize the selection list as necessary, and re-initialize the
 328 selection array.
 329 .Pp
 330 .Fn buildmatch
 331 takes a comma separated match string and compiles it into a
 332 \fBdevstat_match\fR structure that is understood by
 333 .Fn selectdevs .
 334 Match strings have the following format:
 335 .Pp
 336 .Bd -literal -offset indent
 337 device,type,if
 338 .Ed
 339 .Pp
 340 .Fn buildmatch
 341 takes care of allocating and reallocating the match list as necessary.
 342 Currently known match types include:
 343 .Pp
 344 .Bl -tag -width indent -compact
 345 .It device type:
 346 .Bl -tag -width 9n -compact
 347 .It da
 348 Direct Access devices
 349 .It sa
 350 Sequential Access devices
 351 .It printer
 352 Printers
 353 .It proc
 354 Processor devices
 355 .It worm
 356 Write Once Read Multiple devices
 357 .It cd
 358 CD devices
 359 .It scanner
 360 Scanner devices
 361 .It optical
 362 Optical Memory devices
 363 .It changer
 364 Medium Changer devices
 365 .It comm
 366 Communication devices
 367 .It array
 368 Storage Array devices
 369 .It enclosure
 370 Enclosure Services devices
 371 .It floppy
 372 Floppy devices
 373 .El
 374 .Pp
 375 .It interface:
 376 .Bl -tag -width 9n -compact
 377 .It IDE
 378 Integrated Drive Electronics devices
 379 .It SCSI
 380 Small Computer System Interface devices
 381 .It other
 382 Any other device interface
 383 .El
 384 .Pp
 385 .It passthrough:
 386 .Bl -tag -width 9n -compact
 387 .It pass
 388 Passthrough devices
 389 .El
 390 .El
 391 .Pp
 392 .Fn compute_stats
 393 provides an easy way to obtain various device statistics.
 394 Only two arguments are mandatory:
 395 .Va current
 396 and
 397 .Va etime .
 398 Every other argument is optional.
 399 For most applications, the user will want to supply both
 400 .Va current
 401 and
 402 .Va previous
 403 devstat structures so that statistics may be calculated over a given period
 404 of time.
 405 In some instances, for instance when calculating statistics since system boot,
 406 the user may pass in a NULL pointer for the
 407 .Va previous
 408 argument.
 409 In that case,
 410 .Fn compute_stats
 411 will use the total stats in the
 412 .Va current
 413 structure to calculate statistics over
 414 .Va etime .
 415 The various statistics that may be calculated by
 416 .Fn compute_stats
 417 should be mostly explained by the function declaration itself, but for
 418 completeness here is a list of variable names and the statistics that will
 419 be put in them:
 420 .Bl -tag -width transfers_per_second
 421 .It total_bytes
 422 This is the total number of bytes transferred on the given device, both
 423 reads and writes, between the acquisition of
 424 .Va previous
 425 and the acquisition of
 426 .Va current .
 427 If
 428 .Va previous
 429 is NULL, the result will be the total reads and writes given in
 430 .Va current .
 431 .It total_transfers
 432 This is the total number of transfers completed between the
 433 acquisition of
 434 .Va previous
 435 and the acquisition of
 436 .Va current .
 437 If
 438 .Va previous
 439 is NULL, the result will be the total number of transactions listed in
 440 .Va current .
 441 .It total_blocks
 442 This is basically
 443 .Va total_bytes
 444 divided by the device blocksize.
 445 If the device blocksize is listed as
 446 .Sq 0 ,
 447 the device blocksize will default to 512 bytes.
 448 .It kb_per_transfer
 449 This is the average number of kilobytes per transfer during the measurement
 450 period.
 451 .It transfers_per_second
 452 This is the average number of transfers per second.
 453 .It mb_per_second
 454 This is average megabytes per second.
 455 .It blocks_per_second
 456 This is average blocks per second.
 457 If the device blocksize is
 458 .Sq 0 ,
 459 a default blocksize of 512 bytes will be used instead.
 460 .It ms_per_transaction
 461 The average number of milliseconds per transaction.
 462 .El
 463 .Pp
 464 .Fn compute_etime
 465 provides an easy way to find the difference in seconds between two
 466 .Va timeval
 467 structures.
 468 This is most commonly used in conjunction with the time recorded by the
 469 .Fn getdevs
 470 function (in struct
 471 .Va statinfo )
 472 each time it fetches the current
 473 .Nm
 474 list.
 475 .Sh RETURN VALUES
 476 .Fn getnumdevs ,
 477 .Fn getgeneration ,
 478 and
 479 .Fn getversion
 480 return the indicated \fBsysctl\fR variable, or -1 if there is an error
 481 fetching the variable.
 482 .Pp
 483 .Fn checkversion
 484 returns 0 if the kernel and userland
 485 .Nm
 486 versions match.
 487 If they do not match, it returns -1.
 488 .Pp
 489 .Fn getdevs
 490 and
 491 .Fn selectdevs
 492 return -1 in case of an error, 0 if there is no error and 1 if the device
 493 list or selected devices have changed.
 494 A return value of 1 from
 495 .Fn getdevs
 496 is usually a hint to re-run
 497 .Fn selectdevs
 498 because the device list has changed.
 499 .Pp
 500 .Fn buildmatch
 501 returns -1 for error, and 0 if there is no error.
 502 .Pp
 503 .Fn compute_stats
 504 returns -1 for error, and 0 for success.
 505 .Pp
 506 .Fn compute_etime
 507 returns the computed elapsed time.
 508 .Pp
 509 If an error is returned from one of the
 510 .Nm
 511 library functions, the reason for the error is generally printed in
 512 the global string
 513 .Va devstat_errbuf
 514 which is
 515 .Dv DEVSTAT_ERRBUF_SIZE
 516 characters long.
 517 .Sh SEE ALSO
 518 .Xr systat 1 ,
 519 .Xr iostat 8 ,
 520 .Xr rpc.rstatd 8 ,
 521 .Xr vmstat 8 ,
 522 .Xr devstat 9
 523 .Sh HISTORY
 524 The
 525 .Nm
 526 statistics system first appeared in
 527 .Fx 3.0 .
 528 .Sh AUTHORS
 529 .An Kenneth Merry Aq ken@FreeBSD.org
 530 .Sh BUGS
 531 There should probably be an interface to de-allocate memory allocated by
 532 .Fn getdevs ,
 533 .Fn selectdevs ,
 534 and
 535 .Fn buildmatch .
 536 .Pp
 537 .Fn selectdevs
 538 should probably not select more than
 539 .Va maxshowdevs
 540 devices in
 541 .Dq top
 542 mode when no devices have been selected previously.
 543 .Pp
 544 There should probably be functions to perform the statistics buffer
 545 swapping that goes on in most of the clients of this library.
 546 .Pp
 547 The
 548 .Va statinfo
 549 and
 550 .Va devinfo
 551 structures should probably be cleaned up and thought out a little more.