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)

     devstat, getnumdevs, getgeneration, getversion, checkversion, getdevs,
     selectdevs, buildmatch, compute_stats, compute_etime - device statistics
     utility library

     Device Statistics Library (libdevstat, -ldevstat)

     #include <sys/dkstat.h>
     #include <devstat.h>





     getdevs(struct statinfo *stats);

     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);

     buildmatch(char *match_str, struct devstat_match **matches,
         int *num_matches);

     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);

     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

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

           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

     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

     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:


     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

             IDE        Integrated Drive Electronics devices
             SCSI       Small Computer System Interface devices
             other      Any other device interface

             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

     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.

     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.

     systat(1), iostat(8), rpc.rstatd(8), vmstat(8), devstat(9)

     The devstat statistics system first appeared in FreeBSD 3.0.

     Kenneth Merry <>

     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
     swapping 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 11.0-PRERELEASE          May 21, 1998          FreeBSD 11.0-PRERELEASE


Want to link to this manual page? Use this URL:

home | help