devstat.3 (79754) | devstat.3 (81133) |
---|---|
1.\" | 1.\" |
2.\" Copyright (c) 1998, 1999 Kenneth D. Merry. | 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 --- 9 unchanged lines hidden (view full) --- 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.\" | 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 --- 9 unchanged lines hidden (view full) --- 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: head/lib/libdevstat/devstat.3 79754 2001-07-15 07:53:42Z dd $ | 28.\" $FreeBSD: head/lib/libdevstat/devstat.3 81133 2001-08-04 18:25:48Z tmm $ |
29.\" | 29.\" |
30.Dd May 21, 1998 | 30.Dd July 15, 2001 |
31.Dt DEVSTAT 3 32.Os 33.Sh NAME 34.Nm devstat , | 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 , |
|
35.Nm getnumdevs , 36.Nm getgeneration , 37.Nm getversion , 38.Nm checkversion , 39.Nm getdevs , 40.Nm selectdevs , 41.Nm buildmatch , 42.Nm compute_stats , 43.Nm compute_etime 44.Nd device statistics utility library 45.Sh LIBRARY 46.Lb libdevstat 47.Sh SYNOPSIS 48.Fd #include <sys/dkstat.h> 49.Fd #include <devstat.h> 50.Ft int | 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.Fd #include <sys/dkstat.h> 58.Fd #include <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 |
|
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 --- 41 unchanged lines hidden (view full) --- 100.Fa "struct timeval prev_time" 101.Fc 102.Sh DESCRIPTION 103The 104.Nm 105library is a library of helper functions for dealing with the kernel 106.Xr devstat 9 107interface, which is accessible to users via | 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 --- 41 unchanged lines hidden (view full) --- 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 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 |
|
108.Xr sysctl 3 . | 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). |
|
109.Pp | 192.Pp |
110.Fn getnumdevs | 193.Fn devstat_getnumdevs |
111returns the number of devices registered with the 112.Nm 113subsystem in the kernel. 114.Pp | 194returns the number of devices registered with the 195.Nm 196subsystem in the kernel. 197.Pp |
115.Fn getgeneration | 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 |
116returns the current generation of the 117.Nm 118list of devices in the kernel. 119.Pp | 205returns the current generation of the 206.Nm 207list of devices in the kernel. 208.Pp |
120.Fn getversion | 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 |
121returns the current kernel 122.Nm 123version. 124.Pp | 216returns the current kernel 217.Nm 218version. 219.Pp |
125.Fn checkversion 126checks the userland devstat version against the kernel devstat version. If 127the two are identical, it returns zero. Otherwise, it prints an 128appropriate error in | 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 |
129.Va devstat_errbuf 130and returns -1. 131.Pp | 230.Va devstat_errbuf 231and returns -1. 232.Pp |
132.Fn getdevs | 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 |
133fetches the current list of devices and statistics into the supplied 134.Va statinfo | 240fetches the current list of devices and statistics into the supplied 241.Va statinfo |
135structure. The | 242structure. 243The |
136.Va statinfo 137structure can be found in 138.Aq Pa devstat.h : 139.Bd -literal -offset indent 140struct statinfo { 141 long cp_time[CPUSTATES]; 142 long tk_nin; 143 long tk_nout; 144 struct devinfo *dinfo; 145 struct timeval busy_time; 146}; 147.Ed 148.Pp | 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 |
149.Fn getdevs | 257.Fn devstat_getdevs |
150expects the 151.Va statinfo 152structure to be allocated, and it also expects the 153.Va dinfo 154subelement to be allocated and zeroed prior to the first invocation of | 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 |
155.Fn getdevs . | 263.Fn devstat_getdevs . |
156The 157.Va dinfo 158subelement is used to store state between calls, and should not be modified 159after the first call to | 264The 265.Va dinfo 266subelement is used to store state between calls, and should not be modified 267after the first call to |
160.Fn getdevs . | 268.Fn devstat_getdevs . |
161The 162.Va dinfo 163subelement contains the following elements: 164.Bd -literal -offset indent 165struct devinfo { 166 struct devstat *devices; 167 u_int8_t *mem_ptr; 168 long generation; 169 int numdevs; 170}; 171.Ed 172.Pp 173The 174.Va kern.devstat.all 175.Nm sysctl 176variable contains an array of 177.Nm 178structures, but at the head of the array is the current 179.Nm | 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 |
180generation. The reason the generation is at the head of the buffer is so 181that userland software accessing the devstat statistics information can 182atomically get both the statistics information and the corresponding 183generation number. If client software were forced to get the generation 184number via a separate | 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 |
185.Nm sysctl 186variable (which is available for convenience), the list of devices could 187change between the time the client gets the generation and the time the 188client gets the device list. 189.Pp 190The 191.Va mem_ptr 192subelement of the 193.Va devinfo 194structure is a pointer to memory that is allocated, and resized if 195necessary, by | 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 |
196.Fn getdevs . | 304.Fn devstat_getdevs . |
197The devices subelement of the 198.Va devinfo 199structure is basically a pointer to the beginning of the array of devstat 200structures from the 201.Va kern.devstat.all 202.Nm sysctl | 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 |
203variable. The generation subelement of the | 311variable (or the corresponding values read via 312.Xr kvm 3 ) . 313The generation subelement of the |
204.Va devinfo | 314.Va devinfo |
205structure contains the generation number from the 206.Va kern.devstat.all 207.Nm sysctl 208variable. | 315structure contains the corresponding generation number. |
209The 210.Va numdevs 211subelement of the 212.Va devinfo 213structure contains the current 214number of devices registered with the kernel 215.Nm 216subsystem. 217.Pp | 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 |
218.Fn selectdevs | 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 |
219selects devices to display based upon a number of criteria: 220.Bl -tag -width flag 221.It specified devices | 332selects devices to display based upon a number of criteria: 333.Bl -tag -width flag 334.It specified devices |
222Specified devices are the first selection priority. These are generally 223devices specified by name by the user. e.g. da0, da1, cd0. | 335Specified devices are the first selection priority. 336These are generally devices specified by name by the user e.g. da0, da1, cd0. |
224.It match patterns 225These are pattern matching expressions generated by | 337.It match patterns 338These are pattern matching expressions generated by |
226.Fn buildmatch | 339.Fn devstat_buildmatch |
227from user input. 228.It performance 229If performance mode is enabled, devices will be sorted based on the 230.Va bytes 231field in the 232.Va device_selection 233structure passed in to | 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 |
234.Fn selectdevs . | 347.Fn devstat_selectdevs . |
235The 236.Va bytes | 348The 349.Va bytes |
237value currently must be maintained by the user. In the future, 238this may be done for him in a | 350value currently must be maintained by the user. 351In the future, this may be done for him in a |
239.Nm 240library routine. 241If no devices have been selected by name or by pattern, the performance 242tracking code will select every device in the system, and sort them by | 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 |
243performance. If devices have been selected by name or pattern, the 244performance tracking code will honor those selections and will only sort 245among the selected devices. | 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. |
246.It order in the devstat list 247If the selection mode is set to DS_SELECT_ADD, and if there are still less 248than 249.Va maxshowdevs 250devices selected, | 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, |
251.Fn selectdevs | 365.Fn devstat_selectdevs |
252will automatically select up to 253.Va maxshowdevs 254devices. 255.El 256.Pp | 366will automatically select up to 367.Va maxshowdevs 368devices. 369.El 370.Pp |
257.Fn selectdevs | 371.Fn devstat_selectdevs |
258performs selections in four different modes: 259.Bl -tag -width DS_SELECT_ADDONLY 260.It DS_SELECT_ADD 261In add mode, | 372performs selections in four different modes: 373.Bl -tag -width DS_SELECT_ADDONLY 374.It DS_SELECT_ADD 375In add mode, |
262.Fn selectdevs | 376.Fn devstat_selectdevs |
263will select any unselected devices specified by name or matching pattern. 264It will also select more devices, in devstat list order, until the number 265of selected devices is equal to 266.Va maxshowdevs 267or until all devices are 268selected. 269.It DS_SELECT_ONLY 270In only mode, | 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, |
271.Fn selectdevs | 385.Fn devstat_selectdevs |
272will clear all current selections, and will only select devices specified 273by name or by matching pattern. 274.It DS_SELECT_REMOVE 275In remove mode, | 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, |
276.Fn selectdevs 277will remove devices specified by name or by matching pattern. It will not 278select any additional devices. | 390.Fn devstat_selectdevs 391will remove devices specified by name or by matching pattern. 392It will not select any additional devices. |
279.It DS_SELECT_ADDONLY 280In add only mode, | 393.It DS_SELECT_ADDONLY 394In add only mode, |
281.Fn selectdevs | 395.Fn devstat_selectdevs |
282will select any unselected devices specified by name or matching pattern. | 396will select any unselected devices specified by name or matching pattern. |
283In this respect it is identical to add mode. It will not, however, select 284any devices other than those specified. | 397In this respect it is identical to add mode. 398It will not, however, select any devices other than those specified. |
285.El 286.Pp 287In all selection modes, | 399.El 400.Pp 401In all selection modes, |
288.Fn selectdevs | 402.Fn devstat_selectdevs |
289will not select any more than 290.Va maxshowdevs | 403will not select any more than 404.Va maxshowdevs |
291devices. One exception to 292this is when you are in | 405devices. 406One exception to this is when you are in |
293.Dq top | 407.Dq top |
294mode and no devices have been selected. In 295this case, 296.Fn selectdevs 297will select every device in the system. Client programs must pay attention 298to selection order when deciding whether to pay attention to a particular 299device. This may be the wrong behavior, and probably requires additional 300thought. | 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. |
301.Pp | 415.Pp |
302.Fn selectdevs | 416.Fn devstat_selectdevs |
303handles allocation and resizing of the 304.Va dev_select 305structure passed in 306by the client. | 417handles allocation and resizing of the 418.Va dev_select 419structure passed in 420by the client. |
307.Fn selectdevs | 421.Fn devstat_selectdevs |
308uses the 309.Va numdevs 310and 311.Va current_generation 312fields to track the 313current 314.Nm | 422uses the 423.Va numdevs 424and 425.Va current_generation 426fields to track the 427current 428.Nm |
315generation and number of devices. If | 429generation and number of devices. 430If |
316.Va num_selections 317is not the same 318as 319.Va numdevs 320or if 321.Va select_generation 322is not the same as 323.Va current_generation , | 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 , |
324.Fn selectdevs | 439.Fn devstat_selectdevs |
325will resize the selection list as necessary, and re-initialize the 326selection array. 327.Pp | 440will resize the selection list as necessary, and re-initialize the 441selection array. 442.Pp |
328.Fn buildmatch 329takes a comma separated match string and compiles it into a | 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 |
330\fBdevstat_match\fR structure that is understood by 331.Fn selectdevs . 332Match strings have the following format: 333.Pp 334.Bd -literal -offset indent 335device,type,if 336.Ed 337.Pp | 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 |
338.Fn buildmatch | 458.Fn devstat_buildmatch |
339takes care of allocating and reallocating the match list as necessary. 340Currently known match types include: 341.Pp 342.Bl -tag -width indent -compact 343.It device type: 344.Bl -tag -width 9n -compact 345.It da 346Direct Access devices --- 35 unchanged lines hidden (view full) --- 382.Pp 383.It passthrough: 384.Bl -tag -width 9n -compact 385.It pass 386Passthrough devices 387.El 388.El 389.Pp | 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 --- 35 unchanged lines hidden (view full) --- 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 |
|
390.Fn compute_stats | 517.Fn compute_stats |
391provides an easy way to obtain various device statistics. Only two 392arguments are mandatory: | 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 |
393.Va current 394and | 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 |
|
395.Va etime . | 539.Va etime . |
396Every other argument is optional. For most applications, the user will 397want to supply both | 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.El 766.Pp 767.Fn compute_stats 768is deprecated; use 769.Fn devstat_compute_statistics 770instead. 771.Fn compute_stats 772provides an easy way to obtain various device statistics. 773Only two arguments are mandatory: |
398.Va current 399and | 774.Va current 775and |
776.Va etime . 777Every other argument is optional. 778For most applications, the user will want to supply both 779.Va current 780and |
|
400.Va previous 401devstat structures so that statistics may be calculated over a given period | 781.Va previous 782devstat structures so that statistics may be calculated over a given period |
402of time. In some instances, for instance when calculating statistics since 403system boot, the user may pass in a NULL pointer for the | 783of time. 784In some instances, for instance when calculating statistics since system boot, 785the user may pass in a NULL pointer for the |
404.Va previous | 786.Va previous |
405argument. In that case, | 787argument. 788In that case, |
406.Fn compute_stats 407will use the total stats in the 408.Va current 409structure to calculate statistics over 410.Va etime . 411The various statistics that may be calculated by 412.Fn compute_stats 413should be mostly explained by the function declaration itself, but for --- 18 unchanged lines hidden (view full) --- 432.Va current . 433If 434.Va previous 435is NULL, the result will be the total number of transactions listed in 436.Va current . 437.It total_blocks 438This is basically 439.Va total_bytes | 789.Fn compute_stats 790will use the total stats in the 791.Va current 792structure to calculate statistics over 793.Va etime . 794The various statistics that may be calculated by 795.Fn compute_stats 796should be mostly explained by the function declaration itself, but for --- 18 unchanged lines hidden (view full) --- 815.Va current . 816If 817.Va previous 818is NULL, the result will be the total number of transactions listed in 819.Va current . 820.It total_blocks 821This is basically 822.Va total_bytes |
440divided by the device blocksize. If the device blocksize is listed as | 823divided by the device blocksize. 824If the device blocksize is listed as |
441.Sq 0 , 442the device blocksize will default to 512 bytes. 443.It kb_per_transfer 444This is the average number of kilobytes per transfer during the measurement 445period. 446.It transfers_per_second 447This is the average number of transfers per second. 448.It mb_per_second 449This is average megabytes per second. 450.It blocks_per_second | 825.Sq 0 , 826the device blocksize will default to 512 bytes. 827.It kb_per_transfer 828This is the average number of kilobytes per transfer during the measurement 829period. 830.It transfers_per_second 831This is the average number of transfers per second. 832.It mb_per_second 833This is average megabytes per second. 834.It blocks_per_second |
451This is average blocks per second. If the device blocksize is | 835This is average blocks per second. 836If the device blocksize is |
452.Sq 0 , 453a default blocksize of 512 bytes will be used instead. 454.It ms_per_transaction 455The average number of milliseconds per transaction. 456.El 457.Pp | 837.Sq 0 , 838a default blocksize of 512 bytes will be used instead. 839.It ms_per_transaction 840The average number of milliseconds per transaction. 841.El 842.Pp |
458.Fn compute_etime | 843.Fn devstat_compute_etime |
459provides an easy way to find the difference in seconds between two 460.Va timeval | 844provides an easy way to find the difference in seconds between two 845.Va timeval |
461structures. This is most commonly used in conjunction with the time 462recorded by the 463.Fn getdevs | 846structures. 847This is most commonly used in conjunction with the time recorded by the 848.Fn devstat_getdevs |
464function (in struct 465.Va statinfo ) 466each time it fetches the current 467.Nm 468list. | 849function (in struct 850.Va statinfo ) 851each time it fetches the current 852.Nm 853list. |
854.Pp 855.Fn compute_etime 856is the old name of 857.Fn devstat_compute_etime , 858and is deprecated. |
|
469.Sh RETURN VALUES | 859.Sh RETURN VALUES |
470.Fn getnumdevs , 471.Fn getgeneration , | 860.Fn devstat_getnumdevs , 861.Fn devstat_getgeneration , |
472and | 862and |
473.Fn getversion | 863.Fn devstat_getversion |
474return the indicated \fBsysctl\fR variable, or -1 if there is an error 475fetching the variable. 476.Pp | 864return the indicated \fBsysctl\fR variable, or -1 if there is an error 865fetching the variable. 866.Pp |
477.Fn checkversion | 867.Fn devstat_checkversion |
478returns 0 if the kernel and userland 479.Nm | 868returns 0 if the kernel and userland 869.Nm |
480versions match. If they do not match, it returns -1. | 870versions match. 871If they do not match, it returns -1. |
481.Pp | 872.Pp |
482.Fn getdevs | 873.Fn devstat_getdevs |
483and | 874and |
484.Fn selectdevs | 875.Fn devstat_selectdevs |
485return -1 in case of an error, 0 if there is no error and 1 if the device | 876return -1 in case of an error, 0 if there is no error and 1 if the device |
486list or selected devices have changed. A return value of 1 from 487.Fn getdevs | 877list or selected devices have changed. 878A return value of 1 from 879.Fn devstat_getdevs |
488is usually a hint to re-run | 880is usually a hint to re-run |
489.Fn selectdevs | 881.Fn devstat_selectdevs |
490because the device list has changed. 491.Pp | 882because the device list has changed. 883.Pp |
492.Fn buildmatch | 884.Fn devstat_buildmatch |
493returns -1 for error, and 0 if there is no error. 494.Pp 495.Fn compute_stats 496returns -1 for error, and 0 for success. 497.Pp | 885returns -1 for error, and 0 if there is no error. 886.Pp 887.Fn compute_stats 888returns -1 for error, and 0 for success. 889.Pp |
498.Fn compute_etime | 890.Fn devstat_compute_etime |
499returns the computed elapsed time. 500.Pp | 891returns the computed elapsed time. 892.Pp |
893.Fn devstat_compute_statistics 894returns -1 for error, and 0 for success. 895.Pp |
|
501If an error is returned from one of the 502.Nm 503library functions, the reason for the error is generally printed in 504the global string 505.Va devstat_errbuf 506which is 507.Dv DEVSTAT_ERRBUF_SIZE 508characters long. 509.Sh SEE ALSO | 896If an error is returned from one of the 897.Nm 898library functions, the reason for the error is generally printed in 899the global string 900.Va devstat_errbuf 901which is 902.Dv DEVSTAT_ERRBUF_SIZE 903characters long. 904.Sh SEE ALSO |
905.Xr sysctl 1 , |
|
510.Xr systat 1 , | 906.Xr systat 1 , |
907.Xr kvm 3 , 908.Xr sysctl 3 , |
|
511.Xr iostat 8 , 512.Xr rpc.rstatd 8 , 513.Xr vmstat 8 , 514.Xr devstat 9 515.Sh HISTORY 516The 517.Nm 518statistics system first appeared in 519.Fx 3.0 . | 909.Xr iostat 8 , 910.Xr rpc.rstatd 8 , 911.Xr vmstat 8 , 912.Xr devstat 9 913.Sh HISTORY 914The 915.Nm 916statistics system first appeared in 917.Fx 3.0 . |
918The new interface (the functions prefixed with devstat_) first appeared in 919.Fx 5.0 . |
|
520.Sh AUTHORS 521.An Kenneth Merry Aq ken@FreeBSD.org 522.Sh BUGS 523There should probably be an interface to de-allocate memory allocated by | 920.Sh AUTHORS 921.An Kenneth Merry Aq ken@FreeBSD.org 922.Sh BUGS 923There should probably be an interface to de-allocate memory allocated by |
524.Fn getdevs , 525.Fn selectdevs , | 924.Fn devstat_getdevs , 925.Fn devstat_selectdevs , |
526and | 926and |
527.Fn buildmatch . | 927.Fn devstat_buildmatch . |
528.Pp | 928.Pp |
529.Fn selectdevs | 929.Fn devstat_selectdevs |
530should probably not select more than 531.Va maxshowdevs 532devices in 533.Dq top 534mode when no devices have been selected previously. 535.Pp 536There should probably be functions to perform the statistics buffer 537swapping that goes on in most of the clients of this library. 538.Pp 539The 540.Va statinfo 541and 542.Va devinfo 543structures should probably be cleaned up and thought out a little more. | 930should probably not select more than 931.Va maxshowdevs 932devices in 933.Dq top 934mode when no devices have been selected previously. 935.Pp 936There should probably be functions to perform the statistics buffer 937swapping that goes on in most of the clients of this library. 938.Pp 939The 940.Va statinfo 941and 942.Va devinfo 943structures should probably be cleaned up and thought out a little more. |