summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorphk <phk@FreeBSD.org>2003-03-18 13:45:08 +0000
committerphk <phk@FreeBSD.org>2003-03-18 13:45:08 +0000
commit100732c8674a77025bafed14254a5eb4521a8a88 (patch)
tree76b1cf26cc93b6a42a9aaf060546ef08c9b0e41a
parentdcd03e97302b660aacc5561bf624f97146370bed (diff)
downloadFreeBSD-src-100732c8674a77025bafed14254a5eb4521a8a88.zip
FreeBSD-src-100732c8674a77025bafed14254a5eb4521a8a88.tar.gz
Update to match reality closer.
-rw-r--r--lib/libdevstat/devstat.3316
1 files changed, 42 insertions, 274 deletions
diff --git a/lib/libdevstat/devstat.3 b/lib/libdevstat/devstat.3
index 2dbcaf3..babcf71 100644
--- a/lib/libdevstat/devstat.3
+++ b/lib/libdevstat/devstat.3
@@ -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_OTHER
.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
+.It DSM_TOTAL_TRANSFERS_FREE
type: u_int64_t *
.Pp
-The total number of writes between the acquisition of
-.Va previous
-and
-.Va current .
-.It DSM_TOTAL_TRANSFERS_OTHER
-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_OTHER
.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
+.It DSM_TRANSFERS_PER_SECOND_FREE
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
-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
+.It DSM_MS_PER_TRANSACTION_WRITE
+.It DSM_MS_PER_TRANSACTION_FREE
type: long double *
.Pp
-The average rate of read completions 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 read transaction completion.
-.It DSM_MS_PER_TRANSACTION_WRITE
-type: long double *
+.It DSM_BUSY_PCT
+type long double *
.Pp
-The average rate of write transaction completion between the acquisition of
+The percentage of time the device had one or more transactions outstanding
+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_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
OpenPOWER on IntegriCloud