man.bsd.lv manual page server

DESCRIPTION

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 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 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 beginning 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 generally 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 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, 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 specified by name or by matching pattern. It will not select any additional devices.

DS_SELECT_ADDONLY

In add only mode, selectdevs() will select any unselected 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 selection 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 argument 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 acquisition 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 transfer 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 conjunction with the time recorded by the getdevs() function (in struct statinfo) each time it fetches the current devstat list.