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