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, 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
     devstat subsystem in the kernel.

     devstat_getgeneration() returns the current generation of the devstat
     list of devices in	the kernel.

     devstat_getversion() returns the current kernel devstat version.

     devstat_checkversion() checks the userland	devstat	version	against	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
	   devstat_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
	   devstat_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, 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:

     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

     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

     DSM_TOTAL_TRANSFERS_READ

     DSM_TOTAL_TRANSFERS_WRITE

     DSM_TOTAL_TRANSFERS_FREE	     type: u_int64_t *

				     The total number of transactions of the
				     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 *

				     The average number	of transactions	of the
				     specified type per	second between the
				     acquisition of previous and current.

     DSM_MB_PER_SECOND		     type: long	double *

				     The average number	of megabytes trans-
				     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.

     DSM_BUSY_PCT		     type: long	double *

				     The percentage of time the	device had one
				     or	more transactions outstanding between
				     the acquisition of	previous and current.

     DSM_QUEUE_LENGTH		     type: u_int64_t *

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

     devstat_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	10.1			 July 15, 2001			  FreeBSD 10.1

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

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

home | help