EN JA
DEVSTAT(3)
DEVSTAT(3) FreeBSD Library Functions Manual DEVSTAT(3)

名称

devstat, devstat_getnumdevs, devstat_getgeneration, devstat_getversion, devstat_checkversion, devstat_getdevs, devstat_selectdevs, devstat_buildmatch, devstat_compute_statistics, devstat_compute_etimeデバイス統計ユーティリティライブラリ

ライブラリ

Device Statistics Library (libdevstat, -ldevstat)

書式

#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
devstat_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
devstat_buildmatch( char *match_str, struct devstat_match **matches, int *num_matches);

int
devstat_compute_statistics( struct devstat *current, struct devstat *previous, long double etime, ...);

long double
devstat_compute_etime( struct bintime *cur_time, struct bintime *prev_time);

解説

devstat ライブラリは、 sysctl(3)kvm(3) によってユーザに利用しやすい、カーネル devstat(9) インタフェースを処理するための援助関数のライブラリです。すべての関数は、 sysctl(3) を通してデータを読み込むようにする、引数として kvm ハンドルの代わりに NULL を渡すことができる最初の引数として kvm_t * を取ります。そうでなければ、それは、供給されたハンドルを使用する kvm(3) を通して読み込まれます。 devstat_checkversion() 関数は、使用されている各 kvm ハンドル (または sysctl(3) が使用されているなら NULL) で呼び出されるべきです。

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

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

devstat_getversion() 関数は、現在のカーネル devstat バージョンを返します。

devstat_checkversion() 関数は、ユーザランド devstat バージョンとカーネル devstat バージョンをチェックします。 2 つが同一であるなら、0 を返します。そうでなければ、 devstat_errbuf で適切なエラーを印刷 (表示) し、-1 を返します。

devstat_getdevs() 関数は、供給された statinfo 構造体にデバイスと統計の現在のリストを取り出します。 statinfo 構造体は、 < devstat.h> で見つけることができます。

struct statinfo { 
 long            cp_time[CPUSTATES]; 
 long            tk_nin; 
 long            tk_nout; 
 struct devinfo  *dinfo; 
 long double     snap_time; 
};

devstat_getdevs() 関数は、 statinfo 構造体が割り付けられることを求められ、また、 devstat_getdevs() の最初の呼び出しの前に dinfo サブエレメントが割り付けられ 0 で初期化されることも求められます。 dinfo サブエレメントは、呼び出しの間の状態を格納するために使用され、 devstat_getdevs() への最初の呼び出しの後に修正されてはなりません。 dinfo サブエレメントは次のエレメント (要素) を含んでいます。

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

kern.devstat.all sysctl(8) 変数は、 devstat 構造体の配列を含んでいますが、配列の先頭は現在の devstat 世代#です。世代#がバッファの先頭にある理由は、 devstat 統計情報にアクセスするユーザランドソフトウェアが統計情報および対応する世代#番号の両方を不可分に得ることができるためです。クライアントソフトウェアが、個々の sysctl(8) 変数 (それは便宜のため利用可能である) によって世代#番号を得ることを強いられる場合、デバイスのリストは、クライアントが生成を得る時と、クライアントがデバイスリストを得る時の間で変更できます。

devinfo 構造体の mem_ptr サブエレメントは割り付けられ、必要な場合に devstat_getdevs() によってサイズ変更されるメモリへのポインタです。 devinfo 構造体のデバイスサブエレメントは基本的に kern.devstat.all sysctl(8) 変数 (または kvm(3) によって読み込まれた対応する値) からの devstat 構造体の配列の最初へのポインタです。 devinfo 構造体の世代#サブエレメントは、対応する生成#番号を含んでいます。 devinfo 構造体の numdevs サブエレメントは、カーネル devstat サブシステムで登録されたデバイスの現在の数を含んでいます。

devstat_selectdevs() 関数は、多くの基準に基づいたディスプレイへのデバイスを選択します。

