lib/libdevstat/devstat.3

   1 .\"
   2 .\" Copyright (c) 1998, 1999, 2001 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$
  29 .\"
  30 .Dd December 15, 2012
  31 .Dt DEVSTAT 3
  32 .Os
  33 .Sh NAME
  34 .Nm devstat ,
  35 .Nm devstat_getnumdevs ,
  36 .Nm devstat_getgeneration ,
  37 .Nm devstat_getversion ,
  38 .Nm devstat_checkversion ,
  39 .Nm devstat_getdevs ,
  40 .Nm devstat_selectdevs ,
  41 .Nm devstat_buildmatch ,
  42 .Nm devstat_compute_statistics ,
  43 .Nm devstat_compute_etime
  44 .Nd device statistics utility library
  45 .Sh LIBRARY
  46 .Lb libdevstat
  47 .Sh SYNOPSIS
  48 .In devstat.h
  49 .Ft int
  50 .Fn devstat_getnumdevs "kvm_t *kd"
  51 .Ft long
  52 .Fn devstat_getgeneration "kvm_t *kd"
  53 .Ft int
  54 .Fn devstat_getversion "kvm_t *kd"
  55 .Ft int
  56 .Fn devstat_checkversion "kvm_t *kd"
  57 .Ft int
  58 .Fn devstat_getdevs "kvm_t *kd" "struct statinfo *stats"
  59 .Ft int
  60 .Fo devstat_selectdevs
  61 .Fa "struct device_selection **dev_select"
  62 .Fa "int *num_selected"
  63 .Fa "int *num_selections"
  64 .Fa "long *select_generation"
  65 .Fa "long current_generation"
  66 .Fa "struct devstat *devices"
  67 .Fa "int numdevs"
  68 .Fa "struct devstat_match *matches"
  69 .Fa "int num_matches"
  70 .Fa "char **dev_selections"
  71 .Fa "int num_dev_selections"
  72 .Fa "devstat_select_mode select_mode"
  73 .Fa "int maxshowdevs"
  74 .Fa "int perf_select"
  75 .Fc
  76 .Ft int
  77 .Fo devstat_buildmatch
  78 .Fa "char *match_str"
  79 .Fa "struct devstat_match **matches"
  80 .Fa "int *num_matches"
  81 .Fc
  82 .Ft int
  83 .Fo devstat_compute_statistics
  84 .Fa "struct devstat *current"
  85 .Fa "struct devstat *previous"
  86 .Fa "long double etime"
  87 .Fa "..."
  88 .Fc
  89 .Ft "long double"
  90 .Fo devstat_compute_etime
  91 .Fa "struct bintime *cur_time"
  92 .Fa "struct bintime *prev_time"
  93 .Fc
  94 .Sh DESCRIPTION
  95 The
  96 .Nm
  97 library is a library of helper functions for dealing with the kernel
  98 .Xr devstat 9
  99 interface, which is accessible to users via
 100 .Xr sysctl 3
 101 and
 102 .Xr kvm 3 .
 103 All functions that take a
 104 .Vt "kvm_t *"
 105 as first argument can be passed
 106 .Dv NULL
 107 instead of a kvm handle as this argument,
 108 which causes the data to be read via
 109 .Xr sysctl 3 .
 110 Otherwise, it is read via
 111 .Xr kvm 3
 112 using the supplied handle.
 113 The
 114 .Fn devstat_checkversion
 115 function
 116 should be called with each kvm handle that is going to be used (or with
 117 .Dv NULL
 118 if
 119 .Xr sysctl 3
 120 is going to be used).
 121 .Pp
 122 The
 123 .Fn devstat_getnumdevs
 124 function
 125 returns the number of devices registered with the
 126 .Nm
 127 subsystem in the kernel.
 128 .Pp
 129 The
 130 .Fn devstat_getgeneration
 131 function
 132 returns the current generation of the
 133 .Nm
 134 list of devices in the kernel.
 135 .Pp
 136 The
 137 .Fn devstat_getversion
 138 function
 139 returns the current kernel
 140 .Nm
 141 version.
 142 .Pp
 143 The
 144 .Fn devstat_checkversion
 145 function
 146 checks the userland
 147 .Nm
 148 version against the kernel
 149 .Nm
 150 version.
 151 If the two are identical, it returns zero.
 152 Otherwise, it prints an appropriate error in
 153 .Va devstat_errbuf
 154 and returns \-1.
 155 .Pp
 156 The
 157 .Fn devstat_getdevs
 158 function
 159 fetches the current list of devices and statistics into the supplied
 160 .Vt statinfo
 161 structure.
 162 The
 163 .Vt statinfo
 164 structure can be found in
 165 .In devstat.h :
 166 .Bd -literal -offset indent
 167 struct statinfo {
 168         long            cp_time[CPUSTATES];
 169         long            tk_nin;
 170         long            tk_nout;
 171         struct devinfo  *dinfo;
 172         long double     snap_time;
 173 };
 174 .Ed
 175 .Pp
 176 The
 177 .Fn devstat_getdevs
 178 function
 179 expects the
 180 .Vt statinfo
 181 structure to be allocated, and it also expects the
 182 .Va dinfo
 183 subelement to be allocated and zeroed prior to the first invocation of
 184 .Fn devstat_getdevs .
 185 The
 186 .Va dinfo
 187 subelement is used to store state between calls, and should not be modified
 188 after the first call to
 189 .Fn devstat_getdevs .
 190 The
 191 .Va dinfo
 192 subelement contains the following elements:
 193 .Bd -literal -offset indent
 194 struct devinfo {
 195         struct devstat  *devices;
 196         uint8_t         *mem_ptr;
 197         long            generation;
 198         int             numdevs;
 199 };
 200 .Ed
 201 .Pp
 202 The
 203 .Va kern.devstat.all
 204 .Xr sysctl 8
 205 variable contains an array of
 206 .Nm
 207 structures, but at the head of the array is the current
 208 .Nm
 209 generation.
 210 The reason the generation is at the head of the buffer is so that userland
 211 software accessing the
 212 .Nm
 213 statistics information can atomically get
 214 both the statistics information and the corresponding generation number.
 215 If client software were forced to get the generation number via a separate
 216 .Xr sysctl 8
 217 variable (which is available for convenience), the list of devices could
 218 change between the time the client gets the generation and the time the
 219 client gets the device list.
 220 .Pp
 221 The
 222 .Va mem_ptr
 223 subelement of the
 224 .Vt devinfo
 225 structure is a pointer to memory that is allocated, and resized if
 226 necessary, by
 227 .Fn devstat_getdevs .
 228 The devices subelement of the
 229 .Vt devinfo
 230 structure is basically a pointer to the beginning of the array of devstat
 231 structures from the
 232 .Va kern.devstat.all
 233 .Xr sysctl 8
 234 variable (or the corresponding values read via
 235 .Xr kvm 3 ) .
 236 The generation subelement of the
 237 .Vt devinfo
 238 structure contains the corresponding generation number.
 239 The
 240 .Va numdevs
 241 subelement of the
 242 .Vt devinfo
 243 structure contains the current
 244 number of devices registered with the kernel
 245 .Nm
 246 subsystem.
 247 .Pp
 248 The
 249 .Fn devstat_selectdevs
 250 function
 251 selects devices to display based upon a number of criteria:
 252 .Bl -tag -width indent
 253 .It specified devices
 254 Specified devices are the first selection priority.
 255 These are generally devices specified by name by the user e.g.\&
 256 .Li da0 , da1 , cd0 .
 257 .It match patterns
 258 These are pattern matching expressions generated by
 259 .Fn devstat_buildmatch
 260 from user input.
 261 .It performance
 262 If performance mode is enabled, devices will be sorted based on the
 263 .Va bytes
 264 field in the
 265 .Vt device_selection
 266 structure passed in to
 267 .Fn devstat_selectdevs .
 268 The
 269 .Va bytes
 270 value currently must be maintained by the user.
 271 In the future, this may be done for him in a
 272 .Nm
 273 library routine.
 274 If no devices have been selected by name or by pattern, the performance
 275 tracking code will select every device in the system, and sort them by
 276 performance.
 277 If devices have been selected by name or pattern, the performance tracking
 278 code will honor those selections and will only sort among the selected
 279 devices.
 280 .It order in the devstat list
 281 If the selection mode is set to
 282 .Dv DS_SELECT_ADD ,
 283 and if there are still less
 284 than
 285 .Fa maxshowdevs
 286 devices selected,
 287 .Fn devstat_selectdevs
 288 will automatically select up to
 289 .Fa maxshowdevs
 290 devices.
 291 .El
 292 .Pp
 293 The
 294 .Fn devstat_selectdevs
 295 function
 296 performs selections in four different modes:
 297 .Bl -tag -width ".Dv DS_SELECT_ADDONLY"
 298 .It Dv DS_SELECT_ADD
 299 In
 300 .Dq add
 301 mode,
 302 .Fn devstat_selectdevs
 303 will select any unselected devices specified by name or matching pattern.
 304 It will also select more devices, in devstat list order, until the number
 305 of selected devices is equal to
 306 .Fa maxshowdevs
 307 or until all devices are
 308 selected.
 309 .It Dv DS_SELECT_ONLY
 310 In
 311 .Dq only
 312 mode,
 313 .Fn devstat_selectdevs
 314 will clear all current selections, and will only select devices specified
 315 by name or by matching pattern.
 316 .It Dv DS_SELECT_REMOVE
 317 In
 318 .Dq remove
 319 mode,
 320 .Fn devstat_selectdevs
 321 will remove devices specified by name or by matching pattern.
 322 It will not select any additional devices.
 323 .It Dv DS_SELECT_ADDONLY
 324 In
 325 .Dq "add only"
 326 mode,
 327 .Fn devstat_selectdevs
 328 will select any unselected devices specified by name or matching pattern.
 329 In this respect it is identical to
 330 .Dq add
 331 mode.
 332 It will not, however, select any devices other than those specified.
 333 .El
 334 .Pp
 335 In all selection modes,
 336 .Fn devstat_selectdevs
 337 will not select any more than
 338 .Fa maxshowdevs
 339 devices.
 340 One exception to this is when you are in
 341 .Dq top
 342 mode and no devices have been selected.
 343 In this case,
 344 .Fn devstat_selectdevs
 345 will select every device in the system.
 346 Client programs must pay attention to selection order when deciding whether
 347 to pay attention to a particular device.
 348 This may be the wrong behavior, and probably requires additional thought.
 349 .Pp
 350 The
 351 .Fn devstat_selectdevs
 352 function
 353 handles allocation and resizing of the
 354 .Fa dev_select
 355 structure passed in
 356 by the client.
 357 The
 358 .Fn devstat_selectdevs
 359 function
 360 uses the
 361 .Fa numdevs
 362 and
 363 .Fa current_generation
 364 fields to track the
 365 current
 366 .Nm
 367 generation and number of devices.
 368 If
 369 .Fa num_selections
 370 is not the same
 371 as
 372 .Fa numdevs
 373 or if
 374 .Fa select_generation
 375 is not the same as
 376 .Fa current_generation ,
 377 .Fn devstat_selectdevs
 378 will resize the selection list as necessary, and re-initialize the
 379 selection array.
 380 .Pp
 381 The
 382 .Fn devstat_buildmatch
 383 function
 384 takes a comma separated match string and compiles it into a
 385 .Vt devstat_match
 386 structure that is understood by
 387 .Fn devstat_selectdevs .
 388 Match strings have the following format:
 389 .Pp
 390 .D1 Ar device , Ns Ar type , Ns Ar if
 391 .Pp
 392 The
 393 .Fn devstat_buildmatch
 394 function
 395 takes care of allocating and reallocating the match list as necessary.
 396 Currently known match types include:
 397 .Bl -tag -width indent
 398 .It device type:
 399 .Bl -tag -width ".Li enclosure" -compact
 400 .It Li da
 401 Direct Access devices
 402 .It Li sa
 403 Sequential Access devices
 404 .It Li printer
 405 Printers
 406 .It Li proc
 407 Processor devices
 408 .It Li worm
 409 Write Once Read Multiple devices
 410 .It Li cd
 411 CD devices
 412 .It Li scanner
 413 Scanner devices
 414 .It Li optical
 415 Optical Memory devices
 416 .It Li changer
 417 Medium Changer devices
 418 .It Li comm
 419 Communication devices
 420 .It Li array
 421 Storage Array devices
 422 .It Li enclosure
 423 Enclosure Services devices
 424 .It Li floppy
 425 Floppy devices
 426 .El
 427 .It interface:
 428 .Bl -tag -width ".Li enclosure" -compact
 429 .It Li IDE
 430 Integrated Drive Electronics devices
 431 .It Li SCSI
 432 Small Computer System Interface devices
 433 .It Li other
 434 Any other device interface
 435 .El
 436 .It passthrough:
 437 .Bl -tag -width ".Li enclosure" -compact
 438 .It Li pass
 439 Passthrough devices
 440 .El
 441 .El
 442 .Pp
 443 The
 444 .Fn devstat_compute_statistics
 445 function provides complete statistics calculation.
 446 There are four arguments for which values
 447 .Em must
 448 be supplied:
 449 .Fa current ,
 450 .Fa previous ,
 451 .Fa etime ,
 452 and the terminating argument for the varargs list,
 453 .Dv DSM_NONE .
 454 For most applications, the user will want to supply valid
 455 .Vt devstat
 456 structures for both
 457 .Fa current
 458 and
 459 .Fa previous .
 460 In some instances, for instance when calculating statistics since system
 461 boot, the user may pass in a
 462 .Dv NULL
 463 pointer for the
 464 .Fa previous
 465 argument.
 466 In that case,
 467 .Fn devstat_compute_statistics
 468 will use the total stats in the
 469 .Fa current
 470 structure to calculate statistics over
 471 .Fa etime .
 472 For each statistics to be calculated, the user should supply the proper
 473 enumerated type (listed below), and a variable of the indicated type.
 474 All statistics are either integer values, for which a
 475 .Vt uint64_t
 476 is used,
 477 or floating point, for which a
 478 .Vt "long double"
 479 is used.
 480 The statistics that may be calculated are:
 481 .Bl -tag -width ".Dv DSM_TRANSFERS_PER_SECOND_OTHER"
 482 .It Dv DSM_NONE
 483 type: N/A
 484 .Pp
 485 This
 486 .Em must
 487 be the last argument passed to
 488 .Fn devstat_compute_statistics .
 489 It is an argument list terminator.
 490 .It Dv DSM_TOTAL_BYTES
 491 type:
 492 .Vt "uint64_t *"
 493 .Pp
 494 The total number of bytes transferred between the acquisition of
 495 .Fa previous
 496 and
 497 .Fa current .
 498 .It Dv DSM_TOTAL_BYTES_READ
 499 .It Dv DSM_TOTAL_BYTES_WRITE
 500 .It Dv DSM_TOTAL_BYTES_FREE
 501 type:
 502 .Vt "uint64_t *"
 503 .Pp
 504 The total number of bytes in transactions of the specified type
 505 between the acquisition of
 506 .Fa previous
 507 and
 508 .Fa current .
 509 .It Dv DSM_TOTAL_TRANSFERS
 510 type:
 511 .Vt "uint64_t *"
 512 .Pp
 513 The total number of transfers between the acquisition of
 514 .Fa previous
 515 and
 516 .Fa current .
 517 .It Dv DSM_TOTAL_TRANSFERS_OTHER
 518 .It Dv DSM_TOTAL_TRANSFERS_READ
 519 .It Dv DSM_TOTAL_TRANSFERS_WRITE
 520 .It Dv DSM_TOTAL_TRANSFERS_FREE
 521 type:
 522 .Vt "uint64_t *"
 523 .Pp
 524 The total number of transactions of the specified type between
 525 the acquisition of
 526 .Fa previous
 527 and
 528 .Fa current .
 529 .It Dv DSM_TOTAL_DURATION
 530 type:
 531 .Vt "long double *"
 532 .Pp
 533 The total duration of transactions, in seconds, between the acquisition of
 534 .Fa previous
 535 and
 536 .Fa current .
 537 .It Dv DSM_TOTAL_DURATION_OTHER
 538 .It Dv DSM_TOTAL_DURATION_READ
 539 .It Dv DSM_TOTAL_DURATION_WRITE
 540 .It Dv DSM_TOTAL_DURATION_FREE
 541 type:
 542 .Vt "long double *"
 543 .Pp
 544 The total duration of transactions of the specified type between
 545 the acquisition of
 546 .Fa previous
 547 and
 548 .Fa current .
 549 .It Dv DSM_TOTAL_BUSY_TIME
 550 type:
 551 .Vt "long double *"
 552 .Pp
 553 Total time the device had one or more transactions outstanding
 554 between the acquisition of
 555 .Fa previous
 556 and
 557 .Fa current .
 558 .It Dv DSM_TOTAL_BLOCKS
 559 type:
 560 .Vt "uint64_t *"
 561 .Pp
 562 The total number of blocks transferred between the acquisition of
 563 .Fa previous
 564 and
 565 .Fa current .
 566 This number is in terms of the blocksize reported by the device.
 567 If no blocksize has been reported (i.e., the block size is 0), a default
 568 blocksize of 512 bytes will be used in the calculation.
 569 .It Dv DSM_TOTAL_BLOCKS_READ
 570 .It Dv DSM_TOTAL_BLOCKS_WRITE
 571 .It Dv DSM_TOTAL_BLOCKS_FREE
 572 type:
 573 .Vt "uint64_t *"
 574 .Pp
 575 The total number of blocks of the specified type between the acquisition of
 576 .Fa previous
 577 and
 578 .Fa current .
 579 This number is in terms of the blocksize reported by the device.
 580 If no blocksize has been reported (i.e., the block size is 0), a default
 581 blocksize of 512 bytes will be used in the calculation.
 582 .It Dv DSM_KB_PER_TRANSFER
 583 type:
 584 .Vt "long double *"
 585 .Pp
 586 The average number of kilobytes per transfer between the acquisition of
 587 .Fa previous
 588 and
 589 .Fa current .
 590 .It Dv DSM_KB_PER_TRANSFER_READ
 591 .It Dv DSM_KB_PER_TRANSFER_WRITE
 592 .It Dv DSM_KB_PER_TRANSFER_FREE
 593 type:
 594 .Vt "long double *"
 595 .Pp
 596 The average number of kilobytes in the specified type transaction between
 597 the acquisition of
 598 .Fa previous
 599 and
 600 .Fa current .
 601 .It Dv DSM_TRANSFERS_PER_SECOND
 602 type:
 603 .Vt "long double *"
 604 .Pp
 605 The average number of transfers per second between the acquisition of
 606 .Fa previous
 607 and
 608 .Fa current .
 609 .It Dv DSM_TRANSFERS_PER_SECOND_OTHER
 610 .It Dv DSM_TRANSFERS_PER_SECOND_READ
 611 .It Dv DSM_TRANSFERS_PER_SECOND_WRITE
 612 .It Dv DSM_TRANSFERS_PER_SECOND_FREE
 613 type:
 614 .Vt "long double *"
 615 .Pp
 616 The average number of transactions of the specified type per second
 617 between the acquisition of
 618 .Fa previous
 619 and
 620 .Fa current .
 621 .It Dv DSM_MB_PER_SECOND
 622 type:
 623 .Vt "long double *"
 624 .Pp
 625 The average number of megabytes transferred per second between the
 626 acquisition of
 627 .Fa previous
 628 and
 629 .Fa current .
 630 .It Dv DSM_MB_PER_SECOND_READ
 631 .It Dv DSM_MB_PER_SECOND_WRITE
 632 .It Dv DSM_MB_PER_SECOND_FREE
 633 type:
 634 .Vt "long double *"
 635 .Pp
 636 The average number of megabytes per second in the specified type of
 637 transaction between the acquisition of
 638 .Fa previous
 639 and
 640 .Fa current .
 641 .It Dv DSM_BLOCKS_PER_SECOND
 642 type:
 643 .Vt "long double *"
 644 .Pp
 645 The average number of blocks transferred per second between the acquisition of
 646 .Fa previous
 647 and
 648 .Fa current .
 649 This number is in terms of the blocksize reported by the device.
 650 If no blocksize has been reported (i.e., the block size is 0), a default
 651 blocksize of 512 bytes will be used in the calculation.
 652 .It Dv DSM_BLOCKS_PER_SECOND_READ
 653 .It Dv DSM_BLOCKS_PER_SECOND_WRITE
 654 .It Dv DSM_BLOCKS_PER_SECOND_FREE
 655 type:
 656 .Vt "long double *"
 657 .Pp
 658 The average number of blocks per second in the specified type of transaction
 659 between the acquisition of
 660 .Fa previous
 661 and
 662 .Fa current .
 663 This number is in terms of the blocksize reported by the device.
 664 If no blocksize has been reported (i.e., the block size is 0), a default
 665 blocksize of 512 bytes will be used in the calculation.
 666 .It Dv DSM_MS_PER_TRANSACTION
 667 type:
 668 .Vt "long double *"
 669 .Pp
 670 The average duration of transactions between the acquisition of
 671 .Fa previous
 672 and
 673 .Fa current .
 674 .It Dv DSM_MS_PER_TRANSACTION_OTHER
 675 .It Dv DSM_MS_PER_TRANSACTION_READ
 676 .It Dv DSM_MS_PER_TRANSACTION_WRITE
 677 .It Dv DSM_MS_PER_TRANSACTION_FREE
 678 type:
 679 .Vt "long double *"
 680 .Pp
 681 The average duration of transactions of the specified type between the
 682 acquisition of
 683 .Fa previous
 684 and
 685 .Fa current .
 686 .It Dv DSM_BUSY_PCT
 687 type:
 688 .Vt "long double *"
 689 .Pp
 690 The percentage of time the device had one or more transactions outstanding
 691 between the acquisition of
 692 .Fa previous
 693 and
 694 .Fa current .
 695 .It Dv DSM_QUEUE_LENGTH
 696 type:
 697 .Vt "uint64_t *"
 698 .Pp
 699 The number of not yet completed transactions at the time when
 700 .Fa current
 701 was acquired.
 702 .It Dv DSM_SKIP
 703 type: N/A
 704 .Pp
 705 If you do not need a result from
 706 .Fn devstat_compute_statistics ,
 707 just put
 708 .Dv DSM_SKIP
 709 as first (type) parameter and
 710 .Dv NULL
 711 as second parameter.
 712 This can be useful in scenarios where the statistics to be calculated
 713 are determined at run time.
 714 .El
 715 .Pp
 716 The
 717 .Fn devstat_compute_etime
 718 function
 719 provides an easy way to find the difference in seconds between two
 720 .Vt bintime
 721 structures.
 722 This is most commonly used in conjunction with the time recorded by the
 723 .Fn devstat_getdevs
 724 function (in
 725 .Vt "struct statinfo" )
 726 each time it fetches the current
 727 .Nm
 728 list.
 729 .Sh RETURN VALUES
 730 The
 731 .Fn devstat_getnumdevs ,
 732 .Fn devstat_getgeneration ,
 733 and
 734 .Fn devstat_getversion
 735 function
 736 return the indicated sysctl variable, or \-1 if there is an error
 737 fetching the variable.
 738 .Pp
 739 The
 740 .Fn devstat_checkversion
 741 function
 742 returns 0 if the kernel and userland
 743 .Nm
 744 versions match.
 745 If they do not match, it returns \-1.
 746 .Pp
 747 The
 748 .Fn devstat_getdevs
 749 and
 750 .Fn devstat_selectdevs
 751 functions
 752 return \-1 in case of an error, 0 if there is no error, and 1 if the device
 753 list or selected devices have changed.
 754 A return value of 1 from
 755 .Fn devstat_getdevs
 756 is usually a hint to re-run
 757 .Fn devstat_selectdevs
 758 because the device list has changed.
 759 .Pp
 760 The
 761 .Fn devstat_buildmatch
 762 function returns \-1 for error, and 0 if there is no error.
 763 .Pp
 764 The
 765 .Fn devstat_compute_etime
 766 function
 767 returns the computed elapsed time.
 768 .Pp
 769 The
 770 .Fn devstat_compute_statistics
 771 function returns \-1 for error, and 0 for success.
 772 .Pp
 773 If an error is returned from one of the
 774 .Nm
 775 library functions, the reason for the error is generally printed in
 776 the global string
 777 .Va devstat_errbuf
 778 which is
 779 .Dv DEVSTAT_ERRBUF_SIZE
 780 characters long.
 781 .Sh SEE ALSO
 782 .Xr systat 1 ,
 783 .Xr kvm 3 ,
 784 .Xr sysctl 3 ,
 785 .Xr iostat 8 ,
 786 .Xr rpc.rstatd 8 ,
 787 .Xr sysctl 8 ,
 788 .Xr vmstat 8 ,
 789 .Xr devstat 9
 790 .Sh HISTORY
 791 The
 792 .Nm
 793 statistics system first appeared in
 794 .Fx 3.0 .
 795 The new interface (the functions prefixed with
 796 .Li devstat_ )
 797 first appeared in
 798 .Fx 5.0 .
 799 .Sh AUTHORS
 800 .An Kenneth Merry Aq ken@FreeBSD.org
 801 .Sh BUGS
 802 There should probably be an interface to de-allocate memory allocated by
 803 .Fn devstat_getdevs ,
 804 .Fn devstat_selectdevs ,
 805 and
 806 .Fn devstat_buildmatch .
 807 .Pp
 808 The
 809 .Fn devstat_selectdevs
 810 function
 811 should probably not select more than
 812 .Fa maxshowdevs
 813 devices in
 814 .Dq top
 815 mode when no devices have been selected previously.
 816 .Pp
 817 There should probably be functions to perform the statistics buffer
 818 swapping that goes on in most of the clients of this library.
 819 .Pp
 820 The
 821 .Vt statinfo
 822 and
 823 .Vt devinfo
 824 structures should probably be cleaned up and thought out a little more.