日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.3-RELEASE-K, 13.0-RELEASE-K から 13.2-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
DEVSTAT(3) FreeBSD ライブラリ関数マニュアル DEVSTAT(3)
名称
devstat, devstat_getnumdevs, devstat_getgeneration, devstat_getversion,
devstat_checkversion, devstat_getdevs, devstat_selectdevs,
devstat_buildmatch, devstat_compute_statistics, devstat_compute_etime --
デバイス統計ユーティリティライブラリ
ライブラリ
デバイス統計ライブラリ (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 と等しくなるまで、
あるいはすべてのデバイスが選択されるまで、それは、dev
stat リスト順に、より多くのデバイスを選択するでしょ
う。
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 世代#および数を追跡するために numdevs と
current_generation のフィールドを使用します。num_selections が numdevs と
同じでない場合、あるいは select_generation が current_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 Elec
tronics) デバイス
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 *
previous と current の獲得の間で転送され
たバイトの総数です。
DSM_TOTAL_BYTES_READ
DSM_TOTAL_BYTES_WRITE
DSM_TOTAL_BYTES_FREE タイプ: uint64_t *
previous と current の獲得の間で指定され
たタイプのトランザクションのバイトの総数
です。それは引数リストの終端子です。
DSM_TOTAL_TRANSFERS タイプ: uint64_t *
previous と current の獲得の間で転送され
た総数です。
DSM_TOTAL_TRANSFERS_OTHER
DSM_TOTAL_TRANSFERS_READ
DSM_TOTAL_TRANSFERS_WRITE
DSM_TOTAL_TRANSFERS_FREE タイプ: uint64_t *
previous と current の獲得の間で転送され
たバイトの総数です。
DSM_TOTAL_DURATION タイプ: long double *
previous と current の獲得の間で秒単位の
トランザクションの合計の持続時間です。
DSM_TOTAL_DURATION_OTHER
DSM_TOTAL_DURATION_READ
DSM_TOTAL_DURATION_WRITE
DSM_TOTAL_DURATION_FREE タイプ: long double *
previous と current の獲得の間で指定され
たタイプのトランザクションの合計の持続時
間です。
DSM_TOTAL_BUSY_TIME タイプ: long double *
previous と current の獲得の間で 1 つ以上
のトランザクションがあったデバイスの合計
時間。
DSM_TOTAL_BLOCKS タイプ: uint64_t *
previous と current の獲得の間で転送され
たブロックの総数です。この数値は、ブロッ
クサイズに関してデバイスによって報告され
たものです。ブロックサイズが報告されてい
ないなら (すなわち、ブロックサイズは、
0)、デフォルトの 512 バイトのブロックサイ
ズは計算のために使用されます。
DSM_TOTAL_BLOCKS_READ
DSM_TOTAL_BLOCKS_WRITE
DSM_TOTAL_BLOCKS_FREE タイプ: uint64_t *
previous と current の獲得の間で指定され
たタイプのブロックの総数です。この数値
は、ブロックサイズに関してデバイスによっ
て報告されたものです。ブロックサイズが報
告されていないなら (すなわち、ブロックサ
イズは、0)、デフォルトの 512 バイトのブ
ロックサイズは計算のために使用されます。
DSM_KB_PER_TRANSFER タイプ: long double *
previous と current の獲得の間で転送毎の
キロバイトの平均の数です。
DSM_KB_PER_TRANSFER_READ
DSM_KB_PER_TRANSFER_WRITE
DSM_KB_PER_TRANSFER_FREE タイプ: long double *
previous と current の獲得の間で指定され
たタイプのトランザクションのキロバイトの
平均の数です。
DSM_TRANSFERS_PER_SECOND タイプ: long double *
previous と current の獲得の間で秒毎の転
送の平均の数です。
DSM_TRANSFERS_PER_SECOND_OTHER
DSM_TRANSFERS_PER_SECOND_READ
DSM_TRANSFERS_PER_SECOND_WRITE
DSM_TRANSFERS_PER_SECOND_FREE タイプ: long double *
previous と current の獲得の間で秒毎の指
定されたタイプのトランザクションの平均の
数です。
DSM_MB_PER_SECOND タイプ: long double *
previous と current の獲得の間で秒毎に転
送されたメガバイトの平均の数です。
DSM_MB_PER_SECOND_READ
DSM_MB_PER_SECOND_WRITE
DSM_MB_PER_SECOND_FREE タイプ: long double *
previous と current の獲得の間でトランザ
クションの指定されたタイプで秒毎のメガバ
イトの平均の数です。
DSM_BLOCKS_PER_SECOND タイプ: long double *
previous と current の獲得の間で秒毎の転
送されたブロックの平均の数です。この数値
は、ブロックサイズに関してデバイスによっ
て報告されたものです。ブロックサイズが報
告されていないなら (すなわち、ブロックサ
イズは、0)、デフォルトの 512 バイトのブ
ロックサイズは計算のために使用されます。
DSM_BLOCKS_PER_SECOND_READ
DSM_BLOCKS_PER_SECOND_WRITE
DSM_BLOCKS_PER_SECOND_FREE タイプ: long double *
previous と current の獲得の間で指定され
たトランザクションのタイプで秒毎のブロッ
クの平均の数です。この数値は、ブロックサ
イズに関してデバイスによって報告されたも
のです。ブロックサイズが報告されていない
なら (すなわち、ブロックサイズは、0)、デ
フォルトの 512 バイトのブロックサイズは計
算のために使用されます。
DSM_MS_PER_TRANSACTION タイプ: long double *
previous と current の獲得の間でトランザ
クションの平均の持続時間です。
DSM_MS_PER_TRANSACTION_OTHER
DSM_MS_PER_TRANSACTION_READ
DSM_MS_PER_TRANSACTION_WRITE
DSM_MS_PER_TRANSACTION_FREE タイプ: long double *
previous と current の獲得の間で指定され
たタイプのトランザクションの平均の持続時
間です。
DSM_BUSY_PCT タイプ: long double *
previous と current の獲得の間で未解決の
一つ以上のトランザクションがあるデバイス
の時間のパーセンテージです。
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 の中に印刷されます。
関連項目
systat(1), kvm(3), sysctl(3), iostat(8), rpc.rstatd(8), sysctl(8),
vmstat(8), devstat(9)
歴史
devstat 統計システムは、FreeBSD 3.0 ではじめて登場しました。新しいインタ
フェース (devstat_ が前に付けられた関数) は、FreeBSD 5.0 ではじめて登場し
ました。
作者
Kenneth Merry <ken@FreeBSD.org>
バグ
devstat_getdevs(), devstat_selectdevs() と devstat_buildmatch() によって
割り付けられたメモリを割り付け解除するインタフェースが恐らくあるべきで
す。
devstat_selectdevs() 関数は、デバイスが以前に選択されていない場合、
``top'' モードにおいて maxshowdevs デバイスを越える選択をおそらくしてはな
りません。
このライブラリのほとんどのクライアントで行なわれる統計バッファ交換を実行
する関数が恐らくあるべきです。
statinfo と devinfo 構造体は恐らく一掃され、もう少し考え抜くべきです。
FreeBSD 11.2 December 15, 2012 FreeBSD 11.2