指定されたデバイス
指定されたデバイスは最初の選択優先事項です。これらは一般的に、ユーザによって名前で指定されたデバイス、例えば、 da0, da1, cd0 です。
パターンマッチ (照合)
これらはユーザ入力からの devstat_buildmatch() によって生成されたパターン照合式です。
性能
性能モードが有効になる場合、デバイスは、 devstat_selectdevs() に渡された device_selection 構造体中の bytes フィールドに基づいてソートされるでしょう。 bytes 値は現在ユーザによって保守しなければなりません。将来、これは、 devstat ライブラリルーチンでユーザのために行われるかもしれません。デバイスが名前によってあるいはパターンによって選択されていない場合、性能追跡コードはシステムでのすべてのデバイスを選択し、性能によってそれらをソートするでしょう。デバイスが名前またはパターンによって選択された場合、性能追跡コードは、それらの選択を尊重し、選択されたデバイスの中だけでソートするでしょう。
devstat リスト中の順序
選択モードが DS_SELECT_ADD に設定される場合、そして選択されたデバイスがまだ maxshowdevs 未満である場合、 devstat_selectdevs() は、自動的に maxshowdevs デバイスまで選択するでしょう。

devstat_selectdevs() 関数は、4 つの異なるモードで選択を実行します。

DS_SELECT_ADD
“add” (追加) モードにおいて、 devstat_selectdevs() は、名前によってまたは一致するパターンで指定されたなにも選択されていないデバイスを選択するでしょう。また、選択されたデバイスの数が maxshowdevs と等しくなるまで、あるいはすべてのデバイスが選択されるまで、それは、devstat リスト順に、より多くのデバイスを選択するでしょう。
DS_SELECT_ONLY
“only”モードにおいて、 devstat_selectdevs() は現在の選択をすべてクリアし、名前または一致するパターンによって指定されたデバイスだけを選択するでしょう。
DS_SELECT_REMOVE
“remove” (削除) モードにおいて、 devstat_selectdevs() は、名前または一致するパターンによって指定されたデバイスを削除するでしょう。それは追加のデバイスを選択しません。
DS_SELECT_ADDONLY
“add only” (追加のみ) モードにおいて、 devstat_selectdevs() は、名前または一致するパターンによってなにも選択されていないデバイスを選択するでしょう。この点で、それは、“add”モードと同一です。しかしながら、指定されたもの以外のデバイスを選択しません。

すべての選択モードにおいて、 devstat_selectdevs() は、 maxshowdevs デバイスを越えるデバイスは何も選択しません。この 1 つの例外は、“top”モードで、デバイスが選択されていない時です。この場合、 devstat_selectdevs() は、システム中のすべてのデバイスを選択するでしょう。特別のデバイスに注意を払うべきかどうか決定する場合、クライアントプログラムは、選択順序に注意を払わなければなりません。これは間違っている振る舞いかもしれないし、たぶんさらなる考慮を必要とします。

devstat_selectdevs() 関数は、クライアントによって渡された dev_select 構造体の割り付けとサイズ変更することを操作します。 devstat_selectdevs() 関数は、デバイスの現在の devstat 世代#および数を追跡するために numdevscurrent_generation のフィールドを使用します。 num_selectionsnumdevs と同じでない場合、あるいは select_generationcurrent_generation と同じでない場合、 devstat_selectdevs() は選択リストを必要に応じてサイズ変更し、選択配列を再初期化するでしょう。

devstat_buildmatch() 関数はコンマで分離された一致文字列をとり、 devstat_selectdevs() によって理解される devstat_match 構造体へそれをコンパイルします。一致文字列は次の形式を持っています:

device, type, if

devstat_buildmatch() 関数は、必要に応じて一致リストの割り付けと再割り付けを処理をします。現在の既知の一致タイプは次のものを含んでいます。

デバイスタイプ:
da
ダイレクトアクセス (Direct Access) デバイス
sa
シーケンシャルアクセス (Sequential Access) デバイス
printer
プリンタ
proc
プロセッサデバイス
worm
書き込み 1 度読み込み複数 (Write Once Read Multiple) デバイス
cd
CD デバイス
scanner
スキャナデバイス
optical
光学メモリデバイス
changer
媒体自動交換 (Medium Changer) デバイス
comm
通信デバイス
array
記憶装置配列 (Storage Array) デバイス
enclosure
エンクロージャサービス (Enclosure Services) デバイス
floppy
フロッピデバイス
インタフェース:
IDE
統合ドライブエレクトロニクス (Integrated Drive Electronics) デバイス
SCSI
小型コンピュータシステムインタフェース (Small Computer System Interface) デバイス
other
他のデバイスインタフェース
パススルー:
pass
パススルー (Passthrough) デバイス

