FreeBSD Man Pagesdevstat(3)
NAME
devstat, devstat_getnumdevs, devstat_getgeneration, devstat_getversion,
devstat_checkversion, devstat_getdevs, devstat_selectdevs,
devstat_buildmatch, devstat_compute_statistics, devstat_compute_etime --
device statistics utility library
LIBRARY
Device Statistics Library (libdevstat, -ldevstat)
SYNOPSIS
#include <devstat.h>
int
devstat_getnumdevs(kvm_t *kd);
long
devstat_getgeneration(kvm_t *kd);
int
devstat_getversion(kvm_t *kd);
int
devstat_checkversion(kvm_t *kd);
int
devstat_getdevs(kvm_t *kd, struct statinfo *stats);
int
devstat_selectdevs(struct device_selection **dev_select,
int *num_selected, int *num_selections, long *select_generation,
long current_generation, struct devstat *devices, int numdevs,
struct devstat_match *matches, int num_matches,
char **dev_selections, int num_dev_selections,
devstat_select_mode select_mode, int maxshowdevs, int perf_select);
int
devstat_buildmatch(char *match_str, struct devstat_match **matches,
int *num_matches);
int
devstat_compute_statistics(struct devstat *current,
struct devstat *previous, long double etime, ...);
long double
devstat_compute_etime(struct bintime cur_time, struct bintime prev_time);
DESCRIPTION
The devstat library is a library of helper functions for dealing with the
kernel devstat(9) interface, which is accessible to users via sysctl(3)
and kvm(3). All functions that take a kvm_t * as first argument can be
passed NULL instead of a kvm handle as this argument, which causes the
data to be read via sysctl(3). Otherwise, it is read via kvm(3) using
the supplied handle. devstat_checkversion() should be called with each
kvm handle that is going to be used (or with NULL if sysctl(3) is going
to be used).
devstat_getnumdevs() returns the number of devices registered with the
kernel devstat version. If the two are identical, it returns zero. Oth-
erwise, it prints an appropriate error in devstat_errbuf and returns -1.
devstat_getdevs() fetches the current list of devices and statistics into
the supplied statinfo structure. The statinfo structure can be found in
<devstat.h>:
struct statinfo {
long cp_time[CPUSTATES];
long tk_nin;
long tk_nout;
struct devinfo *dinfo;
long double snap_time;
};
devstat_getdevs() expects the statinfo structure to be allocated, and it
also expects the dinfo subelement to be allocated and zeroed prior to the
first invocation of devstat_getdevs(). The dinfo subelement is used to
store state between calls, and should not be modified after the first
call to devstat_getdevs(). The dinfo subelement contains the following
elements:
struct devinfo {
struct devstat *devices;
u_int8_t *mem_ptr;
long generation;
int numdevs;
};
The kern.devstat.all sysctl variable contains an array of devstat struc-
tures, but at the head of the array is the current devstat generation.
The reason the generation is at the head of the buffer is so that user-
land software accessing the devstat statistics information can atomically
get both the statistics information and the corresponding generation num-
ber. If client software were forced to get the generation number via a
separate sysctl variable (which is available for convenience), the list
of devices could change between the time the client gets the generation
and the time the client gets the device list.
The mem_ptr subelement of the devinfo structure is a pointer to memory
that is allocated, and resized if necessary, by devstat_getdevs(). The
devices subelement of the devinfo structure is basically a pointer to the
beginning of the array of devstat structures from the kern.devstat.all
sysctl variable (or the corresponding values read via kvm(3)). The gen-
eration subelement of the devinfo structure contains the corresponding
generation number. The numdevs subelement of the devinfo structure con-
tains the current number of devices registered with the kernel devstat
subsystem.
devstat_selectdevs() selects devices to display based upon a number of
criteria:
specified devices
Specified devices are the first selection priority. These are gen-
erally devices specified by name by the user e.g. da0, da1, cd0.
match patterns
These are pattern matching expressions generated by
pattern, the performance tracking code will select every device in
the system, and sort them by performance. If devices have been
selected by name or pattern, the performance tracking code will
honor those selections and will only sort among the selected
devices.
order in the devstat list
If the selection mode is set to DS_SELECT_ADD, and if there are
still less than maxshowdevs devices selected, devstat_selectdevs()
will automatically select up to maxshowdevs devices.
devstat_selectdevs() performs selections in four different modes:
DS_SELECT_ADD In add mode, devstat_selectdevs() will select any uns-
elected devices specified by name or matching pattern.
It will also select more devices, in devstat list
order, until the number of selected devices is equal
to maxshowdevs or until all devices are selected.
DS_SELECT_ONLY In only mode, devstat_selectdevs() will clear all cur-
rent selections, and will only select devices speci-
fied by name or by matching pattern.
DS_SELECT_REMOVE In remove mode, devstat_selectdevs() will remove
devices specified by name or by matching pattern. It
will not select any additional devices.
DS_SELECT_ADDONLY In add only mode, devstat_selectdevs() will select any
unselected devices specified by name or matching pat-
tern. In this respect it is identical to add mode.
It will not, however, select any devices other than
those specified.
In all selection modes, devstat_selectdevs() will not select any more
than maxshowdevs devices. One exception to this is when you are in
``top'' mode and no devices have been selected. In this case,
devstat_selectdevs() will select every device in the system. Client pro-
grams must pay attention to selection order when deciding whether to pay
attention to a particular device. This may be the wrong behavior, and
probably requires additional thought.
devstat_selectdevs() handles allocation and resizing of the dev_select
structure passed in by the client. devstat_selectdevs() uses the numdevs
and current_generation fields to track the current devstat generation and
number of devices. If num_selections is not the same as numdevs or if
select_generation is not the same as current_generation,
devstat_selectdevs() will resize the selection list as necessary, and re-
initialize the selection array.
devstat_buildmatch() take a comma separated match string and compile it
into a devstat_match structure that is understood by selectdevs(). Match
strings have the following format:
device,type,if
devstat_buildmatch() takes care of allocating and reallocating the match
list as necessary. Currently known match types include:
optical Optical Memory devices
changer Medium Changer devices
comm Communication devices
array Storage Array devices
enclosure Enclosure Services devices
floppy Floppy devices
interface:
IDE Integrated Drive Electronics devices
SCSI Small Computer System Interface devices
other Any other device interface
passthrough:
pass Passthrough devices
devstat_compute_statistics() is an updated version of compute_stats()
that provides more complete statistics calculation. There are four argu-
ments for which values must be supplied: current, previous, etime, and
the terminating argument for the varargs list, DSM_NONE. For most appli-
cations, the user will want to supply valid devstat structures for both
current and previous. In some instances, for instance when calculating
statistics since system boot, the user may pass in a NULL pointer for the
previous argument. In that case, devstat_compute_statistics() will use
the total stats in the current structure to calculate statistics over
etime. For each statistic to be calculated, the user should supply the
proper 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, or floating point, for which a long double is used. The statistics
that may be calculated are:
DSM_NONE type: N/A
This must be the last argument passed to
devstat_compute_statistics(). It is an
argument list terminator.
DSM_TOTAL_BYTES type: u_int64_t *
The total number of bytes transferred
between the acquisition of previous and
current.
DSM_TOTAL_BYTES_READ
DSM_TOTAL_BYTES_WRITE
DSM_TOTAL_BYTES_FREE type: u_int64_t *
The total number of bytes in transactions
of the specified type between the acqui-
sition of previous and current.
DSM_TOTAL_TRANSFERS type: u_int64_t *
The total number of transfers between the
acquisition of previous and current.
DSM_TOTAL_TRANSFERS_OTHER
specified type between the acquisition of
previous and current.
DSM_TOTAL_BLOCKS type: u_int64_t *
The total number of blocks transferred
between the acquisition of previous and
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 calcula-
tion.
DSM_TOTAL_BLOCKS_READ
DSM_TOTAL_BLOCKS_WRITE
DSM_TOTAL_BLOCKS_FREE type: u_int64_t *
The total number of blocks of the speci-
fied type between the acquisition of
previous and 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.
DSM_KB_PER_TRANSFER type: long double *
The average number of kilobytes per
transfer between the acquisition of
previous and current.
DSM_KB_PER_TRANSFER_READ
DSM_KB_PER_TRANSFER_WRITE
DSM_KB_PER_TRANSFER_FREE type: long double *
The average number of kilobytes in the
specified type transaction between the
acquisition of previous and current.
DSM_TRANSFERS_PER_SECOND type: long double *
The average number of transfers per sec-
ond between the acquisition of previous
and current.
DSM_TRANSFERS_PER_SECOND_OTHER
DSM_TRANSFERS_PER_SECOND_READ
DSM_TRANSFERS_PER_SECOND_WRITE
DSM_TRANSFERS_PER_SECOND_FREE type: long double *
ferred per second between the acquisition
of previous and current.
DSM_MB_PER_SECOND_READ
DSM_MB_PER_SECOND_WRITE
DSM_MB_PER_SECOND_FREE type: long double *
The average number of megabytes per sec-
ond in the specified type of transaction
between the acquisition of previous and
current.
DSM_BLOCKS_PER_SECOND type: long double *
The average number of blocks transferred
per second between the acquisition of
previous and 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.
DSM_BLOCKS_PER_SECOND_READ
DSM_BLOCKS_PER_SECOND_WRITE
DSM_BLOCKS_PER_SECOND_FREE type: long double *
The average number of blocks per second
in the specificed type of transaction
between the acquisition of previous and
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 calcula-
tion.
DSM_MS_PER_TRANSACTION type: long double *
The average duration of transactions
between the acquisition of previous and
current.
DSM_MS_PER_TRANSACTION_OTHER
DSM_MS_PER_TRANSACTION_READ
DSM_MS_PER_TRANSACTION_WRITE
DSM_MS_PER_TRANSACTION_FREE type: long double *
The average duration of transactions of
the specified type between the acquisi-
tion of previous and current.
The number of not yet completed transac-
tions at the time when current was
acquired.
DSM_SKIP type: N/A
If you do not need a result from
devstat_compute_statistics(), just put
DSM_SKIP as first (type) parameter and
NULL as second parameter. This can be
useful in scenarios where the statistics
to be calculated are determined at run
time.
devstat_compute_etime() provides an easy way to find the difference in
seconds between two bintime structures. This is most commonly used in
conjunction with the time recorded by the devstat_getdevs() function (in
struct statinfo) each time it fetches the current devstat list.
RETURN VALUES
devstat_getnumdevs(), devstat_getgeneration(), and devstat_getversion()
return the indicated sysctl variable, or -1 if there is an error fetching
the variable.
devstat_checkversion() returns 0 if the kernel and userland devstat ver-
sions match. If they do not match, it returns -1.
devstat_getdevs() and devstat_selectdevs() return -1 in case of an error,
0 if there is no error and 1 if the device list or selected devices have
changed. A return value of 1 from devstat_getdevs() is usually a hint to
re-run devstat_selectdevs() because the device list has changed.
devstat_buildmatch() returns -1 for error, and 0 if there is no error.
devstat_compute_etime() returns the computed elapsed time.
devstat_compute_statistics() returns -1 for error, and 0 for success.
If an error is returned from one of the devstat library functions, the
reason for the error is generally printed in the global string
devstat_errbuf which is DEVSTAT_ERRBUF_SIZE characters long.
SEE ALSO
systat(1), kvm(3), sysctl(3), iostat(8), rpc.rstatd(8), sysctl(8),
vmstat(8), devstat(9)
HISTORY
The devstat statistics system first appeared in FreeBSD 3.0. The new
interface (the functions prefixed with devstat_) first appeared in
FreeBSD 5.0.
AUTHORS
Kenneth Merry <ken@FreeBSD.org>
BUGS
There should probably be an interface to de-allocate memory allocated by
devstat_getdevs(), devstat_selectdevs(), and devstat_buildmatch().
thought out a little more.
FreeBSD 5.4 July 15, 2001 FreeBSD 5.4
SPONSORED LINKS
Man(1) output converted with man2html , sed , awk