d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update to match reality closer.

Browse Source
This commit is contained in:
Poul-Henning Kamp 2003-03-18 13:45:08 +00:00
parent dbd7434863
commit b193011a02
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=112375
1 changed files with 47 additions and 279 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

326
lib/libdevstat/devstat.3
View File

@ -41,15 +41,6 @@
.Nm devstat_buildmatch ,
.Nm devstat_compute_statistics ,
.Nm devstat_compute_etime ,
.Nm getnumdevs ,
.Nm getgeneration ,
.Nm getversion ,
.Nm checkversion ,
.Nm getdevs ,
.Nm selectdevs ,
.Nm buildmatch ,
.Nm compute_stats ,
.Nm compute_etime
.Nd device statistics utility library
.Sh LIBRARY
.Lb libdevstat
@ -108,60 +99,8 @@
.Fc
.Ft long double
.Fo devstat_compute_etime
.Fa "struct timeval cur_time"
.Fa "struct timeval prev_time"
.Fc
.Ft int
.Fn getnumdevs "void"
.Ft long
.Fn getgeneration "void"
.Ft int
.Fn getversion "void"
.Ft int
.Fn checkversion "void"
.Ft int
.Fn getdevs "struct statinfo *stats"
.Ft int
.Fo selectdevs
.Fa "struct device_selection **dev_select"
.Fa "int *num_selected"
.Fa "int *num_selections"
.Fa "long *select_generation"
.Fa "long current_generation"
.Fa "struct devstat *devices"
.Fa "int numdevs"
.Fa "struct devstat_match *matches"
.Fa "int num_matches"
.Fa "char **dev_selections"
.Fa "int num_dev_selections"
.Fa "devstat_select_mode select_mode"
.Fa "int maxshowdevs"
.Fa "int perf_select"
.Fc
.Ft int
.Fo buildmatch
.Fa "char *match_str"
.Fa "struct devstat_match **matches"
.Fa "int *num_matches"
.Fc
.Ft int
.Fo compute_stats
.Fa "struct devstat *current"
.Fa "struct devstat *previous"
.Fa "long double etime"
.Fa "u_int64_t *total_bytes"
.Fa "u_int64_t *total_transfers"
.Fa "u_int64_t *total_blocks"
.Fa "long double *kb_per_transfer"
.Fa "long double *transfers_per_second"
.Fa "long double *mb_per_second"
.Fa "long double *blocks_per_second"
.Fa "long double *ms_per_transaction"
.Fc
.Ft long double
.Fo compute_etime
.Fa "struct timeval cur_time"
.Fa "struct timeval prev_time"
.Fa "struct bintime cur_time"
.Fa "struct bintime prev_time"
.Fc
.Sh DESCRIPTION
The
@ -194,34 +133,16 @@ returns the number of devices registered with the
.Nm
subsystem in the kernel.
.Pp
.Fn getnumdevs
is a deprecated version of
.Fn devstat_getnumdevs
which always uses
.Xr sysctl 3 .
.Pp
.Fn devstat_getgeneration
returns the current generation of the
.Nm
list of devices in the kernel.
.Pp
.Fn getgeneration
is a deprecated version of
.Fn devstat_getgeneration
which always uses
.Xr sysctl 3 .
.Pp
.Fn devstat_getversion
returns the current kernel
.Nm
version.
.Pp
.Fn getversion
is a deprecated version of
.Fn devstat_getversion
which always uses
.Xr sysctl 3 .
.Pp
.Fn devstat_checkversion
checks the userland devstat version against the kernel devstat version.
If the two are identical, it returns zero.
@ -229,12 +150,6 @@ Otherwise, it prints an appropriate error in
.Va devstat_errbuf
and returns -1.
.Pp
.Fn checkversion
is a deprecated version of
.Fn devstat_checkversion
which always uses
.Xr sysctl 3 .
.Pp
.Fn devstat_getdevs
fetches the current list of devices and statistics into the supplied
.Va statinfo
@ -249,7 +164,7 @@ struct statinfo {
long tk_nin;
long tk_nout;
struct devinfo *dinfo;
struct timeval busy_time;
long double snap_time;
};
.Ed
.Pp
@ -321,12 +236,6 @@ number of devices registered with the kernel
.Nm
subsystem.
.Pp
.Fn getdevs
is a deprecated version of
.Fn devstat_getdevs
which always uses
.Xr sysctl 3 .
.Pp
.Fn devstat_selectdevs
selects devices to display based upon a number of criteria:
.Bl -tag -width flag
@ -439,11 +348,6 @@ is not the same as
will resize the selection list as necessary, and re-initialize the
selection array.
.Pp
.Fn selectdevs
is the old name of
.Fn devstat_selectdevs ,
and is deprecated.
.Pp
.Fn devstat_buildmatch
take a comma separated match string and compile it into a
\fBdevstat_match\fR structure that is understood by
@ -506,11 +410,6 @@ Passthrough devices
.El
.El
.Pp
.Fn buildmatch
is the old name of
.Fn devstat_buildmatch ,
and is deprecated.
.Pp
.Fn devstat_compute_statistics
is an updated version of
.Fn compute_stats
@ -557,16 +456,12 @@ The total number of bytes transferred between the acquisition of
and
.Va current .
.It DSM_TOTAL_BYTES_READ
type: u_int64_t *
.Pp
The total number of bytes read between the acquisition of
.Va previous
and
.Va current .
.It DSM_TOTAL_BYTES_WRITE
.It DSM_TOTAL_BYTES_FREE
type: u_int64_t *
.Pp
The total number of bytes written between the acquisition of
The total number of bytes in transactions of the specified type
between the acquisition of
.Va previous
and
.Va current .
@ -577,25 +472,14 @@ The total number of transfers between the acquisition of
.Va previous
and
.Va current .
.It DSM_TOTAL_TRANSFERS_READ
type: u_int64_t *
.Pp
The total number of reads between the acquisition of
.Va previous
and
.Va current .
.It DSM_TOTAL_TRANSFERS_WRITE
type: u_int64_t *
.Pp
The total number of writes between the acquisition of
.Va previous
and
.Va current .
.It DSM_TOTAL_TRANSFERS_OTHER
.It DSM_TOTAL_TRANSFERS_READ
.It DSM_TOTAL_TRANSFERS_WRITE
.It DSM_TOTAL_TRANSFERS_FREE
type: u_int64_t *
.Pp
The total number of transactions that are not reads or writes that occurred
between the acquisition of
The total number of transactions of the specified type between
the acquisition of
.Va previous
and
.Va current .
@ -610,19 +494,11 @@ This number is in terms of the blocksize reported by the device.
If no blocksize has been reported (i.e. the block size is 0), a default
blocksize of 512 bytes will be used in the calculation.
.It DSM_TOTAL_BLOCKS_READ
type: u_int64_t *
.Pp
The total number of blocks read between the acquisition of
.Va previous
and
.Va current .
This number is in terms of the blocksize reported by the device.
If no blocksize has been reported (i.e. the block size is 0), a default
blocksize of 512 bytes will be used in the calculation.
.It DSM_TOTAL_BLOCKS_WRITE
.It DSM_TOTAL_BLOCKS_FREE
type: u_int64_t *
.Pp
The total number of blocks written between the acquisition of
The total number of blocks of the specified type between the acquisition of
.Va previous
and
.Va current .
@ -637,16 +513,12 @@ The average number of kilobytes per transfer between the acquisition of
and
.Va current .
.It DSM_KB_PER_TRANSFER_READ
type: long double *
.Pp
The average number of kilobytes per read transaction between the acquisition of
.Va previous
and
.Va current .
.It DSM_KB_PER_TRANSFER_WRITE
.It DSM_KB_PER_TRANSFER_FREE
type: long double *
.Pp
The average number of kilobytes per write transaction between the acquisition of
The average number of kilobytes in the specified type transaction between
the acquisition of
.Va previous
and
.Va current .
@ -657,25 +529,14 @@ The average number of transfers per second between the acquisition of
.Va previous
and
.Va current .
.It DSM_TRANSFERS_PER_SECOND_READ
type: long double *
.Pp
The average number of reads per second between the acquisition of
.Va previous
and
.Va current .
.It DSM_TRANSFERS_PER_SECOND_WRITE
type: long double *
.Pp
The average number of writes per second between the acquisition of
.Va previous
and
.Va current .
.It DSM_TRANSFERS_PER_SECOND_OTHER
.It DSM_TRANSFERS_PER_SECOND_READ
.It DSM_TRANSFERS_PER_SECOND_WRITE
.It DSM_TRANSFERS_PER_SECOND_FREE
type: long double *
.Pp
The average number of non-read, non-write transactions per second between
the acquisition of
The average number of transactions of the specified type per second
between the acquisition of
.Va previous
and
.Va current .
@ -688,16 +549,12 @@ acquisition of
and
.Va current .
.It DSM_MB_PER_SECOND_READ
type: long double *
.Pp
The average number of megabytes read per second between the acquisition of
.Va previous
and
.Va current .
.It DSM_MB_PER_SECOND_WRITE
.It DSM_MB_PER_SECOND_FREE
type: long double *
.Pp
The average number of megabytes written per second between the acquisition of
The average number of megabytesper second in the specified type of
transaction between the acquisition of
.Va previous
and
.Va current .
@ -712,19 +569,12 @@ This number is in terms of the blocksize reported by the device.
If no blocksize has been reported (i.e. the block size is 0), a default
blocksize of 512 bytes will be used in the calculation.
.It DSM_BLOCKS_PER_SECOND_READ
type: long double *
.Pp
The average number of blocks read per second between the acquisition of
.Va previous
and
.Va current .
This number is in terms of the blocksize reported by the device.
If no blocksize has been reported (i.e. the block size is 0), a default
blocksize of 512 bytes will be used in the calculation.
.It DSM_BLOCKS_PER_SECOND_WRITE
.It DSM_BLOCKS_PER_SECOND_FREE
type: long double *
.Pp
The average number of blocks written per second between the acquisition of
The average number of blocks per second in the specificed type of transaction
between the acquisition of
.Va previous
and
.Va current .
@ -734,33 +584,35 @@ blocksize of 512 bytes will be used in the calculation.
.It DSM_MS_PER_TRANSACTION
type: long double *
.Pp
The average rate of transaction completion between the acquisition of
The average duration of transactions between the acquisition of
.Va previous
and
.Va current .
Note that this isn't a true reflection of the average number of
milliseconds per transaction, but rather is the average rate of transaction
completion.
The number is derived by dividing the time elapsed by the number of
transactions completed.
.It DSM_MS_PER_TRANSACTION_OTHER
.It DSM_MS_PER_TRANSACTION_READ
type: long double *
.Pp
The average rate of read completions between the acquisition of
.Va previous
and
.Va current .
As above, this is not the true number of milliseconds per transaction, but
rather the average rate of read transaction completion.
.It DSM_MS_PER_TRANSACTION_WRITE
.It DSM_MS_PER_TRANSACTION_FREE
type: long double *
.Pp
The average rate of write transaction completion between the acquisition of
The average duration of transactions of the specified type between the
acquisition of
.Va previous
and
.Va current .
As above, this is not the true number of milliseconds per transaction, but
rather the average rate of write transaction completion.
.It DSM_BUSY_PCT
type long double *
.Pp
The percentage of time the device had one or more transactions outstanding
between the acquisition of
.Va previous
and
.Va current .
.It DSM_QUEUE_LENGTH
type: u_int64_t *
.Pp
The number of not yet completed transactions at the time when
.Va current
was acquired.
.It DSM_SKIP
type: N/A
.Pp
@ -775,85 +627,9 @@ This can be useful in scenarios where the statistics to be calculated
are determined at run time.
.El
.Pp
.Fn compute_stats
is deprecated; use
.Fn devstat_compute_statistics
instead.
.Fn compute_stats
provides an easy way to obtain various device statistics.
Only two arguments are mandatory:
.Va current
and
.Va etime .
Every other argument is optional.
For most applications, the user will want to supply both
.Va current
and
.Va previous
devstat structures so that statistics may be calculated over a given period
of time.
In some instances, for instance when calculating statistics since system boot,
the user may pass in a NULL pointer for the
.Va previous
argument.
In that case,
.Fn compute_stats
will use the total stats in the
.Va current
structure to calculate statistics over
.Va etime .
The various statistics that may be calculated by
.Fn compute_stats
should be mostly explained by the function declaration itself, but for
completeness here is a list of variable names and the statistics that will
be put in them:
.Bl -tag -width transfers_per_second
.It total_bytes
This is the total number of bytes transferred on the given device, both
reads and writes, between the acquisition of
.Va previous
and the acquisition of
.Va current .
If
.Va previous
is NULL, the result will be the total reads and writes given in
.Va current .
.It total_transfers
This is the total number of transfers completed between the
acquisition of
.Va previous
and the acquisition of
.Va current .
If
.Va previous
is NULL, the result will be the total number of transactions listed in
.Va current .
.It total_blocks
This is basically
.Va total_bytes
divided by the device blocksize.
If the device blocksize is listed as
.Sq 0 ,
the device blocksize will default to 512 bytes.
.It kb_per_transfer
This is the average number of kilobytes per transfer during the measurement
period.
.It transfers_per_second
This is the average number of transfers per second.
.It mb_per_second
This is average megabytes per second.
.It blocks_per_second
This is average blocks per second.
If the device blocksize is
.Sq 0 ,
a default blocksize of 512 bytes will be used instead.
.It ms_per_transaction
The average number of milliseconds per transaction.
.El
.Pp
.Fn devstat_compute_etime
provides an easy way to find the difference in seconds between two
.Va timeval
.Va bintime
structures.
This is most commonly used in conjunction with the time recorded by the
.Fn devstat_getdevs
@ -862,11 +638,6 @@ function (in struct
each time it fetches the current
.Nm
list.
.Pp
.Fn compute_etime
is the old name of
.Fn devstat_compute_etime ,
and is deprecated.
.Sh RETURN VALUES
.Fn devstat_getnumdevs ,
.Fn devstat_getgeneration ,
@ -895,9 +666,6 @@ because the device list has changed.
.Fn devstat_buildmatch
returns -1 for error, and 0 if there is no error.
.Pp
.Fn compute_stats
returns -1 for error, and 0 for success.
.Pp
.Fn devstat_compute_etime
returns the computed elapsed time.
.Pp