devstat_compute_statistics() 関数は、完全な統計の計算を提供します。値を供給 しなければならない 4 つの引数があります: current, previous, etime と varargs リストのための終わり引数 DSM_NONE です。ほとんどのアプリケーションのために、ユーザは、 current (現在) と previous (前の) の両方のために有効な devstat 構造体を供給しなければなりません。ある場合に、例えば、システムブートからの統計を計算するとき、ユーザは、 previous (前の) 引数のために NULL ポインタを渡すことができます。その場合には、 devstat_compute_statistics() は、 etime 上で統計を計算するのに current (現在) 構造体で合計の統計を使用します。各統計値を計算されるために、ユーザは適切な (下記にリストされている) 列挙型、および示されたタイプの変数を供給するべきです。すべての統計値は、 uint64_t が使用されている整数値か ( long double が使用されている) 浮動小数点のどちらかです。計算される統計は次の通りです:

DSM_NONE
タイプ: N/A (非適用)

devstat_compute_statistics() に渡される最後の引数 でなければなりません 。それは引数リストの終端子です。

DSM_TOTAL_BYTES
タイプ: uint64_t *

previouscurrent の獲得の間で転送されたバイトの総数です。

DSM_TOTAL_BYTES_READ
DSM_TOTAL_BYTES_WRITE
DSM_TOTAL_BYTES_FREE
タイプ: uint64_t *

previouscurrent の獲得の間で指定されたタイプのトランザクションのバイトの総数です。それは引数リストの終端子です。

DSM_TOTAL_TRANSFERS
タイプ: uint64_t *

previouscurrent の獲得の間で転送された総数です。

DSM_TOTAL_TRANSFERS_OTHER
DSM_TOTAL_TRANSFERS_READ
DSM_TOTAL_TRANSFERS_WRITE
DSM_TOTAL_TRANSFERS_FREE
タイプ: uint64_t *

previouscurrent の獲得の間で転送されたバイトの総数です。

DSM_TOTAL_DURATION
タイプ: long double *

previouscurrent の獲得の間で秒単位のトランザクションの合計の持続時間です。

DSM_TOTAL_DURATION_OTHER
DSM_TOTAL_DURATION_READ
DSM_TOTAL_DURATION_WRITE
DSM_TOTAL_DURATION_FREE
タイプ: long double *

previouscurrent の獲得の間で指定されたタイプのトランザクションの合計の持続時間です。

DSM_TOTAL_BUSY_TIME
タイプ: long double *

previouscurrent の獲得の間で 1 つ以上のトランザクションがあったデバイスの合計時間。

DSM_TOTAL_BLOCKS
タイプ: uint64_t *

previouscurrent の獲得の間で転送されたブロックの総数です。この数値は、ブロックサイズに関してデバイスによって報告されたものです。ブロックサイズが報告されていないなら (すなわち、ブロックサイズは、0)、デフォルトの 512 バイトのブロックサイズは計算のために使用されます。

DSM_TOTAL_BLOCKS_READ
DSM_TOTAL_BLOCKS_WRITE
DSM_TOTAL_BLOCKS_FREE
タイプ: uint64_t *

previouscurrent の獲得の間で指定されたタイプのブロックの総数です。この数値は、ブロックサイズに関してデバイスによって報告されたものです。ブロックサイズが報告されていないなら (すなわち、ブロックサイズは、0)、デフォルトの 512 バイトのブロックサイズは計算のために使用されます。

DSM_KB_PER_TRANSFER
タイプ: long double *

previouscurrent の獲得の間で転送毎のキロバイトの平均の数です。

DSM_KB_PER_TRANSFER_READ
DSM_KB_PER_TRANSFER_WRITE
DSM_KB_PER_TRANSFER_FREE
タイプ: long double *

previouscurrent の獲得の間で指定されたタイプのトランザクションのキロバイトの平均の数です。

DSM_TRANSFERS_PER_SECOND
タイプ: long double *

previouscurrent の獲得の間で秒毎の転送の平均の数です。

DSM_TRANSFERS_PER_SECOND_OTHER
DSM_TRANSFERS_PER_SECOND_READ
DSM_TRANSFERS_PER_SECOND_WRITE
DSM_TRANSFERS_PER_SECOND_FREE
タイプ: long double *

previouscurrent の獲得の間で秒毎の指定されたタイプのトランザクションの平均の数です。

DSM_MB_PER_SECOND
タイプ: long double *

previouscurrent の獲得の間で秒毎に転送されたメガバイトの平均の数です。

DSM_MB_PER_SECOND_READ
DSM_MB_PER_SECOND_WRITE
DSM_MB_PER_SECOND_FREE
タイプ: long double *

