lib/libdevstat/devstat.3

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