DragonFly On-Line Manual Pages
DEVSTAT(3) DragonFly Library Functions Manual DEVSTAT(3)
NAME
devstat, getnumdevs, getgeneration, getversion, checkversion, getdevs,
selectdevs, buildmatch, compute_stats, compute_etime -- device statistics
utility library
LIBRARY
Device Statistics Library (libdevstat, -ldevstat)
SYNOPSIS
#include <devstat.h>
int
getnumdevs(void);
long
getgeneration(void);
int
getversion(void);
int
checkversion(void);
int
getdevs(struct statinfo *stats);
int
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
buildmatch(const char *match_str, struct devstat_match **matches,
int *num_matches);
int
compute_stats(struct devstat *current, struct devstat *previous,
long double etime, u_int64_t *total_bytes,
u_int64_t *total_transfers, u_int64_t *total_blocks,
long double *kb_per_transfer, long double *transfers_per_second,
long double *mb_per_second, long double *blocks_per_second,
long double *ms_per_transaction);
long double
compute_etime(struct timeval cur_time, struct timeval 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).
getnumdevs() returns the number of devices registered with the devstat
subsystem in the kernel.
getgeneration() returns the current generation of the devstat list of
devices in the kernel.
getversion() returns the current kernel devstat version.
checkversion() checks the userland devstat version against the kernel
devstat version. If the two are identical, it returns zero. Otherwise,
it prints an appropriate error in devstat_errbuf and returns -1.
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 {
struct kinfo_cputime cp_time;
struct devinfo *dinfo;
struct timeval busy_time;
};
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 getdevs(). The dinfo subelement is used to store
state between calls, and should not be modified after the first call to
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 getdevs(). The devices
subelement of the devinfo structure is basically a pointer to the begin-
ning of the array of devstat structures from the kern.devstat.all sysctl
variable. The generation subelement of the devinfo structure contains
the generation number from the kern.devstat.all sysctl variable. The
numdevs subelement of the devinfo structure contains the current number
of devices registered with the kernel devstat subsystem.
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 buildmatch()
from user input.
performance
If performance mode is enabled, devices will be sorted based on the
bytes field in the device_selection structure passed in to
selectdevs(). The bytes value currently must be maintained by the
user. In the future, this may be done for him in a devstat library
routine. If no devices have been selected by name or by pattern,
the performance tracking code will select every device in the sys-
tem, 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, selectdevs() will
automatically select up to maxshowdevs devices.
selectdevs() performs selections in four different modes:
DS_SELECT_ADD In add mode, selectdevs() will select any unselected
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, selectdevs() will clear all current
selections, and will only select devices specified by
name or by matching pattern.
DS_SELECT_REMOVE In remove mode, selectdevs() will remove devices spec-
ified by name or by matching pattern. It will not
select any additional devices.
DS_SELECT_ADDONLY In add only mode, selectdevs() will select any unse-
lected devices specified by name or matching pattern.
In this respect it is identical to add mode. It will
not, however, select any devices other than those
specified.
In all selection modes, 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, selectdevs() will
select every device in the system. Client programs 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.
selectdevs() handles allocation and resizing of the dev_select structure
passed in by the client. 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, selectdevs()
will resize the selection list as necessary, and re-initialize the selec-
tion array.
buildmatch() takes a comma separated match string and compiles it into a
devstat_match structure that is understood by selectdevs(). Match
strings have the following format:
device,type,if
buildmatch() takes care of allocating and reallocating the match list as
necessary. Currently known match types include:
device type:
da Direct Access devices
sa Sequential Access devices
printer Printers
proc Processor devices
worm Write Once Read Multiple devices
cd CD devices
scanner Scanner devices
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
compute_stats() provides an easy way to obtain various device statistics.
Only two arguments are mandatory: current and etime. Every other argu-
ment is optional. For most applications, the user will want to supply
both current and 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 previous argument. In that case, compute_stats()
will use the total stats in the current structure to calculate statistics
over etime. The various statistics that may be calculated by
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:
total_bytes This is the total number of bytes transferred on
the given device, both reads and writes, between
the acquisition of previous and the acquisition of
current. If previous is NULL, the result will be
the total reads and writes given in current.
total_transfers This is the total number of transfers completed
between the acquisition of previous and the acqui-
sition of current. If previous is NULL, the result
will be the total number of transactions listed in
current.
total_blocks This is basically total_bytes divided by the device
blocksize. If the device blocksize is listed as
`0', the device blocksize will default to 512
bytes.
kb_per_transfer This is the average number of kilobytes per trans-
fer during the measurement period.
transfers_per_second This is the average number of transfers per second.
mb_per_second This is average megabytes per second.
blocks_per_second This is average blocks per second. If the device
blocksize is `0', a default blocksize of 512 bytes
will be used instead.
ms_per_transaction The average number of milliseconds per transaction.
compute_etime() provides an easy way to find the difference in seconds
between two timeval structures. This is most commonly used in conjunc-
tion with the time recorded by the getdevs() function (in struct
statinfo) each time it fetches the current devstat list.
RETURN VALUES
getnumdevs(), getgeneration(), and getversion() return the indicated
sysctl variable, or -1 if there is an error fetching the variable.
checkversion() returns 0 if the kernel and userland devstat versions
match. If they do not match, it returns -1.
getdevs() and 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 getdevs() is usually a hint to re-run selectdevs()
because the device list has changed.
buildmatch() returns -1 for error, and 0 if there is no error.
compute_stats() returns -1 for error, and 0 for success.
compute_etime() returns the computed elapsed time.
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), iostat(8), rpc.rstatd(8), vmstat(8), devstat(9)
HISTORY
The devstat statistics system first appeared in FreeBSD 3.0.
AUTHORS
Kenneth Merry <ken@FreeBSD.org>
BUGS
There should probably be an interface to de-allocate memory allocated by
getdevs(), selectdevs(), and buildmatch().
selectdevs() should probably not select more than maxshowdevs devices in
``top'' mode when no devices have been selected previously.
There should probably be functions to perform the statistics buffer swap-
ping that goes on in most of the clients of this library.
The statinfo and devinfo structures should probably be cleaned up and
thought out a little more.
DragonFly 3.5 May 21, 1998 DragonFly 3.5