Tidy up the markup.
Approved by: re (blanket manpages)
This commit is contained in:
parent
a36c0b6b78
commit
8b7475ed75
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=147690
@ -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.
|
||||||
|
Loading…
Reference in New Issue
Block a user