DEVSTAT

Section: C Library Functions (3)
索引 jman

BSD mandoc

名称

devstat getnumdevs getgeneration getversion checkversion getdevs selectdevs buildmatch compute_stats compute_etime - デバイス統計ユーティリティライブラリ

索引

ライブラリ

Lb libdevstat

索引

書式

In sys/dkstat.h In devstat.h Ft int Fn getnumdevs void Ft long Fn getgeneration void Ft int Fn getversion void Ft int Fn checkversion void Ft int Fn getdevs struct statinfo *stats Ft int Fo 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 buildmatch Fa char *match_str Fa struct devstat_match **matches Fa int *num_matches Fc Ft int Fo compute_stats Fa struct devstat *current Fa struct devstat *previous Fa long double etime Fa u_int64_t *total_bytes Fa u_int64_t *total_transfers Fa u_int64_t *total_blocks Fa long double *kb_per_transfer Fa long double *transfers_per_second Fa long double *mb_per_second Fa long double *blocks_per_second Fa long double *ms_per_transaction Fc Ft long double Fo compute_etime Fa struct timeval cur_time Fa struct timeval prev_time Fc

索引

解説

ライブラリは、カーネル devstat(9) インタフェースを処理するのに便利な関数のライブラリです。カーネル devstat(9) インタフェースは、 sysctl(3) によってユーザがアクセスできます。

Fn getnumdevs は、カーネル内のサブシステムに登録されたデバイスの数を返します。

Fn getgeneration は、カーネル内のデバイスリストの現在の世代を返します。

Fn getversion は、現在のカーネルデバイスバージョンを返します。

Fn checkversion は、カーネルバージョンに対してユーザランド devstat をチェックします。 2 つが同一の場合、0 が返されます。そうでない場合は、 devstat_errbuf に該当するエラーを表示し -1 を返します。

Fn getdevs は、デバイスと統計の現在のリストを取り出して、指定された statinfo 構造に入れます。 statinfo 構造は Aq Pa devstat.h にあります。

struct statinfo {
        long            cp_time[CPUSTATES];
        long            tk_nin;
        long            tk_nout;
        struct devinfo  *dinfo;
        struct timeval  busy_time;
};

Fn getdevs は、 statinfo 構造が割り当てられることを期待し、また、 Fn getdevs の起動の前に dinfo サブエレメントが割り当てられて 0 で初期化されることも期待します。 dinfo サブエレメントは、呼び出しと呼び出しの間の状態を格納するために使用され、最初の Fn getdevs 呼び出しの後には変更してはなりません。 dinfo サブエレメントには次のエレメントが入っています。

struct devinfo {
        struct devstat  *devices;
        u_int8_t        *mem_ptr;
        long            generation;
        int             numdevs;
};

kern.devstat.all sysctl 変数には、構造の配列が入っていますが、配列の先頭は現在の世代です。世代がバッファの先頭にある理由は、統計にアクセスしているユーザランドソフトウェアが自動的に統計情報および対応する世代番号の両方を不可分に得るようにするためです。クライアントソフトウェアが別の sysctl 変数 (これは便宜のために利用できます) を通じて世代番号を得ることを強制された場合、デバイスのリストは、クライアントが世代を得る時刻と、クライアントがデバイスリストを得る時刻の間で変化する可能性があります。

devinfo 構造の mem_ptr サブエレメントは、割り振られたメモリを指すポインタであり、必要であれば、 Fn getdevs によってサイズを変更されます。 devinfo 構造のデバイスサブエレメントは基本的に、 kern.devstat.all sysctl 変数から構造の配列の先頭を指すポインタです。 devinfo 構造の世代サブエレメントには、 kern.devstat.all sysctl 変数からの世代番号が含まれています。 devinfo 構造の numdevs サブエレメントには、カーネルサブシステムで登録されたデバイスの現在の番号が入っています。

Fn selectdevs は、規準の数を基礎にして表示するデバイスを選択します。

指定デバイス: 指定されたデバイスは最初の選択優先順位です。これらは、一般に、ユーザにより名前により指定されたデバイス、たとえば、 da0, da1, cd0 です。
マッチパターン: これらのパターンユーザ入力から Fn buildmatch によって生成されたパターンマッチング式です。
性能: 性能モードが有効な場合、デバイスは、 Fn selectdevs に渡される device_selection 構造内の bytes フィールドを基礎にしてソートされます。 bytes 値は、現時点では、ユーザが保守する必要があります。将来的には、これはライブラリルーチンで行われる可能性があります。デバイスが名前またはパターンによって選択されていない場合、性能追跡コードがシステム内の各デバイスを選択し、これらを性能によってソートします。デバイスが名前またはパターンによって選択されている場合、性能追跡コードはこれらの選択を尊重し、選択されたデバイスの間でだけソートします。
devstat リスト内の順序: 選択モードが DS_SELECT_ADD に設定され、しかも maxshowdevs 未満のデバイスが選択されている場合、 Fn selectdevs が自動的に maxshowdevs デバイスをセットアップします。

Fn selectdevs は、次の 4 つのモードで選択を行います。

DS_SELECT_ADD: 追加モードで、 Fn selectdevs は、名前または一致パターンによって指定された選択されていないデバイスを選択します。また、これはの順序でさらにデバイスを選択します。選択したデバイスの数が maxshowdevs に等しくなるまで、またはすべてのデバイスが選択されるまでです。
DS_SELECT_ONLY: only モードで、 Fn selectdevs は、現在の選択肢をすべてクリアし、名前または一致するパターンで指定されたデバイスだけを選択します。
DS_SELECT_REMOVE: 除去モードで、 Fn selectdevs は、名前または一致パターンによって指定されたデバイスを除去します。追加デバイスは選択しません。
DS_SELECT_ADDONLY: 追加のみモードで、 Fn selectdevs は、名前または一致するパターンで指定された選択されないデバイスを選択します。この点では、これは追加モードと同一です。しかし、指定された以外のデバイスは選択しません。

