スポンサーリンク

DEVSTAT(3) FreeBSD ライブラリ関数マニュアル DEVSTAT(3)

名称

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

ライブラリ

Device Statistics Library (libdevstat, −ldevstat)

書式

#include <sys/dkstat.h>
#include <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_selectionsnumdevs と同じでない場合、または select_generationcurrent_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() は、さまざまなデバイス統計を得るための簡単な方法です。 currentetime の 2 つの引数が必須です。他の各引数はオプションです。ほ とんどのアプリケーションの場合、ユーザは currentpreviousdevstat 構造の両方を指定したいと思うものです。指定期間に渡って統計が計算できるよ うにするためにです。インスタンスによっては、システム起動からの統計を計算 するために、ユーザは 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 構造は、クリーンアップし、もう少し考える必要があ ります。

FreeBSD 10.0 May 21, 1998 FreeBSD 10.0

スポンサーリンク