DEVSTAT(3)

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

ライブラリ
libdevstat

書式
<sys/dkstat.h> <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)

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

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

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

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

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

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

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

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

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

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

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

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

指定デバイス
    指定されたデバイスは最初の選択優先順位です。これらは、一般に、 ユーザにより名前により指定されたデバイス、たとえば、 da0, da1, cd0 です。

マッチパターン
    これらのパターンユーザ入力から buildmatch() によって生成されたパターンマッチング式です。

性能  性能モードが有効な場合、デバイスは、 selectdevs() に渡される device_selection 構造内の bytes フィールドを基礎にしてソートされます。 bytes 値は、現時点では、ユーザが保守する必要があります。将来的には、これは devstat ライブラリルーチンで行われる可能性があります。デバイスが名前または パターンによって選択されていない場合、性能追跡コードがシステム内の 各デバイスを選択し、これらを性能によってソートします。デバイスが名前または パターンによって選択されている場合、性能追跡コードはこれらの選択を尊重し、 選択されたデバイスの間でだけソートします。

devstat リスト内の順序
    選択モードが DS_SELECT_ADD に設定され、しかも maxshowdevs 未満のデバイスが選択されている場合、 selectdevs() が自動的に maxshowdevs デバイスをセットアップします。

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

DS_SELECT_ADD
    追加モードで、 selectdevs() は、名前または一致パターンによって指定された 選択されていないデバイスを選択します。また、これは devstat の順序でさらにデバイスを選択します。選択したデバイスの数が maxshowdevs に等しくなるまで、またはすべてのデバイスが選択されるまでです。

DS_SELECT_ONLY
    only モードで、 selectdevs() は、現在の選択肢をすべてクリアし、 名前または一致するパターンで指定されたデバイスだけを選択します。

DS_SELECT_REMOVE
    除去モードで、 selectdevs() は、名前または一致パターンによって指定されたデバイスを除去します。 追加デバイスは選択しません。

DS_SELECT_ADDONLY
    追加のみモードで、 selectdevs() は、名前または一致する パターンで指定された選択されないデバイスを選択します。この点では、これは 追加モードと同一です。しかし、指定された以外のデバイスは選択しません。

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

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

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

    device,type,if

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
        パススルーデバイス

compute_stats() は、さまざまなデバイス統計を得るための簡単な方法です。 current と etime の 2 つの引数が必須です。他の各引数はオプションです。 ほとんどのアプリケーションの場合、ユーザは current と previous の devstat 構造の両方を指定したいと思うものです。指定期間に渡って統計が 計算できるようにするためにです。インスタンスによっては、システム起動からの 統計を計算するために、ユーザは previous の引数について NULL ポインタを渡すことがあります。その場合、 compute_stats() は、 current の構造内の合計状態を使用して、 etime 時間に渡る統計を計算します。 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
    トランザクションごとの平均ミリ秒数です。

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

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

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

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

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

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

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

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

関連項目
systat(1), iostat(8), rpc.rstatd(8), vmstat(8), devstat(9)

歴史
devstat 統計システムは最初に FreeBSD 3.0 に現れました。

作者
Kenneth Merry <ken@FreeBSD.org>

バグ
getdevs(), selectdevs() 、および buildmatch() によって割り振られたメモリを 割り当て解除するためのインタフェースがおそらくあるはずです。

selectdevs() は、デバイスが以前に選択されていない場合、 “top” モードでは、 maxshowdevs デバイスより多くを選択することはおそらくできません。

このライブラリのほとんどのクライアントについて行われる統計バッファスワップ を実行するための関数がおそらくあるはずです。

statinfo 構造と devinfo 構造は、クリーンアップし、もう少し考える必要があります。