すべての選択モードで、 Fn selectdevs は、 maxshowdevs デバイスを越えるデバイスは選択しません。1 つの例外は、 ``top'' モードにあり、デバイスが選択されていないときです。この場合、 Fn selectdevs は、システム内の各デバイスを選択します。クライアントプログラムは、特定のデバイスに注意を払うかどうか決定するときに、選択の順序に注意を払う必要があります。これはまずい動作であり、さらに考慮する必要があると考えられます。

Fn selectdevs は、クライアントによって渡された dev_select 構造の割り当てとサイズ変更を処理します。 Fn selectdevs は、 numdevs フィールドと current_generation フィールドを使用して、現在の世代とデバイスの数を追跡します。 num_selections が numdevs と同じでない場合、または select_generation が current_generation と同じでない場合、 Fn selectdevs は、選択リストを必要に応じてサイズ変更し、選択配列を初期化し直します。

Fn buildmatch は、コンマで区切られた一致ストリングを取り、 Fn selectdevs が理解する devstat_match 構造にコンパイルします。一致ストリングの形式は次のとおりです。

device,type,if

Fn buildmatch は、必要に応じて、一致リストの割り当てと再割り当てを処理します。現時点で既知の一致タイプには次のものが含まれます。

デバイスタイプ:

da: ダイレクトアクセスデバイス
sa: シーケンシャルアクセスデバイス
printer: プリンタ
proc: プロセッサデバイス
worm: 書き込み 1 回読み取り複数デバイス (Write Once Read Multiple devices)
cd: CD デバイス
scanner: スキャナデバイス
optical: 光学メモリデバイス
changer: 媒体変更 (Medium Changer) デバイス
comm: 通信デバイス
array: ストレージ配列デバイス
enclosure: 囲みサービスデバイス (Enclosure Services devices)
floppy: フロッピデバイス

インタフェース:

IDE: 統合ドライブ電子工学デバイス (Integrated Drive Electronics devices)
SCSI: 小型コンピュータシステムインタフェースデバイス
other: 他のデバイスインタフェース

パススルー:

pass: パススルーデバイス

Fn compute_stats は、さまざまなデバイス統計を得るための簡単な方法です。 current と etime の 2 つの引数が必須です。他の各引数はオプションです。ほとんどのアプリケーションの場合、ユーザは current と previous の構造の両方を指定したいと思うものです。指定期間に渡って統計が計算できるようにするためにです。インスタンスによっては、システム起動からの統計を計算するために、ユーザは previous の引数について NULL ポインタを渡すことがあります。その場合、 Fn compute_stats は、 current の構造内の合計状態を使用して、 etime 時間に渡る統計を計算します。 Fn compute_stats が計算する可能性のある各種統計は、関数宣言自体で主に説明する必要がありますが、完全性を期するために、変数名のリストとそれに入れられる統計を示します。

total_bytes: previous の取得と current の取得の間で、読み取りと書き込みの両方が、指定デバイスで転送されるバイトの合計数です。 previous が NULL の場合、結果は current で与えられる合計の読み取りと書き込みです。
total_transfers: previous の取得と current の取得の間で完了される転送の合計数です。以前が NULL の場合、結果は current 内にリストされるトランザクションの合計数です。
total_blocks: 基本的に total_bytes をデバイスブロックサイズで除算したものです。ブロックサイズが `0' としてリストされている場合、デバイスブロックサイズは、デフォルトで 512 バイトになります。
kb_per_transfer: 測定期間の間の転送ごとの平均 KB 数です。
transfers_per_second: 秒ごとの転送の平均数です。
mb_per_second: 秒ごとの平均 MB です。
locks_per_second: 秒ごとの平均ブロックです。デバイスブロックサイズが `0' の場合、デフォルトのブロックサイズ 512 バイトが代わりに使用されます。
ms_per_transaction: トランザクションごとの平均ミリ秒数です。

Fn compute_etime は、2 つの timeval 構造の間の秒単位の違いを検出する簡単な方法です。これは、 Fn getdevs 関数 ( statinfo 構造体内 ) が、現在のリストを取り出すたびに、 Fn getdevs 関数が記録した時刻とともに最も一般的に使用されます。

索引

戻り値

Fn getnumdevs , Fn getgeneration 、および Fn getversion は、指示された sysctl 変数を返します。変数を取り出すときにエラーがあった場合は -1 を返します。

Fn checkversion は、カーネルとユーザランド devstat バージョンが一致する場合、 0 を返します。一致しない場合、 -1 を返します。

Fn getdevs と Fn selectdevs は、エラーの場合は -1 を返し、エラーがない場合は 0 を返し、デバイスリストまたは選択したデバイスが変化している場合は 1 を返します。 Fn getdevs からの戻り値が 1 であるのは、 Fn selectdevs の再実行のヒントです。デバイスリストが変化しているからです。

Fn buildmatch はエラーの場合は -1 、エラーがない場合は 0 を返します。

Fn compute_stats はエラーの場合は -1 、成功の場合は 0 を返します。

Fn compute_etime 計算済みの経過時間を返します。

ライブラリ関数の 1 つからエラーが返された場合、一般に、エラーの理由がグローバルストリング devstat_errbuf に印刷されます。 devstat_errbuf の長さは DEVSTAT_ERRBUF_SIZE キャラクタです。

索引