The OpenNET Project / Index page

[ новости /+++ | форум | теги | ]

Интерактивная система просмотра системных руководств (man-ов)

 ТемаНаборКатегория 
 
 [Cписок руководств | Печать]

devstat_getdevs (3)
  • >> devstat_getdevs (3) ( FreeBSD man: Библиотечные вызовы )

  • BSD mandoc
     

    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

    Lb libdevstat
    
     
    

    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 Fo devstat_selectdevs Fa struct device_selection **dev_select Fa int *num_selected Fa int *num_selections Fa long *select_generation Fa long current_generation Fa struct devstat *devices Fa int numdevs Fa struct devstat_match *matches Fa int num_matches Fa char **dev_selections Fa int num_dev_selections Fa devstat_select_mode select_mode Fa int maxshowdevs Fa int perf_select Fc Ft int Fo devstat_buildmatch Fa char *match_str Fa struct devstat_match **matches Fa int *num_matches Fc Ft int Fo devstat_compute_statistics Fa struct devstat *current Fa struct devstat *previous Fa long double etime Fa ... Fc Ft long double Fo devstat_compute_etime Fa struct bintime *cur_time Fa struct bintime *prev_time Fc  

    DESCRIPTION

    The 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 Vt 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. The devstat_checkversion ();
    function should be called with each kvm handle that is going to be used (or with NULL if sysctl(3) is going to be used).

    The devstat_getnumdevs ();
    function returns the number of devices registered with the subsystem in the kernel.

    The devstat_getgeneration ();
    function returns the current generation of the list of devices in the kernel.

    The devstat_getversion ();
    function returns the current kernel version.

    The devstat_checkversion ();
    function checks the userland version against the kernel 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 double     snap_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 structures, but at the head of the array is the current generation. The reason the generation is at the head of the buffer is so that userland software accessing the 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 subsystem.

    The devstat_selectdevs ();
    function 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 devstat_buildmatch ();
    from user input.
    performance
    If performance mode is enabled, devices will be sorted based on the bytes field in the Vt 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 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 Fa maxshowdevs devices selected, devstat_selectdevs ();
    will automatically select up to Fa maxshowdevs devices.

    The devstat_selectdevs ();
    function performs selections in four different modes:

    DS_SELECT_ADD
    In ``add'' mode, devstat_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 Fa maxshowdevs or until all devices are selected.
    DS_SELECT_ONLY
    In ``only'' mode, devstat_selectdevs ();
    will clear all current selections, and will only select devices specified 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 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, devstat_selectdevs ();
    will not select any more than Fa 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 Fa dev_select structure passed in by the client. The devstat_selectdevs ();
    function uses the Fa numdevs and Fa current_generation fields to track the current generation and number of devices. If Fa num_selections is not the same as Fa numdevs or if Fa select_generation is not the same as Fa 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:

    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

    The devstat_compute_statistics ();
    function provides complete statistics calculation. There are four arguments for which values must be supplied: Fa current , Fa previous , Fa 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 Fa current and Fa previous . In some instances, for instance when calculating statistics since system boot, the user may pass in a NULL pointer for the Fa previous argument. In that case, devstat_compute_statistics ();
    will use the total stats in the Fa current structure to calculate statistics over Fa 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:

    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: Vt u_int64_t *

    The total number of bytes transferred between the acquisition of Fa previous and Fa current .

    DSM_TOTAL_BYTES_READ
    DSM_TOTAL_BYTES_WRITE
    DSM_TOTAL_BYTES_FREE
    type: Vt u_int64_t *

    The total number of bytes in transactions of the specified type between the acquisition of Fa previous and Fa current .

    DSM_TOTAL_TRANSFERS
    type: Vt u_int64_t *

    The total number of transfers between the acquisition of Fa previous and Fa current .

    DSM_TOTAL_TRANSFERS_OTHER
    DSM_TOTAL_TRANSFERS_READ
    DSM_TOTAL_TRANSFERS_WRITE
    DSM_TOTAL_TRANSFERS_FREE
    type: Vt u_int64_t *

    The total number of transactions of the specified type between the acquisition of Fa previous and Fa current .

    DSM_TOTAL_BLOCKS
    type: Vt u_int64_t *

    The total number of blocks transferred between the acquisition of Fa previous and Fa 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_TOTAL_BLOCKS_READ
    DSM_TOTAL_BLOCKS_WRITE
    DSM_TOTAL_BLOCKS_FREE
    type: Vt u_int64_t *

    The total number of blocks of the specified type between the acquisition of Fa previous and Fa 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: Vt long double *

    The average number of kilobytes per transfer between the acquisition of Fa previous and Fa current .

    DSM_KB_PER_TRANSFER_READ
    DSM_KB_PER_TRANSFER_WRITE
    DSM_KB_PER_TRANSFER_FREE
    type: Vt long double *

    The average number of kilobytes in the specified type transaction between the acquisition of Fa previous and Fa current .

    DSM_TRANSFERS_PER_SECOND
    type: Vt long double *

    The average number of transfers per second between the acquisition of Fa previous and Fa current .

    DSM_TRANSFERS_PER_SECOND_OTHER
    DSM_TRANSFERS_PER_SECOND_READ
    DSM_TRANSFERS_PER_SECOND_WRITE
    DSM_TRANSFERS_PER_SECOND_FREE
    type: Vt long double *

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

    DSM_MB_PER_SECOND
    type: Vt long double *

    The average number of megabytes transferred per second between the acquisition of Fa previous and Fa current .

    DSM_MB_PER_SECOND_READ
    DSM_MB_PER_SECOND_WRITE
    DSM_MB_PER_SECOND_FREE
    type: Vt long double *

    The average number of megabytes per second in the specified type of transaction between the acquisition of Fa previous and Fa current .

    DSM_BLOCKS_PER_SECOND
    type: Vt long double *

    The average number of blocks transferred per second between the acquisition of Fa previous and Fa 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: Vt long double *

    The average number of blocks per second in the specificed type of transaction between the acquisition of Fa previous and Fa 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_MS_PER_TRANSACTION
    type: Vt long double *

    The average duration of transactions between the acquisition of Fa previous and Fa current .

    DSM_MS_PER_TRANSACTION_OTHER
    DSM_MS_PER_TRANSACTION_READ
    DSM_MS_PER_TRANSACTION_WRITE
    DSM_MS_PER_TRANSACTION_FREE
    type: Vt long double *

    The average duration of transactions of the specified type between the acquisition of Fa previous and Fa current .

    DSM_BUSY_PCT
    type: Vt long double *

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

    DSM_QUEUE_LENGTH
    type: Vt u_int64_t *

    The number of not yet completed transactions at the time when Fa 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.

    The devstat_compute_etime ();
    function provides an easy way to find the difference in seconds between two Vt bintime structures. This is most commonly used in conjunction with the time recorded by the devstat_getdevs ();
    function (in Vt struct statinfo ) each time it fetches the current list.  

    RETURN VALUES

    The devstat_getnumdevs (,);
    devstat_getgeneration (,);
    and devstat_getversion ();
    function return the indicated sysctl variable, or -1 if there is an error fetching the variable.

    The devstat_checkversion ();
    function returns 0 if the kernel and userland 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.

    If an error is returned from one of the 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.rstatd8, sysctl(8), vmstat(8), devstat(9)  

    HISTORY

    The statistics system first appeared in Fx 3.0 . The new interface (the functions prefixed with devstat_ first appeared in Fx 5.0 .  

    AUTHORS

    An Kenneth Merry Aq ken@FreeBSD.org  

    BUGS

    There should probably be an interface to de-allocate memory allocated by devstat_getdevs (,);
    devstat_selectdevs (,);
    and devstat_buildmatch (.);

    The devstat_selectdevs ();
    function should probably not select more than Fa 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 Vt statinfo and Vt devinfo structures should probably be cleaned up and thought out a little more.


     

    Index

    NAME
    LIBRARY
    SYNOPSIS
    DESCRIPTION
    RETURN VALUES
    SEE ALSO
    HISTORY
    AUTHORS
    BUGS


    Поиск по тексту MAN-ов: 




    Партнёры:
    PostgresPro
    Inferno Solutions
    Hosting by Hoster.ru
    Хостинг:

    Закладки на сайте
    Проследить за страницей
    Created 1996-2024 by Maxim Chirkov
    Добавить, Поддержать, Вебмастеру