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