previouscurrent の獲得の間でトランザクションの指定されたタイプで秒毎のメガバイトの平均の数です。

DSM_BLOCKS_PER_SECOND
タイプ: long double *

previouscurrent の獲得の間で秒毎の転送されたブロックの平均の数です。この数値は、ブロックサイズに関してデバイスによって報告されたものです。ブロックサイズが報告されていないなら (すなわち、ブロックサイズは、0)、デフォルトの 512 バイトのブロックサイズは計算のために使用されます。

DSM_BLOCKS_PER_SECOND_READ
DSM_BLOCKS_PER_SECOND_WRITE
DSM_BLOCKS_PER_SECOND_FREE
タイプ: long double *

previouscurrent の獲得の間で指定されたトランザクションのタイプで秒毎のブロックの平均の数です。この数値は、ブロックサイズに関してデバイスによって報告されたものです。ブロックサイズが報告されていないなら (すなわち、ブロックサイズは、0)、デフォルトの 512 バイトのブロックサイズは計算のために使用されます。

DSM_MS_PER_TRANSACTION
タイプ: long double *

previouscurrent の獲得の間でトランザクションの平均の持続時間です。

DSM_MS_PER_TRANSACTION_OTHER
DSM_MS_PER_TRANSACTION_READ
DSM_MS_PER_TRANSACTION_WRITE
DSM_MS_PER_TRANSACTION_FREE
タイプ: long double *

previouscurrent の獲得の間で指定されたタイプのトランザクションの平均の持続時間です。

DSM_BUSY_PCT
タイプ: long double *

previouscurrent の獲得の間で未解決の一つ以上のトランザクションがあるデバイスの時間のパーセンテージです。

DSM_QUEUE_LENGTH
タイプ: u_int64_t *

current が獲得されたとき、その時点でまだ終了しないトランザクションの数です。

DSM_SKIP
タイプ: N/A (非適用)

利用者が devstat_compute_statistics() からの結果を必要としないなら、単に最初の (タイプ) パラメータとして DSM_SKIP と 2 番目のパラメータとして NULL を置きます。これは計算された統計が実行時に決定されるシナリオで役に立つ場合があります。

devstat_compute_etime() 関数は、2 つの bintime 構造体の間の秒単位の違いを見つける容易な方法を提供します。これは、それが現在の devstat リストを取って来るごとに、 devstat_getdevs() 関数 ( struct statinfo で) によって記録された時間と共に最も一般的に使用されます。

戻り値

devstat_getnumdevs(), devstat_getgeneration() と devstat_getversion() 関数は、示された sysctl 変数を返します。変数を取って来るエラーがある場合、-1 を返します。

devstat_checkversion() 関数は、カーネルおよびユーザランド devstat バージョンが一致する場合、 0 を返します。それらが一致しない場合、-1 を返します。

devstat_getdevs() と devstat_selectdevs() 関数はエラーの場合は、-1 を返し、エラーがない場合は、0 を返し、デバイスリストあるいは選択されたデバイスが変更された場合は、1 を返します。 devstat_getdevs() からの返り値が 1 であるのは、通常デバイスリストが変更されたので、 devstat_selectdevs() を再実行する手掛かりです。

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

devstat_compute_etime() 関数は計算された経過時間を返します。

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

devstat ライブラリ関数のうちの 1 つからエラーが返される場合、一般的に、エラーの理由は、長さ DEVSTAT_ERRBUF_SIZE 文字であるグローバル文字列 devstat_errbuf の中に印刷されます。

歴史

devstat 統計システムは、 FreeBSD 3.0 ではじめて登場しました。新しいインタフェース ( devstat_ が前に付けられた関数) は、 FreeBSD 5.0 ではじめて登場しました。

作者

Kenneth Merry <ken@FreeBSD.org>

バグ

devstat_getdevs(), devstat_selectdevs() と devstat_buildmatch() によって割り付けられたメモリを割り付け解除するインタフェースが恐らくあるべきです。

devstat_selectdevs() 関数は、デバイスが以前に選択されていない場合、“top”モードにおいて maxshowdevs デバイスを越える選択をおそらくしてはなりません。

このライブラリのほとんどのクライアントで行なわれる統計バッファ交換を実行する関数が恐らくあるべきです。

statinfodevinfo 構造体は恐らく一掃され、もう少し考え抜くべきです。

December 15, 2012 FreeBSD