Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
DEVSTAT(3)	       FreeBSD 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 <sys/dkstat.h>
     #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(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 {
		   long		   cp_time[CPUSTATES];
		   long		   tk_nin;
		   long		   tk_nout;
		   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.

FreeBSD	9.2			 May 21, 1998			   FreeBSD 9.2

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=devstat&sektion=3&manpath=FreeBSD+4.9-RELEASE>

home | help