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