CONTENTS

LIBRARY

SYNOPSIS

DESCRIPTION

The devstat_getnumdevs function returns the number of devices registered with the devstat subsystem in the kernel.

The devstat_getgeneration function returns the current generation of the devstat list of devices in the kernel.

The devstat_getversion function returns the current kernel devstat version.

The devstat_checkversion function 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.

The devstat_getdevs function fetches the current list of devices and statistics into the supplied
.Vt statinfo structure. The
.Vt statinfo structure can be found in
.In devstat.h :
struct statinfo {
long cp_time[CPUSTATES];
long tk_nin;
long tk_nout;
struct devinfo *dinfo;
long doublesnap_time;
};

The devstat_getdevs function expects the
.Vt 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(8) variable contains an array of devstat structures, 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 userland software accessing the devstat statistics information can atomically get both the statistics information and the corresponding generation number. If client software were forced to get the generation number via a separate sysctl(8) 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
.Vt devinfo structure is a pointer to memory that is allocated, and resized if necessary, by devstat_getdevs. The devices subelement of the
.Vt devinfo structure is basically a pointer to the beginning of the array of devstat structures from the kern.devstat.all sysctl(8) variable (or the corresponding values read via kvm(3)). The generation subelement of the
.Vt devinfo structure contains the corresponding generation number. The numdevs subelement of the
.Vt devinfo structure contains the current number of devices registered with the kernel devstat subsystem.

The devstat_selectdevs function selects devices to display based upon a number of criteria:

The devstat_selectdevs function performs selections in four different modes:

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 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.

The devstat_selectdevs function handles allocation and resizing of the dev_select structure passed in by the client. The devstat_selectdevs function 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.

The devstat_buildmatch function takes a comma separated match string and compiles it into a
.Vt devstat_match structure that is understood by devstat_selectdevs. Match strings have the following format:

The devstat_buildmatch function takes care of allocating and reallocating the match list as necessary. Currently known match types include:

The devstat_compute_statistics function provides complete statistics calculation. There are four arguments for which values must be supplied: current, previous, etime, and the terminating argument for the varargs list, DSM_NONE. For most applications, the user will want to supply valid
.Vt 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 statistics 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
.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 devstat_checkversion function returns 0 if the kernel and userland devstat versions match. If they do not match, it returns -1.

The devstat_getdevs and devstat_selectdevs 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. A return value of 1 from devstat_getdevs is usually a hint to re-run devstat_selectdevs because the device list has changed.

The devstat_buildmatch function returns -1 for error, and 0 if there is no error.

The devstat_compute_etime function returns the computed elapsed time.

The devstat_compute_statistics function returns -1 for error, and 0 for success.

HISTORY

AUTHORS

BUGS