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

Tidy up the markup.

Browse Source 
Approved by:	re (blanket manpages)
This commit is contained in:
Ruslan Ermilov 2005-06-30 06:35:51 +00:00
parent a36c0b6b78
commit 8b7475ed75
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=147690
1 changed files with 285 additions and 214 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

499
lib/libdevstat/devstat.3
View File

@ -27,7 +27,7 @@
.\" .\"
.\" $FreeBSD$ .\" $FreeBSD$
.\" .\"
.Dd July 15, 2001 .Dd March 18, 2003
.Dt DEVSTAT 3 .Dt DEVSTAT 3
.Os .Os
.Sh NAME .Sh NAME
@ -47,26 +47,15 @@
.Sh SYNOPSIS .Sh SYNOPSIS
.In devstat.h .In devstat.h
.Ft int .Ft int
.Fo devstat_getnumdevs .Fn devstat_getnumdevs "kvm_t *kd"
.Fa "kvm_t *kd"
.Fc
.Ft long .Ft long
.Fo devstat_getgeneration .Fn devstat_getgeneration "kvm_t *kd"
.Fa "kvm_t *kd"
.Fc
.Ft int .Ft int
.Fo devstat_getversion .Fn devstat_getversion "kvm_t *kd"
.Fa "kvm_t *kd"
.Fc
.Ft int .Ft int
.Fo devstat_checkversion .Fn devstat_checkversion "kvm_t *kd"
.Fa "kvm_t *kd"
.Fc
.Ft int .Ft int
.Fo devstat_getdevs .Fn devstat_getdevs "kvm_t *kd" "struct statinfo *stats"
.Fa "kvm_t *kd"
.Fa "struct statinfo *stats"
.Fc
.Ft int .Ft int
.Fo devstat_selectdevs .Fo devstat_selectdevs
.Fa "struct device_selection **dev_select" .Fa "struct device_selection **dev_select"
@ -97,11 +86,8 @@
.Fa "long double etime" .Fa "long double etime"
.Fa "..." .Fa "..."
.Fc .Fc
.Ft long double .Ft "long double"
.Fo devstat_compute_etime .Fn devstat_compute_etime "struct bintime cur_time" "struct bintime prev_time"
.Fa "struct bintime cur_time"
.Fa "struct bintime prev_time"
.Fc
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Nm .Nm
@ -112,7 +98,7 @@ interface, which is accessible to users via
and and
.Xr kvm 3 . .Xr kvm 3 .
All functions that take a All functions that take a
.Vt kvm_t * .Vt "kvm_t *"
as first argument can be passed as first argument can be passed
.Dv NULL .Dv NULL
instead of a kvm handle as this argument, instead of a kvm handle as this argument,
@ -121,41 +107,57 @@ which causes the data to be read via
Otherwise, it is read via Otherwise, it is read via
.Xr kvm 3 .Xr kvm 3
using the supplied handle. using the supplied handle.
The
.Fn devstat_checkversion .Fn devstat_checkversion
function
should be called with each kvm handle that is going to be used (or with should be called with each kvm handle that is going to be used (or with
.Dv NULL .Dv NULL
if if
.Xr sysctl 3 .Xr sysctl 3
is going to be used). is going to be used).
.Pp .Pp
The
.Fn devstat_getnumdevs .Fn devstat_getnumdevs
function
returns the number of devices registered with the returns the number of devices registered with the
.Nm .Nm
subsystem in the kernel. subsystem in the kernel.
.Pp .Pp
The
.Fn devstat_getgeneration .Fn devstat_getgeneration
function
returns the current generation of the returns the current generation of the
.Nm .Nm
list of devices in the kernel. list of devices in the kernel.
.Pp .Pp
The
.Fn devstat_getversion .Fn devstat_getversion
function
returns the current kernel returns the current kernel
.Nm .Nm
version. version.
.Pp .Pp
The
.Fn devstat_checkversion .Fn devstat_checkversion
checks the userland devstat version against the kernel devstat version. function
checks the userland
.Nm
version against the kernel
.Nm
version.
If the two are identical, it returns zero. If the two are identical, it returns zero.
Otherwise, it prints an appropriate error in Otherwise, it prints an appropriate error in
.Va devstat_errbuf .Va devstat_errbuf
and returns -1. and returns \-1.
.Pp .Pp
The
.Fn devstat_getdevs .Fn devstat_getdevs
function
fetches the current list of devices and statistics into the supplied fetches the current list of devices and statistics into the supplied
.Va statinfo .Vt statinfo
structure. structure.
The The
.Va statinfo .Vt statinfo
structure can be found in structure can be found in
.In devstat.h : .In devstat.h :
.Bd -literal -offset indent .Bd -literal -offset indent
@ -168,9 +170,11 @@ struct statinfo {
}; };
.Ed .Ed
.Pp .Pp
The
.Fn devstat_getdevs .Fn devstat_getdevs
function
expects the expects the
.Va statinfo .Vt statinfo
structure to be allocated, and it also expects the structure to be allocated, and it also expects the
.Va dinfo .Va dinfo
subelement to be allocated and zeroed prior to the first invocation of subelement to be allocated and zeroed prior to the first invocation of
@ -194,17 +198,19 @@ struct devinfo {
.Pp .Pp
The The
.Va kern.devstat.all .Va kern.devstat.all
.Nm sysctl .Xr sysctl 8
variable contains an array of variable contains an array of
.Nm .Nm
structures, but at the head of the array is the current structures, but at the head of the array is the current
.Nm .Nm
generation. generation.
The reason the generation is at the head of the buffer is so that userland The reason the generation is at the head of the buffer is so that userland
software accessing the devstat statistics information can atomically get software accessing the
.Nm
statistics information can atomically get
both the statistics information and the corresponding generation number. both the statistics information and the corresponding generation number.
If client software were forced to get the generation number via a separate If client software were forced to get the generation number via a separate
.Nm sysctl .Xr sysctl 8
variable (which is available for convenience), the list of devices could variable (which is available for convenience), the list of devices could
change between the time the client gets the generation and the time the change between the time the client gets the generation and the time the
client gets the device list. client gets the device list.
@ -212,36 +218,39 @@ client gets the device list.
The The
.Va mem_ptr .Va mem_ptr
subelement of the subelement of the
.Va devinfo .Vt devinfo
structure is a pointer to memory that is allocated, and resized if structure is a pointer to memory that is allocated, and resized if
necessary, by necessary, by
.Fn devstat_getdevs . .Fn devstat_getdevs .
The devices subelement of the The devices subelement of the
.Va devinfo .Vt devinfo
structure is basically a pointer to the beginning of the array of devstat structure is basically a pointer to the beginning of the array of devstat
structures from the structures from the
.Va kern.devstat.all .Va kern.devstat.all
.Nm sysctl .Xr sysctl 8
variable (or the corresponding values read via variable (or the corresponding values read via
.Xr kvm 3 ) . .Xr kvm 3 ) .
The generation subelement of the The generation subelement of the
.Va devinfo .Vt devinfo
structure contains the corresponding generation number. structure contains the corresponding generation number.
The The
.Va numdevs .Va numdevs
subelement of the subelement of the
.Va devinfo .Vt devinfo
structure contains the current structure contains the current
number of devices registered with the kernel number of devices registered with the kernel
.Nm .Nm
subsystem. subsystem.
.Pp .Pp
The
.Fn devstat_selectdevs .Fn devstat_selectdevs
function
selects devices to display based upon a number of criteria: selects devices to display based upon a number of criteria:
.Bl -tag -width flag .Bl -tag -width indent
.It specified devices .It specified devices
Specified devices are the first selection priority. Specified devices are the first selection priority.
These are generally devices specified by name by the user e.g.\& da0, da1, cd0. These are generally devices specified by name by the user e.g.\&
.Li da0 , da1 , cd0 .
.It match patterns .It match patterns
These are pattern matching expressions generated by These are pattern matching expressions generated by
.Fn devstat_buildmatch .Fn devstat_buildmatch
@ -250,7 +259,7 @@ from user input.
If performance mode is enabled, devices will be sorted based on the If performance mode is enabled, devices will be sorted based on the
.Va bytes .Va bytes
field in the field in the
.Va device_selection .Vt device_selection
structure passed in to structure passed in to
.Fn devstat_selectdevs . .Fn devstat_selectdevs .
The The
@ -266,50 +275,64 @@ If devices have been selected by name or pattern, the performance tracking
code will honor those selections and will only sort among the selected code will honor those selections and will only sort among the selected
devices. devices.
.It order in the devstat list .It order in the devstat list
If the selection mode is set to DS_SELECT_ADD, and if there are still less If the selection mode is set to
.Dv DS_SELECT_ADD ,
and if there are still less
than than
.Va maxshowdevs .Fa maxshowdevs
devices selected, devices selected,
.Fn devstat_selectdevs .Fn devstat_selectdevs
will automatically select up to will automatically select up to
.Va maxshowdevs .Fa maxshowdevs
devices. devices.
.El .El
.Pp .Pp
The
.Fn devstat_selectdevs .Fn devstat_selectdevs
function
performs selections in four different modes: performs selections in four different modes:
.Bl -tag -width DS_SELECT_ADDONLY .Bl -tag -width ".Dv DS_SELECT_ADDONLY"
.It DS_SELECT_ADD .It Dv DS_SELECT_ADD
In add mode, In
.Dq add
mode,
.Fn devstat_selectdevs .Fn devstat_selectdevs
will select any unselected devices specified by name or matching pattern. will select any unselected devices specified by name or matching pattern.
It will also select more devices, in devstat list order, until the number It will also select more devices, in devstat list order, until the number
of selected devices is equal to of selected devices is equal to
.Va maxshowdevs .Fa maxshowdevs
or until all devices are or until all devices are
selected. selected.
.It DS_SELECT_ONLY .It Dv DS_SELECT_ONLY
In only mode, In
.Dq only
mode,
.Fn devstat_selectdevs .Fn devstat_selectdevs
will clear all current selections, and will only select devices specified will clear all current selections, and will only select devices specified
by name or by matching pattern. by name or by matching pattern.
.It DS_SELECT_REMOVE .It Dv DS_SELECT_REMOVE
In remove mode, In
.Dq remove
mode,
.Fn devstat_selectdevs .Fn devstat_selectdevs
will remove devices specified by name or by matching pattern. will remove devices specified by name or by matching pattern.
It will not select any additional devices. It will not select any additional devices.
.It DS_SELECT_ADDONLY .It Dv DS_SELECT_ADDONLY
In add only mode, In
.Dq "add only"
mode,
.Fn devstat_selectdevs .Fn devstat_selectdevs
will select any unselected devices specified by name or matching pattern. will select any unselected devices specified by name or matching pattern.
In this respect it is identical to add mode. In this respect it is identical to
.Dq add
mode.
It will not, however, select any devices other than those specified. It will not, however, select any devices other than those specified.
.El .El
.Pp .Pp
In all selection modes, In all selection modes,
.Fn devstat_selectdevs .Fn devstat_selectdevs
will not select any more than will not select any more than
.Va maxshowdevs .Fa maxshowdevs
devices. devices.
One exception to this is when you are in One exception to this is when you are in
.Dq top .Dq top
@ -321,307 +344,341 @@ Client programs must pay attention to selection order when deciding whether
to pay attention to a particular device. to pay attention to a particular device.
This may be the wrong behavior, and probably requires additional thought. This may be the wrong behavior, and probably requires additional thought.
.Pp .Pp
The
.Fn devstat_selectdevs .Fn devstat_selectdevs
function
handles allocation and resizing of the handles allocation and resizing of the
.Va dev_select .Fa dev_select
structure passed in structure passed in
by the client. by the client.
The
.Fn devstat_selectdevs .Fn devstat_selectdevs
function
uses the uses the
.Va numdevs .Fa numdevs
and and
.Va current_generation .Fa current_generation
fields to track the fields to track the
current current
.Nm .Nm
generation and number of devices. generation and number of devices.
If If
.Va num_selections .Fa num_selections
is not the same is not the same
as as
.Va numdevs .Fa numdevs
or if or if
.Va select_generation .Fa select_generation
is not the same as is not the same as
.Va current_generation , .Fa current_generation ,
.Fn devstat_selectdevs .Fn devstat_selectdevs
will resize the selection list as necessary, and re-initialize the will resize the selection list as necessary, and re-initialize the
selection array. selection array.
.Pp .Pp
The
.Fn devstat_buildmatch .Fn devstat_buildmatch
take a comma separated match string and compile it into a function
\fBdevstat_match\fR structure that is understood by takes a comma separated match string and compiles it into a
.Fn selectdevs . .Vt devstat_match
structure that is understood by
.Fn devstat_selectdevs .
Match strings have the following format: Match strings have the following format:
.Pp .Pp
.Bd -literal -offset indent .D1 Ar device , Ns Ar type , Ns Ar if
device,type,if
.Ed
.Pp .Pp
The
.Fn devstat_buildmatch .Fn devstat_buildmatch
function
takes care of allocating and reallocating the match list as necessary. takes care of allocating and reallocating the match list as necessary.
Currently known match types include: Currently known match types include:
.Pp .Bl -tag -width indent
.Bl -tag -width indent -compact
.It device type: .It device type:
.Bl -tag -width 9n -compact .Bl -tag -width ".Li enclosure" -compact
.It da .It Li da
Direct Access devices Direct Access devices
.It sa .It Li sa
Sequential Access devices Sequential Access devices
.It printer .It Li printer
Printers Printers
.It proc .It Li proc
Processor devices Processor devices
.It worm .It Li worm
Write Once Read Multiple devices Write Once Read Multiple devices
.It cd .It Li cd
CD devices CD devices
.It scanner .It Li scanner
Scanner devices Scanner devices
.It optical .It Li optical
Optical Memory devices Optical Memory devices
.It changer .It Li changer
Medium Changer devices Medium Changer devices
.It comm .It Li comm
Communication devices Communication devices
.It array .It Li array
Storage Array devices Storage Array devices
.It enclosure .It Li enclosure
Enclosure Services devices Enclosure Services devices
.It floppy .It Li floppy
Floppy devices Floppy devices
.El .El
.Pp
.It interface: .It interface:
.Bl -tag -width 9n -compact .Bl -tag -width ".Li enclosure" -compact
.It IDE .It Li IDE
Integrated Drive Electronics devices Integrated Drive Electronics devices
.It SCSI .It Li SCSI
Small Computer System Interface devices Small Computer System Interface devices
.It other .It Li other
Any other device interface Any other device interface
.El .El
.Pp
.It passthrough: .It passthrough:
.Bl -tag -width 9n -compact .Bl -tag -width ".Li enclosure" -compact
.It pass .It Li pass
Passthrough devices Passthrough devices
.El .El
.El .El
.Pp .Pp
The
.Fn devstat_compute_statistics .Fn devstat_compute_statistics
function
is an updated version of is an updated version of
.Fn compute_stats .Fn compute_stats
that provides more complete statistics calculation. that provides more complete statistics calculation.
There are four arguments for which values \fBmust\fR be supplied: There are four arguments for which values
.Va current , .Em must
.Va previous , be supplied:
.Va etime , .Fa current ,
.Fa previous ,
.Fa etime ,
and the terminating argument for the varargs list, and the terminating argument for the varargs list,
.Va DSM_NONE . .Dv DSM_NONE .
For most applications, the user will want to supply valid devstat For most applications, the user will want to supply valid
.Vt devstat
structures for both structures for both
.Va current .Fa current
and and
.Va previous . .Fa previous .
In some instances, for instance when calculating statistics since system In some instances, for instance when calculating statistics since system
boot, the user may pass in a NULL pointer for the boot, the user may pass in a
.Va previous .Dv NULL
pointer for the
.Fa previous
argument. argument.
In that case, In that case,
.Fn devstat_compute_statistics .Fn devstat_compute_statistics
will use the total stats in the will use the total stats in the
.Va current .Fa current
structure to calculate statistics over structure to calculate statistics over
.Va etime . .Fa etime .
For each statistic to be calculated, the user should supply the proper For each statistics to be calculated, the user should supply the proper
enumerated type (listed below), and a variable of the indicated type. enumerated type (listed below), and a variable of the indicated type.
All statistics are either integer values, for which a u_int64_t is used, All statistics are either integer values, for which a
or floating point, for which a long double is used. .Vt u_int64_t
is used,
or floating point, for which a
.Vt "long double"
is used.
The statistics that may be calculated are: The statistics that may be calculated are:
.Bl -tag -width DSM_TRANSFERS_PER_SECOND_OTHER .Bl -tag -width ".Dv DSM_TRANSFERS_PER_SECOND_OTHER"
.It DSM_NONE .It Dv DSM_NONE
type: N/A type: N/A
.Pp .Pp
This \fBmust\fR This
.Em must
be the last argument passed to be the last argument passed to
.Fn devstat_compute_statistics . .Fn devstat_compute_statistics .
It is an argument list terminator. It is an argument list terminator.
.It DSM_TOTAL_BYTES .It Dv DSM_TOTAL_BYTES
type: u_int64_t * type:
.Vt "u_int64_t *"
.Pp .Pp
The total number of bytes transferred between the acquisition of The total number of bytes transferred between the acquisition of
.Va previous .Fa previous
and and
.Va current . .Fa current .
.It DSM_TOTAL_BYTES_READ .It Dv DSM_TOTAL_BYTES_READ
.It DSM_TOTAL_BYTES_WRITE .It Dv DSM_TOTAL_BYTES_WRITE
.It DSM_TOTAL_BYTES_FREE .It Dv DSM_TOTAL_BYTES_FREE
type: u_int64_t * type:
.Vt "u_int64_t *"
.Pp .Pp
The total number of bytes in transactions of the specified type The total number of bytes in transactions of the specified type
between the acquisition of between the acquisition of
.Va previous .Fa previous
and and
.Va current . .Fa current .
.It DSM_TOTAL_TRANSFERS .It Dv DSM_TOTAL_TRANSFERS
type: u_int64_t * type:
.Vt "u_int64_t *"
.Pp .Pp
The total number of transfers between the acquisition of The total number of transfers between the acquisition of
.Va previous .Fa previous
and and
.Va current . .Fa current .
.It DSM_TOTAL_TRANSFERS_OTHER .It Dv DSM_TOTAL_TRANSFERS_OTHER
.It DSM_TOTAL_TRANSFERS_READ .It Dv DSM_TOTAL_TRANSFERS_READ
.It DSM_TOTAL_TRANSFERS_WRITE .It Dv DSM_TOTAL_TRANSFERS_WRITE
.It DSM_TOTAL_TRANSFERS_FREE .It Dv DSM_TOTAL_TRANSFERS_FREE
type: u_int64_t * type:
.Vt "u_int64_t *"
.Pp .Pp
The total number of transactions of the specified type between The total number of transactions of the specified type between
the acquisition of the acquisition of
.Va previous .Fa previous
and and
.Va current . .Fa current .
.It DSM_TOTAL_BLOCKS .It Dv DSM_TOTAL_BLOCKS
type: u_int64_t * type:
.Vt "u_int64_t *"
.Pp .Pp
The total number of blocks transferred between the acquisition of The total number of blocks transferred between the acquisition of
.Va previous .Fa previous
and and
.Va current . .Fa current .
This number is in terms of the blocksize reported by the device. 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 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. blocksize of 512 bytes will be used in the calculation.
.It DSM_TOTAL_BLOCKS_READ .It Dv DSM_TOTAL_BLOCKS_READ
.It DSM_TOTAL_BLOCKS_WRITE .It Dv DSM_TOTAL_BLOCKS_WRITE
.It DSM_TOTAL_BLOCKS_FREE .It Dv DSM_TOTAL_BLOCKS_FREE
type: u_int64_t * type:
.Vt "u_int64_t *"
.Pp .Pp
The total number of blocks of the specified type between the acquisition of The total number of blocks of the specified type between the acquisition of
.Va previous .Fa previous
and and
.Va current . .Fa current .
This number is in terms of the blocksize reported by the device. 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 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. blocksize of 512 bytes will be used in the calculation.
.It DSM_KB_PER_TRANSFER .It Dv DSM_KB_PER_TRANSFER
type: long double * type:
.Vt "long double *"
.Pp .Pp
The average number of kilobytes per transfer between the acquisition of The average number of kilobytes per transfer between the acquisition of
.Va previous .Fa previous
and and
.Va current . .Fa current .
.It DSM_KB_PER_TRANSFER_READ .It Dv DSM_KB_PER_TRANSFER_READ
.It DSM_KB_PER_TRANSFER_WRITE .It Dv DSM_KB_PER_TRANSFER_WRITE
.It DSM_KB_PER_TRANSFER_FREE .It Dv DSM_KB_PER_TRANSFER_FREE
type: long double * type:
.Vt "long double *"
.Pp .Pp
The average number of kilobytes in the specified type transaction between The average number of kilobytes in the specified type transaction between
the acquisition of the acquisition of
.Va previous .Fa previous
and and
.Va current . .Fa current .
.It DSM_TRANSFERS_PER_SECOND .It Dv DSM_TRANSFERS_PER_SECOND
type: long double * type:
.Vt "long double *"
.Pp .Pp
The average number of transfers per second between the acquisition of The average number of transfers per second between the acquisition of
.Va previous .Fa previous
and and
.Va current . .Fa current .
.It DSM_TRANSFERS_PER_SECOND_OTHER .It Dv DSM_TRANSFERS_PER_SECOND_OTHER
.It DSM_TRANSFERS_PER_SECOND_READ .It Dv DSM_TRANSFERS_PER_SECOND_READ
.It DSM_TRANSFERS_PER_SECOND_WRITE .It Dv DSM_TRANSFERS_PER_SECOND_WRITE
.It DSM_TRANSFERS_PER_SECOND_FREE .It Dv DSM_TRANSFERS_PER_SECOND_FREE
type: long double * type:
.Vt "long double *"
.Pp .Pp
The average number of transactions of the specified type per second The average number of transactions of the specified type per second
between the acquisition of between the acquisition of
.Va previous .Fa previous
and and
.Va current . .Fa current .
.It DSM_MB_PER_SECOND .It Dv DSM_MB_PER_SECOND
type: long double * type:
.Vt "long double *"
.Pp .Pp
The average number of megabytes transferred per second between the The average number of megabytes transferred per second between the
acquisition of acquisition of
.Va previous .Fa previous
and and
.Va current . .Fa current .
.It DSM_MB_PER_SECOND_READ .It Dv DSM_MB_PER_SECOND_READ
.It DSM_MB_PER_SECOND_WRITE .It Dv DSM_MB_PER_SECOND_WRITE
.It DSM_MB_PER_SECOND_FREE .It Dv DSM_MB_PER_SECOND_FREE
type: long double * type:
.Vt "long double *"
.Pp .Pp
The average number of megabytes per second in the specified type of The average number of megabytes per second in the specified type of
transaction between the acquisition of transaction between the acquisition of
.Va previous .Fa previous
and and
.Va current . .Fa current .
.It DSM_BLOCKS_PER_SECOND .It Dv DSM_BLOCKS_PER_SECOND
type: long double * type:
.Vt "long double *"
.Pp .Pp
The average number of blocks transferred per second between the acquisition of The average number of blocks transferred per second between the acquisition of
.Va previous .Fa previous
and and
.Va current . .Fa current .
This number is in terms of the blocksize reported by the device. 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 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. blocksize of 512 bytes will be used in the calculation.
.It DSM_BLOCKS_PER_SECOND_READ .It Dv DSM_BLOCKS_PER_SECOND_READ
.It DSM_BLOCKS_PER_SECOND_WRITE .It Dv DSM_BLOCKS_PER_SECOND_WRITE
.It DSM_BLOCKS_PER_SECOND_FREE .It Dv DSM_BLOCKS_PER_SECOND_FREE
type: long double * type:
.Vt "long double *"
.Pp .Pp
The average number of blocks per second in the specificed type of transaction The average number of blocks per second in the specificed type of transaction
between the acquisition of between the acquisition of
.Va previous .Fa previous
and and
.Va current . .Fa current .
This number is in terms of the blocksize reported by the device. 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 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. blocksize of 512 bytes will be used in the calculation.
.It DSM_MS_PER_TRANSACTION .It Dv DSM_MS_PER_TRANSACTION
type: long double * type:
.Vt "long double *"
.Pp .Pp
The average duration of transactions between the acquisition of The average duration of transactions between the acquisition of
.Va previous .Fa previous
and and
.Va current . .Fa current .
.It DSM_MS_PER_TRANSACTION_OTHER .It Dv DSM_MS_PER_TRANSACTION_OTHER
.It DSM_MS_PER_TRANSACTION_READ .It Dv DSM_MS_PER_TRANSACTION_READ
.It DSM_MS_PER_TRANSACTION_WRITE .It Dv DSM_MS_PER_TRANSACTION_WRITE
.It DSM_MS_PER_TRANSACTION_FREE .It Dv DSM_MS_PER_TRANSACTION_FREE
type: long double * type:
.Vt "long double *"
.Pp .Pp
The average duration of transactions of the specified type between the The average duration of transactions of the specified type between the
acquisition of acquisition of
.Va previous .Fa previous
and and
.Va current . .Fa current .
.It DSM_BUSY_PCT .It Dv DSM_BUSY_PCT
type: long double * type:
.Vt "long double *"
.Pp .Pp
The percentage of time the device had one or more transactions outstanding The percentage of time the device had one or more transactions outstanding
between the acquisition of between the acquisition of
.Va previous .Fa previous
and and
.Va current . .Fa current .
.It DSM_QUEUE_LENGTH .It Dv DSM_QUEUE_LENGTH
type: u_int64_t * type:
.Vt "u_int64_t *"
.Pp .Pp
The number of not yet completed transactions at the time when The number of not yet completed transactions at the time when
.Va current .Fa current
was acquired. was acquired.
.It DSM_SKIP .It Dv DSM_SKIP
type: N/A type: N/A
.Pp .Pp
If you do not need a result from If you do not need a result from
.Fn devstat_compute_statistics , .Fn devstat_compute_statistics ,
just put just put
.Va DSM_SKIP .Dv DSM_SKIP
as first (type) parameter and as first (type) parameter and
.Va NULL .Dv NULL
as second parameter. as second parameter.
This can be useful in scenarios where the statistics to be calculated This can be useful in scenarios where the statistics to be calculated
are determined at run time. are determined at run time.
@ -629,33 +686,39 @@ are determined at run time.
.Pp .Pp
.Fn devstat_compute_etime .Fn devstat_compute_etime
provides an easy way to find the difference in seconds between two provides an easy way to find the difference in seconds between two
.Va bintime .Vt bintime
structures. structures.
This is most commonly used in conjunction with the time recorded by the This is most commonly used in conjunction with the time recorded by the
.Fn devstat_getdevs .Fn devstat_getdevs
function (in struct function (in
.Va statinfo ) .Vt "struct statinfo" )
each time it fetches the current each time it fetches the current
.Nm .Nm
list. list.
.Sh RETURN VALUES .Sh RETURN VALUES
The
.Fn devstat_getnumdevs , .Fn devstat_getnumdevs ,
.Fn devstat_getgeneration , .Fn devstat_getgeneration ,
and and
.Fn devstat_getversion .Fn devstat_getversion
return the indicated \fBsysctl\fR variable, or -1 if there is an error function
return the indicated sysctl variable, or \-1 if there is an error
fetching the variable. fetching the variable.
.Pp .Pp
The
.Fn devstat_checkversion .Fn devstat_checkversion
function
returns 0 if the kernel and userland returns 0 if the kernel and userland
.Nm .Nm
versions match. versions match.
If they do not match, it returns -1. If they do not match, it returns \-1.
.Pp .Pp
The
.Fn devstat_getdevs .Fn devstat_getdevs
and and
.Fn devstat_selectdevs .Fn devstat_selectdevs
return -1 in case of an error, 0 if there is no error and 1 if the device functions
return \-1 in case of an error, 0 if there is no error, and 1 if the device
list or selected devices have changed. list or selected devices have changed.
A return value of 1 from A return value of 1 from
.Fn devstat_getdevs .Fn devstat_getdevs
@ -663,14 +726,18 @@ is usually a hint to re-run
.Fn devstat_selectdevs .Fn devstat_selectdevs
because the device list has changed. because the device list has changed.
.Pp .Pp
The
.Fn devstat_buildmatch .Fn devstat_buildmatch
returns -1 for error, and 0 if there is no error. function returns \-1 for error, and 0 if there is no error.
.Pp .Pp
The
.Fn devstat_compute_etime .Fn devstat_compute_etime
function
returns the computed elapsed time. returns the computed elapsed time.
.Pp .Pp
The
.Fn devstat_compute_statistics .Fn devstat_compute_statistics
returns -1 for error, and 0 for success. function returns \-1 for error, and 0 for success.
.Pp .Pp
If an error is returned from one of the If an error is returned from one of the
.Nm .Nm
@ -694,7 +761,9 @@ The
.Nm .Nm
statistics system first appeared in statistics system first appeared in
.Fx 3.0 . .Fx 3.0 .
The new interface (the functions prefixed with devstat_) first appeared in The new interface (the functions prefixed with
.Li devstat_ )
first appeared in
.Fx 5.0 . .Fx 5.0 .
.Sh AUTHORS .Sh AUTHORS
.An Kenneth Merry Aq ken@FreeBSD.org .An Kenneth Merry Aq ken@FreeBSD.org
@ -705,9 +774,11 @@ There should probably be an interface to de-allocate memory allocated by
and and
.Fn devstat_buildmatch . .Fn devstat_buildmatch .
.Pp .Pp
The
.Fn devstat_selectdevs .Fn devstat_selectdevs
function
should probably not select more than should probably not select more than
.Va maxshowdevs .Fa maxshowdevs
devices in devices in
.Dq top .Dq top
mode when no devices have been selected previously. mode when no devices have been selected previously.
@ -716,7 +787,7 @@ There should probably be functions to perform the statistics buffer
swapping that goes on in most of the clients of this library. swapping that goes on in most of the clients of this library.
.Pp .Pp
The The
.Va statinfo .Vt statinfo
and and
.Va devinfo .Vt devinfo
structures should probably be cleaned up and thought out a little more. structures should probably be cleaned up and thought out a little more.